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:

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.

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

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.