Azure Key Vault

Kind: azure-kv

Overview

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

This page covers Azure Key Vault specific setup. For the shared resolver workflow and syntax, 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.

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

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

Reference Azure Key Vault secrets from collector configs with the azure-kv secretstore kind.

The operand is vault-name/secret-name.

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

Secret reference

Read the latest value of the mysql-password secret from the my-keyvault vault.

${store:azure-kv:azure_prod:my-keyvault/mysql-password}

Collector config example

Use an Azure Key Vault secret in a collector DSN.

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

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.