Skip to content

feat: endpoint control — surface disabled endpoints across runtime, CC, and example pack#201

Merged
iAlexeze merged 16 commits into
mainfrom
feat/endpoint-control
Jul 5, 2026
Merged

feat: endpoint control — surface disabled endpoints across runtime, CC, and example pack#201
iAlexeze merged 16 commits into
mainfrom
feat/endpoint-control

Conversation

@iAlexeze

@iAlexeze iAlexeze commented Jul 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Summary

Per-CRD HTTP endpoint control and cross-read access visibility, surfaced consistently across the runtime API, Control Center, generated docs, and a new example pack.

What changed

Fixes

  • pkg/e2e/verify.go, pkg/types/e2e.go — statusCode: assertion for port-forward curl steps; previously only jq + equals was checked, HTTP status was ignored
  • cmd/cli/validate.go — singular/plural grammar in ork validate output ("1 CRDs" → "1 CRD")

Runtime (pkg/)

  • pkg/types/types_crd_entry.go — IsHealthEnabled() / IsInfoEnabled() helpers on EndpointsConfig; single source of truth for disabled-endpoint logic
  • pkg/kordinator/crd_health_handers.go — /katalog summary extended with healthEnabled, infoEnabled, crossAccess, GVK, GVR, Mode, Namespaced, Namespace, Description; static fields previously only available from the per-CRD info endpoint now always available

Control Center (cmd/controlcenter/)

  • cc/types.go — CRDSummary gains static fields and CrossAccess; CRDDetail gains HealthEndpointDisabled, InfoEndpointDisabled, CrossAccess; EndpointInfo struct added
  • cc/client.go — FetchCRDDetail skips disabled endpoint calls; synthesises health/info from the always-available /katalog summary; early-return for state: endpoints-disabled with all static fields populated from summary; FetchCRList treats 404 as empty list
  • cc/helper.go — summaryFor, endpointInfoFor, synthHealthFromSummary, synthInfoFromSummary
  • cc/assets/templates/katalog.html — health badge shows normal state + ⊘ secondary badge when health disabled; Workers/Queue/Resources/RBAC rows hidden when info disabled; ⊘ info endpoint disabled row added
  • cc/assets/templates/crd.html — three states: endpoints-disabled full-page notice, HealthEndpointDisabled notice in Runtime Health section, InfoEndpointDisabled notice in operatorBox section
  • cc/assets/templates/crd_docs.html — Endpoints section always shown; Cross-read access row in Overview; operatorBox summary table; Configuration section hidden for disabled CRDs; dead else if in Reconcile Mode fixed

Documentation

  • documentation/orkestra-core/03-controlcenter/generated-docs.md — new page explaining the live-generated per-CRD docs: sections shown, when each appears, resilience to disabled endpoints
  • documentation/concepts/live-api/ — reordered: endpoints reference first, access control second
  • documentation/getting-started/ — 00-kubernetes-basics.md moved to section root; tip callout and Next Steps link added to getting-started index

New Advanced Example Pack

ork init --pack advanced/19-endpoint-control

Three runnable sub-examples:

  • 01-selective-health/ — endpoints: health: false on payment; info and CR list remain active
  • 02-full-disable/ — endpoints: enabled: false on credential; all HTTP surfaces removed; operator reconciles normally
  • 03-fully-dark/ — keyrotation (dark) + auditlog (open) in one Katalog; keyrotation cross-reads auditlog successfully; auditlog's read of keyrotation is denied by crossAccess: false; both outcomes visible in kubectl get printer columns (AuditRef, KeyRef)

Website

  • website/assets/css/main.css — sidebar max-height increased from 800px to 3000px; long sections (Concepts) were clipping the last visible item

Key design decisions

/katalog always responds. Even when per-CRD endpoints are disabled, the top-level /katalog response is always available and carries runtime health state and static fields for every CRD. The CC uses this as the authoritative source when a CRD's own endpoints are off — no synthetic zeros, no degraded badges for intentionally-disabled CRDs.

crossAccess: false blocks inbound, not outbound. The fully-dark example makes this explicit: keyrotation reads auditlog successfully; auditlog's attempt to read keyrotation returns empty. The flag only controls whether others can read you.

state: "endpoints-disabled" as a CC sentinel. Rather than inferring disabled state from 404 responses, the CC receives explicit flags from /katalog and sets a clean state string. Templates branch on it once rather than scattering nil checks.

Control Center

  • CRD with endpoints: health: false — health badge shows healthy state + ⊘ secondary icon; Runtime Health section shows disabled notice; Workers/Queue/Resources still visible
  • CRD with endpoints: enabled: false — CC card shows ⊘ info endpoint disabled; clicking through shows full-page disabled notice with GVK, scope, and cross-read access populated correctly (not "Unknown")
  • Generated docs page (/docs) — Endpoints section shows correct ✓/⊘ per endpoint for all three states; Configuration section absent for fully-disabled CRDs; Overview Cross-read access row present

iAlexeze added 16 commits July 3, 2026 11:21
@iAlexeze
refactor(e2e): Options struct for e2e.New, --workers flag on all e2e …
55c9e2a 
…callers

Replace the positional New(...) signature with New(e2eFile string, opts Options)
so adding future fields does not cascade changes across every call site.

Options struct fields: ClusterCtx, UseCurrentCtx, KeepCluster, Workers,
KindVersion, DevServer, OrkVersion, ValueFiles, HelmArgs.

--workers <n> accepted on ork e2e and ork push to provision worker nodes
alongside the control-plane in the kind cluster created for the run.
Workers and KindVersion propagate into sub-runner New calls for imports.
@iAlexeze
feat(create): --workers and --version for ork create cluster; ork del…
8928054 
…ete cluster

ork create cluster --workers <n> provisions n kind worker nodes alongside
the control-plane. --version <v> selects the kind binary to download
(cached at ~/.orkestra/bin/kind-<version>); previously the version was
hardcoded to v0.27.0.

resolveKind: explicit --version now bypasses the PATH kind binary and uses
the versioned cache entry. An empty version still prefers PATH first, then
falls back to DefaultKindVersion.

waitForNodesReady: replaced the custom polling loop (which checked condition
type, not status, and could return "ready" with NotReady nodes) with
kubectl wait --for=condition=Ready node --all.

ork delete cluster --name <n> is the complement to ork create cluster;
backed by the existing DeleteKindCluster helper.
@iAlexeze
docs: CLI reference for --workers, --version, and ork delete cluster
aa052d5 
create.md: add --workers and --version flag entries, multi-node and
version-pin examples, node-ready behaviour note, pointer to delete.md.

08-e2e.md: add --workers flag.
09-push.md: add --workers flag for the e2e gate cluster.
delete.md: new page for ork delete cluster.
index.md: ork delete cluster entry in the Tooling table.
@iAlexeze
feat(e2e): leaderElection on delete/exec, include blocks, resilience …
0c9b663 
…example refactor

- leaderElection: on kubectl.delete resolves Lease holder and deletes the
  pod by name; replaces shell subcommand anti-pattern in e2e YAML
- leaderElection: on kubectl.exec runs a command inside the leader pod
- validate.go: leaderElection mutually exclusive with file/kind/name on
  delete; mutually exclusive with name/labelSelector on exec
- Rename E2EKubectlPortForwardLeaderElection → E2EKubectlLeaderElection;
  type is now shared by all four kubectl subcommands (YAML keys unchanged)
- include: composition for expect: — long expect sections can be split
  into an e2e/ subfolder and composed with include: entries
- Refactor all three resilience examples to use e2e/ subfolder includes:
  leader-failover (infra-ready, failover, cleanup)
  crd-missing-recovery (health-check, crd-loss, recovery, cleanup)
  admission-protection (degraded, recovery, cleanup)
- Fix: WaitForResource used .Run() for ready checks, letting kubectl
  rollout status and kubectl wait write to the terminal during spinner;
  replaced with .Output(). Same fix for helm repo add/update.
- Revamp documentation/concepts/e2e/04-best-practices.md
- Update 06-leader-led-deployments.md to cover delete and exec subcommands
- Update e2e/index.md description for leader-led-deployments entry
- CHANGELOG.md: v0.7.10 [UNRELEASED] entry
@iAlexeze
test: pkg/ork, pkg/e2e, cmd/cli — happy paths and error paths
8d506d5
@iAlexeze
feat(registry): ork run <ref>, --apply-cr, --use-komposer, komposer.y…
4febd51 
…aml in artifacts

- ork run <name>:<version> pulls the pattern from the registry (if not
  cached) and starts the runtime — no -f flag or local files required
- --apply-cr applies crd.yaml, waits for CRD established, applies cr.yaml
  before starting the runtime; works with OCI refs and local -f paths
- --use-komposer uses komposer.yaml from the pulled pattern instead of
  katalog.yaml; OCI positional arg path only
- --refresh re-pulls the pattern even if already cached
- IsOCIRef helper in pkg/registry/resolve.go distinguishes OCI refs from
  filesystem paths for the positional arg detection
- resolveOCIRunPath helper in cmd/cli/files.go handles pull + path resolution
- applyPatternExamples in run_dev_apply.go applies crd.yaml + cr.yaml from
  the pattern directory; distinct from katalog-declared crdFile/crFiles
- FileKomposer constant added to pkg/registry/constant.go
- komposer.yaml added to OptionalFiles for KatalogKind in pattern.go —
  it was never included as an OCI layer when pushing; re-push required
- documentation/reference/cli/07-run.md rewritten to cover OCI workflow
- documentation/getting-started/07-running-patterns.md new page: full
  inspect → pull → run walkthrough
- CHANGELOG.md: v0.7.10 [UNRELEASED] updated
@iAlexeze
fix: statusCode: assertion for port-forward curl; singular CRD gramma…
1703595 
…r in validate output
@iAlexeze
feat(runtime): extend /katalog summary with endpoint flags, crossAcce…
62f84cc 
…ss, and static CRD fields

IsHealthEnabled/IsInfoEnabled added to EndpointsConfig. CRDSummaryResponse now
carries healthEnabled, infoEnabled, crossAccess, GVK, GVR, Mode, Namespaced,
Namespace, and Description — previously these required a per-CRD info endpoint call.
@iAlexeze
feat(cc): endpoint-aware FetchCRDDetail — disabled endpoints no longe…
d5fc015 
…r show as degraded

Reads healthEnabled/infoEnabled flags from /katalog summary and skips disabled
endpoint calls. Synthesises health and info from the always-available summary.
CRDs with endpoints: enabled: false return state: endpoints-disabled with all
static fields populated. FetchCRList treats 404 as empty list. CrossAccess wired
through CRDSummary and CRDDetail.
@iAlexeze
feat(cc/templates): surface disabled endpoint states across katalog, …
fb3c4fa 
…detail, and docs pages

katalog.html: health badge + ⊘ icon when health disabled; metrics rows gated on
InfoEnabled; ⊘ info endpoint disabled row when fully dark.
crd.html: endpoints-disabled full-page notice; HealthEndpointDisabled notice in
Runtime Health; InfoEndpointDisabled notice in operatorBox section.
crd_docs.html: Endpoints section always shown; crossAccess row in Overview;
operatorBox summary table; Configuration hidden for disabled CRDs; dead else-if
branch fixed in Reconcile Mode.
@iAlexeze
feat(examples+docs): 19-endpoint-control pack and generated docs docu…
8abfcb2 
…mentation

Three-part advanced example pack covering selective health disable, full endpoint
disable, and the fully-dark asymmetric cross-read pattern. Each sub-example has
validate, simulate, e2e, and a walkthrough README. Root simulate/e2e use imports:
to chain all three.

Adds documentation/orkestra-core/03-controlcenter/generated-docs.md covering the
live-generated per-CRD docs page. Updates controlcenter index and changelog.
Adds --dry-run to scripts/fix-bare-fences.py.
@iAlexeze
docs(live-api): reorder pages — endpoints before access control
4497c6c
@iAlexeze
docs: fill gaps in examples README and getting-started guides
388d90a 
- Move 00-kubernetes-basics to getting-started root; add tip callout and Next Steps link in index
- Add 19-endpoint-control to advanced pack table; fix 08-bad-actor description in registry guide
- Add crd-missing-recovery and leader-failover to resilience section in examples/README
- Fix ecosystem-composition: remove non-existent 05-policy-layer/06-all-in-one, use actual 05-all-in-one
- Add registry-guide pack entry and full learning path section (13 examples) to examples/README
@iAlexeze
fix(website): increase sidebar max-height to prevent long sections cl…
ef51ad6 
…ipping
@iAlexeze
fix broken documentation link
060f99e
@iAlexeze
ci: make orkestra-chart-e2e reusable; gate helm release behind chart e2e
c9ce698 
- orkestra-chart-e2e.yml now supports workflow_call with image_tag, repository, and ork inputs; applies chart metadata before running e2e so the tested chart matches what will be released
- release-helm.yml calls it as chart-e2e gate job; helm package-and-push only runs if e2e passes
- Chart.yaml appVersion bumped to 0.7.9
@iAlexeze iAlexeze changed the title feat: endpoint control — surface disabled endpoints across runtime, CC, and docs feat: endpoint control — surface disabled endpoints across runtime, CC, and example pack Jul 5, 2026
@iAlexeze iAlexeze merged commit 7f2e2fb into main Jul 5, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@iAlexeze