document the hive cut-off
This commit is contained in:
parent
11fec06a50
commit
b6dc46d315
3 changed files with 41 additions and 1 deletions
|
|
@ -46,6 +46,13 @@ swarm controller creates both and keeps the tokens in the swarm secret store,
|
||||||
so you set up nothing by hand. A token that goes missing or stops matching the
|
so you set up nothing by hand. A token that goes missing or stops matching the
|
||||||
forge is re-minted within five minutes.
|
forge is re-minted within five minutes.
|
||||||
|
|
||||||
|
Removing a hive from `swarm.hives` revokes its credentials on the next
|
||||||
|
controller start: its forge token, its seat in the `hives` team, its token
|
||||||
|
secret in the store and the store login it uses. The forge account stays, so
|
||||||
|
putting the hive back in `swarm.hives` gives it new credentials within five
|
||||||
|
minutes of that start. The controller logs one `hive is not in the roster` line
|
||||||
|
per hive it cut off.
|
||||||
|
|
||||||
Two things live in the `agent-configs` Forgejo organization:
|
Two things live in the `agent-configs` Forgejo organization:
|
||||||
|
|
||||||
- A config repo per agent, `agent-configs/<name>`. The agent is a read
|
- A config repo per agent, `agent-configs/<name>`. The agent is a read
|
||||||
|
|
|
||||||
|
|
@ -36,7 +36,7 @@ the rest of the cell says how.
|
||||||
| `swarm/agents/<agent>/github-token` | `swarm-controller`, when you link a GitHub account in the swarm UI | the agent, which keeps it in `/run` only; the `<state>/github-token` copy of an earlier version is no longer read | ❌ your token; delete it and link again | ✅ every 2 minutes |
|
| `swarm/agents/<agent>/github-token` | `swarm-controller`, when you link a GitHub account in the swarm UI | the agent, which keeps it in `/run` only; the `<state>/github-token` copy of an earlier version is no longer read | ❌ your token; delete it and link again | ✅ every 2 minutes |
|
||||||
| `swarm/agents/<agent>/backend-env` | `hive-agent-backend-env`, in the agent's container, from the agent's `backendEnvironmentFile` when the leaf holds nothing (field `env`, the file's exact text); or `swarm-controller`, when you set the API-key environment in the swarm UI | the agent | ❌ nothing replaces it without you; a save in the swarm UI overwrites it, including text an agent wrote into an empty leaf; the agent's file stays as it was | ❌ the file in `/run` refreshes every 2 minutes, and the harness and the subagent daemon load it at their next start |
|
| `swarm/agents/<agent>/backend-env` | `hive-agent-backend-env`, in the agent's container, from the agent's `backendEnvironmentFile` when the leaf holds nothing (field `env`, the file's exact text); or `swarm-controller`, when you set the API-key environment in the swarm UI | the agent | ❌ nothing replaces it without you; a save in the swarm UI overwrites it, including text an agent wrote into an empty leaf; the agent's file stays as it was | ❌ the file in `/run` refreshes every 2 minutes, and the harness and the subagent daemon load it at their next start |
|
||||||
| `swarm/agents/<agent>/claude-credentials` | `swarm-claude-login`, when you log the agent in from its card; one version per login | the agent, while it waits for a login | ❌ log in again | ✅ every 30 seconds while waiting |
|
| `swarm/agents/<agent>/claude-credentials` | `swarm-claude-login`, when you log the agent in from its card; one version per login | the agent, while it waits for a login | ❌ log in again | ✅ every 30 seconds while waiting |
|
||||||
| `swarm/hives/<hive>/forge/token` | `swarm-controller`, every 5 minutes | `swarm-controller` and the hive | ✅ when missing or no longer matching the forge | ✅ read on every forge call |
|
| `swarm/hives/<hive>/forge/token` | `swarm-controller`, every 5 minutes; deleted when the hive leaves the roster | `swarm-controller` and the hive | ✅ when missing or no longer matching the forge | ✅ read on every forge call |
|
||||||
| `swarm/agents/<agent>/proxy-credential` | `swarm-controller`: 32 random bytes, at start and every 5 minutes for every agent that holds a store identity | the hive (`hive-c0re`) and the agent, which fetches it | ❌ never replaced: written only while the path holds nothing | ✅ `hive-c0re` re-reads it every 30 seconds |
|
| `swarm/agents/<agent>/proxy-credential` | `swarm-controller`: 32 random bytes, at start and every 5 minutes for every agent that holds a store identity | the hive (`hive-c0re`) and the agent, which fetches it | ❌ never replaced: written only while the path holds nothing | ✅ `hive-c0re` re-reads it every 30 seconds |
|
||||||
| `ssh-agents/sign/swarm-agent` (a signing call, nothing is stored) | the store's SSH CA mount (`ssh-agents`), when the agent's `hive-agent-ssh-cert` unit asks it to sign, which the operator's per-agent `ssh` switch allows the public key the unit generated in its own `/run`; the CA key is generated inside the store by `swarm-bao-agent-ssh-policy` | the agent, which keeps the key and the signed certificate in `/run` only; a target machine trusts the CA's public key by value | ✅ the certificate lasts 60 minutes; the CA is never replaced, and a target that holds a different CA key refuses every certificate | ✅ the agent signs again every 20 minutes |
|
| `ssh-agents/sign/swarm-agent` (a signing call, nothing is stored) | the store's SSH CA mount (`ssh-agents`), when the agent's `hive-agent-ssh-cert` unit asks it to sign, which the operator's per-agent `ssh` switch allows the public key the unit generated in its own `/run`; the CA key is generated inside the store by `swarm-bao-agent-ssh-policy` | the agent, which keeps the key and the signed certificate in `/run` only; a target machine trusts the CA's public key by value | ✅ the certificate lasts 60 minutes; the CA is never replaced, and a target that holds a different CA key refuses every certificate | ✅ the agent signs again every 20 minutes |
|
||||||
| `swarm/hives/<hive>/squid-selfcheck` | `swarm-controller`, in the same pass as the agents' credentials | the hive: `hive-c0re` and `squid-selfcheck-credential` (root) | ❌ never replaced: written only while the path holds nothing | ✅ `hive-c0re` every 30 seconds, the root unit every 10 minutes |
|
| `swarm/hives/<hive>/squid-selfcheck` | `swarm-controller`, in the same pass as the agents' credentials | the hive: `hive-c0re` and `squid-selfcheck-credential` (root) | ❌ never replaced: written only while the path holds nothing | ✅ `hive-c0re` every 30 seconds, the root unit every 10 minutes |
|
||||||
|
|
|
||||||
|
|
@ -42,6 +42,39 @@ controller's grant on `swarm/hives/+/forge/token`), then the controller host,
|
||||||
then the hives. A hive that starts before its token exists reads nothing, and
|
then the hives. A hive that starts before its token exists reads nothing, and
|
||||||
builds nothing, until the controller's next pass.
|
builds nothing, until the controller's next pass.
|
||||||
|
|
||||||
|
## A hive that leaves the roster
|
||||||
|
|
||||||
|
A hive dropped from `swarm.hives` keeps the credentials above until
|
||||||
|
swarm-controller cuts it off (`forge::hive_cutoff`). The roster is the
|
||||||
|
`SWARM_CONTROLLER_HIVES` env var, read at start, so a removal takes effect at
|
||||||
|
the next controller start. On every pass, swarm-controller cuts off each hive
|
||||||
|
that has a forge account with the hive email, or a cert-auth role
|
||||||
|
`hive-<hive>`, and isn't in the roster. A role named `hive-agent-<agent>`
|
||||||
|
belongs to an agent and never matches.
|
||||||
|
|
||||||
|
For each such hive, in this order:
|
||||||
|
|
||||||
|
1. delete its `swarm-hive` forge token,
|
||||||
|
2. remove its account from the `agent-configs/hives` team,
|
||||||
|
3. delete the store secret `swarm/hives/<hive>/forge/token`,
|
||||||
|
4. delete the cert-auth role `hive-<hive>`.
|
||||||
|
|
||||||
|
The role goes last because it marks that work remains: a step that fails
|
||||||
|
leaves the role, and the next pass runs every step again. A step that finds
|
||||||
|
nothing to remove does nothing, so a finished hive costs a few reads per pass.
|
||||||
|
The pass logs one `hive is not in the roster: its credentials are revoked` line
|
||||||
|
per hive with what it removed, and a warning for a hive whose cut-off failed.
|
||||||
|
|
||||||
|
The forge account stays, so a hive put back in the roster gets its token and
|
||||||
|
team seat from the pass above and its role from the store access
|
||||||
|
swarm-controller writes at start.
|
||||||
|
|
||||||
|
Nothing happens when the roster didn't load. An unset or unparseable
|
||||||
|
`SWARM_CONTROLLER_HIVES`, and a roster with no hive, read the same as a removal of every
|
||||||
|
hive, so the controller logs an error at start and skips the
|
||||||
|
cut-off. The attic pull token and the OIDC client secret under
|
||||||
|
`swarm/hives/<hive>/` stay, as does the forge account itself.
|
||||||
|
|
||||||
## Per-agent forge accounts
|
## Per-agent forge accounts
|
||||||
|
|
||||||
Each agent gets its own Forgejo user and access token. swarm-controller
|
Each agent gets its own Forgejo user and access token. swarm-controller
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue