Nodes, agents and the fleet
Enrolling a machine, the agent running on it, and the platform services that place and route work across the fleet.
Every address below is served under the control plane’s base URL. Permission is the guard the route is registered with; who holds it is read from the control plane’s own grant, so it cannot drift from what the server does. A dash means the route carries no permission guard of its own — the access tier below the table is then the whole of what stands in front of it.
Generated from Route. Hand edits to this table are overwritten on the next build — change the Go doc comment, or the generator.
| Route | Permission | Who holds it | Body |
|---|---|---|---|
GET /api/v1/agent/upgrade/check |
nodes:read |
developer, operator, readonly, support |
— |
GET /api/v1/agents/mode |
— | — | — |
GET /api/v1/cluster/health |
— | — | — |
GET /api/v1/cluster/resources |
— | — | — |
GET /api/v1/consul/kv/deployments |
deployments:read |
developer, operator, readonly, support |
— |
GET /api/v1/consul/kv/deployments/{name} |
deployments:read |
developer, operator, readonly, support |
— |
GET /api/v1/consul/kv/scaling-policies |
scaling:read |
developer, operator, readonly, support |
— |
POST /api/v1/consul/simulate-available |
debug:access |
operator |
— |
POST /api/v1/consul/simulate-unavailable |
debug:access |
operator |
— |
GET /api/v1/consul/status |
config:read |
developer, operator, readonly, support |
— |
GET /api/v1/consul/watch/{deployment} |
deployments:read |
developer, operator, readonly, support |
— |
GET /api/v1/enrollments |
nodes:read |
developer, operator, readonly, support |
— |
DELETE /api/v1/enrollments/{nodeName} |
nodes:manage |
operator |
— |
GET /api/v1/gateway/circuit-breakers |
— | — | — |
POST /api/v1/gateway/circuit-breakers/{nodeId}/deployments/{name}/reset |
— | — | — |
POST /api/v1/gateway/circuit-breakers/{nodeId}/reset |
— | — | — |
GET /api/v1/gateway/connections |
— | — | — |
GET /api/v1/gateway/stats |
— | — | — |
GET /api/v1/metrics |
deployments:read |
developer, operator, readonly, support |
— |
POST /api/v1/migrations/analyze |
— | — | — |
GET /api/v1/migrations/current |
— | — | — |
POST /api/v1/migrations/start |
— | — | — |
POST /api/v1/migrations/stop |
— | — | — |
GET /api/v1/nodes |
nodes:read |
developer, operator, readonly, support |
returns Node |
POST /api/v1/nodes |
nodes:manage |
operator |
— |
POST /api/v1/nodes/enroll |
nodes:manage |
operator |
— |
GET /api/v1/nodes/evacuations |
nodes:manage |
operator |
— |
DELETE /api/v1/nodes/{name} |
nodes:manage |
operator |
— |
GET /api/v1/nodes/{name} |
nodes:read |
developer, operator, readonly, support |
returns Node |
GET /api/v1/nodes/{name}/certificates |
nodes:read |
developer, operator, readonly, support |
— |
POST /api/v1/nodes/{name}/cordon |
nodes:manage |
operator |
— |
POST /api/v1/nodes/{name}/drain |
nodes:manage |
operator |
— |
POST /api/v1/nodes/{name}/evacuation/approve |
nodes:manage |
operator |
— |
POST /api/v1/nodes/{name}/evacuation/reject |
nodes:manage |
operator |
— |
POST /api/v1/nodes/{name}/export |
nodes:read |
developer, operator, readonly, support |
— |
POST /api/v1/nodes/{name}/regenerate-token |
nodes:manage |
operator |
— |
GET /api/v1/nodes/{name}/traefik |
nodes:read |
developer, operator, readonly, support |
— |
POST /api/v1/nodes/{name}/uncordon |
nodes:manage |
operator |
— |
POST /api/v1/nodes/{name}/upgrade/approve |
nodes:manage |
operator |
— |
GET /api/v1/nodes/{name}/upgrade/check |
nodes:read |
developer, operator, readonly, support |
— |
GET /api/v1/nodes/{name}/upgrade/history |
nodes:read |
developer, operator, readonly, support |
— |
DELETE /api/v1/nodes/{name}/wireguard |
nodes:manage |
operator |
— |
GET /api/v1/reconcilers |
— | — | — |
GET /api/v1/reconcilers/stats |
— | — | — |
GET /api/v1/reconcilers/{tenantId} |
— | — | — |
POST /api/v1/reconcilers/{tenantId}/reconcile |
— | — | — |
GET /api/v1/tls/test |
config:read |
developer, operator, readonly, support |
— |
GET /api/v1/traefik/routes |
config:read |
developer, operator, readonly, support |
— |
DELETE /api/v1/traefik/routes/{deployment} |
config:write |
an administrator only, through the wildcard grant | — |
GET /api/v1/traefik/routes/{deployment} |
config:read |
developer, operator, readonly, support |
— |
POST /api/v1/traefik/routes/{deployment} |
config:write |
an administrator only, through the wildcard grant | — |
PUT /api/v1/traefik/routes/{deployment} |
config:write |
an administrator only, through the wildcard grant | — |
GET /api/v1/traefik/status |
config:read |
developer, operator, readonly, support |
— |
GET /api/v1/traefik/weighted-services |
config:read |
developer, operator, readonly, support |
— |
Who can reach these at all
Section titled “Who can reach these at all”authenticated — Behind authentication, cross-site-request-forgery validation and tenant extraction. Every call acts inside exactly one tenant.
platform-operator — Platform-operator surface, across tenants. Not part of a tenant’s own API.
Reachable only by an administrator
Section titled “Reachable only by an administrator”No role holds the permissions below explicitly. They are satisfied by the administrator’s wildcard grant and by nothing else, so an operator or a developer cannot call these routes however their tenant is configured. That is a role-model question rather than a documentation one; it is recorded here because a reader planning around it needs to know before they try.
DELETE /api/v1/traefik/routes/{deployment}— needsconfig:writePOST /api/v1/traefik/routes/{deployment}— needsconfig:writePUT /api/v1/traefik/routes/{deployment}— needsconfig:write
Registered more than once
Section titled “Registered more than once”Each route below is registered at more than one place in the control plane. The router serves the first registration; the rest are unreachable. Where two of them carry different permissions the table above shows the one the router uses, and both are listed here — a second registration is where a permission a reader expects to apply turns out not to.
GET /api/v1/reconcilers
pkg/api/server.go:1255— no permission guardpkg/api/server.go:1261— no permission guard
GET /api/v1/reconcilers/stats
pkg/api/server.go:1256— no permission guardpkg/api/server.go:1262— no permission guard
GET /api/v1/reconcilers/{tenantId}
pkg/api/server.go:1257— no permission guardpkg/api/server.go:1263— no permission guard
POST /api/v1/reconcilers/{tenantId}/reconcile
pkg/api/server.go:1258— no permission guardpkg/api/server.go:1264— no permission guard
Guarded in code that never runs
Section titled “Guarded in code that never runs”Each route below is also registered inside a function nothing in the module calls, and that dead registration names a permission the live one does not. The dead permission is not enforced. Reading the source is how a reader would conclude otherwise, which is why it is written down here.
GET /api/v1/reconcilers— served atpkg/api/server.go:1255with no permission guard; declared again atpkg/api/reconciler_handlers.go:298with the guardadmin:read, in a registrar nothing callsGET /api/v1/reconcilers/stats— served atpkg/api/server.go:1256with no permission guard; declared again atpkg/api/reconciler_handlers.go:301with the guardadmin:read, in a registrar nothing callsGET /api/v1/reconcilers/{tenantId}— served atpkg/api/server.go:1257with no permission guard; declared again atpkg/api/reconciler_handlers.go:304with the guardadmin:read, in a registrar nothing callsPOST /api/v1/reconcilers/{tenantId}/reconcile— served atpkg/api/server.go:1258with no permission guard; declared again atpkg/api/reconciler_handlers.go:307with the guardadmin:manage, in a registrar nothing calls