Epic: Make the pack guide and template work for third-party pack authors #43

A third party who follows packs.nebari.dev/building-a-software-pack today and copies the examples ends up with a pack that reports Ready but isn't routed (basic-nginx, wrap-existing-chart). Their ArgoCD Application is rejected by NIC's deny-all default project. Their group restriction doesn't restrict anything, and their app trusts an unverified token. The CRD field tables are accurate. The examples, and the claims the prose makes about routing, deployment and security, are not.

This epic is done when someone starting from a fresh clone of the template, using only these docs, can deploy each example to a NIC v0.14.0 cluster through ArgoCD, reach it over HTTPS with OIDC login working, and every security statement on the site matches what the operator actually enforces.

Every child issue was checked against this repo at 4e50cd0, nebari-operator v0.1.1 and NIC v0.14.0, with file:line evidence in each.

Plan

Phase 1: a copied pack deploys and is reachable

These two block everything else. Until they're fixed, nobody can use the template end to end.

• Examples and docs omit routing, so the operator creates no HTTPRoute or TLS #34 Add routing to basic-nginx, wrap-existing-chart and every docs snippet, and make CI assert RoutingReady and TLSReady plus an existing HTTPRoute instead of Ready alone.
• Docs and ArgoCD examples don't work on a NIC cluster: project: default, unlabeled namespace, no repo credentials #35 Switch every ArgoCD Application example to project: nebari-apps, label namespaces through managedNamespaceMetadata, add a real Application YAML to build-your-own, and document repo credentials for private packs.

Phase 2: the security story is true

Pack authors make access-control decisions based on these pages, so the docs have to describe what is actually enforced.

• Docs say auth.groups restricts access, but the operator doesn't enforce it #36 Stop presenting auth.groups as access control until security: auth.groups is documented as access control but is not enforced at the gateway nebari-operator#153 lands.
• Auth docs and example app trust the IdToken without verifying its signature #37 Verify the IdToken in the example app and docs, match the exact cookie name, and offer a NetworkPolicy that limits ingress to Envoy.
• CRD reference claims only the app's pods can read the OIDC client secret #39 Describe what the OIDC secret Role grants and who else can read the secret.

Phase 3: the reference matches the operator

• Template pins operator v0.1.0-alpha.19; NIC deploys alpha.20 and the latest release is v0.1.1 #40 Decide which operator version the template targets (what NIC deploys, the latest release, or both in CI) and move every pin.
• CRD reference is missing newer fields and condition reasons, and documents fields that do nothing #41 Add the missing fields and condition reasons, and mark the fields the operator doesn't implement.
• Auth Flow page lists the wrong names for the HTTPRoute, SecurityPolicy and Certificate #38 Correct the resource names on the Auth Flow page.
• Auth Flow page tells local developers to disable NebariApp, contradicting dev/Makefile #42 Remove the local-dev limitation that contradicts dev/Makefile.

Guardrails so this doesn't drift again

• An integration job that mimics NIC: create the nebari-apps and deny-all default AppProjects in the kind cluster and deploy each example through an ArgoCD Application, not helm install. That would have caught Examples and docs omit routing, so the operator creates no HTTPRoute or TLS #34 and Docs and ArgoCD examples don't work on a NIC cluster: project: default, unlabeled namespace, no repo credentials #35.
• docs/*.md and docs/site/src/content/docs/*.md are hand-maintained copies, and several of these bugs exist in both. We should either generate one from the other or check in CI that they match.
• Generate the CRD reference field tables from the operator's CRD at the pinned version, so CRD reference is missing newer fields and condition reasons, and documents fields that do nothing #41 doesn't come back on the next operator release.
• Raise the operator field comments that the docs copied (auth.groups, serviceAccountName) upstream so the generated reference doesn't reintroduce Docs say auth.groups restricts access, but the operator doesn't enforce it #36 and CRD reference claims only the app's pods can read the OIDC client secret #39.

Related

• docs: add nebari-app Helm steps to build-your-own nebari-docs#738 adds a Helm path for the nebari-app library chart and repeats the missing-routing values block from Examples and docs omit routing, so the operator creates no HTTPRoute or TLS #34. It should wait for the fix pattern from Examples and docs omit routing, so the operator creates no HTTPRoute or TLS #34.
• security: auth.groups is documented as access control but is not enforced at the gateway nebari-operator#153: auth.groups is not enforced at the gateway.