vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs/setup: run bao operator init on the host, and say when to delete the token

Browse source 
The host now has a wrapped bao (#4154, deployed) carrying the store's
address, CA and client cert, so the init step is a bare command there
instead of a root-login hop with an SNI override. The container route
stays as one sentence explaining why it needs the two extra pieces.

The delete step said "once that has run" without saying what -- the
rebuild, or the unit succeeding. It now names the check that settles it,
because deleting the token before the role exists leaves the unit
skipping forever and looks exactly like a store nobody bootstrapped.

Closes #4162
This commit is contained in:
atlas 2026-09-10 18:34:59 +02:00
commit a1b2541d62
1 changed files with 19 additions and 15 deletions
Download patch file Download diff file Expand all files Collapse all files

34
docs/getting-started/setup.md
View file

@ -51,22 +51,23 @@ 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 you point anything at it.
Run this **inside the store's container** — `nixos-container root-login
swarm-bao`. The store's TLS certificate is issued for its DNS name and carries
no IP SAN, and that name resolves to the bridge rather than to the container
from in there, so neither `127.0.0.1` nor the name works on its own. Verify the
name while connecting on loopback:
Run this **on the host**. The `bao` there is a wrapper carrying this store's
address, its CA, and the host's client certificate already, so nothing needs
exporting:
```bash
export BAO_ADDR=https://127.0.0.1:8200
export BAO_TLS_SERVER_NAME=bao.<swarm domain> # `deploy.bao.domain`, the CN the cert carries
bao operator init # keep the keys it prints and the root token OFF this host
sudo bao operator init # keep the keys it prints and the root token OFF this host
```
From the **host** instead, `BAO_ADDR=https://bao.<swarm domain>:8200` reaches
the same store and needs no SNI override — that's the address every unit in
the tree builds, and what `swarm-controller` connects to.
`sudo` because the client certificate and key sit under
`/var/lib/swarm-bao-pki`, which is mode `0700`.
Inside the store's container (`nixos-container root-login swarm-bao`) the same
command needs two extra pieces, because the certificate carries no IP SAN and
its DNS name resolves to the bridge from in there: export
`BAO_ADDR=https://127.0.0.1:8200` alongside `BAO_TLS_SERVER_NAME=bao.<swarm
domain>` to verify the name while connecting on loopback. The host is the
shorter path.
While you still hold that root token, mint the one credential the swarm needs
to grant itself anything. Cert auth answers a _role_, so nothing can
@ -113,9 +114,12 @@ grants still come from `-output-policy`, not from a swarm that came up on them.
What that 403 does _not_ tell you is whether the login or the write was
refused — `bao read auth/cert/certs/swarm-controller` separates the two.
**Delete the file once that has run.** The unit skips when it's absent, so a
host that has finished bootstrapping stops carrying the credential — and the
TTL above means a forgotten one expires rather than lingering.
**Delete the file only once `bao read auth/cert/certs/swarm-controller` returns
the role.** The unit skips when the token is absent, so a host that has finished
bootstrapping stops carrying the credential — but deleting it before the role
exists leaves the unit skipping forever with nothing to show for it, and looks
exactly like a store that was never bootstrapped. The TTL above means a
forgotten one expires rather than lingering.
Whether anything more is needed depends on
`services.hyperhive.deploy.bao.seal`: