@cryptotaxi247 / netdata-1 / commits / eecca9a91

docs(secretstore): improve secret store backend documentation (#22099)

- Rewrite overview descriptions to lead with user benefit instead of jargon - Add realistic collector config examples (MySQL DSN + Elasticsearch/PostgreSQL/HTTP check) with explicit descriptions explaining the secret substitution mechanics - Move standalone reference examples into format.description as inline examples - Document that secretstore configs support ${env:...}, ${file:...}, ${cmd:...} resolvers - Add ${env:...} alternative examples for Azure client_secret and Vault token - Add "Choosing a Resolver" decision guide to SECRETS.md - Add "Multiple Secretstores" and "Mixing Resolver Types" sections to SECRETS.md - Add Docker Secrets and Kubernetes Secrets notes to the Files section - Add config directory creation instructions for /etc/netdata/go.d/ss/ - Add IAM/RBAC minimum permission hints per backend - Fix GCP limitations (was describing default behavior, not actual limitations) - Fix Vault examples: remove unnecessary tls_skip_verify default, add Enterprise namespace example - Add token_file re-read behavior note for Vault - Add GKE Workload Identity note for GCP metadata mode - Add region "no auto-detection" note for AWS - Fix schema bug: minLength -> minItems for array validation in secretstore.json - Change default code fence language from text to yaml in collector_configs template

Ilya Mashchenko committed Mar 31, 2026 at 18:34 UTC eecca9a91b2104cdea0d25350ec7d0a0b834e32a

13 files changed +394 -148

integrations/gen_doc_secrets_page.py

+37

@@ -27,6 +27,7 @@ SECRETS_PAGE = {

27 ],

28 "jump_to": [

29 {"label": "Resolver Quick Reference", "anchor": "resolver-quick-reference"},

30 + {"label": "Choosing a Resolver", "anchor": "choosing-a-resolver"},

31 {"label": "Environment Variables", "anchor": "environment-variables"},

32 {"label": "Files", "anchor": "files"},

33 {"label": "Commands", "anchor": "commands"},

@@ -61,6 +62,12 @@ SECRETS_PAGE = {

62 "notes": "Configure the secretstore first, then reference it from collector configs.",

63 },

64 ],

65 + "choosing_a_resolver": [

66 + "Use `${env:...}` or `${file:...}` for simple setups where secrets are already available locally on the Netdata host.",

67 + "Use `${cmd:...}` when you need dynamic secret retrieval via a trusted local command, such as 1Password CLI or a custom script.",

68 + "Use `${store:...}` when your organization manages secrets centrally in a cloud provider or Vault and you want Netdata to pull from that source directly.",

69 + "You can use different resolver types across different collectors, different jobs within the same collector, or even within the same configuration value. See [Mixing resolver types](#mixing-resolver-types).",

70 + ],

71 "sections": {

72 "env": {

73 "heading": "## Environment Variables",

@@ -87,6 +94,8 @@ jobs:

94 "The file path must be absolute.",

95 "Netdata trims leading and trailing whitespace from the file contents.",

96 "The file must exist on the Netdata host and be readable by the `netdata` user.",

97 + "**Docker Secrets**: Docker mounts secrets as files under `/run/secrets/` inside the container. Use `${file:/run/secrets/<secret-name>}` to read them.",

98 + "**Kubernetes Secrets**: If you mount Kubernetes Secrets as volume files in the Netdata pod, reference them with `${file:/path/to/mounted/secret}`.",

99 ],

100 },

101 "cmd": {

@@ -130,6 +139,32 @@ jobs:

139 ],

140 "file_intro": "Each secretstore backend has its own file under `/etc/netdata/go.d/ss/`:",

141 "file_note": "File-based secretstores are loaded at agent startup. If you edit these files, restart the Netdata Agent to apply the changes.",

142 + "file_directory": (

143 + "If the `/etc/netdata/go.d/ss/` directory does not exist, create it:\n\n"

144 + "```bash\n"

145 + "sudo mkdir -p /etc/netdata/go.d/ss\n"

146 + "sudo chown netdata:netdata /etc/netdata/go.d/ss\n"

147 + "sudo chmod 0750 /etc/netdata/go.d/ss\n"

148 + "```\n\n"

149 + "Secretstore configuration files may contain sensitive values such as tokens or client secrets. "

150 + "Restrict directory and file permissions to the `netdata` user."

151 + ),

152 + "mixing": (

153 + "You can mix different resolver types in the same configuration value or the same config file. "

154 + "For example, you might read the username from an environment variable and the password from a secretstore:\n\n"

155 + "```yaml\n"

156 + "jobs:\n"

157 + " - name: mysql_prod\n"

158 + ' dsn: "${env:MYSQL_USER}:${store:vault:vault_prod:secret/data/netdata/mysql#password}@tcp(127.0.0.1:3306)/"\n'

159 + "```\n\n"

160 + "Different jobs within the same collector config file can also use different resolver types."

161 + ),

162 + "multiple_stores": (

163 + "Each secretstore config file can contain multiple `jobs` entries, each with a unique store name. "

164 + "You can use different secretstore backends simultaneously. "

165 + "For example, you might configure a Vault store for database credentials and an AWS Secrets Manager store for API keys, "

166 + "then reference each one using its `${store:<kind>:<name>:<operand>}` syntax in the relevant collector configs."

167 + ),

168 },

169 "secretstores": {

170 "heading": "## Supported Secretstore Backends",

@@ -145,6 +180,7 @@ jobs:

180 "security_notes": [

181 "Prefer secret references over plain-text credentials in collector configs.",

182 "Prefer platform-native identity modes for production when a backend supports them, such as instance roles, managed identities, or metadata-based credentials.",

183 + "Secretstore configuration values (such as tokens and client secrets) also support `${env:...}`, `${file:...}`, and `${cmd:...}` resolvers. Use them to avoid storing backend credentials in plain text. Note that `${store:...}` references are not supported inside secretstore configurations.",

184 "Keep local secret material readable only by the `netdata` user, including token files, service account files, and any files used with `${file:...}`.",

185 "Use `${cmd:...}` only with trusted local commands and absolute paths.",

186 ],

@@ -288,6 +324,7 @@ def build_page_context() -> Dict[str, Any]:

324 f'[{jump["label"]}](#{jump["anchor"]})' for jump in SECRETS_PAGE["jump_to"]

325 ),

326 "quick_reference": SECRETS_PAGE["quick_reference"],

327 + "choosing_a_resolver": SECRETS_PAGE["choosing_a_resolver"],

328 "sections": [

329 SECRETS_PAGE["sections"]["env"],

330 SECRETS_PAGE["sections"]["file"],

integrations/schemas/secretstore.json

+1 -1

@@ -167,7 +167,7 @@

167 "properties": {

168 "list": {

169 "type": "array",

170 - "minLength": 1,

170 + "minItems": 1,

171 "items": {

172 "$ref": "#/$defs/collector_configs_example"

173 }

integrations/templates/collector_configs.md

+1 -1

@@ -20,7 +20,7 @@

21 [[ example.description ]]

23 -```[[ example.language or 'text' ]]

23 +```[[ example.language or 'yaml' ]]

24 [[ example.content ]]

25 ```

26 [% endfor %]

integrations/templates/secrets.md

+16

@@ -17,6 +17,12 @@

18 [% endfor %]

20 +## Choosing a Resolver

21 +

22 +[% for item in page.choosing_a_resolver %]

23 +- [[ item ]]

24 +[% endfor %]

25 +

26 [% for section in page.sections %]

27 [[ section.heading ]]

@@ -75,6 +81,16 @@ Each file contains a `jobs` array. The backend kind is determined by the filenam

82 :::

84 +[[ page.store.file_directory ]]

85 +

86 +### Multiple Secretstores

87 +

88 +[[ page.store.multiple_stores ]]

89 +

90 +### Mixing Resolver Types

91 +

92 +[[ page.store.mixing ]]

93 +

94 [[ page.secretstores.heading ]]

96 [[ page.secretstores.intro ]]

src/collectors/SECRETS.md

+37 -1

@@ -6,7 +6,7 @@ Netdata lets you reference secret values in collector configs instead of storing

7 ### Jump To

9 -[Resolver Quick Reference](#resolver-quick-reference) • [Environment Variables](#environment-variables) • [Files](#files) • [Commands](#commands) • [Secretstores](#secretstores) • [Supported Secretstore Backends](#supported-secretstore-backends) • [How It Works](#how-it-works) • [Troubleshooting](#troubleshooting)

9 +[Resolver Quick Reference](#resolver-quick-reference) • [Choosing a Resolver](#choosing-a-resolver) • [Environment Variables](#environment-variables) • [Files](#files) • [Commands](#commands) • [Secretstores](#secretstores) • [Supported Secretstore Backends](#supported-secretstore-backends) • [How It Works](#how-it-works) • [Troubleshooting](#troubleshooting)

12 ## Resolver Quick Reference

@@ -18,6 +18,13 @@ Netdata lets you reference secret values in collector configs instead of storing

18 | Command | `${cmd:/absolute/path/to/command args}` | Secrets returned by a trusted local command | The command path must be absolute. Netdata uses a 10-second timeout. |

19 | Secretstore | `${store:<kind>:<name>:<operand>}` | Secrets stored in remote backends such as Vault, AWS, Azure, or GCP | Configure the secretstore first, then reference it from collector configs. |

21 +## Choosing a Resolver

22 +

23 +- Use `${env:...}` or `${file:...}` for simple setups where secrets are already available locally on the Netdata host.

24 +- Use `${cmd:...}` when you need dynamic secret retrieval via a trusted local command, such as 1Password CLI or a custom script.

25 +- Use `${store:...}` when your organization manages secrets centrally in a cloud provider or Vault and you want Netdata to pull from that source directly.

26 +- You can use different resolver types across different collectors, different jobs within the same collector, or even within the same configuration value. See [Mixing resolver types](#mixing-resolver-types).

27 +

28 ## Environment Variables

30 Use `${env:VARIABLE_NAME}` to read a secret from the Netdata process environment.

@@ -44,6 +51,8 @@ jobs:

51 - The file path must be absolute.

52 - Netdata trims leading and trailing whitespace from the file contents.

53 - The file must exist on the Netdata host and be readable by the `netdata` user.

54 +- **Docker Secrets**: Docker mounts secrets as files under `/run/secrets/` inside the container. Use `${file:/run/secrets/<secret-name>}` to read them.

55 +- **Kubernetes Secrets**: If you mount Kubernetes Secrets as volume files in the Netdata pod, reference them with `${file:/path/to/mounted/secret}`.

57 ## Commands

@@ -114,6 +123,32 @@ File-based secretstores are loaded at agent startup. If you edit these files, re

123

124 :::

125

126 +If the `/etc/netdata/go.d/ss/` directory does not exist, create it:

127 +

128 +```bash

129 +sudo mkdir -p /etc/netdata/go.d/ss

130 +sudo chown netdata:netdata /etc/netdata/go.d/ss

131 +sudo chmod 0750 /etc/netdata/go.d/ss

132 +```

133 +

134 +Secretstore configuration files may contain sensitive values such as tokens or client secrets. Restrict directory and file permissions to the `netdata` user.

135 +

136 +### Multiple Secretstores

137 +

138 +Each secretstore config file can contain multiple `jobs` entries, each with a unique store name. You can use different secretstore backends simultaneously. For example, you might configure a Vault store for database credentials and an AWS Secrets Manager store for API keys, then reference each one using its `${store:<kind>:<name>:<operand>}` syntax in the relevant collector configs.

139 +

140 +### Mixing Resolver Types

141 +

142 +You can mix different resolver types in the same configuration value or the same config file. For example, you might read the username from an environment variable and the password from a secretstore:

143 +

144 +```yaml

145 +jobs:

146 + - name: mysql_prod

147 + dsn: "${env:MYSQL_USER}:${store:vault:vault_prod:secret/data/netdata/mysql#password}@tcp(127.0.0.1:3306)/"

148 +```

149 +

150 +Different jobs within the same collector config file can also use different resolver types.

151 +

152 ## Supported Secretstore Backends

153

154 Use the backend README for provider-specific authentication, operand rules, configuration examples, and troubleshooting.

@@ -137,6 +172,7 @@ Use the backend README for provider-specific authentication, operand rules, conf

172

173 - Prefer secret references over plain-text credentials in collector configs.

174 - Prefer platform-native identity modes for production when a backend supports them, such as instance roles, managed identities, or metadata-based credentials.

175 +- Secretstore configuration values (such as tokens and client secrets) also support `${env:...}`, `${file:...}`, and `${cmd:...}` resolvers. Use them to avoid storing backend credentials in plain text. Note that `${store:...}` references are not supported inside secretstore configurations.

176 - Keep local secret material readable only by the `netdata` user, including token files, service account files, and any files used with `${file:...}`.

177 - Use `${cmd:...}` only with trusted local commands and absolute paths.

178

src/go/plugin/agent/secrets/secretstore/backends/aws/integrations/aws-sm.md

+29 -20

@@ -20,9 +20,9 @@ Kind: aws-sm

21 ## Overview

23 -Use AWS Secrets Manager as a secretstore backend when you want Netdata collectors to read secrets from AWS at runtime instead of storing them in plain text in collector configuration files.

23 +Netdata can pull collector credentials directly from AWS Secrets Manager at runtime, so you never store passwords or tokens in plain-text configuration files.

25 -This page covers AWS Secrets Manager specific setup. For the shared resolver workflow and syntax, see [Secrets Management](https://github.com/netdata/netdata/blob/master/src/collectors/SECRETS.md).

25 +This page covers AWS Secrets Manager 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).

28 ### Limitations

@@ -54,7 +54,7 @@ For production on AWS, prefer `ecs` or `imds` over `env` so credentials are supp

55 #### Allow access to Secrets Manager

57 -The AWS identity used by this secretstore must be allowed to read the secrets you reference in collector configs in the configured `region`.

57 +The AWS identity used by this secretstore must have the `secretsmanager:GetSecretValue` permission on the secrets you reference in collector configs. Scope the IAM policy to only the secret ARNs Netdata needs.

60 #### Plan for file-based changes

@@ -75,7 +75,7 @@ The following options can be defined for this secretstore backend.

76 |:-----|:------------|:--------|:---------:|

77 | [auth_mode](#option-auth-mode) | How Netdata obtains AWS credentials. | env | yes |

78 -| region | AWS region used for Secrets Manager requests. | | yes |

78 +| region | AWS region used for Secrets Manager requests. There is no automatic region detection — you must always set this explicitly. | | yes |

80 <a id="option-auth-mode"></a>

81 ##### auth_mode

@@ -148,13 +148,13 @@ jobs:

148

149 ## Use in collector configs

150

151 -Reference AWS Secrets Manager secrets from collector configs with the `aws-sm` secretstore kind.

151 +Use the `${store:aws-sm:...}` syntax to reference AWS Secrets Manager secrets in any string field of a collector configuration file.

152

153

154 The operand is `secret-name` or `secret-name#key`.

155

156 -- Use `secret-name` to return the whole `SecretString`.

157 -- Use `secret-name#key` to read one top-level field from a JSON `SecretString`.

156 +- Use `secret-name` to return the whole `SecretString`, for example: `${store:aws-sm:aws_prod:netdata/mysql/password}`.

157 +- Use `secret-name#key` to read one top-level field from a JSON `SecretString`, for example: `${store:aws-sm:aws_prod:netdata/mysql#password}`.

158 - If you use `#key`, Netdata parses the secret value as JSON. Secret resolution fails if the value is not valid JSON or if the key does not exist.

159 - Nested paths such as `parent.child` are not interpreted as nested JSON lookups.

160

@@ -168,28 +168,37 @@ ${store:aws-sm:<store-name>:<secret-name[#key]>}

168 - `<secret-name[#key]>`: The AWS Secrets Manager secret name, optionally followed by `#key` to read one field from a JSON `SecretString`.

169

170 ### Examples

171 -#### Whole secret value

171 +#### MySQL collector with password from AWS Secrets Manager

172

173 -Return the full `SecretString` stored under the `netdata/mysql/password` secret.

173 +This example configures a MySQL collector job in `/etc/netdata/go.d/mysql.conf`.

174 +The password in the DSN connection string is not stored in plain text. Instead,

175 +`${store:aws-sm:aws_prod:netdata/mysql#password}` tells Netdata to fetch the secret

176 +named `netdata/mysql` from the `aws_prod` store, extract the `password` field from

177 +its JSON value, and substitute it into the DSN at runtime.

178

175 -```text

176 -${store:aws-sm:aws_prod:netdata/mysql/password}

177 -```

178 -#### JSON field from SecretString

179

180 -Read the `password` field from a JSON `SecretString`.

180 +```yaml

181 +# /etc/netdata/go.d/mysql.conf

182 +jobs:

183 + - name: mysql_prod

184 + dsn: "netdata:${store:aws-sm:aws_prod:netdata/mysql#password}@tcp(127.0.0.1:3306)/"

185

182 -```text

183 -${store:aws-sm:aws_prod:netdata/mysql#password}

186 ```

185 -#### Collector config example

187 +#### Elasticsearch collector with HTTP basic auth

188 +

189 +This example configures an Elasticsearch collector job in `/etc/netdata/go.d/elasticsearch.conf`.

190 +The `password` field uses a secret reference instead of a plain-text password. Netdata fetches

191 +the secret named `netdata/elasticsearch/password` from the `aws_prod` store and substitutes

192 +its full value into the `password` field at runtime.

193

187 -Use an AWS-stored password in a collector DSN.

194

195 ```yaml

196 +# /etc/netdata/go.d/elasticsearch.conf

197 jobs:

191 - - name: mysql_prod

192 - dsn: "netdata:${store:aws-sm:aws_prod:netdata/mysql#password}@tcp(127.0.0.1:3306)/"

198 + - name: es_prod

199 + url: https://elasticsearch.example.com:9200

200 + username: netdata

201 + password: "${store:aws-sm:aws_prod:netdata/elasticsearch/password}"

202

203 ```

204

src/go/plugin/agent/secrets/secretstore/backends/aws/metadata.yaml

+28 -18

@@ -14,9 +14,9 @@ keywords:

14 - 'aws secrets manager'

15 overview:

16 description: |

17 - Use AWS Secrets Manager as a secretstore backend when you want Netdata collectors to read secrets from AWS at runtime instead of storing them in plain text in collector configuration files.

17 + Netdata can pull collector credentials directly from AWS Secrets Manager at runtime, so you never store passwords or tokens in plain-text configuration files.

19 - This page covers AWS Secrets Manager specific setup. For the shared resolver workflow and syntax, see [Secrets Management](/src/collectors/SECRETS.md).

19 + This page covers AWS Secrets Manager 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 existing secrets from AWS Secrets Manager. It does not create, rotate, or manage those secrets. If you use `secret-name#key`, the secret value must be stored as a JSON `SecretString`.

22 setup:

@@ -33,7 +33,7 @@ setup:

33 For production on AWS, prefer `ecs` or `imds` over `env` so credentials are supplied by the platform instead of being stored in the Netdata service environment.

34 - title: 'Allow access to Secrets Manager'

35 description: |

36 - The AWS identity used by this secretstore must be allowed to read the secrets you reference in collector configs in the configured `region`.

36 + The AWS identity used by this secretstore must have the `secretsmanager:GetSecretValue` permission on the secrets you reference in collector configs. Scope the IAM policy to only the secret ARNs Netdata needs.

37 - title: 'Plan for file-based changes'

38 description: |

39 If you edit `/etc/netdata/go.d/ss/aws-sm.conf`, restart the Netdata Agent to load the updated secretstore definition.

@@ -59,7 +59,7 @@ setup:

60 For production on AWS, prefer `ecs` or `imds` when Netdata runs on ECS or EC2. Use `env` when you intentionally manage credentials in the Netdata service environment.

61 - name: 'region'

62 - description: 'AWS region used for Secrets Manager requests.'

62 + description: 'AWS region used for Secrets Manager requests. There is no automatic region detection — you must always set this explicitly.'

63 default_value: ''

64 required: true

65 examples:

@@ -90,7 +90,7 @@ setup:

90 region: us-east-1

91 collector_configs:

92 description: |

93 - Reference AWS Secrets Manager secrets from collector configs with the `aws-sm` secretstore kind.

93 + Use the `${store:aws-sm:...}` syntax to reference AWS Secrets Manager secrets in any string field of a collector configuration file.

94 summary:

95 operand_format: 'secret-name[#key]'

96 example_operand: 'netdata/mysql#password'

@@ -98,8 +98,8 @@ collector_configs:

98 description: |

99 The operand is `secret-name` or `secret-name#key`.

100

101 - - Use `secret-name` to return the whole `SecretString`.

102 - - Use `secret-name#key` to read one top-level field from a JSON `SecretString`.

101 + - Use `secret-name` to return the whole `SecretString`, for example: `${store:aws-sm:aws_prod:netdata/mysql/password}`.

102 + - Use `secret-name#key` to read one top-level field from a JSON `SecretString`, for example: `${store:aws-sm:aws_prod:netdata/mysql#password}`.

103 - If you use `#key`, Netdata parses the secret value as JSON. Secret resolution fails if the value is not valid JSON or if the key does not exist.

104 - Nested paths such as `parent.child` are not interpreted as nested JSON lookups.

105 syntax: '${store:aws-sm:<store-name>:<secret-name[#key]>}'

@@ -113,21 +113,31 @@ collector_configs:

113 description: 'The AWS Secrets Manager secret name, optionally followed by `#key` to read one field from a JSON `SecretString`.'

114 examples:

115 list:

116 - - name: 'Whole secret value'

117 - description: 'Return the full `SecretString` stored under the `netdata/mysql/password` secret.'

118 - language: 'text'

119 - content: '${store:aws-sm:aws_prod:netdata/mysql/password}'

120 - - name: 'JSON field from SecretString'

121 - description: 'Read the `password` field from a JSON `SecretString`.'

122 - language: 'text'

123 - content: '${store:aws-sm:aws_prod:netdata/mysql#password}'

124 - - name: 'Collector config example'

125 - description: 'Use an AWS-stored password in a collector DSN.'

126 - language: 'yaml'

116 + - name: 'MySQL collector with password from AWS Secrets Manager'

117 + description: |

118 + This example configures a MySQL collector job in `/etc/netdata/go.d/mysql.conf`.

119 + The password in the DSN connection string is not stored in plain text. Instead,

120 + `${store:aws-sm:aws_prod:netdata/mysql#password}` tells Netdata to fetch the secret

121 + named `netdata/mysql` from the `aws_prod` store, extract the `password` field from

122 + its JSON value, and substitute it into the DSN at runtime.

123 content: |

124 + # /etc/netdata/go.d/mysql.conf

125 jobs:

126 - name: mysql_prod

127 dsn: "netdata:${store:aws-sm:aws_prod:netdata/mysql#password}@tcp(127.0.0.1:3306)/"

128 + - name: 'Elasticsearch collector with HTTP basic auth'

129 + description: |

130 + This example configures an Elasticsearch collector job in `/etc/netdata/go.d/elasticsearch.conf`.

131 + The `password` field uses a secret reference instead of a plain-text password. Netdata fetches

132 + the secret named `netdata/elasticsearch/password` from the `aws_prod` store and substitutes

133 + its full value into the `password` field at runtime.

134 + content: |

135 + # /etc/netdata/go.d/elasticsearch.conf

136 + jobs:

137 + - name: es_prod

138 + url: https://elasticsearch.example.com:9200

139 + username: netdata

140 + password: "${store:aws-sm:aws_prod:netdata/elasticsearch/password}"

141 troubleshooting:

142 problems:

143 list:

src/go/plugin/agent/secrets/secretstore/backends/azure/integrations/azure-kv.md

+41 -13

@@ -20,9 +20,9 @@ Kind: azure-kv

21 ## Overview

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

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

25 -This page covers Azure Key Vault specific setup. For the shared resolver workflow and syntax, see [Secrets Management](https://github.com/netdata/netdata/blob/master/src/collectors/SECRETS.md).

25 +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).

28 ### Limitations

@@ -54,7 +54,7 @@ Prefer `managed_identity` for production on Azure when Netdata runs on an Azure

55 #### Allow secret read access

57 -The Azure identity used by this secretstore must be allowed to read secret values from the target vaults.

57 +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`.

60 #### Plan for file-based changes

@@ -127,6 +127,20 @@ jobs:

127 client_id: 00000000-0000-0000-0000-000000000000

128 client_secret: your-client-secret

129

130 +```

131 +###### Service principal with credentials from environment

132 +

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

134 +

135 +```yaml

136 +jobs:

137 + - name: azure_prod

138 + mode: service_principal

139 + mode_service_principal:

140 + tenant_id: "${env:AZURE_TENANT_ID}"

141 + client_id: "${env:AZURE_CLIENT_ID}"

142 + client_secret: "${env:AZURE_CLIENT_SECRET}"

143 +

144 ```

145 ###### Managed identity

146

@@ -154,10 +168,10 @@ jobs:

168

169 ## Use in collector configs

170

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

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

172

173

160 -The operand is `vault-name/secret-name`.

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

175

176 Netdata requests the latest secret value from `https://<vault-name>.vault.azure.net/secrets/<secret-name>?api-version=7.4`.

177 Both `vault-name` and `secret-name` must use only letters, numbers, and hyphens.

@@ -172,23 +186,37 @@ ${store:azure-kv:<store-name>:<vault-name/secret-name>}

186 - `<vault-name/secret-name>`: The Azure Key Vault name and the secret name, separated by `/`.

187

188 ### Examples

175 -#### Secret reference

189 +#### MySQL collector with password from Azure Key Vault

190

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

191 +This example configures a MySQL collector job in `/etc/netdata/go.d/mysql.conf`.

192 +The password in the DSN connection string is not stored in plain text. Instead,

193 +`${store:azure-kv:azure_prod:my-keyvault/mysql-password}` tells Netdata to fetch

194 +the secret named `mysql-password` from the `my-keyvault` vault using the `azure_prod`

195 +store, and substitute its value into the DSN at runtime.

196

179 -```text

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

181 -```

182 -#### Collector config example

183 -

184 -Use an Azure Key Vault secret in a collector DSN.

197

198 ```yaml

199 +# /etc/netdata/go.d/mysql.conf

200 jobs:

201 - name: mysql_prod

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

203

204 ```

205 +#### PostgreSQL collector with password from Azure Key Vault

206 +

207 +This example configures a PostgreSQL collector job in `/etc/netdata/go.d/postgres.conf`.

208 +The `password` field uses a secret reference instead of a plain-text value. Netdata fetches

209 +the secret named `postgres-password` from the `my-keyvault` vault and substitutes its value

210 +into the `password` field at runtime.

211 +

212 +

213 +```yaml

214 +# /etc/netdata/go.d/postgres.conf

215 +jobs:

216 + - name: postgres_prod

217 + dsn: "postgresql://netdata:${store:azure-kv:azure_prod:my-keyvault/postgres-password}@localhost:5432/postgres"

218 +

219 +```

220

221

222 ## Troubleshooting

src/go/plugin/agent/secrets/secretstore/backends/azure/metadata.yaml

+34 -12

@@ -14,9 +14,9 @@ keywords:

14 - 'azure key vault'

15 overview:

16 description: |

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

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.

19 - This page covers Azure Key Vault specific setup. For the shared resolver workflow and syntax, see [Secrets Management](/src/collectors/SECRETS.md).

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:

@@ -33,7 +33,7 @@ setup:

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.

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.

@@ -93,6 +93,16 @@ setup:

93 tenant_id: 00000000-0000-0000-0000-000000000000

94 client_id: 00000000-0000-0000-0000-000000000000

95 client_secret: your-client-secret

96 + - name: 'Service principal with credentials from environment'

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

98 + config: |

99 + jobs:

100 + - name: azure_prod

101 + mode: service_principal

102 + mode_service_principal:

103 + tenant_id: "${env:AZURE_TENANT_ID}"

104 + client_id: "${env:AZURE_CLIENT_ID}"

105 + client_secret: "${env:AZURE_CLIENT_SECRET}"

106 - name: 'Managed identity'

107 description: 'Use the managed identity attached to the Azure resource running Netdata.'

108 config: |

@@ -109,13 +119,13 @@ setup:

119 mode: default

120 collector_configs:

121 description: |

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

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

123 summary:

124 operand_format: 'vault-name/secret-name'

125 example_operand: 'my-keyvault/mysql-password'

126 format:

127 description: |

118 - The operand is `vault-name/secret-name`.

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

129

130 Netdata requests the latest secret value from `https://<vault-name>.vault.azure.net/secrets/<secret-name>?api-version=7.4`.

131 Both `vault-name` and `secret-name` must use only letters, numbers, and hyphens.

@@ -130,17 +140,29 @@ collector_configs:

140 description: 'The Azure Key Vault name and the secret name, separated by `/`.'

141 examples:

142 list:

133 - - name: 'Secret reference'

134 - description: 'Read the latest value of the `mysql-password` secret from the `my-keyvault` vault.'

135 - language: 'text'

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

137 - - name: 'Collector config example'

138 - description: 'Use an Azure Key Vault secret in a collector DSN.'

139 - language: 'yaml'

143 + - name: 'MySQL collector with password from Azure Key Vault'

144 + description: |

145 + This example configures a MySQL collector job in `/etc/netdata/go.d/mysql.conf`.

146 + The password in the DSN connection string is not stored in plain text. Instead,

147 + `${store:azure-kv:azure_prod:my-keyvault/mysql-password}` tells Netdata to fetch

148 + the secret named `mysql-password` from the `my-keyvault` vault using the `azure_prod`

149 + store, and substitute its value into the DSN at runtime.

150 content: |

151 + # /etc/netdata/go.d/mysql.conf

152 jobs:

153 - name: mysql_prod

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

155 + - name: 'PostgreSQL collector with password from Azure Key Vault'

156 + description: |

157 + This example configures a PostgreSQL collector job in `/etc/netdata/go.d/postgres.conf`.

158 + The `password` field uses a secret reference instead of a plain-text value. Netdata fetches

159 + the secret named `postgres-password` from the `my-keyvault` vault and substitutes its value

160 + into the `password` field at runtime.

161 + content: |

162 + # /etc/netdata/go.d/postgres.conf

163 + jobs:

164 + - name: postgres_prod

165 + dsn: "postgresql://netdata:${store:azure-kv:azure_prod:my-keyvault/postgres-password}@localhost:5432/postgres"

166 troubleshooting:

167 problems:

168 list:

src/go/plugin/agent/secrets/secretstore/backends/gcp/integrations/gcp-sm.md

+32 -22

@@ -20,14 +20,14 @@ Kind: gcp-sm

21 ## Overview

23 -Use Google Secret Manager as a secretstore backend when you want Netdata collectors to read secrets from GCP at runtime instead of storing them in plain text in collector configuration files.

23 +Netdata can pull collector credentials directly from Google Secret Manager at runtime, so you never store passwords or tokens in plain-text configuration files.

25 -This page covers Google Secret Manager specific setup. For the shared resolver workflow and syntax, see [Secrets Management](https://github.com/netdata/netdata/blob/master/src/collectors/SECRETS.md).

25 +This page covers Google Secret Manager 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).

28 ### Limitations

30 -If you omit the version in the operand, Netdata reads the `latest` secret version automatically.

30 +Netdata reads existing secrets from Google Secret Manager. It does not create, rotate, or manage those secrets. If you omit the version in the operand, Netdata reads the `latest` secret version automatically.

33 ## Setup

@@ -58,7 +58,7 @@ If you use `service_account_file`, the JSON file contains a private key. Keep it

59 #### Allow Secret Manager access

61 -The Google identity used by this secretstore must be allowed to access the referenced secrets in Google Secret Manager.

61 +The Google identity used by this secretstore must have the `roles/secretmanager.secretAccessor` IAM role on the secrets you reference from collector configs. Do not use broader roles like `roles/secretmanager.admin`.

64 #### Plan for file-based changes

@@ -79,14 +79,14 @@ The following options can be defined for this secretstore backend.

80 |:------|:-----|:------------|:--------|:---------:|

82 -| **Service Account File** | mode_service_account_file.path | Path to a service account JSON file. Required when `mode` is `service_account_file`. The file contains a private key and should be readable only by the `netdata` user or another tightly scoped owner. | | yes |

82 +| **Service Account File** | mode_service_account_file.path | Absolute path to a service account JSON file. Required when `mode` is `service_account_file`. The file contains a private key and should be readable only by the `netdata` user or another tightly scoped owner. | | yes |

84 <a id="option-mode"></a>

85 ##### mode

87 Supported values:

89 -- `metadata`: get an access token from the Google metadata server.

89 +- `metadata`: get an access token from the Google metadata server. This works in GCE, GKE (with Workload Identity configured), Cloud Run, and other Google Cloud environments where the metadata server is reachable.

90 - `service_account_file`: use a local service account JSON file.

92 Prefer `metadata` for production when Netdata runs in a supported Google Cloud environment. Use `service_account_file` when you need explicit credentials or when the metadata server is not available.

@@ -140,14 +140,15 @@ jobs:

140

141 ## Use in collector configs

142

143 -Reference Google Secret Manager secrets from collector configs with the `gcp-sm` secretstore kind.

143 +Use the `${store:gcp-sm:...}` syntax to reference Google Secret Manager secrets in any string field of a collector configuration file.

144

145

146 The operand is `project/secret` or `project/secret/version`.

147

148 -If you omit the version, Netdata uses `latest`.

148 +- Use `project/secret` to read the latest version, for example: `${store:gcp-sm:gcp_prod:my-project/mysql-password}`.

149 +- Use `project/secret/version` to read a specific version, for example: `${store:gcp-sm:gcp_prod:my-project/mysql-password/3}`.

150 +

151 Project IDs may use letters, numbers, `.`, `_`, `:`, or `-`. Secret names and versions may use letters, numbers, `_`, or `-`.

150 -When you specify a version, use the version name accepted by Secret Manager, such as `3`.

152

153

154 ```text

@@ -159,28 +160,37 @@ ${store:gcp-sm:<store-name>:<project/secret[/version]>}

160 - `<project/secret[/version]>`: The Google Cloud project ID, secret name, and optional version.

161

162 ### Examples

162 -#### Latest version

163 +#### MySQL collector with password from Google Secret Manager

164

164 -Read the latest version of the `mysql-password` secret from the `my-project` project.

165 +This example configures a MySQL collector job in `/etc/netdata/go.d/mysql.conf`.

166 +The password in the DSN connection string is not stored in plain text. Instead,

167 +`${store:gcp-sm:gcp_prod:my-project/mysql-password}` tells Netdata to fetch the

168 +latest version of the `mysql-password` secret from the `my-project` project using

169 +the `gcp_prod` store, and substitute its value into the DSN at runtime.

170

166 -```text

167 -${store:gcp-sm:gcp_prod:my-project/mysql-password}

168 -```

169 -#### Specific version

171

171 -Read version `3` of the `mysql-password` secret.

172 +```yaml

173 +# /etc/netdata/go.d/mysql.conf

174 +jobs:

175 + - name: mysql_prod

176 + dsn: "netdata:${store:gcp-sm:gcp_prod:my-project/mysql-password}@tcp(127.0.0.1:3306)/"

177

173 -```text

174 -${store:gcp-sm:gcp_prod:my-project/mysql-password/3}

178 ```

176 -#### Collector config example

179 +#### HTTP check collector with password from Google Secret Manager

180 +

181 +This example configures an HTTP check collector job in `/etc/netdata/go.d/httpcheck.conf`.

182 +The `password` field uses a secret reference instead of a plain-text value. Netdata fetches

183 +the `api-password` secret from the `my-project` project and substitutes its value into the

184 +`password` field at runtime.

185

178 -Use a Google Secret Manager secret in a collector DSN.

186

187 ```yaml

188 +# /etc/netdata/go.d/httpcheck.conf

189 jobs:

182 - - name: mysql_prod

183 - dsn: "netdata:${store:gcp-sm:gcp_prod:my-project/mysql-password}@tcp(127.0.0.1:3306)/"

190 + - name: internal_api

191 + url: https://api.example.com/health

192 + username: netdata

193 + password: "${store:gcp-sm:gcp_prod:my-project/api-password}"

194

195 ```

196

src/go/plugin/agent/secrets/secretstore/backends/gcp/metadata.yaml

+31 -20

@@ -14,11 +14,11 @@ keywords:

14 - 'google secret manager'

15 overview:

16 description: |

17 - Use Google Secret Manager as a secretstore backend when you want Netdata collectors to read secrets from GCP at runtime instead of storing them in plain text in collector configuration files.

17 + Netdata can pull collector credentials directly from Google Secret Manager at runtime, so you never store passwords or tokens in plain-text configuration files.

19 - This page covers Google Secret Manager specific setup. For the shared resolver workflow and syntax, see [Secrets Management](/src/collectors/SECRETS.md).

19 + This page covers Google Secret Manager 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 - If you omit the version in the operand, Netdata reads the `latest` secret version automatically.

21 + Netdata reads existing secrets from Google Secret Manager. It does not create, rotate, or manage those secrets. If you omit the version in the operand, Netdata reads the `latest` secret version automatically.

22 setup:

23 prerequisites:

24 list:

@@ -35,7 +35,7 @@ setup:

35 If you use `service_account_file`, the JSON file contains a private key. Keep it on the Netdata host, make it readable by the `netdata` user, and restrict access as tightly as possible. A common setup is `chmod 0600` with ownership that allows the `netdata` user to read the file.

36 - title: 'Allow Secret Manager access'

37 description: |

38 - The Google identity used by this secretstore must be allowed to access the referenced secrets in Google Secret Manager.

38 + The Google identity used by this secretstore must have the `roles/secretmanager.secretAccessor` IAM role on the secrets you reference from collector configs. Do not use broader roles like `roles/secretmanager.admin`.

39 - title: 'Plan for file-based changes'

40 description: |

41 If you edit `/etc/netdata/go.d/ss/gcp-sm.conf`, restart the Netdata Agent to load the updated secretstore definition.

@@ -55,13 +55,13 @@ setup:

55 detailed_description: |

56 Supported values:

58 - - `metadata`: get an access token from the Google metadata server.

58 + - `metadata`: get an access token from the Google metadata server. This works in GCE, GKE (with Workload Identity configured), Cloud Run, and other Google Cloud environments where the metadata server is reachable.

59 - `service_account_file`: use a local service account JSON file.

61 Prefer `metadata` for production when Netdata runs in a supported Google Cloud environment. Use `service_account_file` when you need explicit credentials or when the metadata server is not available.

62 - name: 'mode_service_account_file.path'

63 group: 'Service Account File'

64 - description: 'Path to a service account JSON file. Required when `mode` is `service_account_file`. The file contains a private key and should be readable only by the `netdata` user or another tightly scoped owner.'

64 + description: 'Absolute path to a service account JSON file. Required when `mode` is `service_account_file`. The file contains a private key and should be readable only by the `netdata` user or another tightly scoped owner.'

65 default_value: ''

66 required: true

67 examples:

@@ -85,7 +85,7 @@ setup:

85 path: /etc/netdata/gcp-service-account.json

86 collector_configs:

87 description: |

88 - Reference Google Secret Manager secrets from collector configs with the `gcp-sm` secretstore kind.

88 + Use the `${store:gcp-sm:...}` syntax to reference Google Secret Manager secrets in any string field of a collector configuration file.

89 summary:

90 operand_format: 'project/secret[/version]'

91 example_operand: 'my-project/mysql-password'

@@ -93,9 +93,10 @@ collector_configs:

93 description: |

94 The operand is `project/secret` or `project/secret/version`.

96 - If you omit the version, Netdata uses `latest`.

96 + - Use `project/secret` to read the latest version, for example: `${store:gcp-sm:gcp_prod:my-project/mysql-password}`.

97 + - Use `project/secret/version` to read a specific version, for example: `${store:gcp-sm:gcp_prod:my-project/mysql-password/3}`.

98 +

99 Project IDs may use letters, numbers, `.`, `_`, `:`, or `-`. Secret names and versions may use letters, numbers, `_`, or `-`.

98 - When you specify a version, use the version name accepted by Secret Manager, such as `3`.

100 syntax: '${store:gcp-sm:<store-name>:<project/secret[/version]>}'

101 parts:

102 list:

@@ -107,21 +108,31 @@ collector_configs:

108 description: 'The Google Cloud project ID, secret name, and optional version.'

109 examples:

110 list:

110 - - name: 'Latest version'

111 - description: 'Read the latest version of the `mysql-password` secret from the `my-project` project.'

112 - language: 'text'

113 - content: '${store:gcp-sm:gcp_prod:my-project/mysql-password}'

114 - - name: 'Specific version'

115 - description: 'Read version `3` of the `mysql-password` secret.'

116 - language: 'text'

117 - content: '${store:gcp-sm:gcp_prod:my-project/mysql-password/3}'

118 - - name: 'Collector config example'

119 - description: 'Use a Google Secret Manager secret in a collector DSN.'

120 - language: 'yaml'

111 + - name: 'MySQL collector with password from Google Secret Manager'

112 + description: |

113 + This example configures a MySQL collector job in `/etc/netdata/go.d/mysql.conf`.

114 + The password in the DSN connection string is not stored in plain text. Instead,

115 + `${store:gcp-sm:gcp_prod:my-project/mysql-password}` tells Netdata to fetch the

116 + latest version of the `mysql-password` secret from the `my-project` project using

117 + the `gcp_prod` store, and substitute its value into the DSN at runtime.

118 content: |

119 + # /etc/netdata/go.d/mysql.conf

120 jobs:

121 - name: mysql_prod

122 dsn: "netdata:${store:gcp-sm:gcp_prod:my-project/mysql-password}@tcp(127.0.0.1:3306)/"

123 + - name: 'HTTP check collector with password from Google Secret Manager'

124 + description: |

125 + This example configures an HTTP check collector job in `/etc/netdata/go.d/httpcheck.conf`.

126 + The `password` field uses a secret reference instead of a plain-text value. Netdata fetches

127 + the `api-password` secret from the `my-project` project and substitutes its value into the

128 + `password` field at runtime.

129 + content: |

130 + # /etc/netdata/go.d/httpcheck.conf

131 + jobs:

132 + - name: internal_api

133 + url: https://api.example.com/health

134 + username: netdata

135 + password: "${store:gcp-sm:gcp_prod:my-project/api-password}"

136 troubleshooting:

137 problems:

138 list:

src/go/plugin/agent/secrets/secretstore/backends/vault/integrations/vault.md

+58 -21

@@ -20,14 +20,14 @@ Kind: vault

21 ## Overview

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

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

25 -This page covers Vault specific setup. For the shared resolver workflow and syntax, see [Secrets Management](https://github.com/netdata/netdata/blob/master/src/collectors/SECRETS.md).

25 +This page covers 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).

28 ### Limitations

30 -Netdata reads existing secrets from Vault. It does not create or renew Vault tokens. If the configured token expires or becomes invalid, secret resolution fails until Netdata can read a valid token again. For KV v2 secrets, Netdata does not add `/data/` to the path automatically.

30 +Netdata reads existing secrets from Vault. It does not create or renew Vault tokens. If the configured token expires or becomes invalid, secret resolution fails until Netdata can read a valid token again. If you use `token_file` mode, Netdata re-reads the file on every secret resolution, so an external process (e.g. Vault Agent, a cron job) can renew the token by writing to the file. For KV v2 secrets, Netdata does not add `/data/` to the path automatically.

33 ## Setup

@@ -58,7 +58,7 @@ Prefer `token_file` for production so the Vault token is not embedded directly i

59 #### Allow access to the referenced secret paths

61 -The Vault token used by this secretstore must be allowed to read the paths you reference from collector configs.

61 +The Vault token used by this secretstore must have a policy that grants `read` capability on the paths you reference from collector configs. Scope the policy to only the paths Netdata needs.

64 #### Plan for file-based changes

@@ -135,13 +135,24 @@ jobs:

135 mode_token:

136 token: your-vault-token

137 addr: https://vault.example

138 - namespace: admin

139 - tls_skip_verify: false

138 +

139 +```

140 +###### Token from environment variable

141 +

142 +Use a `${env:...}` resolver for the Vault token to avoid storing it in plain text in the secretstore config file.

143 +

144 +```yaml

145 +jobs:

146 + - name: vault_prod

147 + mode: token

148 + mode_token:

149 + token: "${env:VAULT_TOKEN}"

150 + addr: https://vault.example

151

152 ```

153 ###### Token file

154

144 -Read the Vault token from a local file on the Netdata host.

155 +Read the Vault token from a local file on the Netdata host. Netdata re-reads the file on every secret resolution, so an external process can renew the token by writing to this file.

156

157 ```yaml

158 jobs:

@@ -152,11 +163,25 @@ jobs:

163 addr: https://vault.example

164

165 ```

166 +###### Vault Enterprise with namespace

167 +

168 +Connect to a Vault Enterprise server using a specific namespace.

169 +

170 +```yaml

171 +jobs:

172 + - name: vault_enterprise

173 + mode: token_file

174 + mode_token_file:

175 + path: /var/lib/netdata/vault.token

176 + addr: https://vault.example

177 + namespace: admin

178 +

179 +```

180

181

182 ## Use in collector configs

183

159 -Reference Vault secrets from collector configs with the `vault` secretstore kind.

184 +Use the `${store:vault:...}` syntax to reference Vault secrets in any string field of a collector configuration file.

185

186

187 The operand is `path#key`.

@@ -164,6 +189,9 @@ The operand is `path#key`.

189 Netdata sends the path to Vault as `/v1/<path>` exactly as you provide it. For KV v2 secrets, include `/data/` in the path yourself.

190 The `path` must not be empty and must not contain `..`, `?`, or `#`.

191

192 +- KV v1 example: `${store:vault:vault_prod:secret/netdata/mysql#password}`.

193 +- KV v2 example: `${store:vault:vault_prod:secret/data/netdata/mysql#password}` — note the `/data/` segment, Netdata does not add it automatically.

194 +

195

196 ```text

197 ${store:vault:<store-name>:<path#key>}

@@ -174,28 +202,37 @@ ${store:vault:<store-name>:<path#key>}

202 - `<path#key>`: The Vault API path and the secret field name, separated by `#`.

203

204 ### Examples

177 -#### KV v1 secret

205 +#### MySQL collector with password from Vault

206

179 -Read the `password` field from a KV v1 secret.

207 +This example configures a MySQL collector job in `/etc/netdata/go.d/mysql.conf`.

208 +The password in the DSN connection string is not stored in plain text. Instead,

209 +`${store:vault:vault_prod:secret/data/netdata/mysql#password}` tells Netdata to

210 +read the KV v2 secret at `secret/data/netdata/mysql` from the `vault_prod` store,

211 +extract the `password` field from the response, and substitute it into the DSN at runtime.

212

181 -```text

182 -${store:vault:vault_prod:secret/netdata/mysql#password}

183 -```

184 -#### KV v2 secret

213

186 -Read the `password` field from a KV v2 secret. Include `/data/` in the path.

214 +```yaml

215 +# /etc/netdata/go.d/mysql.conf

216 +jobs:

217 + - name: mysql_prod

218 + dsn: "netdata:${store:vault:vault_prod:secret/data/netdata/mysql#password}@tcp(127.0.0.1:3306)/"

219

188 -```text

189 -${store:vault:vault_prod:secret/data/netdata/mysql#password}

220 ```

191 -#### Collector config example

221 +#### Elasticsearch collector with HTTP basic auth from Vault

222 +

223 +This example configures an Elasticsearch collector job in `/etc/netdata/go.d/elasticsearch.conf`.

224 +The `password` field uses a secret reference instead of a plain-text value. Netdata reads the

225 +KV v2 secret at `secret/data/netdata/elasticsearch` from the `vault_prod` store, extracts the

226 +`password` field, and substitutes it at runtime.

227

193 -Use a Vault secret in a collector DSN.

228

229 ```yaml

230 +# /etc/netdata/go.d/elasticsearch.conf

231 jobs:

197 - - name: mysql_prod

198 - dsn: "netdata:${store:vault:vault_prod:secret/data/netdata/mysql#password}@tcp(127.0.0.1:3306)/"

232 + - name: es_prod

233 + url: https://elasticsearch.example.com:9200

234 + username: netdata

235 + password: "${store:vault:vault_prod:secret/data/netdata/elasticsearch#password}"

236

237 ```

238

src/go/plugin/agent/secrets/secretstore/backends/vault/metadata.yaml

+49 -19

@@ -13,11 +13,11 @@ keywords:

13 - 'hashicorp vault'

14 overview:

15 description: |

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

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

18 - This page covers Vault specific setup. For the shared resolver workflow and syntax, see [Secrets Management](/src/collectors/SECRETS.md).

18 + This page covers 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).

19 limitations: |

20 - Netdata reads existing secrets from Vault. It does not create or renew Vault tokens. If the configured token expires or becomes invalid, secret resolution fails until Netdata can read a valid token again. For KV v2 secrets, Netdata does not add `/data/` to the path automatically.

20 + Netdata reads existing secrets from Vault. It does not create or renew Vault tokens. If the configured token expires or becomes invalid, secret resolution fails until Netdata can read a valid token again. If you use `token_file` mode, Netdata re-reads the file on every secret resolution, so an external process (e.g. Vault Agent, a cron job) can renew the token by writing to the file. For KV v2 secrets, Netdata does not add `/data/` to the path automatically.

21 setup:

22 prerequisites:

23 list:

@@ -34,7 +34,7 @@ setup:

34 Prefer `token_file` for production so the Vault token is not embedded directly in the secretstore configuration.

35 - title: 'Allow access to the referenced secret paths'

36 description: |

37 - The Vault token used by this secretstore must be allowed to read the paths you reference from collector configs.

37 + The Vault token used by this secretstore must have a policy that grants `read` capability on the paths you reference from collector configs. Scope the policy to only the paths Netdata needs.

38 - title: 'Plan for file-based changes'

39 description: |

40 If you edit `/etc/netdata/go.d/ss/vault.conf`, restart the Netdata Agent to load the updated secretstore definition.

@@ -96,10 +96,17 @@ setup:

96 mode_token:

97 token: your-vault-token

98 addr: https://vault.example

99 - namespace: admin

100 - tls_skip_verify: false

99 + - name: 'Token from environment variable'

100 + description: 'Use a `${env:...}` resolver for the Vault token to avoid storing it in plain text in the secretstore config file.'

101 + config: |

102 + jobs:

103 + - name: vault_prod

104 + mode: token

105 + mode_token:

106 + token: "${env:VAULT_TOKEN}"

107 + addr: https://vault.example

108 - name: 'Token file'

102 - description: 'Read the Vault token from a local file on the Netdata host.'

109 + description: 'Read the Vault token from a local file on the Netdata host. Netdata re-reads the file on every secret resolution, so an external process can renew the token by writing to this file.'

110 config: |

111 jobs:

112 - name: vault_prod_file_token

@@ -107,9 +114,19 @@ setup:

114 mode_token_file:

115 path: /var/lib/netdata/vault.token

116 addr: https://vault.example

117 + - name: 'Vault Enterprise with namespace'

118 + description: 'Connect to a Vault Enterprise server using a specific namespace.'

119 + config: |

120 + jobs:

121 + - name: vault_enterprise

122 + mode: token_file

123 + mode_token_file:

124 + path: /var/lib/netdata/vault.token

125 + addr: https://vault.example

126 + namespace: admin

127 collector_configs:

128 description: |

112 - Reference Vault secrets from collector configs with the `vault` secretstore kind.

129 + Use the `${store:vault:...}` syntax to reference Vault secrets in any string field of a collector configuration file.

130 summary:

131 operand_format: 'path#key'

132 example_operand: 'secret/data/netdata/mysql#password'

@@ -119,6 +136,9 @@ collector_configs:

136

137 Netdata sends the path to Vault as `/v1/<path>` exactly as you provide it. For KV v2 secrets, include `/data/` in the path yourself.

138 The `path` must not be empty and must not contain `..`, `?`, or `#`.

139 +

140 + - KV v1 example: `${store:vault:vault_prod:secret/netdata/mysql#password}`.

141 + - KV v2 example: `${store:vault:vault_prod:secret/data/netdata/mysql#password}` — note the `/data/` segment, Netdata does not add it automatically.

142 syntax: '${store:vault:<store-name>:<path#key>}'

143 parts:

144 list:

@@ -130,21 +150,31 @@ collector_configs:

150 description: 'The Vault API path and the secret field name, separated by `#`.'

151 examples:

152 list:

133 - - name: 'KV v1 secret'

134 - description: 'Read the `password` field from a KV v1 secret.'

135 - language: 'text'

136 - content: '${store:vault:vault_prod:secret/netdata/mysql#password}'

137 - - name: 'KV v2 secret'

138 - description: 'Read the `password` field from a KV v2 secret. Include `/data/` in the path.'

139 - language: 'text'

140 - content: '${store:vault:vault_prod:secret/data/netdata/mysql#password}'

141 - - name: 'Collector config example'

142 - description: 'Use a Vault secret in a collector DSN.'

143 - language: 'yaml'

153 + - name: 'MySQL collector with password from Vault'

154 + description: |

155 + This example configures a MySQL collector job in `/etc/netdata/go.d/mysql.conf`.

156 + The password in the DSN connection string is not stored in plain text. Instead,

157 + `${store:vault:vault_prod:secret/data/netdata/mysql#password}` tells Netdata to

158 + read the KV v2 secret at `secret/data/netdata/mysql` from the `vault_prod` store,

159 + extract the `password` field from the response, and substitute it into the DSN at runtime.

160 content: |

161 + # /etc/netdata/go.d/mysql.conf

162 jobs:

163 - name: mysql_prod

164 dsn: "netdata:${store:vault:vault_prod:secret/data/netdata/mysql#password}@tcp(127.0.0.1:3306)/"

165 + - name: 'Elasticsearch collector with HTTP basic auth from Vault'

166 + description: |

167 + This example configures an Elasticsearch collector job in `/etc/netdata/go.d/elasticsearch.conf`.

168 + The `password` field uses a secret reference instead of a plain-text value. Netdata reads the

169 + KV v2 secret at `secret/data/netdata/elasticsearch` from the `vault_prod` store, extracts the

170 + `password` field, and substitutes it at runtime.

171 + content: |

172 + # /etc/netdata/go.d/elasticsearch.conf

173 + jobs:

174 + - name: es_prod

175 + url: https://elasticsearch.example.com:9200

176 + username: netdata

177 + password: "${store:vault:vault_prod:secret/data/netdata/elasticsearch#password}"

178 troubleshooting:

179 problems:

180 list: