Skip to main content

ADR 022 — Governed deployment control path

  • Status: Accepted (2026-06-24) — recorded during the deployment-ops framework build (Phase 0-3)
  • Authors: Platform ops
  • Related: ADR 005, ADR 015; Phase 0 snapshot, Phase 2 report, and the Deployment Ops Framework Plan were working documents from the deployment-ops framework build and are not present anywhere in the current checked-out workspace (not found under any of the ~40 sibling repos)

Context​

The deployment-ops framework needs one place where consequential platform actions are authorized, audited, and reviewed. Phase 0 recon confirmed that the /manage path is reachable through api.alpha-swarm.ai behind Cloudflare Access; it did not confirm a dedicated manage.alpha-swarm.ai hostname. Phase 2 recorded that alphaswarm_controller is the declared owner of workload lifecycle operations while alphaswarm_ops_console had direct kubectl controls as governance debt.

Direct kubectl actions from an operator console are easy to test, but they skip the controller's policy, four-eyes, and audit path. That would create a third control plane alongside the controller and admin surfaces. It also makes cleanup actions harder to prove because the sign-off ledger is separated from the actor that actually mutates resources.

Decision​

All mutating deployment and workload control actions route through alphaswarm_controller /manage.

This includes scale, restart, rollout, halt, cleanup, Terraform apply/destroy, and any future action that changes Kubernetes, Cloudflare, AWS, Terraform state, Helm releases, workloads, or deployment flags. The ops console and admin UI are clients of /manage; they do not become alternate executors.

Read-only observation may still use safe inventory paths such as Kubernetes get/list/watch, Cloudflare DNS reads, and controller/admin health reads, provided they do not expose secrets.

Consequences​

Positive

  • There is one audit trail for deployment writes, rather than separate UI, console, and script trails.
  • The ops console can stay useful for discover/analyze/debug/monitor without gaining broad cluster mutation rights.
  • Phase 4 cleanup items can require per-item sign-off before the controller executes a governed action.

Negative / risks

  • Local operator workflows that previously relied on direct kubectl controls need a /manage token/session and controller availability.
  • /manage public reachability is Cloudflare-Access-gated through api.alpha-swarm.ai/manage; dry-run and smoke checks must distinguish "auth required" from "route absent." A dedicated manage.* hostname remains unverified until DNS and tunnel routing are explicitly added.

Rejected

  • Keeping raw kubectl scale/restart/rollout in the default ops-console catalog. Confirmation prompts are not a governance boundary.
  • Adding a second governance system inside alphaswarm_ops_console. That would duplicate the controller's existing role.

Rollout​

  1. Remove or hide raw mutating kubectl actions from the default console catalog.
  2. Add disabled/default-off /manage action specs for future governed control.
  3. Require controller auth and per-item sign-off before enabling those actions.
  4. Keep Phase 4 cleanup execution item-by-item, with rollback evidence recorded in the cleanup report ledger.