GCP Cloud KMS Key Manager

The GCP Cloud KMS Key Manager stores the Trust Domain Server's signing keys in Google Cloud KMS. This provides HSM-backed key storage, centralized key management, and Cloud Audit Logs of all signing operations.

How it works

On startup, the Trust Domain Server verifies connectivity to the configured key ring. Signing keys are discovered lazily: Keys are loaded from Cloud KMS on demand during signing operations, not in bulk at startup. New keys are created during key rotation. All cryptographic operations (signing, key generation) are performed inside Cloud KMS. Private key material never leaves Google infrastructure.

How to Deploy

Step 1 — Set Up GCP IAM

Create a GCP service account and grant it the following permissions on the key ring resource:

cloudkms.keyRings.get
cloudkms.cryptoKeys.create
cloudkms.cryptoKeys.get
cloudkms.cryptoKeys.list
cloudkms.cryptoKeys.update
cloudkms.cryptoKeyVersions.destroy
cloudkms.cryptoKeyVersions.get
cloudkms.cryptoKeyVersions.useToSign
cloudkms.cryptoKeyVersions.viewPublicKey

You can grant these with a custom IAM role, or use the predefined roles/cloudkms.admin role scoped to the key ring:

gcloud kms keyrings add-iam-policy-binding KEY_RING \
  --location LOCATION \
  --project PROJECT_ID \
  --member "serviceAccount:SA_EMAIL" \
  --role roles/cloudkms.admin

For GKE deployments, use Workload Identity Federation to bind the Trust Domain Server's Kubernetes service account to the GCP service account:

gcloud iam service-accounts add-iam-policy-binding SA_EMAIL \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"

Then annotate the Kubernetes service account:

kubectl annotate serviceaccount KSA_NAME \
  --namespace NAMESPACE \
  iam.gke.io/gcp-service-account=SA_EMAIL

Step 2 — Update cluster configuration

The key ring must already exist before configuring the key manager. The Trust Domain Server will not create the key ring — only the keys within it.

section: KeyManager
schema: v1
spec:
  extensions:
    gcpKMS:
      projectID: "my-project"
      location: "us-central1"
      keyRing: "my-key-ring"

Apply it using spirlctl:

spirlctl config set trust-domain-deployment --id <deployment-id> key-manager.yaml

Or using Terraform:

resource "spirl_cluster_config" "key_manager" {
  cluster_id = spirl_cluster.my_cluster.id
  sections = {
    KeyManager = <<-YAML
      section: KeyManager
      schema: v1
      spec:
        extensions:
          gcpKMS:
            projectID: "my-project"
            location: "us-central1"
            keyRing: "my-key-ring"
    YAML
  }
}

Once a configuration document passes validation and is stored, the Defakto control plane syncs it to your Trust Domain Servers automatically. No server or agent restart is required.

Configuration Reference

Field	Required	Default	Description
projectID	Yes	—	GCP project ID where the key ring resides.
location	Yes	—	GCP region or multi-region for the key ring (e.g., us-central1, us-east1, global).
keyRing	Yes	—	Name of the existing Cloud KMS key ring. The key ring must exist before the Trust Domain Server starts.
credentialsFile	No	Application Default Credentials	Path to a service account key JSON file. If omitted, ADC is used (recommended for GKE with Workload Identity).
keyTags	No	None	User-defined labels applied to all Cloud KMS keys created by the Trust Domain Server. Label keys cannot use the google: or defakto- prefixes.

Step 3 — Verify

On startup, the Trust Domain Server logs confirmation of the key ring it connected to. Signing operations appear in Cloud Audit Logs under the cloudkms.googleapis.com service — look for AsymmetricSign method calls.

Migration

To migrate from the default CRD-based key manager to GCP Cloud KMS:

1. Prepare GCP resources — Create the key ring and set up IAM permissions as described above.
2. Apply the GCP Cloud KMS configuration — Use spirlctl config set to add the KeyManager section with the gcpKMS extension. The GCP Cloud KMS key manager becomes the active key manager immediately, but no new keys are generated at this point; existing CRD-based keys continue to handle all signing operations.
3. Wait for key rotation — At the next scheduled key rotation, new signing keys are created in Cloud KMS. The previous CRD-based keys remain active until they expire and are fully rotated out. Agents and workloads are not impacted during the transition.

This is a zero-downtime migration. The timeline to full migration depends on your key rotation schedule.

Security Considerations

• Key material never leaves Cloud KMS. All signing is performed via the Cloud KMS API. Private key bytes are not accessible to the Trust Domain Server process.
• HSM protection. All keys are created with HSM protection level. Key material cannot be exported.
• RSA-PSS not supported. RSA keys are created as PKCS#1 v1.5 — GCP KMS bakes the padding scheme into the key at creation time. PSS signing is not available with this key manager.
• Cloud Audit Logs. Every AsymmetricSign call appears in Cloud Audit Logs with the caller identity, timestamp, and key version name.
• Workload Identity. Use GKE Workload Identity Federation rather than a static service account key file so credentials rotate automatically.
• Automatic key cleanup. Defakto automatically schedules unused keys for destruction in Cloud KMS. Orphaned keys from the current deployment are cleaned up every 48 hours (keys with a heartbeat older than 48 hours). Stale keys from decommissioned deployments in the same trust domain are removed every 24 hours (keys with a heartbeat older than 14 days).
• Key ring availability. The Trust Domain Server depends on Cloud KMS availability in the configured region. Plan for multi-region key rings or cross-region failover if required.