Skip to main content

ADR 023 — Ops console RBAC and API auth seam

  • Status: Accepted (2026-06-24) — implemented as Phase 3 hardening, not yet activated live
  • Authors: Platform ops
  • Related: ADR 022, alphaswarm_ops_console; the Phase 2 report and Deployment Ops Framework Plan were working documents from the deployment-ops framework build and are not present anywhere in the current checked-out workspace

Context​

alphaswarm_ops_console is the deployment-ops framework's primary operator workspace. It already provides a data-driven CommandSpec/ActionSpec catalog, SSE operation logs, history storage, and vanilla-JS UI without a build step.

Before Phase 3, it was safe as a local development tool but not safe to expose as a cluster service: the console had no auth of its own, and the production catalog included direct mutating kubectl controls. Phase 1 added read-only platform-monitor and topology visibility. Phase 3 then added Kubernetes manifests, read-only RBAC, and an API auth seam without applying anything live.

Decision​

When explicitly activated by an operator, deploy the ops console as a new additive workload in alphaswarm-ops with read-only RBAC by default and an explicit /api auth seam. The current "default-off" posture is procedural: the manifests are not applied by default. If applied, the Deployment declares a normal serving replica and must already have the auth/RBAC prerequisites in place.

The default Kubernetes role may read cluster inventory needed by monitor, discover, and topology views. It must not include mutating verbs. The console's API auth defaults remain local-dev friendly, but bearer mode fails closed when enabled without a configured token. /healthz and /version remain lightweight health/introspection endpoints.

Mutating controls are not authorized by the console itself. They remain disabled until wired as governed /manage clients per ADR 022.

Consequences​

Positive

  • The console can be deployed for read-only operational visibility without giving it broad cluster-admin powers.
  • The same no-build UI and existing test model remain intact.
  • Activation is reversible because all Kubernetes objects are net-new under alphaswarm-ops.

Negative / risks

  • Cluster-wide read access still needs review because topology requires cross-namespace inventory.
  • Bearer auth is a minimal seam, not a complete identity provider integration. Production exposure should still sit behind the existing edge auth path or a stronger delegated identity mechanism.
  • Operators must provision an auth Secret before enabling bearer mode.

Rejected

  • Exposing the console API unauthenticated outside localhost.
  • Granting mutating Kubernetes verbs in the default RBAC role.
  • Replacing the no-build console UI with React/Vite just to add dashboards.

Rollout​

  1. Keep the manifests unapplied until operator approval; do not treat replicas: 1 in the unapplied Deployment as automatic activation.
  2. Provision the API bearer secret or equivalent edge-auth integration before exposing /api.
  3. Run Kubernetes render/dry-run validation before any activation.
  4. Enable governed control actions only after controller /manage auth is wired and tested.