Netdata can pull collector credentials directly from AWS Secrets Manager at runtime, so you never store passwords or tokens in plain-text configuration files.
This page covers AWS Secrets Manager specific setup. For the full resolver overview and syntax reference, including simpler alternatives like ${env:...}, ${file:...}, and ${cmd:...}, see Secrets Management.
Limitations
Netdata reads existing secrets from AWS Secrets Manager. It does not create, rotate, or manage those secrets. If you use secret-name#key, the secret value must be stored as a JSON SecretString.
The Dynamic Configuration Test action runs the configured production credential-source path and discards the result. In env mode it reads the Netdata process environment without network access. In ecs mode it performs one logical request to the ECS task credential endpoint. In imds mode it performs the IMDSv2 token, role-name, and credential requests sequentially. Metadata redirects and proxies are disabled. Go can transparently retransmit a bodyless metadata GET once after a qualifying reused-connection failure; the Test does not add application retries.
Operational success proves only that the selected source returned non-empty access-key and secret-key values at that time. The session token remains optional and is not part of the guarantee. Test does not contact AWS Secrets Manager, STS, KMS, or another AWS data-plane endpoint, so it does not prove that AWS accepts the credentials, that they are current or temporary, that the configured region is correct, or that the identity can read or decrypt any secret.
Test requires no additional AWS IAM permission beyond the configured credential source and does not mutate an AWS resource or policy. IMDS mode creates only the normal short-lived metadata-service token and can produce ordinary metadata-service telemetry.
Each credential-source response is limited to 1 MiB. Every request uses the configured timeout; IMDS can consume approximately three sequential timeout periods, while an earlier Dynamic Configuration caller deadline or cancellation wins.
Setup
You can configure the aws-sm secretstore in two ways:
Edit /etc/netdata/go.d/ss/aws-sm.conf and add a jobs entry.
Prerequisites
Provide AWS credentials
Choose one supported authentication mode and make sure the Netdata Agent can obtain credentials for it:
env: set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY for the Netdata service. Set AWS_SESSION_TOKEN too if you use temporary credentials.
ecs: run Netdata in ECS with a task role so AWS_CONTAINER_CREDENTIALS_RELATIVE_URI is available.
imds: run Netdata on EC2 with an instance profile and access to IMDSv2.
For production on AWS, prefer ecs or imds over env so credentials are supplied by the platform instead of being stored in the Netdata service environment.
Allow access to Secrets Manager
The AWS identity used by this secretstore must have the secretsmanager:GetSecretValue permission on the secrets you reference in collector configs. Scope the IAM policy to only the secret ARNs Netdata needs.
Plan for file-based changes
If you edit /etc/netdata/go.d/ss/aws-sm.conf, restart the Netdata Agent to load the updated secretstore definition.
Configuration
Options
The following options can be defined for this secretstore backend.
AWS region used for Secrets Manager requests. There is no automatic region detection — you must always set this explicitly.
yes
timeout
Timeout in seconds for HTTP requests made by this secretstore backend.
3
no
auth_mode
Supported values:
env: read credentials from the Netdata process environment.
ecs: read credentials from the ECS task credentials endpoint.
imds: read credentials from the EC2 Instance Metadata Service.
For production on AWS, prefer ecs or imds when Netdata runs on ECS or EC2. Use env when you intentionally manage credentials in the Netdata service environment.
via UI
Open the Netdata Dynamic Configuration UI.
Go to Collectors -> go.d -> SecretStores -> aws-sm.
Add a new secretstore and give it a store name.
Fill in the backend-specific settings.
Save the secretstore.
via File
Define the secretstore in /etc/netdata/go.d/ss/aws-sm.conf.
Each file contains a jobs array, and the secretstore kind is determined by the filename.
After editing the file, restart the Netdata Agent to load the updated secretstore definition.
Examples
Environment credentials
Use environment-provided AWS credentials for the Netdata service.
Use the ${store:aws-sm:...} syntax to reference AWS Secrets Manager secrets in any string field of a collector configuration file.
The operand is secret-name or secret-name#key.
Use secret-name to return the whole SecretString, for example: ${store:aws-sm:aws_prod:netdata/mysql/password}.
Use secret-name#key to read one top-level field from a JSON SecretString, for example: ${store:aws-sm:aws_prod:netdata/mysql#password}.
If you use #key, Netdata parses the secret value as JSON. Secret resolution fails if the value is not valid JSON or if the key does not exist.
Nested paths such as parent.child are not interpreted as nested JSON lookups.
${store:aws-sm:<store-name>:<secret-name[#key]>}
aws-sm: The secretstore backend kind.
<store-name>: The name of the configured secretstore, for example aws_prod.
<secret-name[#key]>: The AWS Secrets Manager secret name, optionally followed by #key to read one field from a JSON SecretString.
Examples
MySQL collector with password from AWS Secrets Manager
This example configures a MySQL collector job in /etc/netdata/go.d/mysql.conf.
The password in the DSN connection string is not stored in plain text. Instead,
${store:aws-sm:aws_prod:netdata/mysql#password} tells Netdata to fetch the secret
named netdata/mysql from the aws_prod store, extract the password field from
its JSON value, and substitute it into the DSN at runtime.
This example configures an Elasticsearch collector job in /etc/netdata/go.d/elasticsearch.conf.
The password field uses a secret reference instead of a plain-text password. Netdata fetches
the secret named netdata/elasticsearch/password from the aws_prod store and substitutes
its full value into the password field at runtime.
Check the Netdata Agent logs when the collector starts or restarts. AWS resolver errors include messages such as AWS_ACCESS_KEY_ID is not set, parsing SecretString as JSON, or key 'password' not found in SecretString JSON.
AWS credentials are not found
Check the selected auth_mode.
For env, make sure the Netdata service has AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
For ecs, make sure Netdata runs in ECS and AWS_CONTAINER_CREDENTIALS_RELATIVE_URI is available.
For imds, make sure the EC2 instance profile is attached and IMDSv2 is reachable.
The Dynamic Configuration Test fails
The Test action exercises only the configured credential source. It does not call AWS Secrets Manager or test a secret path.
For env, verify that the Netdata service environment contains non-empty AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY values.
For ecs, verify that AWS_CONTAINER_CREDENTIALS_RELATIVE_URI is present and is a valid path-style relative URI supplied by ECS.
For imds, verify that IMDSv2 is reachable, returns a non-empty token, and exposes one valid IAM role name and its credentials.
A successful Test does not prove that AWS accepts the returned credentials or that they have permission to access a particular secret. Check the configured region, secretsmanager:GetSecretValue, and any required kms:Decrypt permission separately.
Access denied or wrong region
Confirm the configured region and make sure the AWS identity used by Netdata can read the referenced secret in that region.
JSON key lookup fails
If you use secret-name#key, the secret must be stored as a JSON SecretString, and the requested key must exist as a top-level field in that JSON object.
The observability platform companies need to succeed
