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

# Vault


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


Kind: vault

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

## Overview

Netdata can pull collector credentials directly from HashiCorp Vault at runtime, so you never store passwords or tokens in plain-text configuration files.

This page covers Vault 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 Vault. It does not create or renew Vault tokens. If the configured token expires or becomes invalid, secret resolution fails until Netdata can read a valid token again. If you use `token_file` mode, Netdata re-reads the file on every secret resolution, so an external process (e.g. Vault Agent, a cron job) can renew the token by writing to the file. For KV v2 secrets, Netdata does not add `/data/` to the path automatically.


## Setup

You can configure the `vault` secretstore in two ways:

| Method | Best for | How to |
|:--|:--|:--|
| [**UI**](#via-ui) | Fast setup without editing files | Go to `Collectors -> go.d -> SecretStores -> vault`, then add a secretstore. |
| [**File**](#via-file) | File-based configuration or automation | Edit `/etc/netdata/go.d/ss/vault.conf` and add a `jobs` entry. |

### Prerequisites

#### Make Vault reachable

Netdata must be able to reach your Vault server at the address you configure in `addr`.


#### Provide a Vault token

Choose one supported authentication mode and make sure Netdata can use it:

- `token`: store the Vault token directly in the secretstore configuration.
- `token_file`: store the Vault token in a local file on the Netdata host that is readable by the `netdata` user.

Prefer `token_file` for production so the Vault token is not embedded directly in the secretstore configuration.


#### Allow access to the referenced secret paths

The Vault token used by this secretstore must have a policy that grants `read` capability on the paths you reference from collector configs. Scope the policy to only the paths Netdata needs.


#### Plan for file-based changes

If you edit `/etc/netdata/go.d/ss/vault.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>



| Group | Option | Description | Default | Required |
|:------|:-----|:------------|:--------|:---------:|
|  | [mode](#option-mode) | How Vault authentication is provided. | token | yes |
|  | addr | Vault server address / base URL. |  | yes |
|  | namespace | Optional Vault Enterprise namespace. Leave it empty for open-source Vault or when your Vault deployment does not use namespaces. |  | no |
|  | [tls_skip_verify](#option-tls-skip-verify) | Disable TLS certificate verification for Vault requests. | no | no |
|  | timeout | Timeout in seconds for HTTP requests made by this secretstore backend. | 3 | no |
| **Token** | mode_token.token | Vault token value. Required when `mode` is `token`. |  | yes |
| **Token File** | mode_token_file.path | Path to a file containing the Vault token. Required when `mode` is `token_file`. |  | yes |

<a id="option-mode"></a>
##### mode

Supported values:

- `token`: store the Vault token directly in the secretstore configuration.
- `token_file`: read the Vault token from a local file on the Netdata host.

Prefer `token_file` for production so the token is stored separately from the secretstore configuration.


<a id="option-tls-skip-verify"></a>
##### tls_skip_verify

This is insecure. Use it only as a temporary workaround or in a non-production environment.



</details>


#### via UI

1. Open the Netdata Dynamic Configuration UI.
2. Go to `Collectors -> go.d -> SecretStores -> vault`.
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/vault.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

###### Token

Store the Vault token directly in the secretstore definition.

```yaml
jobs:
  - name: vault_prod
    mode: token
    mode_token:
      token: your-vault-token
    addr: https://vault.example

```
###### Token from environment variable

Use a `${env:...}` resolver for the Vault token to avoid storing it in plain text in the secretstore config file.

```yaml
jobs:
  - name: vault_prod
    mode: token
    mode_token:
      token: "${env:VAULT_TOKEN}"
    addr: https://vault.example

```
###### Token file

Read the Vault token from a local file on the Netdata host. Netdata re-reads the file on every secret resolution, so an external process can renew the token by writing to this file.

```yaml
jobs:
  - name: vault_prod_file_token
    mode: token_file
    mode_token_file:
      path: /var/lib/netdata/vault.token
    addr: https://vault.example

```
###### Vault Enterprise with namespace

Connect to a Vault Enterprise server using a specific namespace.

```yaml
jobs:
  - name: vault_enterprise
    mode: token_file
    mode_token_file:
      path: /var/lib/netdata/vault.token
    addr: https://vault.example
    namespace: admin

```


## Use in collector configs

Use the `${store:vault:...}` syntax to reference Vault secrets in any string field of a collector configuration file.


The operand is `path#key`.

Netdata sends the path to Vault as `/v1/<path>` exactly as you provide it. For KV v2 secrets, include `/data/` in the path yourself.
The `path` must not be empty and must not contain `..`, `?`, or `#`.

- KV v1 example: `${store:vault:vault_prod:secret/netdata/mysql#password}`.
- KV v2 example: `${store:vault:vault_prod:secret/data/netdata/mysql#password}` — note the `/data/` segment, Netdata does not add it automatically.


```text
${store:vault:<store-name>:<path#key>}
```

- `vault`: The secretstore backend kind.
- `<store-name>`: The name of the configured secretstore, for example `vault_prod`.
- `<path#key>`: The Vault API path and the secret field name, separated by `#`.

### Examples
#### MySQL collector with password from Vault

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:vault:vault_prod:secret/data/netdata/mysql#password}` tells Netdata to
read the KV v2 secret at `secret/data/netdata/mysql` from the `vault_prod` store,
extract the `password` field from the response, and substitute it into the DSN at runtime.


```yaml
# /etc/netdata/go.d/mysql.conf
jobs:
  - name: mysql_prod
    dsn: "netdata:${store:vault:vault_prod:secret/data/netdata/mysql#password}@tcp(127.0.0.1:3306)/"

```
#### Elasticsearch collector with HTTP basic auth from Vault

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 value. Netdata reads the
KV v2 secret at `secret/data/netdata/elasticsearch` from the `vault_prod` store, extracts the
`password` field, and substitutes it at runtime.


```yaml
# /etc/netdata/go.d/elasticsearch.conf
jobs:
  - name: es_prod
    url: https://elasticsearch.example.com:9200
    username: netdata
    password: "${store:vault:vault_prod:secret/data/netdata/elasticsearch#password}"

```


## Troubleshooting

### Find the exact error

Check the Netdata Agent logs when the collector starts or restarts. Vault resolver errors include messages such as `vault returned HTTP 403`, `vault path contains invalid characters`, `operand must be in format 'path#key'`, or `key 'password' not found in vault response`.


### Vault returns permission denied or the token has expired

Check the Vault token policy and, if you use Vault Enterprise namespaces, confirm that `namespace` is correct. If you use a short-lived token, make sure the token is renewed or replaced before it expires.


### Secret or key is not found

Check the operand carefully:

- Make sure the path is the Vault API path.
- For KV v2, make sure the path includes `/data/`.
- Make sure the `key` exists in the returned secret payload.


### TLS verification fails

Make sure the Netdata host trusts the CA that signed the Vault certificate. Use `tls_skip_verify: true` only as an insecure workaround.


### Token file cannot be read

Check the file path, file contents, and that the `netdata` user can read the file.



