Learn Secret Management - Automated Auto-Unseal Strategy in the Cloud
Automating OpenBao unsealing after maintenance with cloud KMS: configuring seal awskms on AWS, gcpckms on Google Cloud, and azurekeyvault on Microsoft Azure so the server is ready to serve immediately.
#Introduction
In episode 15 you built an HA cluster with Raft and node quorum. Episode 16 solves the one remaining operational problem: every time the server restarts — whether for maintenance or a reboot — OpenBao locks itself again and must be unsealed manually. With auto-unseal based on cloud KMS, the server unlocks itself on boot.
#Why Manual Unsealing Is a Problem
OpenBao stores its master key encrypted; to read it, you must enter a number of key shares until the threshold is met. In Shamir mode, that means a human must be present every time the server comes up. Imagine a five-node cluster rebooting at the same time — all of them waiting for a human.
Auto-unseal moves this responsibility to cloud KMS: the root key is encrypted with a KMS key, and on boot OpenBao asks the KMS to decrypt it. The server comes up without human intervention, which matters a lot for autoscaling and disaster recovery.
#How Auto-Unseal Works
The mechanism is similar: instead of splitting the master key into shares, OpenBao hands the root key encryption to the KMS. At startup, OpenBao contacts the KMS with the configured credentials, decrypts the root key, and proceeds to the unsealed state. Manual unseal keys are no longer needed on every restart.
#Auto-Unseal Configuration
The seal block in the configuration determines the KMS provider. Here are all three.
#AWS KMS
seal "awskms" {
region = "ap-southeast-1"
kms_key_id = "arn:aws:kms:ap-southeast-1:123456789012:key/abcd1234"
}
storage "raft" {
path = "/opt/openbao/data"
node_id = "node1"
}AWS credentials are taken from AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, from an instance profile, or from the SDK configuration. Make sure that role has kms:Decrypt and kms:Encrypt permissions on the key pointed to by kms_key_id.
#GCP Cloud KMS
seal "gcpckms" {
project = "my-project"
region = "global"
key_ring = "openbao-keys"
crypto_key = "openbao-unseal"
}GCP authentication uses Application Default Credentials. OpenBao looks for the key in the designated key_ring and crypto_key, in the specified region. The cloudkms.cryptoKeyVersions.useToDecrypt permission is required.
#Azure Key Vault
seal "azurekeyvault" {
tenant_id = "12345678-1234-1234-1234-123456789012"
client_id = "12345678-1234-1234-1234-123456789013"
client_secret = "client-secret"
vault_name = "openbao-kv"
key_name = "openbao-unseal"
}A service principal with unwrap permission on the key in Key Vault becomes the credentials used. Each provider has its own parameters and authentication method, but the end result is the same: the server unlocks itself.
#KMS Provider Comparison
| Aspect | AWS KMS | GCP Cloud KMS | Azure Key Vault |
|---|---|---|---|
| Seal block | awskms | gcpckms | azurekeyvault |
| Authentication | Access key or instance profile | Application Default Credentials | Service principal |
| Main parameters | region, kms_key_id | project, key_ring, crypto_key | tenant_id, vault_name, key_name |
| Key permissions | kms:Decrypt and Encrypt | useToDecrypt | unwrap key |
Choose the provider based on where you already run in the cloud. They all support the same goal: eliminating the manual unseal ritual.
Important
The KMS key used for auto-unseal is the last guardian of all your secrets. Protect access to that key as tightly as possible — anyone who can unlock the KMS key can unlock OpenBao. For example, restrict the IAM role to only kms:Decrypt on the specific key.
#Migrating from a Shamir Seal to KMS
If you have been using a Shamir seal for a long time, there is no need to rebuild from scratch. OpenBao supports seal migration: change the seal block in the configuration, restart the server, then unseal once with the old key shares.
bao operator unseal
bao operator unseal
bao operator unsealOnce the Shamir threshold is met during the migration process, the root key is re-encrypted using the new KMS key. From then on, bao operator unseal is no longer called manually — the server unlocks itself through the KMS on every boot.
Tip
Keep the old key shares until the migration is truly proven successful. Only after the server restarts and comes back unsealed automatically can the old key shares be safely destroyed.
#Limitations and Security Considerations
Auto-unseal is not magic. If the KMS is unreachable at boot, OpenBao stays locked until the connection recovers. For full readiness:
- Make sure KMS credentials are stored in a safe place: a secrets manager, instance profile, or service account.
- Combine with an HA cluster so failover does not wait for a human.
- Test recovery scenarios: shut down a node, reboot it, and confirm it comes back unsealed without intervention.
#Conclusion
In this episode 16, you understood why manual unsealing is an operational burden, how KMS-based auto-unseal works, and the seal "awskms", seal "gcpckms", and seal "azurekeyvault" configurations so OpenBao is ready to serve immediately after the server boots.
Key takeaways:
- Auto-unseal moves root key encryption from Shamir shares to cloud KMS.
- The server unlocks itself on boot without human intervention.
- Choose the provider based on your infrastructure: AWS, GCP, or Azure.
- Protect the KMS key as tightly as possible; it is the security foundation of the entire cluster.
In the next episode, episode 17, we close the last layer before production: audit logging, security hardening, and compliance to keep OpenBao transparent and well-documented.