AWS Secrets Manager

Kind: aws-sm

Overview

Use AWS Secrets Manager as a secretstore backend when you want Netdata collectors to read secrets from AWS at runtime instead of storing them in plain text in collector configuration files.

This page covers AWS Secrets Manager specific setup. For the shared resolver workflow and syntax, 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.

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 be allowed to read the secrets you reference in collector configs in the configured region.

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.		yes

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

Reference AWS Secrets Manager secrets from collector configs with the aws-sm secretstore kind.

The operand is secret-name or secret-name#key.

• Use secret-name to return the whole SecretString.
• Use secret-name#key to read one top-level field from a JSON SecretString.
• 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

Whole secret value

Return the full SecretString stored under the netdata/mysql/password secret.

${store:aws-sm:aws_prod:netdata/mysql/password}

JSON field from SecretString

Read the password field from a JSON SecretString.

${store:aws-sm:aws_prod:netdata/mysql#password}

Collector config example

Use an AWS-stored password in a collector DSN.

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

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.

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.