Vault

Kind: vault

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.

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	Fast setup without editing files	Go to Collectors -> go.d -> SecretStores -> vault, then add a secretstore.
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.

Config options

Group	Option	Description	Default	Required
	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	Disable TLS certificate verification for Vault requests.	no	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

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.

tls_skip_verify

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

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.

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.

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.

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.

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.

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

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

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