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:

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.

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

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.