shcizo/package-updater
1
0
Fork 0
Code Issues 8 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: document master/agent phase 1 and add master stack example

Browse Source
This commit is contained in:
shcizo
2026-10-12 15:04:43 +02:00
parent 05610391e3
commit 4f092eaf79
4 changed files with 79 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/plans/2026-10-12-master-agent-phase-1-inventory.md
+7
View File
@@ -29,6 +29,13 @@
- The agent detects changes by re-running the full inventory after Docker events settle and diffing it against the last one sent, rather than re-inspecting individual items. Same messages on the wire, much less code.
- The envelope is `{type, payload}`. The `id` field arrives in phase 2 together with jobs.
- Only the tables phase 1 needs are created. `desired_ref`, `available_*`, `last_poll_error`, `image_versions` and `update_jobs` arrive in later phases' migrations.
- The agents column is named `swarm_manager` (spec: `is_swarm_manager`), and services carry a single unique `location_key` column instead of one unique index per kind.
- Templates and static assets live under `internal/master/web/` (embedded there), not a top-level `web/` directory.
- The master has no `/metrics` or `/version` endpoint in phase 1; only `/healthz`.
- The overview shows all Swarm services in one "Swarm" group, not one group per cluster.
- The session cookie gets the `Secure` flag only when `PUBLIC_URL` starts with `https://`, so a local http setup works.
- The agent runs a full re-inventory every 60 seconds in addition to Docker events, because a Swarm replica dying on another node emits no event on the manager running the agent.
- Known limitation: the master files Swarm services under the cluster ID the agent reports in its hello. An agent whose token leaks can therefore overwrite or remove the overview rows of any Swarm cluster. This matches the spec's statement that a leaked token can feed false inventory but not command machines; phase 2 must not route Swarm jobs based only on the cluster ID an agent claims.
## Review Focus