Secret Manager from Cloud Shell: store a key, rotate it, then retire the old version

Secret Manager, in plain words

Secret Manager is a locked drawer for the small, sensitive strings your apps need: API keys, database passwords, OAuth client secrets, TLS keys. Instead of baking them into source code or an environment file, you store them once in Google Cloud and let only the identities that need them read them. Everything is encrypted in transit and at rest by default, and you can bring your own Cloud KMS key (CMEK) if your rules demand it.

Two ideas carry most of the service. A secret is the named container that holds labels, replication settings and IAM permissions. A secret version holds the actual bytes (up to 64 KiB) and is numbered 1, 2, 3 and so on. Rotating a key means adding a new version, not editing the old one. Each version can be enabled, disabled (reads fail, but you can switch it back on) or destroyed (the data is gone for good). The alias latest always points at the newest version, which is handy in a lab but risky in production, where Google advises pinning a version number.

Pricing is by active version and by read. The free tier covers 6 active versions, 10,000 access operations and 3 rotation notifications per month for each billing account. Beyond that, an active version costs about $0.06 a month and reads cost $0.03 per 10,000. Enabled and disabled versions both count as active; destroyed ones are free, and creating or changing secrets costs nothing. Automatic replication is billed as one location; user-managed replication is billed once per region you pick. There were no Secret Manager release notes in the last two weeks; the most recent entries, from August and September 2026, were about Parameter Manager, its companion service for plain configuration values.

The AI angle

AI apps are full of keys: a third-party model API key, a vector database password, an OAuth client for a tool your agent calls. The Gemini Enterprise Agent Platform (formerly Vertex AI) docs for deployed agents on Agent Runtime say API keys and OAuth client secrets are kept in Secret Manager at the project level, where several agents can share them and labels can tag which agent uses which. Calls to Google's own models from inside Google Cloud should use a service account and IAM (for example roles/aiplatform.user) rather than a stored key, so reserve Secret Manager for credentials Google Cloud cannot issue for you.

Hands-on lab: Store, rotate and retire a practice secret

Create a secret holding a random practice value, read it back, add a second version, disable and destroy the first, inspect who can read it, then delete the secret.

1. Point gcloud at your project and enable the API

   Open Cloud Shell, set the project, pick a secret name and turn on the Secret Manager API. Enabling it is free.

   gcloud config set project YOUR_PROJECT_ID
   export SECRET_ID="sandbox-lab-secret"
   gcloud services enable secretmanager.googleapis.com

   Done

2. Create the secret with a random first version

   --data-file=- reads the value from standard input, so the value never appears in your command line or shell history. openssl rand makes a fake 32-character key, and tr -d strips the trailing newline so it is not stored as part of the value. With no replication flags the secret uses automatic replication, billed as one location.

   openssl rand -hex 16 | tr -d '\n' | gcloud secrets create "$SECRET_ID" \
     --data-file=- --labels=purpose=sandbox-lab
   
   gcloud secrets describe "$SECRET_ID"

   Done

3. Read it back

   Read version 1 by number and again through the latest alias; both print the same value because only one version exists. Output goes to the terminal as text, which is fine for this hex string; for binary secrets the reference suggests --out-file instead.

   gcloud secrets versions access 1 --secret="$SECRET_ID"; echo
   gcloud secrets versions access latest --secret="$SECRET_ID"; echo

   Done

4. Rotate: add a second version

   Adding a version is how you rotate. Afterwards latest points at version 2, while version 1 still works until you switch it off. List the versions to see both, with their state.

   openssl rand -hex 16 | tr -d '\n' | gcloud secrets versions add "$SECRET_ID" --data-file=-
   
   gcloud secrets versions access latest --secret="$SECRET_ID"; echo
   gcloud secrets versions list "$SECRET_ID"

   Done

5. Disable, then destroy the old version

   Disabling is the safe first move: reads of version 1 now fail with an error, but you could re-enable it if an app breaks. Once you are sure, destroy it; that is permanent, and destroyed versions stop counting toward billing. Finally, look at the secret's IAM policy. It is empty, which means only project-level roles such as Owner can read it; in real use you would grant roles/secretmanager.secretAccessor on this one secret to the app's service account.

   gcloud secrets versions disable 1 --secret="$SECRET_ID"
   gcloud secrets versions access 1 --secret="$SECRET_ID"   # expect an error
   
   gcloud secrets versions destroy 1 --secret="$SECRET_ID" --quiet
   gcloud secrets versions list "$SECRET_ID"
   
   gcloud secrets get-iam-policy "$SECRET_ID"

   Done

gcloud secrets delete "$SECRET_ID" --quiet

# Confirm: this should print nothing
gcloud secrets list --filter="name:$SECRET_ID"

# Optional, practice-only project with no other secrets:
# gcloud services disable secretmanager.googleapis.com
unset SECRET_ID

Gotchas

• Disabled versions still count as active and are billed; only destroyed versions are free. Disable first to test, then destroy what you no longer need.
• echo "value" adds a newline that becomes part of the stored secret and can break logins; use printf, echo -n, or strip it as this lab does.
• Avoid latest in production. A Cloud Run environment variable reads the secret only when an instance starts, so Google recommends pinning a version number there; a mounted volume reads it on each file read.
• IAM can be granted on a secret but not on a single version, so anyone with access to a secret can read every enabled version of it.
• User-managed replication bills each chosen region separately: 5 versions in 3 regions count as 15 active versions.