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:

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.

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

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.