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


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


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



