Vault

Kind: vault

Overview

Use Vault as a secretstore backend when you want Netdata collectors to read secrets from HashiCorp Vault at runtime instead of storing them in plain text in collector configuration files.

This page covers Vault specific setup. For the shared resolver workflow and syntax, 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. 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 be allowed to read the paths you reference from collector configs.

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
    namespace: admin
    tls_skip_verify: false

Token file

Read the Vault token from a local file on the Netdata host.

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

Use in collector configs

Reference Vault secrets from collector configs with the vault secretstore kind.

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

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

KV v1 secret

Read the password field from a KV v1 secret.

${store:vault:vault_prod:secret/netdata/mysql#password}

KV v2 secret

Read the password field from a KV v2 secret. Include /data/ in the path.

${store:vault:vault_prod:secret/data/netdata/mysql#password}

Collector config example

Use a Vault secret in a collector DSN.

jobs:
  - name: mysql_prod
    dsn: "netdata:${store:vault:vault_prod:secret/data/netdata/mysql#password}@tcp(127.0.0.1:3306)/"

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.