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:

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.

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

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.