Cloud KMS
Cloud KMS (Key Management Service) stores the encryption keys that services use on your behalf. The GCP platform creates two key rings: one for the customer-managed encryption of the audit trail, one with a key per stage for the secrets encrypted in Git.
What it does
A key ring groups keys in one location, and each key has versions; the primary version encrypts, any enabled version decrypts. Automatic rotation creates a new primary version on a schedule. Key rings and keys can never be deleted in Cloud KMS, only their versions destroyed. A service encrypts with a customer-managed encryption key (CMEK) when its service agent holds roles/cloudkms.cryptoKeyEncrypterDecrypter on the key; a person or pipeline uses a key directly with the same role, or with Decrypter alone to read only. Keys are software-protected by default, or held in a hardware security module (HSM) at a higher price.
How BuiltForProd uses it
One module, modules/kms, builds both key rings. Every key is symmetric, rotates every 365 days, is software-protected and carries prevent_destroy, so a plan that would remove it fails.
| Key ring | Project | Keys | Who uses them |
|---|---|---|---|
acme-audit | acme-core-audit | audit-logs | The project's Cloud Storage service agent and Cloud Logging CMEK account |
acme-sops | acme-core-security | sops-sandbox, sops-dev, sops-staging, sops-prod | People and the secrets syncer, per stage (below) |
The audit key. The kms-audit unit creates the key in acme-core-audit, and the central log bucket and the archive bucket of Cloud Logging both encrypt with audit-logs. The module looks up the project's two service agents, which also makes Google create them if they do not exist yet, and grants each Encrypter/Decrypter on the key. The unit's comment names the HSM option (about $1 to $2.50 per key version per month).
The SOPS keys. The kms-sops unit gives each stage its own key and grants it narrowly:
| Principal | sops-sandbox, sops-dev | sops-staging, sops-prod |
|---|---|---|
acme-platform-leads, acme-devops-leads | Encrypter/Decrypter | Encrypter/Decrypter |
| Platform and DevOps engineers; app, ETL and AI leads and engineers | Encrypter/Decrypter | none |
sa-acme-secrets-syncer | Decrypter | Decrypter |
Each stage's key is published to that stage as the contract parameter platform--kms-sops-key, and the SOPS configuration of the Secrets Blueprint names the four keys.
Blueprint CMEK. The Data and ETL Blueprint can encrypt its lake buckets and BigQuery datasets with a key of your choice through the stage value kms_key_name, empty (Google-managed encryption) by default; the Cloud Storage and BigQuery service agents then need Encrypter/Decrypter on that key.
Terms you will see
| Term | Meaning |
|---|---|
| Key ring | A named, regional group of keys: acme-audit, acme-sops. |
| Key version | One generation of key material; rotation adds a new primary version. |
| CMEK | A customer-managed key a service encrypts its data with. |
| Service agent | The Google-managed account of a service that uses the key in your project. |
| Protection level | SOFTWARE here; HSM keeps the key in a hardware security module. |
Where to read more
- GCP Enterprise Baseline overview and the GCP Secrets Blueprint overview.
- SOPS for how the stage keys encrypt secrets in Git.
- Defense in depth for encryption as one layer among several.