Orkestra · Architecture

katalog.yaml

The central declaration. Every plane reads from it — nothing is configured separately.

Gateway reads: serve · tokens · aliases · auth Runtime reads: operatorBox · lifecycle · watch · status CLI reads: validate · simulate · e2e · generate

↓ ↓ ↓

CI pipelineOIDC token · polls pollUrl

Browser · Control Centerform generated from serve declaration

Webhook intakeGitHub · GitLab · Slack · generic

curl · SDKflat intent · no apiVersion · no kind

kubectl · GitOpsFlux · ArgoCD · direct CR apply

↓

Intent Plane · Gateway · self-service · auth · translation · provenance

ork serve play · ork gate · ork webhook play

target resolution → token check → CR construction → field translation → provenance stamp → admission → CR delivered

Every delivered CR carries permanent annotations: serve-target · serve-alias · serve-source · serve-token-class

↓

Execution Plane · Runtime · per-CRD OperatorBox · reconciliation

ork simulate · ork simulate --envtest · ork e2e

OperatorBox — per CRD, per reconcile

Absorbed by the runtime

informer workqueue worker pool leader election

retries + backoff finalizers status patching panic recovery

admission webhooks validation rules mutation rules RBAC

health endpoints Prometheus metrics drift correction owner references

Yours to declare or write

onCreate / onReconcile / onDelete — declarative templates

hooks — Go for non-HTTP logic

constructor — keep your existing Reconcile

validation / mutation rules — declared, not coded

status.fields — template expressions

↓ ↓

Observation Plane

Control Center /katalog API Prometheus metrics health endpoints Kubernetes events operator docs

Resource Plane

Deployments · Services StatefulSets · Jobs Custom Resources external systems workloads

Testing — one tool per layer, nothing mocked

Intent layer

ork serve play no cluster

Full 6-stage delivery chain from a flat intent file. Same code as production.

ork gate no cluster

Admission rules against a CR you provide directly. Reproduces webhook denials locally.

ork webhook play no cluster

Webhook intake — branch filters, watch patterns, content fetch, full delivery chain.

Execution layer

ork simulate no cluster

Real reconciler against an in-memory store. Template expressions, when: conditions, status propagation. Sub-second.

ork simulate --envtest no cluster

Same reconciler against a real kube-apiserver + etcd spun locally. CRD schema enforcement, real watch streams. ~3–5s.

System layer

ork e2e real cluster

Real Kubernetes cluster. Real admission webhooks with TLS. Actual pod scheduling, finalizer sequencing, leader election. The only layer that needs a cluster.

Steps 1–4 run in milliseconds.
ork e2e is the gate before ork push — not the inner loop.