mirror of https://github.com/dredx/prole.git synced 2026-09-23 12:03:59 +00:00

chrisfu 6d484ef13e docs(plans): k3d-mirror-of-GKE plan + Phase 1 brief for Junie

The next development thread is knoe-auth Phase 2 OIDC iteration, which
just landed on main but has no fast inner-loop. Instead of bouncing
edits through the GKE deploy chain, we want a laptop-resident model
where knoe-auth runs from the IDE / mvn against real Postgres + KDC
brought up in k3d.

Two new docs:

  docs/plans/k3d-gke-mirror.md
    Architectural plan. Top-to-bottom rationale for what the k3d
    model should mirror, what we deliberately skip (supabase, kong,
    oauth2-proxy, Studio — all unnecessary for knoe-auth's surfaces),
    and the phasing. Captures the three scope decisions taken
    2026-05-02 with the user:
      - knoe-auth runs on the laptop, not as a pod (faster inner loop)
      - stack scope is CNPG + KDC only
      - single-replica CNPG, realm KNOE.LOCAL (distinct from KNOE.DEV)
    Out-of-scope for Phase 1 listed explicitly so reviewer
    expectations match scope: SPNEGO E2E, image-build-and-load,
    supabase, oauth2-proxy, OidcCodeService DB persistence.

  docs/plans/junie/k3d-knoe-auth-dev-loop.md
    Phase 1 brief. Concrete deliverables:
      - k8s/knoe/knoe-kdc-{deployment,service,configmap,pvc,init-job}.yaml
      - etc/init_knoe_auth.sh --mode k3d flag (or sibling script)
      - Makefile: k3d-knoe-{up,pf,down}
      - etc/krb5.local.conf (with udp_preference_limit=1 for
        kubectl port-forward UDP flakiness on macOS)
      - docs/local-dev-knoe-auth.md (engineer-facing)
      - scripts/k3d-knoe-smoke.sh
    Definition of done: a fresh-clone laptop can `make k3d-knoe-up`
    + `make k3d-knoe-pf` + `mvn -pl authority spring-boot:run` and
    hit /health, /.well-known/openid-configuration in <8 minutes.

Index updates:
  docs/plans/README.md           — k3d-gke-mirror.md row added
  docs/plans/junie/README.md     — split into Active / Shipped;
                                   k3d brief listed under Active;
                                   the 5 shipped-2026-05-02 briefs
                                   moved to Shipped with commit refs.
  docs/TODO.md In-progress       — k3d brief now top of "In progress";
                                   the previously in-flight "Phase 2
                                   pg_oauth in install/deploy.sh"
                                   item demoted to "paused" (resume
                                   after the local dev loop lands).

No code changes; all docs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-02 04:45:28 -07:00

5.2 KiB

Raw Blame History

Plans

Engineering plans for the knoe.dev platform. Each document scopes one initiative — its strategic context, design, schema, and the components it adds — and is intended to outlive the implementation work itself: when the work ships, the plan stays as the architectural reference.

Who this is for

You are a junior or mid-level engineer who has been invited to contribute to knoe.dev. These documents are written for you. They assume:

You are comfortable reading code and skimming a Maven pom.xml.
You have used Kubernetes at least casually (kubectl get pods, helm charts).
You may not have prior Kerberos, OIDC, or CNPG experience — relevant terms are defined inline or in the glossary section of each plan.
You have not seen this repo before. Each plan starts with the strategic context and links to existing code before it asks you to write any.

If a sentence in a plan assumes knowledge you don't have, that's a bug in the plan — open an issue.

What lives here

File	Initiative	When you should read it
`knoe-auth-round-1.md`	Identity backbone for the platform: MIT Kerberos KDC + invite-anchored web enrollment + TOTP 2FA. Round 1 of N. Shipped.	Before touching `authority/`, `etc/init_kdc.sh`, `etc/init_knoe_users.sh`, anything in `deploy/gcp/gke/knoe-auth-` or `knoe-kdc-`, or the `knoe.*` database schema.
`deployment-modes.md`	Four-mode installer (`min` / `k3d` / `k3s` / `gke`) with a welcome-screen mode selector and a `min`-mode fast-path through the wizard. Shipped in Phase 0.	Before touching `knoe/ui/screens/welcome.py`, `knoe/ui/screens/navigation.py`, or adding any new wizard screen.
`k3d-gke-mirror.md`	Laptop-resident model of the GKE platform — minimum-viable k3d stack (CNPG + KDC) that lets host-side knoe-auth iterate against real Postgres + Kerberos. Active. Phase 1 in flight (Junie).	Before touching `k8s/knoe/knoe-kdc-`, the `make k3d-knoe-` targets, or `docs/local-dev-knoe-auth.md`. Phase 1 brief at `junie/k3d-knoe-auth-dev-loop.md`.
`customer-deploy-resync.md`	Original plan to converge `~/dev/prole` onto `knoe-db/main` as a customer-deploy branch. Dormant — prole rebrand merged into `main`; no separate prole working tree currently under development.	Only if you're considering activating a per-customer branching workflow.
`junie/` (subdirectory)	Self-contained, single-task work briefs for Junie to consume from inside the IDE. Tactical, single-MR scope, paired against numbered items in `../TODO.md`.	When you want to hand a discrete task to Junie or audit what's been queued.
`../TODO.md` (sibling)	Master TODO index — single source of truth for unfinished work, including reality-vs-intent gaps flagged in `CLAUDE.md`/`AGENTS.md`.	Before picking up any task, to see what's already on the queue.

Each plan follows the same shape: Context → How it's wired (file references) → Architecture → Schema / API → Step-by-step → Verification → Glossary.

Status conventions

A plan in this directory has one of three statuses, declared at the top:

Active plan. Not yet implemented. — the design is agreed, the code isn't there yet. Read deliverables top-to-bottom.
Implemented and operational. Architectural reference. — the work shipped. The doc explains how it works and why; cross-references point at real files. Read the context and the rationale; jump to specific sections when you have a question.
Archived. — superseded by a later round or a different approach. Lives in archive/ with a one-line "see X instead" pointer.

Customer deploys

The knoe.dev platform is designed to support per-customer deployments via branches in this repo, not separate forks. Customer-specific divergence (config, branding, on-prem manifests, kubeconfig handling) would live on a branch named after the customer; platform changes always land on main and customer branches rebase or merge from main on a regular cadence.

Currently no customer branch is active. The original plan to converge ~/dev/prole into a customer/prole.org branch is captured in customer-deploy-resync.md and is dormant — the prole→knoe rebrand has merged into main itself, and there is no separate ~/dev/prole working tree under development. origin and knoe remotes both point at upstream git@git-ssh.knoe.dev:knoe.dev/knoe-db.git.

How to propose a new plan

Copy knoe-auth-round-1.md as a template — the section structure is the convention.
Lead with why (one or two paragraphs). Half the value of a plan is forcing the author to articulate the motivation.
Cite real files with paths relative to the repo root. If you reference something that doesn't exist yet, label it (net-new) so a reader doesn't go hunting.
End with a Verification section — a short checklist a reviewer can run to decide whether the plan is done, or — once shipped — that the implementation still matches the spec.
Open an MR. Plans are reviewed like code.

5.2 KiB Raw Blame History