Service Account Design Guide for GCP KMS Auto Unseal (For Vault Ops)

Vault Auto Unseal automatically decrypts the master key at startup by depending on an external KMS, reducing the operational burden of manual unsealing. On GCP, the gcpckms seal using Cloud KMS is officially supported.

From an Ops perspective, this article focuses on service account (SA) design for GCP KMS Auto Unseal. We organize the exam-relevant points (least privilege, key material handling, Workload Identity recommendation) along with the operational pitfalls around permissions, location mismatches, and log auditing.

How It Works and Responsibility Boundaries

Vault's gcpckms seal wraps/unwraps Vault's master key using a Cloud KMS symmetric key (purpose=encryption). At startup, the Vault process calls Cloud KMS Encrypt/Decrypt APIs using the attached SA's ADC (Application Default Credentials). Once decryption succeeds, it can read data from storage (Raft, GCS, etc.).

The key design point is that Auto Unseal only requires KMS Encrypt/Decrypt permissions. Management permissions like KMS key creation, rotation, and policy changes should be separated into a different SA. This way, even if the Vault runtime SA is compromised, the damage to key management is contained.

• Vault runs with only KMS Encrypt/Decrypt permissions (including initialization and re-encryption)
• The KMS key location must match the region in Vault's configuration
• ADC uses attached SAs on GCE/GKE or Workload Identity depending on the environment. Avoid distributing key files

GCP KMS Auto Unseal call flow (high level)

Service Account Role Separation (Principle of Least Privilege)

Auto Unseal requirements are narrow. Always separate the often-confused "Vault runtime SA (for Unseal)" and "KMS management SA (key lifecycle)." Further splitting out the permissions needed for Vault's data storage and audit log destinations clarifies fault isolation and permission boundaries.

Exam note: Do not grant admin roles (Owner/Editor, KMS Admin) to the Unseal SA. The iron rule is to grant roles/cloudkms.cryptoKeyEncrypterDecrypter scoped to the KMS key resource.

• Unseal SA: KMS Encrypt/Decrypt only (per-key scope)
• KMS management SA: key creation, rotation, IAM updates (project/keyring scope)
• Storage SA: GCS and network permissions minimized via separate roles

Concrete Least-Privilege IAM (Cloud KMS)

The permission required for Vault's gcpckms seal is the principal role roles/cloudkms.cryptoKeyEncrypterDecrypter, which encapsulates cloudkms.cryptoKeyVersions.useToEncrypt and cloudkms.cryptoKeyVersions.useToDecrypt. Grant it only on the target cryptoKey. Granting it broadly at project or keyring level invites unintended key usage.

When using Workload Identity, grant the above role to the GSA via the KSA→GSA binding. On GCE, attach the target GSA to the instance/template and confirm that unnecessary default Editor roles, etc., are not attached.

• Location match: align the KMS key location with Vault's region (= KMS location)
• Org policy/tags: set labels and tags on KMS keys to clarify access boundaries
• Auditability: always enable Cloud Audit Logs for KMS Decrypt/Encrypt calls

Deployment Patterns (GCE / GKE Workload Identity / Autopilot)

GCE: Attach the Vault runtime SA to the instance (or MIG). ADC is supplied via metadata. No key files needed.

GKE Workload Identity: Bind the GSA to the KSA, run the Pod with the KSA, and grant the KMS role to the GSA. Autopilot follows the same flow but does not require directly editing the node SA.

• GCE: Pin the service account in the instance template, and prefer the default (minimum) scope over full Cloud API access
• GKE: Bind the GSA to the KSA via annotations and align with RBAC and PSP/PodSecurity
• In all cases, strictly enforce the no-key-file-distribution policy

Security Boundaries and Auditing (Operational Essentials)

For auditing, continuously log KMS Encrypt/Decrypt calls in Cloud Audit Logs and correlate them with Vault startup times and scale events. Set up SIEM notifications to immediately detect abnormal frequency or off-hours Decrypt activity.

Rotate keys in KMS; Vault can automatically Encrypt/Decrypt with the new version (the Decrypter still works on older versions). Document SLOs for rotation cadence and key lifetimes, and mirror the same permission design at backup/DR sites.

• Split KMS keys by purpose (dedicate one for Vault)
• Alert on Decrypt rate limits and failures
• If using boundaries like VPC Service Controls, include KMS access within the perimeter

Implementation Steps and Troubleshooting

Below is a least-privilege example. The location is global as a sample. In production, choose based on latency and regulatory requirements.

Typical failures include location mismatches, attaching the wrong SA, over-/under-scoped KMS roles, and broken Workload Identity bindings. Cross-reference error messages with audit logs for fast isolation.

• Create keys with purpose=encryption (symmetric)
• Grant only roles/cloudkms.cryptoKeyEncrypterDecrypter to the Unseal SA
• The region in Vault's config must match the KMS key's location

Example procedure (gcloud + Vault config)

# 0) 変数
PROJECT_ID="my-project"
LOCATION="global"
KEYRING="vault-unseal"
KEY="vault-unseal-key"
UNSEAL_SA_NAME="vault-unseal-sa"
UNSEAL_SA="${UNSEAL_SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

# 1) SA作成（Unseal用）
gcloud iam service-accounts create ${UNSEAL_SA_NAME} \
  --project=${PROJECT_ID} \
  --description="Vault Auto Unseal runtime SA" \
  --display-name="Vault Unseal SA"

# 2) KMSキーリングとキー（対称鍵）
gcloud kms keyrings create ${KEYRING} \
  --location=${LOCATION} --project=${PROJECT_ID}

gcloud kms keys create ${KEY} \
  --location=${LOCATION} --keyring=${KEYRING} \
  --purpose=encryption --project=${PROJECT_ID}

# 3) 最小権限の付与（cryptoKeyスコープ）
gcloud kms keys add-iam-policy-binding ${KEY} \
  --location=${LOCATION} --keyring=${KEYRING} \
  --member=serviceAccount:${UNSEAL_SA} \
  --role=roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project=${PROJECT_ID}

# 4) GCEにアタッチ（例）
#   インスタンステンプレートで --service-account ${UNSEAL_SA}
#   GKEの場合はWorkload IdentityでGSA:${UNSEAL_SA}をKSAにバインド

# 5) Vaultサーバ設定（gcpckmsシール）
#   region はKMSのlocationに合わせる（例: global, us-east1 など）
cat >/etc/vault.d/vault.hcl <<'EOF'
ui = true
listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = 1
}
storage "raft" {
  path = "/opt/vault/data"
}
seal "gcpckms" {
  project    = "my-project"
  region     = "global"      # = KMS location
  key_ring   = "vault-unseal"
  crypto_key = "vault-unseal-key"
}
EOF

# 6) 起動と初期化
# systemctl enable --now vault
# vault operator init -key-shares=1 -key-threshold=1
# -> Auto Unsealのため、起動時にKMSへ自動Decrypt呼び出し

# トラブルシュートの要点
# - permission denied: iamPolicyBindingの対象が"cryptoKey"か再確認
# - location mismatch: vault.hclのregionとKMSキーlocationが同一か
# - Workload Identity: KSA<->GSAバインド、トークンのAudience設定を再確認
# - 429 / rate limit: 再試行間隔、起動のスロットリング、KMS割当の見直し

Check Your Understanding

Frequently Asked Questions