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 b11d490
Browse filesBrowse the repository at this point in the historyBrowse files
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]>
Copy file name to clipboardExpand all lines: packages/apps/openbao/README.md
+12-5Lines changed: 12 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,6 +9,8 @@ It provides identity-based secrets and encryption management for cloud infrastru
9
9
10
10
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.
11
11
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
+
12
14
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`.
13
15
14
16
```bash
@@ -48,15 +50,20 @@ To rotate the key:
48
50
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
51
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.
50
52
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
+
51
57
### Migrating an existing instance from Shamir
52
58
53
59
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
60
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.
60
67
61
68
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`.
0 commit comments