<!--startmeta
custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/go/plugin/agent/secrets/secretstore/backends/aws/README.md"
meta_yaml: "https://github.com/netdata/netdata/edit/master/src/go/plugin/agent/secrets/secretstore/backends/aws/metadata.yaml"
sidebar_label: "AWS Secrets Manager"
learn_status: "Published"
learn_rel_path: "Collecting Metrics/Secrets Management/Secret Stores"
keywords: ['secretstore', 'secrets', 'aws', 'aws-sm', 'aws secrets manager']
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE SECRETSTORE'S metadata.yaml FILE"
endmeta-->

# AWS Secrets Manager


<img src="https://netdata.cloud/img/aws.svg" width="150"/>


Kind: aws-sm

<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />

## 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](https://github.com/netdata/netdata/blob/master/src/collectors/SECRETS.md).


### 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**](#via-ui) | Fast setup without editing files | Go to `Collectors -> go.d -> SecretStores -> aws-sm`, then add a secretstore. |
| [**File**](#via-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.

<details open><summary>Config options</summary>



| Option | Description | Default | Required |
|:-----|:------------|:--------|:---------:|
| [auth_mode](#option-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 |

<a id="option-auth-mode"></a>
##### 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.



</details>


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

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

```
###### ECS task role

Use credentials provided to a Netdata task running in ECS.

```yaml
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.

```yaml
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.


```text
${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.


```yaml
# /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.


```yaml
# /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.
