AWS Secrets Manager

Kind: aws-sm

Overview

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:

Method	Best for	How to
UI	Fast setup without editing files	Go to Collectors -> go.d -> SecretStores -> aws-sm, then add a secretstore.
File	File-based configuration or automation	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.

Config options

Option	Description	Default	Required
auth_mode	How Netdata obtains AWS credentials.	env	yes
region	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

1. Open the Netdata Dynamic Configuration UI.
2. Go to Collectors -> go.d -> SecretStores -> aws-sm.
3. Add a new secretstore and give it a store name.
4. Fill in the backend-specific settings.
5. 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.

jobs:
  - name: aws_prod
    auth_mode: env
    region: us-east-1

ECS task role

Use credentials provided to a Netdata task running in ECS.

jobs:
  - name: aws_ecs
    auth_mode: ecs
    region: us-east-1

EC2 instance profile

Use the instance profile attached to the EC2 instance running Netdata.

jobs:
  - name: aws_imds
    auth_mode: imds
    region: us-east-1

Use in collector configs

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.

# /etc/netdata/go.d/mysql.conf
jobs:
  - name: mysql_prod
    dsn: "netdata:${store:aws-sm:aws_prod:netdata/mysql#password}@tcp(127.0.0.1:3306)/"

Elasticsearch collector with HTTP basic auth

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.

# /etc/netdata/go.d/elasticsearch.conf
jobs:
  - name: es_prod
    url: https://elasticsearch.example.com:9200
    username: netdata
    password: "${store:aws-sm:aws_prod:netdata/elasticsearch/password}"

Troubleshooting

Find the exact error

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.