You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 79d805e
Browse filesBrowse the repository at this point in the historyBrowse files
docs(openbao): key rotation needs an explicit pod replacement and a re-wrap check
The upstream chart updates the StatefulSet with OnDelete and the server
copies its HCL to /tmp/storageconfig.hcl at startup, so changing
seal.secretName never reaches a running pod. Document the replacement
order for standalone and HA (standbys first, active last), the log line
the new active node writes when it re-wraps the stored keys, and why
the previous key has to stay configured until then.
Signed-off-by: txmazing <[email protected]>
Copy file name to clipboardExpand all lines: packages/apps/openbao/README.md
+21-2Lines changed: 21 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -27,7 +27,26 @@ By default OpenBAO uses Shamir key shares: after every pod restart an operator h
27
27
28
28
`keyId` is a permanent identifier for that key material. OpenBAO refuses to start with a key whose identifier it has already seen with different material, so change `keyId` whenever you change the key.
29
29
30
-
To rotate the key, create a second Secret, move the current pair to `previousSecretName`/`previousKeyId` and put the new pair in `secretName`/`keyId`. This is the n-1 rotation the static seal documents: `current_key`is used for new seal operations while `previous_key` still decrypts what was written before. Keep both Secrets in place until OpenBAO has re-wrapped storage with the new key, then drop the `previous*` values and delete the old Secret.
30
+
To rotate the key:
31
+
32
+
1. Create a second Secret with the new key material and pick a new `keyId`.
33
+
2. Move the current pair to `previousSecretName`/`previousKeyId`, put the new pair in `secretName`/`keyId` and upgrade the release. This only changes the StatefulSet template. The upstream chart uses the `OnDelete` update strategy and the server copies its HCL to `/tmp/storageconfig.hcl` at startup, so running pods keep the old key and the old config until they are replaced.
34
+
3. Replace the pods. Standalone: delete the single pod. HA: delete the standby pods one at a time, waiting for each to rejoin and unseal, then delete the active pod so that leadership moves to a pod that already runs the new config. Do not delete the active pod first: once a node with the new config has taken over, a standby still on the old template cannot unseal after a restart.
35
+
36
+
```bash
37
+
kubectl -n <namespace> delete pod <release>-2 # standby
38
+
kubectl -n <namespace> delete pod <release>-1 # standby
39
+
kubectl -n <namespace> delete pod <release>-0 # active, last
40
+
```
41
+
42
+
4. Confirm the rotation before touching the old key. The node that becomes active with the new config re-wraps the stored barrier and recovery keys with `current_key` and logs it:
Until those lines have appeared, storage is still wrapped with the previous key. The static seal decrypts by the key identifier stored with the data and refuses an identifier it does not know (`unknown key id for data`), which is why both keys have to stay configured until the re-wrap is done.
49
+
5. Drop the `previous*` values, upgrade, and replace the pods once more in the same order. A pod that unseals with the new key alone proves the re-wrap. Delete the old Secret last.
31
50
32
51
> Switching an existing Shamir-sealed instance to `static` is a seal migration and needs `bao operator unseal -migrate`; see the OpenBAO [seal migration](https://openbao.org/docs/concepts/seal/#seal-migration) documentation. The chart does not run the migration for you. It does refuse to change `seal.type` on an instance that already runs with another seal, because a plain config change would leave a barrier nobody can decrypt. Set `seal.allowMigration: true` only for the upgrade in which you run the migration, then remove it. Migrating away from `static` needs the old stanza kept with `disabled = "true"` and its key still mounted, which this chart does not render; that direction is refused regardless of `allowMigration`.
33
52
@@ -64,7 +83,7 @@ Keep a copy of the key outside the cluster: a Raft snapshot or a data PVC is unr
64
83
| `seal.type` | Seal type. `shamir` keeps the current behaviour; `static` enables auto-unseal from `secretName`. | `string` | `shamir` |
65
84
| `seal.secretName` | Existing Secret in the release namespace whose key `key` holds the base64 text of 32 random bytes (for example `openssl rand -base64 32`). Required when `type` is `static`. | `string` | `""` |
66
85
| `seal.keyId` | Permanent identifier of the current key. Change it whenever the key material changes; OpenBAO refuses a key whose identifier it has already seen with different material. Required when `type` is `static`. | `string` | `""` |
67
-
| `seal.previousSecretName` | Secret holding the previous key during an n-1 key rotation. | `string` | `""` |
86
+
| `seal.previousSecretName` | Secret holding the previous key during an n-1 key rotation. Keep it until the pods have been replaced and the active node has logged `upgrading stored keys`; see the README. | `string` | `""` |
68
87
| `seal.previousKeyId` | Identifier of the previous key. Required when `previousSecretName` is set. | `string` | `""` |
69
88
| `seal.allowMigration` | Acknowledge a seal migration. The chart refuses to change `type` on an existing instance unless this is `true`; set it only while running `bao operator unseal -migrate`, then remove it. | `bool` | `false` |
Copy file name to clipboardExpand all lines: packages/apps/openbao/values.schema.json
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -158,7 +158,7 @@
158
158
"default": ""
159
159
},
160
160
"previousSecretName": {
161
-
"description": "Secret holding the previous key during an n-1 key rotation.",
161
+
"description": "Secret holding the previous key during an n-1 key rotation. Keep it until the pods have been replaced and the active node has logged `upgrading stored keys`; see the README.",
Copy file name to clipboardExpand all lines: packages/apps/openbao/values.yaml
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -94,7 +94,7 @@ ui: true
94
94
## @field {SealType} type - Seal type. `shamir` keeps the current behaviour; `static` enables auto-unseal from `secretName`.
95
95
## @field {string} secretName - Existing Secret in the release namespace whose key `key` holds the base64 text of 32 random bytes (for example `openssl rand -base64 32`). Required when `type` is `static`.
96
96
## @field {string} keyId - Permanent identifier of the current key. Change it whenever the key material changes; OpenBAO refuses a key whose identifier it has already seen with different material. Required when `type` is `static`.
97
-
## @field {string} [previousSecretName] - Secret holding the previous key during an n-1 key rotation.
97
+
## @field {string} [previousSecretName] - Secret holding the previous key during an n-1 key rotation. Keep it until the pods have been replaced and the active node has logged `upgrading stored keys`; see the README.
98
98
## @field {string} [previousKeyId] - Identifier of the previous key. Required when `previousSecretName` is set.
99
99
## @field {bool} [allowMigration] - Acknowledge a seal migration. The chart refuses to change `type` on an existing instance unless this is `true`; set it only while running `bao operator unseal -migrate`, then remove it.
0 commit comments