<!--startmeta
custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/go/plugin/agent/secrets/secretstore/backends/gcp/README.md"
meta_yaml: "https://github.com/netdata/netdata/edit/master/src/go/plugin/agent/secrets/secretstore/backends/gcp/metadata.yaml"
sidebar_label: "Google Secret Manager"
learn_status: "Published"
learn_rel_path: "Collecting Metrics/Secrets Management/Secret Stores"
keywords: ['secretstore', 'secrets', 'gcp', 'gcp-sm', 'google secret manager']
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE SECRETSTORE'S metadata.yaml FILE"
endmeta-->

# Google Secret Manager


<img src="https://netdata.cloud/img/google.svg" width="150"/>


Kind: gcp-sm

<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />

## 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](https://github.com/netdata/netdata/blob/master/src/collectors/SECRETS.md).


### 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:

| Method | Best for | How to |
|:--|:--|:--|
| [**UI**](#via-ui) | Fast setup without editing files | Go to `Collectors -> go.d -> SecretStores -> gcp-sm`, then add a secretstore. |
| [**File**](#via-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 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.

<details open><summary>Config options</summary>



| Group | Option | Description | Default | Required |
|:------|:-----|:------------|:--------|:---------:|
|  | [mode](#option-mode) | GCP authentication mode. | metadata | 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 |
|  | timeout | Timeout in seconds for HTTP requests made by this secretstore backend. | 3 | no |

<a id="option-mode"></a>
##### 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.



</details>


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

```yaml
jobs:
  - name: gcp_metadata
    mode: metadata

```
###### Service account file

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

```yaml
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 `-`.


```text
${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.


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

```
#### 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.


```yaml
# /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.
