Vault × AWS KMS Auto Unseal: A Practical IAM Design and Operations Guide

AWS KMS Auto Unseal is a mechanism where Vault sends a decryption request to KMS at startup and unseals automatically. It significantly reduces the operational burden of manual unsealing.

This article walks through the design of IAM roles, KMS keys, and the startup path, as well as auditing, DR, and rotation — all from a real-world operations perspective. Areas where version differences tend to show up are called out as warnings.

How AWS KMS Auto Unseal Works and Its Prerequisites

Vault has an internal master key used for storage encryption. In an Auto Unseal configuration, this master key is wrapped (encrypted) by AWS KMS and stored, and at startup Vault uses the KMS decrypt API to unseal automatically. This eliminates the need for Shamir-based manual unsealing.

The prerequisites are a symmetric KMS key (customer-managed key), a least-privilege IAM role for that key, and reachability from the Vault server to the KMS endpoint. The core permissions are typically kms:Decrypt and kms:Encrypt; depending on environment and version, kms:DescribeKey or the kms:GenerateDataKey family may also be referenced.

• Vault's awskms seal halts at the startup phase if KMS decryption fails
• A KMS key that is disabled or pending deletion cannot be used to unseal
• Using encryption context (kms_context) reduces the risk of key misuse
• Even with Auto Unseal, handling and auditing the initial Root Token remains critical

High-level Auto Unseal flow

Example Vault server configuration (awskms seal)

seal "awskms" {
  region      = "ap-northeast-1"
  kms_key_id  = "arn:aws:kms:ap-northeast-1:111122223333:key/abcd-ef01-2345-6789-abcdef012345"
  # 必要に応じてロール引受け
  role_arn    = "arn:aws:iam::111122223333:role/vault-unseal"
  # 誤用防止のための暗号化コンテキスト（推奨）
  kms_context = "App=vault-prod"
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = 1
}

storage "raft" {
  path = "/opt/vault/data"
  node_id = "vault-1"
}

Designing the IAM Role and KMS Key (Least Privilege and Multi-Account)

The basic approach is to prepare an IAM role attached to the Vault runtime (EC2/VM/container) and grant least-privilege permissions on the target KMS key. In a single-account setup, allowing it only through the IAM policy is enough, but explicitly listing the Principal in the key policy is also a stable operating pattern.

For cross-account, either the role in the Vault account assumes a role in the KMS account, or the KMS key policy permits the Vault account's role as a Principal. Either way, kms:Decrypt and kms:Encrypt are the core actions, and DescribeKey is useful for health checks. Combine this with encryption context (kms_context) to conditionally prevent key misuse.

• Core of least privilege: kms:Decrypt, kms:Encrypt (and, as needed, kms:DescribeKey and the kms:GenerateDataKey family)
• Spelling out the Principal in the key policy makes intent clear in operations that cross account boundaries
• Use encryption context as an IAM condition to prevent misuse and over-privilege
• Organize cross-account access with either AssumeRole or a Principal specified in the key policy

Example least-privilege IAM policy (combined with encryption context)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VaultKmsCore",
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt",
        "kms:Encrypt",
        "kms:DescribeKey"
      ],
      "Resource": "arn:aws:kms:ap-northeast-1:111122223333:key/abcd-ef01-2345-6789-abcdef012345",
      "Condition": {
        "StringEquals": {
          "kms:EncryptionContext:App": "vault-prod"
        }
      }
    }
  ]
}

Credential Supply and Stabilizing the Startup Path

Vault's awskms seal uses the AWS SDK's standard credential search order. In typical setups, it relies on role-based authentication from an EC2 instance profile or EKS IRSA, or it reads environment variables (such as AWS_ACCESS_KEY_ID).

Controlling the startup order matters in practice. If Vault starts before the network stack and the metadata service (IMDS/STS) are reachable, KMS decryption will fail. Stabilize it with systemd dependencies, retries (Restart=on-failure), and backoff.

• Preferred: easily rotatable role-based authentication (instance profile/IRSA)
• Restrict environment variables to testing or temporary use; avoid persisting them
• Pre-check reachability to the KMS region and VPC endpoint at startup
• Operate one-shot configuration via Cloud-Init or user data together with monitoring

Example systemd unit (dependencies and environment supply)

[Unit]
Description=HashiCorp Vault Server
After=network-online.target
Wants=network-online.target

[Service]
User=vault
Group=vault
EnvironmentFile=-/etc/vault.d/aws.env
ExecStart=/usr/local/bin/vault server -config=/etc/vault.d/vault.hcl
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Operations: Key Points for Availability, DR, and Rotation

Multi-AZ should be a given. To prepare for DR and regional failures, consider KMS multi-region keys. Replica keys share the same key ID lineage, making decryption compatibility easy to maintain, and you can design things so a Vault cluster starting in another region can still unseal with the same logical key.

KMS automatic rotation (for symmetric keys) is designed to preserve decryption compatibility for prior ciphertext, so normally no reconfiguration on the Vault side is required. Conversely, disabling a key or putting it in pending-deletion state makes unsealing impossible, so change management and a defined maintenance window are essential.

• Simplify DR design with multi-region keys
• Rotation is safe under the compatibility-preservation premise, but change management must be strict
• Reaching KMS privately via a VPC endpoint is also an effective design
• Monitor kms:Decrypt activity with CloudTrail and metrics

Representative CLI commands used in operations (examples)

# ローテーション有効化（対称キー）
aws kms enable-key-rotation --key-id arn:aws:kms:ap-northeast-1:111122223333:key/abcd-ef01-2345-6789-abcdef012345

# マルチリージョンキーのレプリカ作成（例）
aws kms replicate-key \
  --key-id arn:aws:kms:ap-northeast-1:111122223333:key/abcd-ef01-2345-6789-abcdef012345 \
  --replica-region us-west-2

Security Hardening and Auditing (Encryption Context / CloudTrail)

By setting an encryption context (kms_context) and requiring a match in IAM or key policy conditions, you can prevent misuse of the same key for other purposes. The exact string match between the Vault side and the policy side is the key.

For auditing, use CloudTrail to make kms:Decrypt and kms:Encrypt visible, and detect anomalous frequencies and denial events. Correlating with Vault audit logs makes timeline alignment easier and is effective for root-cause analysis.

• Manage kms_context as a fixed value such as the environment name (for example, App=vault-prod)
• Detect Decrypt failures immediately via CloudTrail Insights or alerts
• Strictly minimize the Principal in the key policy and use conditional allow statements
• Strictly separate test keys from production keys (manage with tags and policies)

Example KMS key policy (encryption context required)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowVaultRoleWithContext",
      "Effect": "Allow",
      "Principal": {"AWS": "arn:aws:iam::111122223333:role/vault-unseal"},
      "Action": ["kms:Decrypt", "kms:Encrypt", "kms:DescribeKey"],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:EncryptionContext:App": "vault-prod"
        }
      }
    }
  ]
}

Comparison With Other Methods and Migration Considerations

Auto Unseal excels at startup automation and audit ease, but it depends on KMS reachability and permissions. Shamir manual unsealing has fewer external dependencies but a high operational burden. Transit Auto-Unseal (Vault Transit) enables KMS-independent automation, but the availability of the central Transit becomes a new prerequisite.

When migrating from an existing cluster, reproduce the same configuration in a test environment in advance, verify KMS permissions, reachability, and context conditions, and then apply changes in stages. Allowed APIs may be added across version differences, so minimize and adjust the allowed actions while watching the audit logs.

• For production migration, switch one node at a time during planned downtime and confirm cluster stability — that is the safe approach
• Always prepare a rollback procedure (restoring the previous configuration and a manual unseal method)
• For cross-region or cross-account setups, confirm successful Decrypt in CloudTrail beforehand

Example pre-migration connectivity and permission tests (encrypt/decrypt)

# 1) テスト用の暗号化・復号（コンテキスト一致）
aws kms encrypt \
  --key-id arn:aws:kms:ap-northeast-1:111122223333:key/abcd-ef01-2345-6789-abcdef012345 \
  --plaintext "test" \
  --encryption-context App=vault-prod \
  --query CiphertextBlob --output text > /tmp/ctxt.b64

aws kms decrypt \
  --ciphertext-blob fileb:///tmp/ctxt.b64 \
  --encryption-context App=vault-prod \
  --query Plaintext --output text | base64 -d

# 2) Vaultの状態確認（起動後）
vault status

Check Your Understanding

Frequently Asked Questions