tegwick
16ca97b277
Assistant: codex Assistant-Model: gpt-6.1-sol Assistant-Session: 01a126e1-76f8-7643-8cf3-e93336539ade
291 lines
15 KiB
Markdown
291 lines
15 KiB
Markdown
---
|
|
id: FLEX-WP-0036
|
|
type: workplan
|
|
title: "Runtime rename: flex-auth to access-engine, run side by side, consumers switch one at a time"
|
|
domain: infotech
|
|
repo: access-engine
|
|
status: active
|
|
owner: claude
|
|
topic_slug: netkingdom
|
|
created: "2026-10-10"
|
|
updated: "2026-10-10"
|
|
origin: demand
|
|
origin_ref: founder 2026-10-10 ("the relicts are too disorienting")
|
|
related: [FLEX-WP-0020]
|
|
state_hub_workstream_id: "af0f8d77-af04-569b-8e79-6c47eb8f1087"
|
|
---
|
|
|
|
`FLEX-WP-0020` renamed the repository only. `FLEX-DEC-2026-013` kept every
|
|
runtime name as `flex-auth` and deferred a product/runtime rebrand to "a later
|
|
workplan after soak". This is that workplan. The founder asked for it on
|
|
2026-10-10 because a repo called `access-engine` that deploys, builds, logs and
|
|
authenticates as `flex-auth` disorients every agent that works on it.
|
|
`FLEX-WP-0020-T11` (the soak) is still open. This plan does not wait for it to
|
|
start drafting, but T06 onward must not apply until T11 closes.
|
|
|
|
## What is renamed
|
|
|
|
| Surface | Today | Target | Who has to act |
|
|
| --- | --- | --- | --- |
|
|
| Kubernetes namespace | `flex-auth` | `access-engine` | operator |
|
|
| Deployments, Services, SAs, NetworkPolicies, Helm releases | `flex-auth-<consumer>` (9 pins) | `access-engine-<consumer>` | operator |
|
|
| TokenReview ClusterRoleBindings | `flex-auth-*-tokenreviewer` (9) | `access-engine-*-tokenreviewer` | operator |
|
|
| Service DNS consumers call | `flex-auth-<c>.flex-auth.svc.cluster.local.` | `access-engine-<c>.access-engine.svc.cluster.local.` | each consumer |
|
|
| Consumer egress NetworkPolicies | name namespace `flex-auth` | `access-engine` | `informed-decision`, `tenant-engine`, `user-engine` (net-kingdom `sso-mfa/k8s`) |
|
|
| Caller token audience | `flex-auth` | `access-engine` | PDP first, then each consumer |
|
|
| `resource.system` naming the PDP itself | `flex-auth` (ops-warden lane `flex-auth-policy-check`) | `access-engine` | PDP first, then ops-warden (`FLEX-DEC-2026-015`) |
|
|
| Container package | `coulomb/flex-auth` | `coulomb/access-engine` | this repo + Forgejo operator |
|
|
| Helm chart | `charts/flex-auth` | `charts/access-engine` | this repo |
|
|
| Go module, `cmd/`, binary | `github.com/netkingdom/flex-auth`, `flex-auth` | `.../access-engine`, `access-engine` | this repo; external callers of the binary |
|
|
| Env vars | `FLEX_AUTH_*` | `ACCESS_ENGINE_*` | this repo |
|
|
| Prose: SCOPE, INTENT, docs, canon, routing catalog | `flex-auth` | `access-engine` | this repo, net-kingdom, ops-warden |
|
|
|
|
Not renamed: the `FLEX-WP-`, `FLEX-DEC-` and `FLEX-IN-` id prefixes, all State
|
|
Hub UUIDs, and historical records (decision logs, archived workplans, decision
|
|
records already emitted). Each of those names what existed at the time it was
|
|
written.
|
|
|
|
## Rules for every task
|
|
|
|
1. **Run side by side, never rename in place.** Renaming a namespace, Service
|
|
or audience in place cuts off every consumer still using the old name. That
|
|
is a fail-closed outage nobody decided on. Each new `access-engine-*` pin is
|
|
started next to its `flex-auth-*` twin at the same image digest, and the
|
|
twin is retired only after its consumer has switched.
|
|
2. **The PDP accepts the new value before any consumer sends it**
|
|
(`FLEX-DEC-2026-015`): ship acceptance of both values first, then let
|
|
consumers flip, then retire the old value.
|
|
3. **One consumer at a time.** Each consumer switches on its own schedule and
|
|
under its own owner's work record. This plan records the handoff id and
|
|
waits for evidence. It never closes a task owned by another repo.
|
|
4. **Every live step needs the founder's go**, per pin, as T04 of
|
|
`FLEX-WP-0035` did.
|
|
|
|
## Decide the target names and supersede the retain table
|
|
|
|
```task
|
|
id: FLEX-WP-0036-T01
|
|
status: wait
|
|
needs_human: true
|
|
intervention_note: "Exact new runtime principals/naming are included in the single daily red batch with the nine TokenReview grants; no per-item question."
|
|
priority: high
|
|
state_hub_task_id: "4f9a796d-832f-5936-8a34-eb980f6e1b57"
|
|
```
|
|
|
|
Record `FLEX-DEC-2026-021`: runtime names move to `access-engine`, following
|
|
the table above. It supersedes the runtime rows of `FLEX-DEC-2026-013`. Fix
|
|
the namespace, release and DNS pattern, the audience value, and the
|
|
`resource.system` value. Settle the binary question: rename it outright, or
|
|
ship `access-engine` with a `flex-auth` alias for one release.
|
|
|
|
Gate: decision accepted by the founder.
|
|
|
|
2026-10-10: binary settled by `FLEX-DEC-2026-020` (founder): renamed outright,
|
|
`flex-auth` is a stub that prints the rename and exits 2. The other target
|
|
names in the table still need the founder's acceptance.
|
|
|
|
2026-10-11: target names are captured as proposed FLEX-DEC-2026-021. The new reviewer subjects are the scope-expansion component and are already in the single daily red batch. Binary disposition FLEX-DEC-2026-020 remains accepted; no founder acceptance of this broader table is fabricated.
|
|
|
|
## Inventory every consumer reference and open handoffs
|
|
|
|
```task
|
|
id: FLEX-WP-0036-T02
|
|
status: progress
|
|
priority: high
|
|
depends_on: [FLEX-WP-0036-T01]
|
|
state_hub_task_id: "8f597899-677e-544b-ad58-26aab2614312"
|
|
```
|
|
|
|
For each consumer, list every place that names the runtime: URL, audience,
|
|
egress policy, routing catalog entries, scripts, tests, stance maps, and the
|
|
`resource.system` value. Known consumers: `ops-warden` (two pins, plus
|
|
`flex-auth-policy-check`, registry and manifest scripts), `secrets-engine`,
|
|
`user-engine` (two pins: check and readback), `tenant-engine`,
|
|
`informed-decision` (lifecycle, sitting and t03 pins), and `net-kingdom`
|
|
(`sso-mfa/k8s/**`). Also check the State Hub, `state-hub` CLI and
|
|
`railiance-fabric` discovery for runtime names. Request one work-record id
|
|
from each owner.
|
|
|
|
Gate: `docs/runtime-rename-inventory.md` with one row per reference and an
|
|
owner handoff id per consumer.
|
|
|
|
2026-10-10 inventory written. Handoff ids are not yet requested. They wait for
|
|
T01, so each owner gets the exact new URL and audience in one message. Found
|
|
that informed-decision's component tests and ops-warden's production smoke
|
|
script run a binary whose path comes from an env var. A binary built from
|
|
current source must now come from `./cmd/access-engine`.
|
|
|
|
## Make the PDP accept both names
|
|
|
|
```task
|
|
id: FLEX-WP-0036-T03
|
|
status: wait
|
|
priority: high
|
|
depends_on: [FLEX-WP-0036-T01, FLEX-WP-0036-T04, RPF-WP-0044-T07]
|
|
state_hub_task_id: "487525e5-c89e-586e-8e9b-54ac6da0804e"
|
|
```
|
|
|
|
Caller auth accepts `access-engine` and `flex-auth` audiences, and packages
|
|
and caller bindings accept both `resource.system` values. Decision records
|
|
must still state which value the request carried, so nothing is rewritten
|
|
silently. Add tests for both values on every pin's package.
|
|
|
|
Gate: tests; a new image rolled to the existing `flex-auth-*` pins through
|
|
reviewed reversible blue execution under
|
|
`the-custodian/canon/standards/build-mode-change-authorization_v0.1.md`.
|
|
The ordered live prerequisite must be verified before rollout.
|
|
|
|
2026-10-11 source preparation: bounded compatibility accepts both exact PDP
|
|
audiences in Kubernetes TokenReview and records an actually reviewed spelling.
|
|
Custom audiences, installed service principals and protected-consumer system
|
|
bindings retain their existing meanings. All nine current pins authenticate both
|
|
audiences; eight enforcement packages retain their fixture outcomes, canonical
|
|
request bindings and original `resource.system` spelling. The ninth pin is the
|
|
separate application-readback route, whose installed binding is
|
|
`application-readback`, not a protected-system grant. There is no current
|
|
PDP-self resource lane in these pin packages; the old inventory's
|
|
`flex-auth-policy-check` example is a policy-routing lane outside this secret
|
|
fetch package. No new self-lane or caller grant is created to fill that absence.
|
|
T03 remains progress until the new image and ordered live checks are proven.
|
|
|
|
2026-10-11: source compatibility is tested and locally built. The next native step waits for the accepted runtime table, published exact artifact and the ordered Argo ownership proof (RPF-WP-0044-T07). No new founder rollout question; the source/public-package scope lives in the existing single batch.
|
|
|
|
## Rename the source
|
|
|
|
```task
|
|
id: FLEX-WP-0036-T04
|
|
status: wait
|
|
needs_human: true
|
|
intervention_note: "New public coulomb/access-engine image package publication is included in the single daily red batch. Local source/build checks pass; paired publication has not run."
|
|
priority: medium
|
|
depends_on: [FLEX-WP-0036-T01]
|
|
state_hub_task_id: "ff7fd369-326f-5044-aaa4-96c5f45c80e9"
|
|
```
|
|
|
|
Go module, `cmd/access-engine`, binary, `ACCESS_ENGINE_*` env vars (read the
|
|
old names for one release, with a warning), `charts/access-engine`, and CI
|
|
publishing to `coulomb/access-engine`. Publish to `coulomb/flex-auth` too
|
|
until T07 is done, so the old pins can still roll back. No runtime change.
|
|
|
|
Gate: build, tests and stage-1 render green; CI publishes both packages, and
|
|
both resolve to the same digest.
|
|
|
|
2026-10-10 binary part done ahead of the rest (`FLEX-DEC-2026-020`). The CLI is
|
|
now `cmd/access-engine` and the image entrypoint is
|
|
`/usr/local/bin/access-engine`. The image also ships the `flex-auth` stub.
|
|
Updated: Makefile, CI, `tools/verify-posture.sh`, `tenancy.yaml` and the live
|
|
docs. Workplans, decisions and ADRs are left as written.
|
|
|
|
2026-10-10 also done: Go module `github.com/netkingdom/access-engine`; no other
|
|
repo imports it. `ACCESS_ENGINE_RUN_TOPAZ_INTEGRATION` replaces the only
|
|
`FLEX_AUTH_*` variable, and the old name skips the test with a message naming
|
|
the new one. README identity paragraph and title updated. Still to do, and
|
|
deliberately left for T05: the chart name, because it changes selector labels,
|
|
which are immutable on a `helm upgrade`, so it ships with the new releases.
|
|
Also the image package and the `/opt/flex-auth` paths, which every live pin's
|
|
args reference.
|
|
|
|
2026-10-11: source now includes canonical `/opt/access-engine/examples` and retains the legacy paths for existing pins. The lifecycle Containerfile starts the renamed engine rather than the retired stub. The old Topaz integration variable remains usable for one release with a warning; an explicit new value takes precedence. CI builds once, publishes to the already admitted legacy package on normal push, and has an explicit paired-publication dispatch for the new package. `tools/publish-runtime-images.sh` independently compares both registry manifest digests; a local image ID or equal config alone is not publication proof. The new public package is a daily red-batch item; no paired dispatch has run. T04 remains progress until accepted publication resolves both repositories to the same immutable digest.
|
|
|
|
## Stand up the access-engine namespace next to flex-auth
|
|
|
|
```task
|
|
id: FLEX-WP-0036-T05
|
|
status: wait
|
|
priority: medium
|
|
depends_on: [FLEX-WP-0036-T03, FLEX-WP-0036-T04]
|
|
state_hub_task_id: "13b93d7a-8341-5c76-9ae8-0f36b45b10fc"
|
|
```
|
|
|
|
Create the `access-engine` namespace, then one `access-engine-<consumer>` pin
|
|
for each live `flex-auth-<consumer>` pin. Each new pin runs the same image
|
|
digest and package as its twin and gets its own TokenReview binding. Ingress
|
|
admits the same consumer as the twin does. Extend
|
|
`TestReadbackPinMatchesParticipantPins` to cover the new pins, and add a test
|
|
that each twin pair runs the same digest.
|
|
|
|
Gate: every new pin Ready, `/healthz` 200, anonymous requests 401; founder go.
|
|
Blocked on `FLEX-WP-0020-T11` closing.
|
|
|
|
2026-10-11: native wait qualified once against existing `depends_on` T03/T04:
|
|
coordinator must prove predecessor image rollout on existing pins before any
|
|
new namespace/pin creation. No wait-task inspection or new grant was needed.
|
|
Actual source preparation adds the renamed chart, exact-content generated twins,
|
|
explicit audience/reviewer paths and render/fixture correspondence checks.
|
|
Twins retain the exact existing image repository/digest and policy argv; these
|
|
are migration compatibility details until an identical digest is published under
|
|
the renamed repository and the baked new paths are proven. No namespace or
|
|
release has been created by this preparation. Local source preparation is reversible blue work under
|
|
`the-custodian/canon/standards/build-mode-change-authorization_v0.1.md`.
|
|
Native rollout creates nine new ServiceAccount subjects bound to cluster-scoped
|
|
`create` on `authentication.k8s.io/tokenreviews`; matching the prior role's verbs
|
|
does not make those new principals an unchanged access scope. It is one red
|
|
access-scope-expansion item in the single daily batch, including exact binding
|
|
revocation recovery. No per-item founder request is needed. The first prepared
|
|
blue receipt is preserved as superseded by the classification correction; no
|
|
native action occurred. T03/T04 and ordered predecessor gates remain unchanged.
|
|
|
|
## Consumers switch over, one at a time
|
|
|
|
```task
|
|
id: FLEX-WP-0036-T06
|
|
status: wait
|
|
priority: medium
|
|
depends_on: [FLEX-WP-0036-T02, FLEX-WP-0036-T05]
|
|
state_hub_task_id: "f0470e5c-3ea7-506c-b8bb-3ade0b57ff88"
|
|
```
|
|
|
|
Each consumer changes its URL, its egress policy (add the new namespace before
|
|
removing the old one), its audience and, for ops-warden, `owner_repo`. One row
|
|
per consumer in the inventory, closed with that owner's evidence: a live
|
|
allow and a live deny against the new pin, and no traffic left on the twin
|
|
(from twin logs).
|
|
|
|
Gate: every inventory row closed with owner evidence.
|
|
|
|
2026-10-11 native dependency wait qualified once on existing T02/T05 and
|
|
ordered predecessor live proof; no consumer switch executed. Actual source work
|
|
adds a deterministic `MigrationReadiness` classifier and public-source
|
|
re-derivation/owner handoff report. All five owners still require source work;
|
|
operator and tunnel custody remains with their owners. The verifier refuses to
|
|
turn comments, spoofed hosts, unsigned readiness flags or source-only changes
|
|
into native readiness. Owner-authenticated live allow/deny and timed old-twin
|
|
no-traffic/soak evidence remain necessary; this task is not closed by the report.
|
|
|
|
## Retire the flex-auth runtime
|
|
|
|
```task
|
|
id: FLEX-WP-0036-T07
|
|
status: todo
|
|
priority: medium
|
|
depends_on: [FLEX-WP-0036-T06]
|
|
state_hub_task_id: "e46c9c8e-a114-5c49-b035-22fdbd6a435b"
|
|
```
|
|
|
|
After a soak with no traffic on the old pins: uninstall each `flex-auth-*`
|
|
release and its TokenReview binding, delete the `flex-auth` namespace, drop
|
|
the old audience and `resource.system` from acceptance (`FLEX-DEC-2026-015`
|
|
order), and stop publishing `coulomb/flex-auth`. Keep the flattened emergency
|
|
manifests in `deploy/` only as rewritten for the new names.
|
|
|
|
Gate: founder go; `kubectl get ns flex-auth` NotFound; every consumer's checks
|
|
still allow and deny as expected.
|
|
|
|
## Prose, canon and layer declaration
|
|
|
|
```task
|
|
id: FLEX-WP-0036-T08
|
|
status: todo
|
|
priority: low
|
|
depends_on: [FLEX-WP-0036-T06]
|
|
state_hub_task_id: "be5440aa-4584-5e4f-9459-242ecf5c7199"
|
|
```
|
|
|
|
SCOPE, INTENT and its layer declaration, the conformance doc, the stance
|
|
register reviews, `.claude/rules`, the `deploy/` and `railiance/` READMEs,
|
|
`railiance/app.toml`, and `ops-warden`'s routing catalog and credential-routing
|
|
canon. Raise the canon-naming item (`FLEX-WP-0030` B5) as closed. Historical
|
|
records stay as written.
|
|
|
|
Gate: `grep -rn flex-auth` over live docs returns only historical records and
|
|
deliberate notes about the old name.
|