docs/swarm: the store's init step, its identity, and its first reader
bao operator init stays manual: it emits recovery keys and a root token, so automating it would put the disaster-recovery material on the host it is the recovery path for. The unseal note is split by seal mode, since pkcs11 unseals itself and only shamir needs an operator per boot. secrets.md said nothing reads the store and nothing mints its identity; setup.md said the deployment must supply the certificate. All three are false now. They name the first reader, why that credential and not authelia's OIDC secret, that every failure path leaves the local token in place, and that the minted paths are mkDefaults an operator's own paths beat. Delta sweep clean: 0 hits for useSelfSigned / acme / swarm-services / 'nothing reads' / 'issued and unused'; control returns 12 for serverCertFile. The single 'no reader' hit is a module-eval comment describing the absence arm.
This commit is contained in:
parent
aa784a746d
commit
c1b7be1135
2 changed files with 64 additions and 5 deletions
|
|
@ -44,7 +44,41 @@ echo "hunter2" | hivectl gateway create-user mara --password-stdin
|
|||
hivectl gateway list-users
|
||||
```
|
||||
|
||||
### 3 · Swarm SSO (only when `deploy.authelia`)
|
||||
### 3 · Secret store (only when `deploy.bao`)
|
||||
|
||||
⚠️ **A sealed store still answers.** OpenBao starts uninitialised and
|
||||
sealed, so the container is up and the port responds while every read
|
||||
times out — the failure looks like a hang, not like a store that was
|
||||
never initialised. Do this before anything is pointed at it.
|
||||
|
||||
```bash
|
||||
# On the host that RUNS the store, once.
|
||||
bao operator init # keep the keys it prints and the root token OFF this host
|
||||
```
|
||||
|
||||
Whether anything more is needed depends on
|
||||
`services.hyperhive.deploy.bao.seal`:
|
||||
|
||||
- **`pkcs11`** (the default) — the key is bound to the host's TPM and the
|
||||
store unseals itself on every restart. `init` is the only manual step.
|
||||
- **`shamir`** — no TPM, so `bao operator unseal` is needed again after
|
||||
every restart, with the keys `init` printed.
|
||||
|
||||
The store serves TLS, and on a hive that deploys it you need do nothing: a
|
||||
first-boot unit mints a CA of the store's own plus the two leaves it signs —
|
||||
the store's server certificate and this host's client certificate — and points
|
||||
`deploy.bao.serverCertFile`, `.serverKeyFile` and `.clientCaFile` at them.
|
||||
|
||||
Those are `mkDefault`s, so naming your own paths wins. Do that when your
|
||||
certificates come from a real internal CA; the store has no opinion about
|
||||
which. ⚠️ Not the gateway's HTTPS certificates and not the hive CA — this is
|
||||
**mTLS between services and the store**, a separate trust domain, because a
|
||||
store that took its identity from an authority it will itself distribute could
|
||||
never come up before that authority.
|
||||
|
||||
Making even the `init` unnecessary is tracked in issue #3768.
|
||||
|
||||
### 4 · Swarm SSO (only when `deploy.authelia`)
|
||||
|
||||
⚠️ **Required to finish the install, not optional.** Authelia treats an
|
||||
empty user store as a fatal startup error, so until this runs the
|
||||
|
|
@ -70,7 +104,7 @@ than amend — adding the group afterwards is `swarmctl user update mara
|
|||
Detail, including what the password is and why this stays manual:
|
||||
[`swarm/sso.md`](swarm/sso.md).
|
||||
|
||||
### 4 · Swarm UI (only when `deploy.swarm-ui`, on by default with the controller)
|
||||
### 5 · Swarm UI (only when `deploy.swarm-ui`, on by default with the controller)
|
||||
|
||||
Nothing to run — it is served on the swarm apex
|
||||
(`https://<swarm.domain>/`) as soon as the host rebuilds. Two things
|
||||
|
|
@ -86,7 +120,7 @@ decide whether you can actually open it:
|
|||
Detail, including why reachability is deliberately not the access
|
||||
control: [`swarm/ui.md`](swarm/ui.md).
|
||||
|
||||
### 5 · Matrix
|
||||
### 6 · Matrix
|
||||
|
||||
```bash
|
||||
# 5a. Ensure the hive-internal admin account exists first
|
||||
|
|
@ -107,7 +141,7 @@ hivectl matrix promote-user mara
|
|||
The human operator's own matrix account is created via swarm SSO instead of
|
||||
a manual `hivectl` step — see step 3 (`swarmctl user add`).
|
||||
|
||||
### 6 · Spawn sub-agents
|
||||
### 7 · Spawn sub-agents
|
||||
|
||||
Sub-agent creation goes through the approval queue — ruth proposes, the
|
||||
operator approves, the container builds. From ruth's own turn (inside
|
||||
|
|
@ -128,7 +162,7 @@ request_init_config(name: "iris")
|
|||
|
||||
See [`approvals.md`](approvals.md) for the full flow.
|
||||
|
||||
### 7 · Useful host commands
|
||||
### 8 · Useful host commands
|
||||
|
||||
```bash
|
||||
# Roster: all agents, status, rev, parent, pending reminders
|
||||
|
|
|
|||
Loading…
Reference in a new issue