Google Secret Manager

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.

This page covers Google Secret Manager specific setup. For the shared resolver workflow and syntax, see Secrets Management.

Limitations

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:

Method	Best for	How to
UI	Fast setup without editing files	Go to Collectors -> go.d -> SecretStores -> gcp-sm, then add a secretstore.
File	File-based configuration or automation	Edit /etc/netdata/go.d/ss/gcp-sm.conf and add a jobs entry.

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 be allowed to access the referenced secrets in Google Secret Manager.

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.

Config options

Group	Option	Description	Default	Required
	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

mode

Supported values:

• metadata: get an access token from the Google metadata server.
• 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

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

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

If you omit the version, Netdata uses latest. 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.

${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

Latest version

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

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

Specific version

Read version 3 of the mysql-password secret.

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

Collector config example

Use a Google Secret Manager secret in a collector DSN.

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

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.