Watch
0
0
Fork
You've already forked hyperhive
0

document the controller tcp listener and its two leaves

This commit is contained in:
atlas 2026-11-15 16:15:29 +01:00 • committed by mara
commit cd786ef401

View file

@ -498,6 +498,33 @@ The controller registers the hooks within five minutes of having both the forge
token and the secret. It keeps trying, at most five minutes apart, for as long
as the forge or the secret store is down. A restart isn't needed to recover.
The URL hooks register against is `deploy.swarm-controller.publicUrl`, default
`https://<swarm.domain>`. It names the vhost that fronts the controller, so it stays right
whether the gateway reaches the controller by socket or by its TCP listener. Set it when another
URL fronts the controller.
## Reaching the controller over TCP (optional)
By default the gateway reaches the controller through a unix socket on the same host. Setting
`swarm.controller.tcp.enable` and `swarm.controller.tcp.domain` on **every host of the swarm**
adds a TLS listener beside the socket and points the gateway's `/api/` and `/webhook/forge/`
locations at it by that name. Nothing else changes: the socket stays, and the operator gate on
`/api/` stays.
What you provide:
- `swarm.controller.tcp.domain`, resolvable from the gateway's host. Nginx resolves it when it
loads its config.
- `deploy.swarm-controller.tcp.openFirewall = true` on the controller's host only when a gateway
on another host dials it. The port (`swarm.controller.tcp.port`, default 9443) stays closed
until you do, and `deploy.swarm-controller.tcp.listenAddress` picks the bound address.
What you don't: both certificates come from the secret store with no manual step
([`ca.md`](ca.md#the-controllers-tcp-listener-has-two-leaves-of-its-own)). The listener accepts
the gateway's client certificate and nothing else, so reaching the port gets a stranger a refused
handshake. The swarm UI's vhost is still declared on the host that runs the controller, so the
gateway that dials the listener runs there too.
## Agent identity minting
A store identity that fails to mint logs `swarm jobq: mint_agent_identity