examples

package
v0.7.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 28, 2026 License: Apache-2.0 Imports: 1 Imported by: 0

README

Orkestra Examples

A progressive set of examples — from a single Deployment to multi-source composition, autoscaling, cross-operator dependencies, and full platform stacks built from custom resources.

The fastest way to start

ork init my-operator --pack beginner
cd my-operator/beginner/01-hello-website
ork run --dev

The examples are embedded in the CLI binary — no internet connection needed. They are extracted instantly into your project folder.

Choose your pack

ork init my-operator                                # defaults to beginner
ork init my-operator --pack beginner                # Simple CRDs, Deployments, Services
ork init my-operator --pack intermediate            # Multi-resource, conditions, state machines, Komposer
ork init my-operator --pack advanced                # Hooks, constructors, validation, registries, autoscale, custom resources
ork init my-operator --pack security                # Deletion protection, namespace isolation, admission webhooks
ork init my-operator --pack resilience              # Operators that stay running — panic recovery, degraded state
ork init my-operator --pack use-cases               # Full-stack, cross-CRD, external gates, multi-region, and more
ork init my-operator --pack from-controller-runtime # Migrate from controller-runtime: all 5 options in one pack
ork init my-operator --pack ecosystem-composition   # Build an IDP: ArgoCD, cert-manager, Crossplane, Prometheus

List all packs:

ork init --list-packs

After init, your examples live at:

my-operator/
└── <pack>/
    ├── e2e.yaml            full suite — runs all examples in one command
    └── <example>/
        ├── README.md       step-by-step walkthrough
        ├── katalog.yaml    operator definition
        ├── crd.yaml        the CRD to install
        ├── cr.yaml         sample custom resource
        └── e2e.yaml        end-to-end test for this example

Learning Path

Beginner — --pack beginner

Start here. No cluster setup beyond the ork CLI.

Example What you learn
01 — Hello Website Your first operator. One CRD, one Deployment.
02 — With ServiceAccount RBAC, ServiceAccount wiring, multiple resources.
03 — Copy Secret Built-in Kubernetes kinds. Cross-namespace secret copy.
03b — Copy ConfigMap Same pattern applied to ConfigMaps.
Intermediate — --pack intermediate

You know the basics. Now use more of Orkestra's surface.

Example What you learn
04 — Multi-Resource ConfigMap, status fields, child resource status propagation.
05 — When Conditions Conditional resource creation. Topology that changes with CR state.
06 — Basic Komposer Composing two Katalogs. Environment-specific overrides.
07 — CRD File crdFile: — derive API types from the CRD YAML, no apiTypes: needed.
08 — State Machine Phase-driven reconciliation. Ordered transitions with status guards.
Advanced — --pack advanced

Production patterns. Admission policy, typed Go operators, autoscaling, custom resources, and more.

Example What you learn
07 — Validation and Mutation Admission-time deny/warn. Defaults. Full status.
08 — Komposer with Registry OCI registry source. Multi-environment Komposer.
09 — Go Hooks Typed hooks. OrkestraRegistry from Go.
10 — Custom Constructor Full reconciler control. Migration from existing operators.
11 — Mixed Operator Pattern Dynamic + Hooks + Constructor in one binary.
12 — Autoscale Queue-depth autoscaling, sibling metrics, external gates.
13 — Dependencies Ordered startup across CRDs in-binary, cross-binary, cross-cluster.
14 — Cross-Operator Share data between operators.
15 — Any Language Generate Katalogs from Python, Go, or Node.js.
16 — Custom Resources Compose third-party CRDs as children — 7 sub-examples from single child to full platform.
17 — API Type Override Override API types per Komposer import without editing source Katalogs.
18 — CRD File Komposer crdFile: across Komposer imports.
Security — --pack security

Protect your cluster from accidental deletions, rogue workloads, and bad input.

Example What you learn
Admission Webhooks Validate and mutate CRs at admission time.
Deletion Protection Block deletion of critical CRs via admission.
Namespace Protection Restrict what namespaces operators can act on.
Resilience — --pack resilience

Operators that stay running when things go wrong.

Example What you learn
Safe Reconcile Panic isolation in the worker pool. A nil pointer in a typed hook is caught and recovered — the operator keeps running and other CRDs are unaffected.
Use Cases — --pack use-cases

Real-world patterns combining multiple Orkestra features.

Example What you learn
Full-Stack App forEach + external + cross + once + anyOf in one CR.
Multi-Region Map Deploy across regions using forEach over a map.
CRD Conversion Multi-version CRDs with or without a conversion webhook.
Custom Target spec.custom.target: kubernetes — use ork e2e as a test harness for any operator.
External Gate resource creation on upstream health checks.
Multi-Tenancy Namespace isolation, per-tenant configuration.
Enrich Inject data from external sources into CR status.
Normalize Validate and normalise CR fields at reconcile time.
Profiles Apply different resource configurations based on environment profiles.
From controller-runtime — --pack from-controller-runtime

Migrating an existing operator from controller-runtime to Orkestra. Six progressive examples from baseline to all-5-options.

Example What you learn
00 — Baseline The controller-runtime starting point. The before picture.
01 — Declarative Zero Go. Same behaviour.
02 — Hybrid Declarative + one Go hook for resources templates can't express.
03 — Hooks Only All resources in Go. Typed access to your CRD spec.
04 — Constructor Migration Lift the existing reconcile loop into Orkestra's constructor.
05 — Constructor Ork Resources Same constructor, Orkestra resource helpers replace manual Get/Create/Patch.
06 — Ork Migrate ork migrate rewrites controller-runtime reconcilers automatically.
07 — All Options All five migration options running in one binary via Komposer.
Ecosystem Composition — --pack ecosystem-composition

Build an internal developer platform on top of the tools you already run.

Example What you learn
00 — ArgoCD App CRD → ArgoCD Application. Status propagation. Admission rules.
01 — cert-manager SecurityConfig CRD → Certificate.
02 — Prometheus MonitoringConfig CRD → ServiceMonitor + PrometheusRule.
03 — Crossplane Infra CRD → Crossplane Composite Claim.
04 — Platform Stack All four, composed with Komposer.
05 — Policy Layer Shared admission motif across all CRDs. Deletion protection.
06 — All-in-One Single PlatformResource CRD, workloadType discriminator, all four tools.

E2E test suites

Every example ships with e2e.yaml. Every pack ships with a root e2e.yaml that runs the full suite.

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

# Run an entire pack
ork e2e -f beginner/e2e.yaml
ork e2e -f intermediate/e2e.yaml
ork e2e -f security/e2e.yaml
ork e2e -f resilience/e2e.yaml

# Simulate the full pack (no cluster needed)
ork simulate ./...

Prerequisites

All examples:

  • ork CLI — curl get.orkestra.sh | bash
  • A running Kubernetes cluster (ork create cluster works for every example here)
  • kubectl configured

Advanced typed examples (09, 10, 11) also require:

  • Go 1.22+
  • make registry && make build to compile your operator binary before running e2e

Running any example

# 1. Pick a pack and scaffold your project
ork init my-operator --pack beginner
cd my-operator/beginner/01-hello-website

# 2. Start the runtime
ork run --dev

# 3. Watch the resources appear
kubectl get websites -n default

# 4. Cleanup
./cleanup.sh

Each example's README.md has the exact commands for that example.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var FS embed.FS

FS contains all example packs baked into the CLI at build time. Imported only by CLI commands — excluded from the runtime binary.

developer

Functions

This section is empty.

Types

This section is empty.

Source Files

View all Source files

Directories

Path Synopsis
advanced
15-any-language command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.