Secret Manager and Cloud KMS

The default replication policy is automatic: Google replicates the payload to locations it chooses and the secret is reachable from the global endpoint secretmanager.googleapis.com. Choose user-managed replication when data residency rules require named locations. A user-managed policy lists one or more regions or multi-regions, and each location can use its own CMEK key.

Regional secrets (generally available since 2024-10-14) are a separate resource type pinned to a single location and served by the regional endpoint secretmanager.REGION.rep.googleapis.com. They suit workloads that must keep both the payload and the API traffic in one region. Multi-region locations for secrets have also been available since 2026-06. Regional and global secrets are different resources with different names (projects/PROJECT_ID/locations/REGION/secrets/NAME), and not every integration supports the regional form. In particular, Cloud Run does not support regional secrets, so the Bookshelf secrets used from Cloud Run stay global with automatic or user-managed replication. See Create a regional secret.

Derived from Create and access a secret, Add a secret version and gcloud secrets create.

REPLACE_ME is a placeholder. In practice the value comes from a password generator, an upstream system or a file produced by a pipeline, and it must not be committed or left in shell history. The --data-file=- form reads standard input, which keeps the value out of the process list. Reading with versions access prints the payload to the terminal, so use it for diagnosis, and pipe it to a consumer rather than saving it in a script.

User-managed and regional variants:

Derived from Choose a replication policy and Create a regional secret.

Derived from Manage secret versions and Add an alias to a secret version.

A disabled version cannot be accessed but can be re-enabled, which makes disabling the right first step when a credential is suspected to be unused. Destroying is irreversible once the delay elapses. Aliases are resolved by the Secret Manager API and client libraries; integrations that take a version number (such as the Cloud Run flag below) accept a number or latest, so check the integration before relying on an alias.

Derived from Create and manage labels and Tags for Secret Manager.

Cloud Run resolves a secret reference when an instance starts. There are two ways to expose it, with different update behaviour.

Derived from Configure secrets for services and gcloud run services update.

The Cloud Run runtime service account needs secretAccessor on the secret. Deployment fails if it does not. Cloud Run only supports global secrets, as noted above. --update-secrets and --remove-secrets change one binding without replacing the rest. The mechanics of services, revisions and traffic splits are in Cloud Run and Cloud Run Scaling, Traffic and Jobs; the related environment-variable and volume handling for plain configuration is in Runtime Configuration.

The managed Secret Manager add-on for GKE (a CSI driver that Google installs and upgrades) mounts secrets into pods as files and can mirror them into Kubernetes Secrets. It reached general availability on 2024-08-20, gained automatic rotation of mounted secrets on 2025-09-01 and the sync to Kubernetes Secrets on 2026-04-16. It requires Workload Identity Federation for GKE, which Autopilot clusters have on by default.

Derived from Use the Secret Manager add-on for GKE.

The workload declares what to mount with a SecretProviderClass whose provider is gke, then references it from a CSI volume:

Derived from Use the Secret Manager add-on for GKE and the Secrets Store CSI Driver documentation.

Replace my-project-id with the project ID (the manifest cannot read shell variables). A synced Kubernetes Secret exists only while at least one pod mounts the class, and its value lives in etcd, so the file mount is the safer default; use the sync only for software that insists on a secretKeyRef or an envFrom. Mounting by file, a pod sees the new content after rotation within the configured interval, whereas an environment variable populated from a synced Secret needs a pod restart. More on GKE workloads, namespaces and Gateway API is in Deploying Microservices on GKE and GKE Clusters.

Import the com.google.cloud:libraries-bom in dependencyManagement and add com.google.cloud:google-cloud-secretmanager without a version; see Google Cloud Libraries BOM and Secret Manager client libraries.

Derived from the access secret version sample.

Creating a client opens a channel, so create one per application and reuse it, and cache the value for a short time instead of calling the API for every request: access operations are billed and quota-limited. Run with a version of latest only when the code can tolerate a changing value.

Spring Cloud GCP’s Secret Manager support turns secrets into configuration properties, so catalog-api reads its password like any other Spring property. The starter is spring-cloud-gcp-starter-secretmanager (version managed by spring-cloud-gcp-dependencies 8.x for Spring Boot 4, 7.4.x for Spring Boot 3).

Derived from Spring Cloud GCP Secret Manager.

The sm@ import enables the property source; ${sm@secret-id} resolves the latest version and ${sm@secret-id/version} pins one. The values are loaded when the application context starts, so a rotated secret needs a restart unless refresh is configured. Keep the property placeholders in committed files and never the values. Profiles and layered configuration are covered in Configuration and Profiles. For a Cloud SQL password specifically, prefer IAM database authentication (see Cloud SQL) so that no password exists at all; the secret remains the fallback for engines that lack it.

Cloud Build reads a secret during a build without writing it to the build config or logs: declare it under availableSecrets.secretManager with a versionName and an env name, list the name in a step’s secretEnv, and grant the build’s service account secretAccessor on that secret (see Use secrets in Cloud Build and Container Registry and Builds). GitHub’s encrypted secrets suit a token only GitHub uses; a value that production also needs should live in one place. A workflow can authenticate with Workload Identity Federation (no key file) through google-github-actions/auth and fetch it with get-secretmanager-secrets, using an identity that holds only secretAccessor. Federation setup is in Identity and Access; the CI side is in Docker CI/CD with GitHub Actions.

Single-tenant HSM options and EKM through a VPC are variations of the last two rows. The protection level is fixed when the key is created. Software and HSM keys can be used in the same CMEK configurations.

Derived from Create a key, Key rotation and gcloud kms keys create.

--destroy-scheduled-duration is set at creation (default 30 days) and cannot be changed afterwards; it is the period a destroyed-by-request key version waits before it is erased. Use --protection-level=hsm for Cloud HSM. Encrypting and decrypting small payloads directly:

Derived from Encrypt and decrypt data with a symmetric key.

Direct encryption is limited to 64 KiB of plaintext; for larger data use envelope encryption (the data is encrypted with a data key, which KMS wraps), which is what CMEK-enabled Google services do for you.

Separate the people who manage keys (cloudkms.admin) from the identities that use them (cryptoKeyEncrypterDecrypter). Grant on the key rather than on the project:

Derived from Cloud KMS IAM permissions and roles.

Autokey creates keys on demand so that platform teams do not have to pre-provision key rings for every service. A folder is configured with an Autokey key project; when a developer creates a protected resource, the service asks Autokey for a key handle, and Autokey creates a key with the right location, rotation and protection level, grants the service agent, and returns it. The setup is performed by a folder administrator and works for the supported services listed in the documentation:

An administrator with roles/cloudkms.autokeyAdmin on the folder runs gcloud kms autokey-config update with the folder and key project; a developer then runs gcloud kms key-handles create with a --resource-type-selector. See Cloud KMS Autokey overview and Enable Autokey.

The supported resource types and the exact flags change as services are added, so confirm them on the linked pages. Autokey suits organisations with many teams; for a single Bookshelf project a manually created key as above is simpler. Resource hierarchy and folder concepts are in Resource Hierarchy and Projects.

Derived from the Terraform registry pages google_secret_manager_secret, google_kms_crypto_key.

Do not define the secret version in Terraform with a literal value: the payload would end up in the state file. Create the container in Terraform and add versions out of band, or use the write-only attribute that the provider documents for secret data, so the value is not stored. State handling and modules are in Infrastructure as Code.