Skip to content

Commit 5ac585d

Browse files
committed
docs(openbao): spell out the Shamir to static seal migration steps
The migration note said what the chart refuses and where OpenBAO documents the migration, but not the order of operations under the OnDelete strategy. A Helm upgrade with allowMigration changes only the pod template, so a pod that is not replaced still runs the Shamir configuration when unseal -migrate is issued. The note is now a numbered procedure with the pod replacement, the per node unseal -migrate on the standby pods, the step-down of the active node and the final upgrade that drops allowMigration, following the OpenBAO seal migration documentation. Assisted-by: LLM Signed-off-by: Yan Bondarenko <[email protected]>
1 parent fd530c9 commit 5ac585d

1 file changed

Lines changed: 11 additions & 1 deletion

File tree

‎packages/apps/openbao/README.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,17 @@ To rotate the key:
4848
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.
4949
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. The cluster administrator deletes the old Secret last.
5050

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`.
51+
### Migrating an existing instance from Shamir
52+
53+
Switching a running Shamir-sealed instance to `static` is a seal migration, see the OpenBAO [seal migration](https://openbao.org/docs/concepts/seal/#seal-migration) documentation. The chart does not run it for you. It refuses a changed `seal.type` on an instance that already runs with another seal, because a plain config change would leave a barrier nobody can decrypt. OpenBAO documents the migration as a procedure with downtime, so plan a window.
54+
55+
1. A cluster administrator creates the key Secret as described above.
56+
2. Set `seal.type: static` with `secretName` and `keyId`, add `seal.allowMigration: true` and upgrade the release. The StatefulSet uses the `OnDelete` strategy, so the running pods keep the Shamir configuration until they are replaced.
57+
3. Standalone. Delete the pod. When it is back, run `bao operator unseal -migrate` with each Shamir unseal key. The server performs the migration and the Shamir keys become the recovery keys.
58+
4. HA. Delete one standby pod, wait for it to come back and run `bao operator unseal -migrate` on it with each Shamir unseal key. Repeat for the other standby pods one at a time. Then run `bao operator step-down` on the active node. The new active node performs the migration and logs its completion. Delete the old active pod last, so that it restarts with the static configuration and unseals on its own.
59+
5. Remove `seal.allowMigration` and upgrade the release once more.
60+
61+
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`.
5262

5363
Keep a copy of the key outside the cluster: a Raft snapshot or a data PVC is unreadable without it.
5464

0 commit comments

Comments
 (0)