examples

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Jun 2, 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/examples/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, 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 use-cases         # Full-stack, cross-CRD, external gates, multi-region
ork init my-operator --pack rollback          # Zero-config and configurable failure recovery
ork init my-operator --pack developer         # Deploy your app without writing YAML

List all packs:

ork init --list-packs

After init, your examples live at:

my-operator/
└── examples/
    └── <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
            └── cleanup.sh      removes everything the example created

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 — Website with Service Multiple resources. Drift correction.
03 — Copy Secret Built-in Kubernetes kinds. Cross-namespace secret copy.
BONUS 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 with Status 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.
Advanced — --pack advanced

Production patterns. Admission policy, registry composition, Go hooks, autoscaling, custom resources.

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. External API calls.
10 — Custom Constructor Full reconciler control. Migration from existing operators.
11 — Mixed Operator Pattern Dynamic + Hooks + Constructor together 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 Communication Share data between operators: in-binary, cross-binary, cross-cluster.
15 — Any Language Generate Katalogs from Python, Go, or Node.js.
16 — Custom Resources Compose third-party CRDs as children of your own — see below.
16 — Custom Resources (sub-examples)

This example set has its own progression, from a single child CR all the way to full platform composition:

Sub-example What you learn
01 — Single Child CR onCreate.custom, templates, owner references, cascade deletion.
02 — Status Propagation hasStatus: true, reading child status back into the parent.
03 — Conditional Children when: — create, skip, and cleanup child CRs based on parent flags.
04 — Drift Correction reconcile: true — keep child CRs in sync on every reconcile.
05 — forEach Sharding forEach: fan-out — one child CR per list element.
06 — Full Platform Composition Motif imports, three child CRs, status aggregation across the stack.
07 — Multi-CRD Pipeline Multiple child CRs + multiple controllers in one Katalog from a Motif.
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.
Use Cases — --pack use-cases

Real-world patterns combining multiple Orkestra features.

Example What you learn
Full-Stack App Frontend + backend + database composed as one CR.
CRD Conversion Multi-version CRDs with or without a conversion webhook. Two approaches, same result.
Multi-Region Map Deploy the same workload across multiple regions using forEach.
Rollback Zero-config and configurable failure recovery.
Rollback — --pack rollback

Focus on failure recovery patterns.

Example What you learn
Rollback sub-examples Automatic rollback, configurable policies, recovery hooks.
Developer — --pack developer

Deploy your app to Kubernetes without writing operator code or knowing CRDs.

Example What you learn
01 — One Project Single-service deployment, zero YAML knowledge required.
02 — Frontend + Backend Two services, automatic wiring.
03 — Rollback + Ingress Ingress, rollback, HTTPS.
04 — Notifications Slack/webhook alerts on deployment events.
05 — Deletion Protection Prevent accidental deletion of running services.
06 — Docker Compose + Postgres Lift a Docker Compose stack into Kubernetes as-is.

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

Each suite creates a kind cluster, runs all examples in sequence, and tears everything down. No extra setup needed.

Prerequisites

All examples:

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

Advanced typed examples require:

  • Go 1.22+ for hook and constructor examples

Running any example

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

# 2. Start the operator
ork run --dev

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

# 4. Cleanup
chmod +x cleanup.sh
./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.