---
title: "GCP Secret Manager"
description: "Configure Aerospike Secret Agent with GCP Secret Manager via attached service accounts, ADC, or impersonation."
---

# GCP Secret Manager

> For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt)
> 
> All documentation pages available in markdown.

Secret Agent can authenticate with GCP Secret Manager using the following methods:

-   [Attached service account](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa)
-   [Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc)
-   [Service account impersonation](https://cloud.google.com/docs/authentication/use-service-account-impersonation)

## Attached service account

This is the recommended way to authenticate with GCP because it does not require any credentials in the Secret Agent configuration file. When Secret Agent runs on a GCP VM with a service account attached, it automatically uses the credentials of that service account. The attached service account must have the `Secret Manager Secret Accessor` role.

To configure Secret Agent on a GCP VM with an attached service account:

1.  Create a secret in GCP Secret Manager. In this example, the secret is named `TestingSecret`.
2.  Create a service account with the `Secret Manager Secret Accessor` role. In this example, the service account is named `test-service-account@xxx.iam.gserviceaccount.com`.
3.  Create a VM with the `test-service-account@xxx.iam.gserviceaccount.com` service account attached. From the GCP console:
    1.  Click **Create Instance** in **VM Instances** under **Compute Engine**.
    2.  Go to **Identity and API access**.
    3.  Select `test-service-account@xxx.iam.gserviceaccount.com` in **Service account**.
4.  Install Secret Agent on the GCP VM.
5.  Configure Secret Agent to fetch secrets from GCP Secret Manager.
6.  Start Secret Agent.

Sample configuration file:

```yaml
service:

  tcp:

    endpoint: 0.0.0.0:3005

secret-manager:

  gcp:

    resources:

      TestRes: projects/xxxxxxxxxxxx/secrets/TestingSecret/versions/latest

log:

  level: info
```

## Application Default Credentials

Application Default Credentials (ADC) is a strategy that the Google Cloud client libraries use to automatically find credentials based on the application environment. With ADC, you can provide credentials to Secret Agent by setting an environment variable, placing a credentials file on disk, or specifying a credential file path directly in the Secret Agent configuration.

Use ADC when Secret Agent runs outside of GCP (for example, on-premises or in another cloud provider), when the GCP VM does not have a service account attached, or when you need to authenticate with a different service account from the one attached to the VM.

Secret Agent looks for Application Default Credentials in the following order:

1.  Secret Agent configuration file.
2.  The environment variable `GOOGLE_APPLICATION_CREDENTIALS`.
3.  The default credentials file `~/.config/gcloud/application_default_credentials.json`.
4.  GCP VM attached service account credentials.

To configure Secret Agent with Application Default Credentials:

1.  Create a service account with the `Secret Manager Secret Accessor` role. In this example, the service account is named `test-service-account@xxx.iam.gserviceaccount.com`.
2.  Create a secret in GCP Secret Manager. In this example, the secret is named `TestingSecret`.
3.  Download the key file in JSON format for the `test-service-account@xxx.iam.gserviceaccount.com` service account.
4.  Install Secret Agent on the machine.
5.  Configure Secret Agent and set the `credential-file` parameter to the path of the downloaded service account credential file.
6.  Start Secret Agent.

Sample configuration file:

```yaml
service:

  tcp:

    endpoint: 0.0.0.0:3005

secret-manager:

  gcp:

    resources:

      TestRes: projects/xxxxxxxxxxxx/secrets/TestingSecret/versions/latest

    credential-file: PATH_TO_SERVICE_ACCOUNT_CREDENTIAL_FILE

log:

  level: info
```

## Service account impersonation

You can use service account impersonation with either of the preceding authentication methods (attached service account and Application Default Credentials). With impersonation, you start with an authenticated principal (your Google Account or a service account) and request short-lived credentials for a service account that has authorization to access secrets. The authenticated principal must have permission to impersonate the target service account.

Service account impersonation is more secure than using a service account key because it requires a prior authenticated identity, and the credentials created through impersonation do not persist. By comparison, authenticating with a service account key requires no prior authentication, and the persistent key is a high-risk credential if exposed.

To configure Secret Agent with service account impersonation:

1.  Create a secret in GCP Secret Manager. In this example, the secret is named `TestingSecret`.
2.  Create a service account with the `Service Account Token Creator` role. In this example, this service account is named `base-service-account@xxx.iam.gserviceaccount.com`.
3.  Create a service account with the `Secret Manager Secret Accessor` role. In this example, this service account is named `test-service-account@xxx.iam.gserviceaccount.com`.
4.  Verify that the `IAM Service Account Credentials API` is enabled for your GCP project.
5.  Create a GCP VM with `base-service-account@xxx.iam.gserviceaccount.com` attached. From the GCP console:
    1.  Click **Create Instance** in **VM Instances** under **Compute Engine**.
    2.  Go to **Identity and API access**.
    3.  Select `base-service-account@xxx.iam.gserviceaccount.com` in **Service account**.
6.  Install Secret Agent on the GCP VM.
7.  Configure Secret Agent to fetch secrets from GCP Secret Manager. Set `impersonate` to `test-service-account@xxx.iam.gserviceaccount.com` in the configuration file. This service account has permission to access secrets.
8.  Start Secret Agent.

Sample configuration file:

```yaml
service:

  tcp:

    endpoint: 0.0.0.0:3005

secret-manager:

  gcp:

    resources:

      TestRes: projects/xxxxxxxxxxxx/secrets/TestingSecret/versions/latest

    credential-file: PATH_TO_BASE_SERVICE_ACCOUNT_CREDENTIAL_FILE

    impersonate: test-service-account@xxx.iam.gserviceaccount.com

log:

  level: info
```

## Accessing secrets across projects

You can access secrets across GCP projects using the same service account credentials.

1.  Create a service account with the `Secret Manager Secret Accessor` role in `Project1`. In this example, the service account is named `test-service-account-project1@xxx.iam.gserviceaccount.com`.
2.  Create a secret in another GCP project (`Project2`). In this example, the secret is named `TestingSecretProject2`.
3.  Download the key file in JSON format for `test-service-account-project1@xxx.iam.gserviceaccount.com`.
4.  Grant `test-service-account-project1@xxx.iam.gserviceaccount.com` the `Secret Manager Secret Accessor` role in `Project2`. From the GCP console:
    1.  Select `Project2` from the project list.
    2.  Go to **Grant Access** in **IAM**.
    3.  Add `test-service-account-project1@xxx.iam.gserviceaccount.com` as a principal and assign the `Secret Manager Secret Accessor` role.
5.  Install Secret Agent on the machine.
6.  Configure Secret Agent and set the `credential-file` parameter to the path of the downloaded service account credential file.
7.  Start Secret Agent.

Sample configuration file for cross-project access:

```yaml
service:

  tcp:

    endpoint: 0.0.0.0:3005

secret-manager:

  gcp:

    resources:

      TestResProj2: projects/yyyyyyyyyyyy/secrets/TestingSecretProject2/versions/latest

    credential-file: PATH_TO_SERVICE_ACCOUNT_CREDENTIAL_FILE

log:

  level: info
```

## Accessing multiple versions of a secret

Secrets in GCP Secret Manager can have multiple versions. To access specific versions, define each as a separate resource in the configuration file:

```yaml
service:

  tcp:

    endpoint: 0.0.0.0:3005

secret-manager:

  gcp:

    resources:

      TestResV1: projects/yyyyyyyyyyyy/secrets/TestingSecret/versions/1

      TestResV2: projects/yyyyyyyyyyyy/secrets/TestingSecret/versions/2

      TestResLatest: projects/yyyyyyyyyyyy/secrets/TestingSecret/versions/latest

log:

  level: info
```