Transit¶
This guide declares encryption keys of OpenBao's transit secrets engine in Kubernetes, with scheduled rotation and an on-demand rotation from Git.
Before you begin¶
A Ready connection whose OpenBao policy allows sys/mounts/<mount> to enable the engine, and
<mount>/keys/* for the keys (OpenBao policy for the operator).
1. Enable the engine¶
Create a SecretsMount with type: transit, as in this fragment of a spec:
2. Create the keys¶
A TransitKey creates a key and keeps its settings. This file has an AES-256-GCM encryption key
that rotates every 30 days and an HMAC key:
# An AES-256-GCM transit key for application encryption that rotates every 30 days, plus an HMAC key.
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: TransitKey
metadata:
name: obco-app-encryption
namespace: openbao-config
spec:
connectionRef:
kind: OpenBaoConnection
name: openbao
creationPolicy: CreateOrAdopt
deletionPolicy: Orphan
driftDetection: Enabled
mountPath: transit
name: obco-app
type: aes256-gcm96
derived: true
convergentEncryption: true
exportable: true
allowPlaintextBackup: true
autoRotatePeriod: 720h
minDecryptionVersion: 1
minEncryptionVersion: 0
deletionAllowed: false
rotateNonce: "2026-11-14"
---
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: TransitKey
metadata:
name: obco-app-hmac
namespace: openbao-config
spec:
connectionRef:
kind: OpenBaoConnection
name: openbao
mountPath: transit
type: hmac
keySize: 64
autoRotatePeriodmakes OpenBao rotate the key on a schedule.rotateNoncerotates the key once each time you change it to a new value, for example after an incident. The first value the operator sees does not rotate.minDecryptionVersionkeeps old key versions from decrypting.type,derived,convergentEncryptionandkeySizeare immutable, andexportableandallowPlaintextBackupcannot be turned off once on: the API server refuses such a change.
Both keys keep the default deletionPolicy: Orphan, so deleting a resource leaves its key in OpenBao.
TransitKey is a destructive kind (ADR 0013): to destroy the key
when its resource is deleted, set deletionPolicy: Delete and the annotation
openbaoconfig.io/allow-destructive-delete: "true". With both, the operator sets deletionAllowed just before
it deletes the key. The deletion is irreversible: data encrypted with a deleted key cannot be decrypted again.
3. Check that it worked¶
Both keys show Ready True, and OpenBao lists the key's versions and settings.
Troubleshooting¶
| symptom | check |
|---|---|
kubectl apply is refused with type is immutable or a similar message |
the field is fixed at creation: create a new key under another name instead |
rotateNonce changed but the version did not |
a value seen first at creation or adoption does not rotate; change it again |
| encryption fails with a context error | a derived key needs a context on every request |
Related¶
- API reference: TransitKey, SecretsMount.