Skip to content

Commit b11d490

Browse files
committed
docs(openbao): name the trade-off of the static seal and the pod replacement after the upgrade
The auto-unseal section told the reader to keep a copy of the key outside the cluster, which covers availability, and said nothing about confidentiality. With static the key sits in a Secret in the same cluster as the data it unwraps, so the barrier is worth what access to Secrets in that namespace, to etcd and to backups is worth. The section now says so before the reader picks a seal. The apiserver egress label is rendered through server.extraLabels, and the StatefulSet uses the OnDelete strategy, so pods created by an earlier chart version keep running without the label after the upgrade. An HA instance hung on the missing label stays hung until its pods are deleted. The README now has that step. Assisted-by: LLM Signed-off-by: Yan Bondarenko <[email protected]>
1 parent 2443c80 commit b11d490

1 file changed

Lines changed: 12 additions & 5 deletions

File tree

‎packages/apps/openbao/README.md‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ It provides identity-based secrets and encryption management for cloud infrastru
99

1010
By default OpenBAO uses Shamir key shares, so after every pod restart an operator has to unseal each replica by hand. Setting `seal.type: static` switches the instance to OpenBAO's [`seal "static"`](https://openbao.org/docs/configuration/seal/static/), which unseals the barrier from a 32-byte key read from a Secret in the tenant namespace. The chart never generates, stores or rotates the key. It only mounts the Secret you name.
1111

12+
The choice is a trade-off. With `static` the key sits in a Secret in the same cluster as the data it unwraps, so the barrier is only as strong as access to Secrets in that namespace, to etcd and to backups. Shamir keeps the key material out of the cluster at the price of a manual unseal after every restart. Pick `static` when availability after a restart matters more than that boundary.
13+
1214
1. A cluster administrator creates the key Secret in the tenant namespace. Tenant roles grant no access to Secrets, so tenant users can neither create the key nor read it back. The pods mount the Secret and do not start until it exists, so have it created before you set `seal.type: static`. The value is the base64 text of 32 random bytes, stored under the key `key`.
1315

1416
```bash
@@ -48,15 +50,20 @@ To rotate the key:
4850
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.
4951
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.
5052

53+
### Upgrading an existing instance
54+
55+
This version labels the server pods with `policy.cozystack.io/allow-to-apiserver: "true"`, which the tenant network policy needs before `service_registration "kubernetes"` can reach the API server (#2793). The StatefulSet uses the `OnDelete` strategy, so pods created by an earlier version keep running without the label after the upgrade. Delete them once, in HA mode one at a time, so that they come back labelled. An HA instance that hangs at start because of #2793 stays hung until its pods are replaced.
56+
5157
### Migrating an existing instance from Shamir
5258

5359
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.
5460

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.
61+
1. Take a restorable backup first, OpenBAO asks for one before any seal migration. In HA mode `bao operator raft snapshot save <file>` writes it, in standalone mode copy the data volume.
62+
2. A cluster administrator creates the key Secret as described above.
63+
3. 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.
64+
4. 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.
65+
5. 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.
66+
6. Remove `seal.allowMigration` and upgrade the release once more.
6067

6168
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`.
6269

0 commit comments

Comments
 (0)