Learning to Orkestrate

Every Orkestra capability is demonstrated in a runnable example. This page is the map. Whether you are writing your first operator or converting an existing Go controller, start here.

Two commands to your first operator

ork init
ork run

No cluster? Add --dev to create a temporary kind cluster. Requires Docker.

Packs

Examples are grouped into packs. Pull any pack with ork init --pack <name>.

Pack	Focus
Beginner	Foundation — CRDs, templates, status, owner references
Intermediate	`when:`, Komposer basics, state machines, CRD files
Advanced	Admission, composition, escape hatches, autoscaling, cross-operator
Use-cases	Normalize, enrich, profiles, full-stack patterns, external calls, motif composition
Security	Admission, deletion protection, namespace isolation
Resilience	Panic recovery, degraded state, operator isolation
Registry Guide	Distribution — publish, version, gate, consume, and automate the full pattern lifecycle
Migration Guide	Migrating an existing controller-runtime operator to Orkestra — five options, zero lock-in
Ecosystem Guide	Wrapping ArgoCD, cert-manager, Prometheus, and Crossplane with Orkestra abstraction layers

Running any example

Every example follows the same pattern:

ork init --pack <pack>
cd <pack>/<example>
ork run           # defaults to katalog.yaml, then komposer.yaml
ork control       # localhost:8081 · orkestra / orkestra

Pass -f <file> when the Katalog or Komposer uses a non-default filename. ork e2e defaults to e2e.yaml.

E2E test suites

Every example ships with a runnable e2e.yaml. Every pack ships with a root e2e.yaml that imports all sub-examples.

# Run a single example end-to-end
cd beginner/01-hello-website && ork e2e

# Run an entire pack in one command
ork e2e -f beginner/e2e.yaml
ork e2e -f intermediate/e2e.yaml
ork e2e -f security/e2e.yaml

Each suite creates a kind cluster, runs all examples in sequence, and tears everything down. No setup required beyond the ork CLI and Docker.

Each example has its own README.md. Follow it — it tells you exactly what to apply, what to observe, and what the expected output is. The README is the guide; the YAML files are the demonstration.

Which example to start with

New to Kubernetes operators

Start with beginner/01-hello-website — the mental model it builds is the foundation for everything else.

Know Kubernetes, new to Orkestra

beginner/01-hello-website, then intermediate/05-when-conditions and advanced/07-validation-mutation

Migrating from controller-runtime, Kubebuilder, or Operator SDK

Migration Guide — the full migration pack; see all five options before choosing one
ork migrate <file> to automate the constructor path for an existing reconciler
advanced/09-hooks to wrap existing Go logic
advanced/10-constructor to bring a full reconciler across intact

Building a platform

advanced/08-komposer-registry and advanced/13-dependencies
Then use-cases/full-stack-app/06-full-stack for how the patterns compose

Supply chain and policy enforcement

use-cases/external/03-image-signing → 07-vault-secret-gate → 08-opa-policy
Then 10-motif-composition to see them composed as reusable motifs

Enforcing org policy without Go

use-cases/external/08-opa-policy for runtime decisions
advanced/07-validation-mutation for admission-time enforcement

Status propagation and drift correction

advanced/16-custom-resources sub-examples 02 and 04

Cross-operator data sharing

advanced/14-cross-operator/01-in-binary

Autoscaling workers

advanced/12-autoscale/02-based-on-own-metrics

Publishing and distributing operators

Start with registry-guide/00-consume — pull a proven pattern and deploy it before building your own
Then registry-guide/02-katalog-api through 04-katalog-platform to build the publish → gate → distribute pipeline
registry-guide/05-komposer for production deployment with admission and deletion protection
registry-guide/12-ork-action to automate everything in CI

Supply chain verification

registry-guide/08-bad-actor — simulate passed, ork plan caught what the assertions missed

Available packs

ork init --list