Google Cloud Secret Manager

The google ingredient stores keys in Google Cloud Secret Manager. Application variables stay in .ramenv.vault.toml. ramenv uses the Google Cloud Rust SDK’s Application Default Credentials (ADC), which you configure separately from the gcloud CLI’s active login.

Local ADC setup

gcloud auth application-default login
ramenv init --ingredient google

For a monorepo, use ramenv init workspace --ingredient google instead.

Initialization asks for a storage project ID. It accepts my-project or projects/my-project, then stores projects/my-project as provider_location in .ramenv.keyrefs.toml.

gcloud auth login alone is not enough. Changing the CLI’s active account does not change an existing ADC file. If GOOGLE_APPLICATION_CREDENTIALS points to another identity, unset it before relying on local ADC.

Enable the API and permissions

An administrator with service-enablement permissions can enable Secret Manager:

gcloud services enable secretmanager.googleapis.com --project=my-project

This command uses gcloud’s CLI credentials. ramenv authenticates with ADC.

The identity selected by ADC needs these permissions:

Operation	IAM permission
Create key secrets	secretmanager.secrets.create
Write key versions	secretmanager.versions.add
Read pinned versions	secretmanager.versions.access
Remove key secrets	secretmanager.secrets.delete

roles/secretmanager.secretAccessor permits reads only. Initialization and key management also need create, write, or delete permissions. roles/secretmanager.admin includes these operations, but a custom role can limit access to the permissions you need.

Creation requires access on the parent project. Scope access to existing secrets when possible. On Compute Engine, OAuth access scopes can restrict access in addition to IAM; use suitable scopes such as cloud-platform.

Credential selection

ADC searches in order:

1. The JSON file named by GOOGLE_APPLICATION_CREDENTIALS.
2. The local ADC file created by gcloud auth application-default login.
3. A supported workload’s metadata identity when no credential file is configured or found locally.

A configured credential file or local ADC file overrides metadata identity. A missing explicitly configured file, malformed JSON, unreadable file, or unsupported configuration returns an error. Only an absent default local ADC file permits metadata fallback.

There is no RAMENV_GOOGLE_CREDENTIAL setting. Token or Secret Manager authorization failures do not cause ramenv to try another identity.

Impersonation and quota

For local development without downloading a service-account private key:

gcloud auth application-default login \
  --impersonate-service-account=ramenv@my-project.iam.gserviceaccount.com

Your user needs permission to generate tokens for that account, usually roles/iam.serviceAccountTokenCreator. The impersonated account needs Secret Manager access.

If user ADC has no quota project:

gcloud auth application-default set-quota-project my-project

The identity needs serviceusage.services.use on that project. GOOGLE_CLOUD_QUOTA_PROJECT can override the SDK’s quota/billing project. Neither the quota project nor gcloud’s active project changes the workspace’s saved storage project.

Deploy with workload identity

Attach a service account with Secret Manager read permissions or configure supported workload identity. To use metadata credentials, omit local ADC files and unset GOOGLE_APPLICATION_CREDENTIALS.

Outside Google Cloud, supported external-account federation uses a credential configuration file. Prefer federation or impersonation over long-lived service-account keys. See deployment.

Versions and deletion

Saved refs use numeric versions:

projects/<project>/secrets/<secret>/versions/<version>

ramenv checks them against the saved project and reads the pinned version, never latest. Updates add a version and record its reference after pending remote operations succeed. New secrets use automatic replication.

Environment removal deletes the whole key secret and all its versions. Deleting a secret already missing is treated as success.

For PermissionDenied, check the selected ADC identity, saved storage project, IAM permissions, API enablement, and quota requirements. The source authentication guide has additional SDK configuration details.