GCP Secret Manager

The gcp-secret-manager provider resolves secrets from Google Cloud Secret Manager using the Secret Manager v1 REST API. It supports three authentication modes: service-account JSON key, Application Default Credentials (ADC), and GKE Workload Identity.

GKE Workload Identity is the recommended production mode for platform deployments on Google Kubernetes Engine. No secrets are persisted - the GKE metadata server brokers the token via the pod's KSA-to-GSA binding.

Prerequisites

A GCP project with Secret Manager API enabled (gcloud services enable secretmanager.googleapis.com).
An IAM identity (service account or workload identity) with roles/secretmanager.secretAccessor on the required secrets.
For service-account-json mode: a service account JSON key file.
For workload-identity mode: a GKE cluster with Workload Identity configured.

Configuration

Field	Type	Required	Description
`projectId`	string	Yes	GCP project ID
`authMode`	string	Yes	`service-account-json`, `adc`, or `workload-identity`
`serviceAccountJsonCredentialId`	string	If `service-account-json`	Credential ID of the JSON key (stored via `rensei-encrypted`)
`secretNameTemplate`	string	No	Template for building the secret name (default: `{orgId}--{kind}`)
`version`	string	No	Secret version to access (default: `latest`)

Secret naming convention

Secrets are accessed as:

projects/{projectId}/secrets/{secretName}/versions/{version}

The default secretNameTemplate maps {orgId}/{kind} → {orgId}--{kind} (replacing / with -- since GCP secret names cannot contain slashes). Override to match your existing naming scheme.

# Default layout
gcloud secrets create "org_abc123--anthropic-api-key" --data-file=- <<< "sk-ant-..."

JSON secrets are auto-detected: a parseable JSON object populates multiField, and the primary scalar is extracted using the field priority: apiToken → accessToken → apiKey → token → value.

Authentication modes

service-account-json

Uses a GCP service account JSON key file. The key is stored via registry chaining - the serviceAccountJsonCredentialId must point to a separate credentials row in rensei-encrypted. The provider extracts the private key from the JSON file and uses it to sign a JWT for the OAuth2 token endpoint (RFC 7523 JWT-bearer flow).

A service account JSON key contains a private RSA key. Always store it via rensei-encrypted using serviceAccountJsonCredentialId - never inline the JSON in the GCP config row's payload.

{
  "projectId": "my-gcp-project",
  "authMode": "service-account-json",
  "serviceAccountJsonCredentialId": "cred_..."
}

Access tokens are cached per (orgId, projectId) and renewed at 80% of expires_in.

adc (Application Default Credentials)

Resolves credentials from the GOOGLE_APPLICATION_CREDENTIALS environment variable (file path to a service account JSON) or the GCE/Cloud Run metadata server.

ADC is opt-in only. Rensei never auto-falls-back to ADC when no authMode is configured. This is an explicit operator decision to prevent the host machine's ambient GCP credentials from inadvertently being used by the platform.

{
  "projectId": "my-gcp-project",
  "authMode": "adc"
}

Ensure GOOGLE_APPLICATION_CREDENTIALS is set to the path of a service account key file, or that the platform runs on a GCE/Cloud Run instance with an attached service account.

workload-identity (recommended for GKE)

No secrets in the database. The provider requests a token from the GKE metadata server at:

http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token

Configure the GKE Workload Identity binding:

# Bind your Kubernetes ServiceAccount to a GCP ServiceAccount
gcloud iam service-accounts add-iam-policy-binding \
  rensei-platform@my-gcp-project.iam.gserviceaccount.com \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:my-gcp-project.svc.id.goog[rensei/rensei-platform]"

kubectl annotate serviceaccount rensei-platform \
  --namespace rensei \
  iam.gke.io/gcp-service-account=rensei-platform@my-gcp-project.iam.gserviceaccount.com

{
  "projectId": "my-gcp-project",
  "authMode": "workload-identity"
}

Setup

Create your secrets in GCP Secret Manager.

Grant the appropriate IAM role to your identity.

For service-account-json mode: store the JSON key in Rensei first:

curl -X POST https://rensei.ai/api/org/credentials \
  -H "Authorization: Bearer rsk_live_..." \
  -d '{
    "kind": "gcp-service-account-json",
    "value": "{ \"type\": \"service_account\", ... }"
  }'
# Copy the returned credential ID

Configure the GCP provider:

curl -X POST https://rensei.ai/api/org/credential-backend \
  -H "Authorization: Bearer rsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "providerType": "gcp-secrets",
    "config": {
      "projectId": "my-gcp-project",
      "authMode": "service-account-json",
      "serviceAccountJsonCredentialId": "cred_..."
    }
  }'

Test via Settings → Security → Credential Backend → Test Connection.

SDK vs REST API

The provider uses fetch against the Secret Manager v1 REST API directly. Adding @google-cloud/secret-manager would pull in google-auth-library + google-gax + gRPC tooling - heavy for a single REST call. The JWT-bearer and metadata-server flows are stable and well-documented; the hand-rolled implementation keeps the dependency surface small.

Refresh policy

GCP secret versions have no built-in TTL. refreshAt defaults to resolvedAt + 1h. Access token caches for service-account-json and workload-identity modes pre-renew at 80% of the token's expires_in.

Security notes

The service-account-json JSON key file contains a private RSA key. Always chain through rensei-encrypted - never inline in the GCP config row.
The platform never auto-falls-back to ADC. ADC is explicit operator opt-in only.
The provider does not auto-register in bootstrap.ts.
All error paths redact access tokens and private key material before surfacing messages.

On this page