AWS KMS Key Manager

The AWS KMS Key Manager stores the Trust Domain Server's signing keys in AWS Key Management Service (KMS) rather than in a Kubernetes CRD. This provides HSM-backed key storage, centralized key management, and CloudTrail audit logging of all signing operations.

How it works

On startup, the Trust Domain Server discovers its signing keys in KMS using reserved tags applied at key creation time. New keys are created during key rotation, not on startup. Cryptographic operations (signing, key generation) are performed inside KMS; the private key material never leaves AWS infrastructure.

How to Deploy

Step 1 — Set Up AWS IAM

The Trust Domain Server needs an IAM role with the following permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:CreateKey",
        "kms:GetPublicKey",
        "kms:ScheduleKeyDeletion",
        "kms:Sign",
        "kms:TagResource"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "tagging:GetResources"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "sts:GetCallerIdentity"
      ],
      "Resource": "*"
    }
  ]
}

For EKS deployments, use IRSA (IAM Roles for Service Accounts) to associate this role with the Trust Domain Server's Kubernetes service account.

Step 2 — Update cluster configuration

section: KeyManager
schema: v1
spec:
  extensions:
    awsKMS:
      region: "us-east-1"

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:
          awsKMS:
            region: "us-east-1"
    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
region	No	AWS SDK default (local region)	AWS region where KMS keys will be created and stored.
keyPolicyFile	No	Auto-generated from Trust Domain Server IAM role	Path to a custom KMS key policy JSON file, accessible from the Trust Domain Server.
keyTags	No	None	User-defined tags applied to all KMS keys created by the Trust Domain Server. Tag keys cannot use the aws: or defakto- prefixes.

Step 3 — Verify

On startup, the Trust Domain Server logs which KMS key aliases or IDs it is using. Check CloudTrail for kms:Sign events to confirm signing operations are being routed through KMS.

Migration

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

1. Prepare AWS resources — Set up your IAM role and permissions as described above.
2. Apply the AWS KMS configuration — Use spirlctl config set to add the KeyManager section with the awsKMS extension. The AWS 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 AWS KMS. The previous 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 KMS. All signing is performed via KMS API calls. Private key bytes are not accessible to the Trust Domain Server process.
• CloudTrail audit. Every kms:Sign call appears in CloudTrail with the caller identity, timestamp, and key ID.
• Automatic key cleanup. Defakto automatically schedules unused keys for deletion in KMS. Orphaned keys are cleaned up every 48 hours, and stale keys from decommissioned deployments are removed every 24 hours.
• Region availability. The Trust Domain Server depends on KMS availability in the configured region. Plan for cross-region failover if required.