Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 45 ยท Identity and Security

Secret Manager and Cloud KMS

Store passwords and API keys in Secret Manager, understand versions and rotation, and learn envelope encryption and CMEK with Cloud KMS, with a runnable demo.

Every application has secrets: database passwords, API keys, signing keys. The worst place for them is your source code, a container image or a plain environment file in a repository. Google Cloud offers two related services for doing better. Secret Manager stores small secret values, with versions and access control. Cloud Key Management Service (KMS) manages encryption keys and performs cryptographic operations without ever showing you the key.

Beginners often mix them up, so remember the split: Secret Manager holds a thing your app needs to read (a password). Cloud KMS holds a key used to protect data (and does the encrypting for you).

Secret Manager

A secret is a named container. The actual values are versions inside it, numbered 1, 2, 3 and so on. A version is immutable: to change a password you add a new version rather than editing the old one. Read-only commands for the common flow:

Terminal
gcloud services enable secretmanager.googleapis.com

gcloud secrets create db-password --replication-policy=automatic

printf 's3cr3t-value' | gcloud secrets versions add db-password --data-file=-

gcloud secrets versions access latest --secret=db-password

Notes on those commands:

  • Feeding the value through stdin keeps it out of shell history better than putting it on the command line, but always treat the terminal as sensitive.
  • latest is an alias that always points to the newest enabled version. For production, many teams pin a specific version number so a bad new value cannot break a running service by surprise, then roll forward on purpose.
  • Versions can be disabled (reversible) or destroyed (permanent), which is how you retire a leaked value.

Access is controlled by IAM (IAM basics). The key role is roles/secretmanager.secretAccessor, which lets a service account read values. Grant it on the single secret, not the whole project:

Terminal
gcloud secrets add-iam-policy-binding db-password \
  --member="serviceAccount:[email protected]" \
  --role="roles/secretmanager.secretAccessor"

Services such as Cloud Run can expose a secret to your container as an environment variable or as a mounted file, so your code reads it like any configuration while the value itself never lives in your repository. In code, a client library fetches it at startup:

Python
from google.cloud import secretmanager

client = secretmanager.SecretManagerServiceClient()
name = "projects/my-project-id/secrets/db-password/versions/latest"
password = client.access_secret_version(name=name).payload.data.decode("utf-8")

Replication policy: automatic or user-managed

A secret's replication policy decides in which regions its payload is stored. It is chosen when the secret is created and cannot be changed afterwards.

  • Automatic: Google decides where to store replicas and maximizes availability. This is the default and the simplest, and the secret is not tied to any particular region.
  • User-managed: you list the regions (--replication-policy=user-managed --locations=europe-west1,europe-west4). Use it when data-residency rules say a secret may only live in certain countries, or when you want it near the workloads that read it.
Terminal
gcloud secrets create eu-api-key --replication-policy=user-managed \
  --locations=europe-west1,europe-west4

Both policies keep several copies for availability. The choice is about where (regionalization and compliance), not whether the secret is replicated.

Python Which regions hold the secret?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Rotation

Secrets should change over time, and they must change quickly after any suspected leak. Secret Manager can send a notification on a schedule (through Pub/Sub) so that your own code can generate a new password, update the database, and add a new version. The service does not change the password in your database by itself; the rotation logic is yours. A good rotation plan has three steps: add the new version, restart or reload consumers, then disable the old version after you have checked that nothing still uses it.

Cloud KMS

Cloud KMS stores keys in key rings (a grouping by location) as keys, each with numbered key versions. You ask KMS to encrypt or decrypt, and the key material never leaves the service (hardware-backed options also exist).

Terminal
gcloud kms keyrings create app-keys --location=europe-west1

gcloud kms keys create orders-key \
  --keyring=app-keys --location=europe-west1 \
  --purpose=encryption \
  --rotation-period=90d \
  --next-rotation-time=2027-01-15T00:00:00Z

echo -n "card ending 4242" | gcloud kms encrypt \
  --keyring=app-keys --location=europe-west1 --key=orders-key \
  --plaintext-file=- --ciphertext-file=note.enc

A symmetric key can rotate automatically: a new version becomes primary for new encryptions, while old versions stay available to decrypt old data. Rotation is therefore cheap and does not require re-encrypting everything.

Envelope encryption

KMS requests are meant for small payloads, and calling KMS for every byte of a large file would be slow. The standard solution is envelope encryption:

Envelope encryption in four steps

Make a data key Generate a fresh random key locally for this one file.
Encrypt the data Use the data key to scramble the large payload.
Wrap the key Ask KMS to encrypt the data key with the master key.
Store both Keep the ciphertext and the wrapped key together.

To read, have KMS unwrap the data key, then decrypt locally.

1 / 2

The wrapped data key is safe to store next to the data because only KMS can unwrap it, and KMS checks IAM first. Revoking someone's permission on the master key makes every file they could reach unreadable to them, and you can rotate the master key without touching the data.

sequenceDiagram
  participant App
  participant KMS
  participant Store as Storage
  App->>App: generate data key, encrypt file
  App->>KMS: wrap(data key)
  KMS-->>App: wrapped key
  App->>Store: ciphertext + wrapped key
  Store-->>App: (later) ciphertext + wrapped key
  App->>KMS: unwrap(wrapped key)
  KMS-->>App: data key

The big data never goes to KMS; only the tiny key does.

CMEK: bring your own key

By default, Google encrypts your data at rest in its services with keys it manages, and you do nothing. Customer-managed encryption keys (CMEK) let a service such as Cloud Storage, BigQuery or Compute Engine disks use a KMS key you control. You gain the ability to disable or destroy the key, set rotation, and see key usage in audit logs. You also take on a duty: if you destroy a key, the data it protects is gone for good. Use CMEK when a compliance rule demands it, not as a default.

A stand-in: envelope encryption with node:crypto

The Piston runner has no network and no Google account, so the "KMS" below is a small class of ours that holds a master key in memory. The encryption itself is real: AES-256-GCM from Node's built-in node:crypto. A real KMS would run in Google's service, check IAM, and never hand out its key. The point here is the flow, not the product.

Node.js Stand-in: envelope encryption

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Run it a few times: the lengths stay the same while the random bytes change. The data key is different for every message, so exposing one data key reveals only one message.

A stand-in: versions and rotation

This second demo models secret versions, latest, pinning and disabling. It is a plain data structure, not Google's API.

JS Stand-in: secret versions, latest and pinning

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Habits that pay off

  • Never commit secrets; add secret files to .gitignore and scan repositories for leaked keys.
  • One secret per purpose, with secretAccessor granted to one service account on that secret.
  • Rotate on a schedule, and immediately after any possible exposure.
  • Use KMS and CMEK deliberately; remember that destroying a key destroys the data under it.
  • Do not log secret values. Log that a secret was read, never what it contained.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You want your app to read a database password at startup. Which service fits?

    Secret Manager holds values the app needs to read. KMS manages keys and performs cryptographic operations.
  2. 2. In envelope encryption, what does KMS encrypt?

    The data is encrypted locally with a data key, and KMS wraps that small key so only authorized callers can unwrap it.
  3. 3. What happens to a secret when you add a new version?

    Versions are immutable. Old versions remain until disabled or destroyed, so you can roll back or retire them deliberately.
  4. 4. What is the main risk of destroying a CMEK key?

    Without the key, nothing can decrypt the data. That is both the power of CMEK and the reason to guard key deletion.

Summary

  • Secret Manager stores secret values as immutable versions with IAM-controlled access; rotation logic is yours.
  • Cloud KMS manages keys and does cryptography without exposing key material; keys rotate by creating new versions.
  • Envelope encryption encrypts data locally with a data key and uses KMS only to wrap that key.
  • CMEK gives you control of the key behind a Google service, and the responsibility that goes with it.
  • The runnable demos are stand-ins: real encryption, but not Google's service.

Next: Compute Engine Virtual Machines