Google Secret Manager

Kind: gcp-sm

Overview

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 full resolver overview and syntax reference, including simpler alternatives like ${env:...}, ${file:...}, and ${cmd:...}, see Secrets Management.

Limitations

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

You can configure the gcp-sm secretstore in two ways:

Prerequisites

Choose a GCP authentication mode

Choose one supported authentication mode and make sure the Netdata Agent can use it:

• metadata: run Netdata in a Google Cloud environment where the metadata server is reachable.
• service_account_file: provide a service account JSON file on the Netdata host.

Prefer metadata for production when Netdata runs in a supported Google Cloud environment. Use service_account_file when Netdata runs outside Google Cloud or when you need explicit credentials.

Protect the service account file

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.

Allow Secret Manager access

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

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

Configuration

Options

The following options can be defined for this secretstore backend.

mode

Supported values:

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

via UI

1. Open the Netdata Dynamic Configuration UI.
2. Go to Collectors -> go.d -> SecretStores -> gcp-sm.
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/gcp-sm.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

Metadata server

Use credentials from the Google metadata server.

jobs:
  - name: gcp_metadata
    mode: metadata

Service account file

Use a service account JSON file stored on the Netdata host.

jobs:
  - name: gcp_service_account
    mode: service_account_file
    mode_service_account_file:
      path: /etc/netdata/gcp-service-account.json

Use in collector configs

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.

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

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

• gcp-sm: The secretstore backend kind.
• <store-name>: The name of the configured secretstore, for example gcp_prod.
• <project/secret[/version]>: The Google Cloud project ID, secret name, and optional version.

Examples

MySQL collector with password from Google Secret Manager

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.

# /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)/"

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.

# /etc/netdata/go.d/httpcheck.conf
jobs:
  - name: internal_api
    url: https://api.example.com/health
    username: netdata
    password: "${store:gcp-sm:gcp_prod:my-project/api-password}"

Troubleshooting

Find the exact error

Check the Netdata Agent logs when the collector starts or restarts. GCP resolver errors include messages such as metadata token request returned HTTP 404, invalid project ID, invalid version, or reading service account file.

Metadata mode does not work

mode: metadata requires the Google metadata server. If Netdata is not running in a supported Google Cloud environment, switch to service_account_file.

Service account file cannot be read

Check the file path, the JSON contents, and that the netdata user can read the file. Because the file contains a private key, keep its permissions as tight as possible.

Permission denied or secret not found

Make sure the Google identity used by Netdata can access the referenced secret, and confirm that the operand uses the correct project/secret or project/secret/version format.