Azure Key Vault

Kind: azure-kv

Overview

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

This page covers Azure Key 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 the latest version of a secret value from Azure Key Vault. The operand format does not select a specific secret version.

Setup

You can configure the azure-kv secretstore in two ways:

Method	Best for	How to
UI	Fast setup without editing files	Go to Collectors -> go.d -> SecretStores -> azure-kv, then add a secretstore.
File	File-based configuration or automation	Edit /etc/netdata/go.d/ss/azure-kv.conf and add a jobs entry.

Prerequisites

Choose an Azure authentication mode

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

• service_principal: provide tenant_id, client_id, and client_secret.
• managed_identity: run Netdata on an Azure resource with a managed identity.
• default: use the Azure SDK DefaultAzureCredential chain, which automatically tries available Azure credential sources such as environment-based credentials, managed identity, and local developer credentials.

Prefer managed_identity for production on Azure when Netdata runs on an Azure resource with an attached identity. Use service_principal for explicit application credentials. Use default for Azure SDK auto-discovery or local development convenience.

Allow secret read access

The Azure identity used by this secretstore must be allowed to read secret values from the target vaults. Assign the Key Vault Secrets User built-in role scoped to the vault. Do not use broader roles like Key Vault Administrator.

Plan for file-based changes

If you edit /etc/netdata/go.d/ss/azure-kv.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	Azure authentication mode.	default	yes
Service Principal	mode_service_principal.tenant_id	Azure tenant ID. Required when mode is service_principal.		yes
	mode_service_principal.client_id	Azure application / service principal client ID. Required when mode is service_principal.		yes
	mode_service_principal.client_secret	Azure application / service principal client secret. Required when mode is service_principal.		yes
Managed Identity	mode_managed_identity.client_id	Optional client ID of a user-assigned managed identity when mode is managed_identity. Leave it empty for the system-assigned identity.		no

mode

Supported values:

• service_principal: use an Azure app / service principal.
• managed_identity: use the managed identity attached to the Azure resource running Netdata.
• default: use the Azure SDK DefaultAzureCredential chain. It automatically tries available Azure credential sources such as environment-based credentials, managed identity, and local developer credentials.

Prefer managed_identity for production on Azure. Use service_principal for explicit app credentials. Use default when you want Azure SDK auto-discovery or local development convenience.

via UI

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

Service principal

Use explicit Azure app credentials.

jobs:
  - name: azure_prod
    mode: service_principal
    mode_service_principal:
      tenant_id: 00000000-0000-0000-0000-000000000000
      client_id: 00000000-0000-0000-0000-000000000000
      client_secret: your-client-secret

Service principal with credentials from environment

Use ${env:...} resolvers for sensitive fields to avoid storing the client secret in plain text in the secretstore config file.

jobs:
  - name: azure_prod
    mode: service_principal
    mode_service_principal:
      tenant_id: "${env:AZURE_TENANT_ID}"
      client_id: "${env:AZURE_CLIENT_ID}"
      client_secret: "${env:AZURE_CLIENT_SECRET}"

Managed identity

Use the managed identity attached to the Azure resource running Netdata.

jobs:
  - name: azure_vm
    mode: managed_identity
    mode_managed_identity:
      client_id: 00000000-0000-0000-0000-000000000000

Default credential chain

Use the Azure SDK default credential chain.

jobs:
  - name: azure_default
    mode: default

Use in collector configs

Use the ${store:azure-kv:...} syntax to reference Azure Key Vault secrets in any string field of a collector configuration file.

The operand is vault-name/secret-name, for example: ${store:azure-kv:azure_prod:my-keyvault/mysql-password}.

Netdata requests the latest secret value from https://<vault-name>.vault.azure.net/secrets/<secret-name>?api-version=7.4. Both vault-name and secret-name must use only letters, numbers, and hyphens.

${store:azure-kv:<store-name>:<vault-name/secret-name>}

• azure-kv: The secretstore backend kind.
• <store-name>: The name of the configured secretstore, for example azure_prod.
• <vault-name/secret-name>: The Azure Key Vault name and the secret name, separated by /.

Examples

MySQL collector with password from Azure Key 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:azure-kv:azure_prod:my-keyvault/mysql-password} tells Netdata to fetch the secret named mysql-password from the my-keyvault vault using the azure_prod store, and substitute its value into the DSN at runtime.

# /etc/netdata/go.d/mysql.conf
jobs:
  - name: mysql_prod
    dsn: "netdata:${store:azure-kv:azure_prod:my-keyvault/mysql-password}@tcp(127.0.0.1:3306)/"

PostgreSQL collector with password from Azure Key Vault

This example configures a PostgreSQL collector job in /etc/netdata/go.d/postgres.conf. The password field uses a secret reference instead of a plain-text value. Netdata fetches the secret named postgres-password from the my-keyvault vault and substitutes its value into the password field at runtime.

# /etc/netdata/go.d/postgres.conf
jobs:
  - name: postgres_prod
    dsn: "postgresql://netdata:${store:azure-kv:azure_prod:my-keyvault/postgres-password}@localhost:5432/postgres"

Troubleshooting

Find the exact error

Check the Netdata Agent logs when the collector starts or restarts. Azure resolver errors include messages such as invalid vault name, invalid secret name, or Azure Key Vault returned HTTP 403.

Azure authentication fails

Check the selected mode and the credentials it requires.

• For service_principal, verify tenant_id, client_id, and client_secret.
• For managed_identity, make sure Netdata runs on an Azure resource with an attached identity.
• For default, confirm that one of the Azure SDK credential sources is available to the Netdata process.

Secret lookup fails

Check the operand format. It must be vault-name/secret-name, and both names must use only letters, numbers, and hyphens.

Access denied

Make sure the Azure identity used by Netdata can read secret values from the target vault.