| 1 | # yamllint disable rule:line-length |
| 2 | --- |
| 3 | id: 'secretstore-azure-kv' |
| 4 | meta: |
| 5 | kind: 'azure-kv' |
| 6 | name: 'Azure Key Vault' |
| 7 | link: 'https://azure.microsoft.com/en-us/products/key-vault' |
| 8 | icon_filename: 'azure.svg' |
| 9 | keywords: |
| 10 | - 'secretstore' |
| 11 | - 'secrets' |
| 12 | - 'azure' |
| 13 | - 'azure-kv' |
| 14 | - 'azure key vault' |
| 15 | overview: |
| 16 | description: | |
| 17 | Netdata can pull collector credentials directly from Azure Key Vault at runtime, so you never store passwords or tokens in plain-text configuration files. |
| 18 | |
| 19 | 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](/src/collectors/SECRETS.md). |
| 20 | limitations: | |
| 21 | Netdata reads the latest version of a secret value from Azure Key Vault. The operand format does not select a specific secret version. |
| 22 | setup: |
| 23 | prerequisites: |
| 24 | list: |
| 25 | - title: 'Choose an Azure authentication mode' |
| 26 | description: | |
| 27 | Choose one supported authentication mode and make sure the Netdata Agent can use it: |
| 28 | |
| 29 | - `service_principal`: provide `tenant_id`, `client_id`, and `client_secret`. |
| 30 | - `managed_identity`: run Netdata on an Azure resource with a managed identity. |
| 31 | - `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. |
| 32 | |
| 33 | 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. |
| 34 | - title: 'Allow secret read access' |
| 35 | description: | |
| 36 | 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`. |
| 37 | - title: 'Plan for file-based changes' |
| 38 | description: | |
| 39 | If you edit `/etc/netdata/go.d/ss/azure-kv.conf`, restart the Netdata Agent to load the updated secretstore definition. |
| 40 | configuration: |
| 41 | file: |
| 42 | name: 'go.d/ss/azure-kv.conf' |
| 43 | options: |
| 44 | description: 'The following options can be defined for this secretstore backend.' |
| 45 | folding: |
| 46 | title: 'Config options' |
| 47 | enabled: true |
| 48 | list: |
| 49 | - name: 'mode' |
| 50 | description: 'Azure authentication mode.' |
| 51 | default_value: 'default' |
| 52 | required: true |
| 53 | detailed_description: | |
| 54 | Supported values: |
| 55 | |
| 56 | - `service_principal`: use an Azure app / service principal. |
| 57 | - `managed_identity`: use the managed identity attached to the Azure resource running Netdata. |
| 58 | - `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. |
| 59 | |
| 60 | 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. |
| 61 | - name: 'mode_service_principal.tenant_id' |
| 62 | group: 'Service Principal' |
| 63 | description: 'Azure tenant ID. Required when `mode` is `service_principal`.' |
| 64 | default_value: '' |
| 65 | required: true |
| 66 | - name: 'mode_service_principal.client_id' |
| 67 | group: 'Service Principal' |
| 68 | description: 'Azure application / service principal client ID. Required when `mode` is `service_principal`.' |
| 69 | default_value: '' |
| 70 | required: true |
| 71 | - name: 'mode_service_principal.client_secret' |
| 72 | group: 'Service Principal' |
| 73 | description: 'Azure application / service principal client secret. Required when `mode` is `service_principal`.' |
| 74 | default_value: '' |
| 75 | required: true |
| 76 | - name: 'mode_managed_identity.client_id' |
| 77 | group: 'Managed Identity' |
| 78 | description: 'Optional client ID of a user-assigned managed identity when `mode` is `managed_identity`. Leave it empty for the system-assigned identity.' |
| 79 | default_value: '' |
| 80 | required: false |
| 81 | - name: 'timeout' |
| 82 | description: 'Timeout in seconds for HTTP requests made by this secretstore backend.' |
| 83 | default_value: 3 |
| 84 | required: false |
| 85 | examples: |
| 86 | folding: |
| 87 | title: 'Example configuration' |
| 88 | enabled: true |
| 89 | list: |
| 90 | - name: 'Service principal' |
| 91 | description: 'Use explicit Azure app credentials.' |
| 92 | config: | |
| 93 | jobs: |
| 94 | - name: azure_prod |
| 95 | mode: service_principal |
| 96 | mode_service_principal: |
| 97 | tenant_id: 00000000-0000-0000-0000-000000000000 |
| 98 | client_id: 00000000-0000-0000-0000-000000000000 |
| 99 | client_secret: your-client-secret |
| 100 | - name: 'Service principal with credentials from environment' |
| 101 | description: 'Use `${env:...}` resolvers for sensitive fields to avoid storing the client secret in plain text in the secretstore config file.' |
| 102 | config: | |
| 103 | jobs: |
| 104 | - name: azure_prod |
| 105 | mode: service_principal |
| 106 | mode_service_principal: |
| 107 | tenant_id: "${env:AZURE_TENANT_ID}" |
| 108 | client_id: "${env:AZURE_CLIENT_ID}" |
| 109 | client_secret: "${env:AZURE_CLIENT_SECRET}" |
| 110 | - name: 'Managed identity' |
| 111 | description: 'Use the managed identity attached to the Azure resource running Netdata.' |
| 112 | config: | |
| 113 | jobs: |
| 114 | - name: azure_vm |
| 115 | mode: managed_identity |
| 116 | mode_managed_identity: |
| 117 | client_id: 00000000-0000-0000-0000-000000000000 |
| 118 | - name: 'Default credential chain' |
| 119 | description: 'Use the Azure SDK default credential chain.' |
| 120 | config: | |
| 121 | jobs: |
| 122 | - name: azure_default |
| 123 | mode: default |
| 124 | collector_configs: |
| 125 | description: | |
| 126 | Use the `${store:azure-kv:...}` syntax to reference Azure Key Vault secrets in any string field of a collector configuration file. |
| 127 | summary: |
| 128 | operand_format: 'vault-name/secret-name' |
| 129 | example_operand: 'my-keyvault/mysql-password' |
| 130 | format: |
| 131 | description: | |
| 132 | The operand is `vault-name/secret-name`, for example: `${store:azure-kv:azure_prod:my-keyvault/mysql-password}`. |
| 133 | |
| 134 | Netdata requests the latest secret value from `https://<vault-name>.vault.azure.net/secrets/<secret-name>?api-version=7.4`. |
| 135 | Both `vault-name` and `secret-name` must use only letters, numbers, and hyphens. |
| 136 | syntax: '${store:azure-kv:<store-name>:<vault-name/secret-name>}' |
| 137 | parts: |
| 138 | list: |
| 139 | - name: 'azure-kv' |
| 140 | description: 'The secretstore backend kind.' |
| 141 | - name: '<store-name>' |
| 142 | description: 'The name of the configured secretstore, for example `azure_prod`.' |
| 143 | - name: '<vault-name/secret-name>' |
| 144 | description: 'The Azure Key Vault name and the secret name, separated by `/`.' |
| 145 | examples: |
| 146 | list: |
| 147 | - name: 'MySQL collector with password from Azure Key Vault' |
| 148 | description: | |
| 149 | This example configures a MySQL collector job in `/etc/netdata/go.d/mysql.conf`. |
| 150 | The password in the DSN connection string is not stored in plain text. Instead, |
| 151 | `${store:azure-kv:azure_prod:my-keyvault/mysql-password}` tells Netdata to fetch |
| 152 | the secret named `mysql-password` from the `my-keyvault` vault using the `azure_prod` |
| 153 | store, and substitute its value into the DSN at runtime. |
| 154 | content: | |
| 155 | # /etc/netdata/go.d/mysql.conf |
| 156 | jobs: |
| 157 | - name: mysql_prod |
| 158 | dsn: "netdata:${store:azure-kv:azure_prod:my-keyvault/mysql-password}@tcp(127.0.0.1:3306)/" |
| 159 | - name: 'PostgreSQL collector with password from Azure Key Vault' |
| 160 | description: | |
| 161 | This example configures a PostgreSQL collector job in `/etc/netdata/go.d/postgres.conf`. |
| 162 | The `password` field uses a secret reference instead of a plain-text value. Netdata fetches |
| 163 | the secret named `postgres-password` from the `my-keyvault` vault and substitutes its value |
| 164 | into the `password` field at runtime. |
| 165 | content: | |
| 166 | # /etc/netdata/go.d/postgres.conf |
| 167 | jobs: |
| 168 | - name: postgres_prod |
| 169 | dsn: "postgresql://netdata:${store:azure-kv:azure_prod:my-keyvault/postgres-password}@localhost:5432/postgres" |
| 170 | troubleshooting: |
| 171 | problems: |
| 172 | list: |
| 173 | - name: 'Find the exact error' |
| 174 | description: | |
| 175 | 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`. |
| 176 | - name: 'Azure authentication fails' |
| 177 | description: | |
| 178 | Check the selected `mode` and the credentials it requires. |
| 179 | |
| 180 | - For `service_principal`, verify `tenant_id`, `client_id`, and `client_secret`. |
| 181 | - For `managed_identity`, make sure Netdata runs on an Azure resource with an attached identity. |
| 182 | - For `default`, confirm that one of the Azure SDK credential sources is available to the Netdata process. |
| 183 | - name: 'Secret lookup fails' |
| 184 | description: | |
| 185 | Check the operand format. It must be `vault-name/secret-name`, and both names must use only letters, numbers, and hyphens. |
| 186 | - name: 'Access denied' |
| 187 | description: | |
| 188 | Make sure the Azure identity used by Netdata can read secret values from the target vault. |