Ingest New Documentation (#2819)

Co-authored-by: netdatabot <43409846+netdatabot@users.noreply.github.com>

Author: github-actions[bot]

docs/Collecting Metrics/Secret Stores/AWS Secrets Manager.mdx

@@ -25,9 +25,9 @@ Kind: aws-sm
 
 ## Overview
 
-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.
+Netdata can pull collector credentials directly from AWS Secrets Manager at runtime, so you never store passwords or tokens in plain-text configuration files.
 
-This page covers AWS Secrets Manager specific setup. For the shared resolver workflow and syntax, see [Secrets Management](/docs/collecting-metrics/secrets-management).
+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](/docs/collecting-metrics/secrets-management).
 
 
 ### Limitations
@@ -59,7 +59,7 @@ For production on AWS, prefer `ecs` or `imds` over `env` so credentials are supp
 
 #### Allow access to Secrets Manager
 
-The AWS identity used by this secretstore must be allowed to read the secrets you reference in collector configs in the configured `region`.
+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.
 
 
 #### Plan for file-based changes
@@ -81,7 +81,7 @@ The following options can be defined for this secretstore backend.
 | Option | Description | Default | Required |
 |:-----|:------------|:--------|:---------:|
 | [auth_mode](#option-auth-mode) | How Netdata obtains AWS credentials. | env | yes |
-| region | AWS region used for Secrets Manager requests. |  | yes |
+| region | AWS region used for Secrets Manager requests. There is no automatic region detection — you must always set this explicitly. |  | yes |
 
 <a id="option-auth-mode"></a>
 ##### auth_mode
@@ -154,13 +154,13 @@ jobs:
 
 ## Use in collector configs
 
-Reference AWS Secrets Manager secrets from collector configs with the `aws-sm` secretstore kind.
+Use the `${store:aws-sm:...}` syntax to reference AWS Secrets Manager secrets in any string field of a collector configuration file.
 
 
 The operand is `secret-name` or `secret-name#key`.
 
-- Use `secret-name` to return the whole `SecretString`.
-- Use `secret-name#key` to read one top-level field from a JSON `SecretString`.
+- Use `secret-name` to return the whole `SecretString`, for example: `${store:aws-sm:aws_prod:netdata/mysql/password}`.
+- Use `secret-name#key` to read one top-level field from a JSON `SecretString`, for example: `${store:aws-sm:aws_prod:netdata/mysql#password}`.
 - 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.
 - Nested paths such as `parent.child` are not interpreted as nested JSON lookups.
 
@@ -174,28 +174,37 @@ ${store:aws-sm:<store-name>:<secret-name[#key]>}
 - `<secret-name[#key]>`: The AWS Secrets Manager secret name, optionally followed by `#key` to read one field from a JSON `SecretString`.
 
 ### Examples
-#### Whole secret value
+#### MySQL collector with password from AWS Secrets Manager
 
-Return the full `SecretString` stored under the `netdata/mysql/password` secret.
+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:aws-sm:aws_prod:netdata/mysql#password}` tells Netdata to fetch the secret
+named `netdata/mysql` from the `aws_prod` store, extract the `password` field from
+its JSON value, and substitute it into the DSN at runtime.
 
-```text
-${store:aws-sm:aws_prod:netdata/mysql/password}
-```
-#### JSON field from SecretString
 
-Read the `password` field from a JSON `SecretString`.
+```yaml
+# /etc/netdata/go.d/mysql.conf
+jobs:
+  - name: mysql_prod
+    dsn: "netdata:${store:aws-sm:aws_prod:netdata/mysql#password}@tcp(127.0.0.1:3306)/"
 
-```text
-${store:aws-sm:aws_prod:netdata/mysql#password}
 ```
-#### Collector config example
+#### Elasticsearch collector with HTTP basic auth
+
+This example configures an Elasticsearch collector job in `/etc/netdata/go.d/elasticsearch.conf`.
+The `password` field uses a secret reference instead of a plain-text password. Netdata fetches
+the secret named `netdata/elasticsearch/password` from the `aws_prod` store and substitutes
+its full value into the `password` field at runtime.
 
-Use an AWS-stored password in a collector DSN.
 
 ```yaml
+# /etc/netdata/go.d/elasticsearch.conf
 jobs:
-  - name: mysql_prod
-    dsn: "netdata:${store:aws-sm:aws_prod:netdata/mysql#password}@tcp(127.0.0.1:3306)/"
+  - name: es_prod
+    url: https://elasticsearch.example.com:9200
+    username: netdata
+    password: "${store:aws-sm:aws_prod:netdata/elasticsearch/password}"
 
 ```
 

docs/Collecting Metrics/Secret Stores/Azure Key Vault.mdx

@@ -25,9 +25,9 @@ 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.
+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 shared resolver workflow and syntax, see [Secrets Management](/docs/collecting-metrics/secrets-management).
+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](/docs/collecting-metrics/secrets-management).
 
 
 ### Limitations
@@ -59,7 +59,7 @@ Prefer `managed_identity` for production on Azure when Netdata runs on an Azure
 
 #### Allow secret read access
 
-The Azure identity used by this secretstore must be allowed to read secret values from the target vaults.
+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
@@ -133,6 +133,20 @@ jobs:
       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
 
@@ -160,10 +174,10 @@ jobs:
 
 ## Use in collector configs
 
-Reference Azure Key Vault secrets from collector configs with the `azure-kv` secretstore kind.
+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`.
+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.
@@ -178,23 +192,37 @@ ${store:azure-kv:<store-name>:<vault-name/secret-name>}
 - `<vault-name/secret-name>`: The Azure Key Vault name and the secret name, separated by `/`.
 
 ### Examples
-#### Secret reference
+#### MySQL collector with password from Azure Key Vault
 
-Read the latest value of the `mysql-password` secret from the `my-keyvault` 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.
 
-```text
-${store:azure-kv:azure_prod:my-keyvault/mysql-password}
-```
-#### Collector config example
-
-Use an Azure Key Vault secret in a collector DSN.
 
 ```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

docs/Collecting Metrics/Secret Stores/Google Secret Manager.mdx

@@ -25,14 +25,14 @@ Kind: gcp-sm
 
 ## Overview
 
-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.
+Netdata can pull collector credentials directly from Google Secret Manager at runtime, so you never store passwords or tokens in plain-text configuration files.
 
-This page covers Google Secret Manager specific setup. For the shared resolver workflow and syntax, see [Secrets Management](/docs/collecting-metrics/secrets-management).
+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](/docs/collecting-metrics/secrets-management).
 
 
 ### Limitations
 
-If you omit the version in the operand, Netdata reads the `latest` secret version automatically.
+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.
 
 
 ## Setup
@@ -63,7 +63,7 @@ If you use `service_account_file`, the JSON file contains a private key. Keep it
 
 #### Allow Secret Manager access
 
-The Google identity used by this secretstore must be allowed to access the referenced secrets in Google Secret Manager.
+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`.
 
 
 #### Plan for file-based changes
@@ -85,14 +85,14 @@ The following options can be defined for this secretstore backend.
 | Group | Option | Description | Default | Required |
 |:------|:-----|:------------|:--------|:---------:|
 |  | [mode](#option-mode) | GCP authentication mode. | metadata | yes |
-| **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 |
+| **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 |
 
 <a id="option-mode"></a>
 ##### mode
 
 Supported values:
 
-- `metadata`: get an access token from the Google metadata server.
+- `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.
 - `service_account_file`: use a local service account JSON file.
 
 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.
@@ -146,14 +146,15 @@ jobs:
 
 ## Use in collector configs
 
-Reference Google Secret Manager secrets from collector configs with the `gcp-sm` secretstore kind.
+Use the `${store:gcp-sm:...}` syntax to reference Google Secret Manager secrets in any string field of a collector configuration file.
 
 
 The operand is `project/secret` or `project/secret/version`.
 
-If you omit the version, Netdata uses `latest`.
+- Use `project/secret` to read the latest version, for example: `${store:gcp-sm:gcp_prod:my-project/mysql-password}`.
+- Use `project/secret/version` to read a specific version, for example: `${store:gcp-sm:gcp_prod:my-project/mysql-password/3}`.
+
 Project IDs may use letters, numbers, `.`, `_`, `:`, or `-`. Secret names and versions may use letters, numbers, `_`, or `-`.
-When you specify a version, use the version name accepted by Secret Manager, such as `3`.
 
 
 ```text
@@ -165,28 +166,37 @@ ${store:gcp-sm:<store-name>:<project/secret[/version]>}
 - `<project/secret[/version]>`: The Google Cloud project ID, secret name, and optional version.
 
 ### Examples
-#### Latest version
+#### MySQL collector with password from Google Secret Manager
 
-Read the latest version of the `mysql-password` secret from the `my-project` project.
+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:gcp-sm:gcp_prod:my-project/mysql-password}` tells Netdata to fetch the
+latest version of the `mysql-password` secret from the `my-project` project using
+the `gcp_prod` store, and substitute its value into the DSN at runtime.
 
-```text
-${store:gcp-sm:gcp_prod:my-project/mysql-password}
-```
-#### Specific version
 
-Read version `3` of the `mysql-password` secret.
+```yaml
+# /etc/netdata/go.d/mysql.conf
+jobs:
+  - name: mysql_prod
+    dsn: "netdata:${store:gcp-sm:gcp_prod:my-project/mysql-password}@tcp(127.0.0.1:3306)/"
 
-```text
-${store:gcp-sm:gcp_prod:my-project/mysql-password/3}
 ```
-#### Collector config example
+#### HTTP check collector with password from Google Secret Manager
+
+This example configures an HTTP check collector job in `/etc/netdata/go.d/httpcheck.conf`.
+The `password` field uses a secret reference instead of a plain-text value. Netdata fetches
+the `api-password` secret from the `my-project` project and substitutes its value into the
+`password` field at runtime.
 
-Use a Google Secret Manager secret in a collector DSN.
 
 ```yaml
+# /etc/netdata/go.d/httpcheck.conf
 jobs:
-  - name: mysql_prod
-    dsn: "netdata:${store:gcp-sm:gcp_prod:my-project/mysql-password}@tcp(127.0.0.1:3306)/"
+  - name: internal_api
+    url: https://api.example.com/health
+    username: netdata
+    password: "${store:gcp-sm:gcp_prod:my-project/api-password}"
 
 ```