<!--startmeta
custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/go/plugin/agent/secrets/secretstore/backends/azure/README.md"
meta_yaml: "https://github.com/netdata/netdata/edit/master/src/go/plugin/agent/secrets/secretstore/backends/azure/metadata.yaml"
sidebar_label: "Azure Key Vault"
learn_status: "Published"
learn_rel_path: "Collecting Metrics/Secrets Management/Secret Stores"
keywords: ['secretstore', 'secrets', 'azure', 'azure-kv', 'azure key vault']
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE SECRETSTORE'S metadata.yaml FILE"
endmeta-->

# Azure Key Vault


<img src="https://netdata.cloud/img/azure.svg" width="150"/>


Kind: azure-kv

<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />

## 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](https://github.com/netdata/netdata/blob/master/src/collectors/SECRETS.md).


### 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**](#via-ui) | Fast setup without editing files | Go to `Collectors -> go.d -> SecretStores -> azure-kv`, then add a secretstore. |
| [**File**](#via-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.

<details open><summary>Config options</summary>



| Group | Option | Description | Default | Required |
|:------|:-----|:------------|:--------|:---------:|
|  | [mode](#option-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 |
|  | timeout | Timeout in seconds for HTTP requests made by this secretstore backend. | 3 | no |

<a id="option-mode"></a>
##### 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.



</details>


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

```yaml
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.

```yaml
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.

```yaml
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.

```yaml
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.


```text
${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.


```yaml
# /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.


```yaml
# /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.
