Getting Started

Orkestra turns a YAML file into a working Kubernetes operator. This guide takes you from zero to a running operator — no Go, no code generation.

Requirements

• A running Kubernetes cluster — kind recommended for local development
• kubectl configured and pointing at your cluster

No cluster yet? Use ork run --dev below — it creates a local kind cluster automatically.

Install

macOS (Homebrew)

brew install orkspace/tap/ork orkspace/tap/orkcc

This installs two binaries: ork (the operator CLI) and orkcc (the Control Center).

Linux / macOS (curl)

curl -sSL https://get.orkestra.sh | bash

Verify

ork version

Your First Operator

Step 1 — Scaffold a project

ork init

ork init creates a katalog.yaml in the current directory, ready to run.

Step 2 — Start the operator

If you have a running cluster:

ork run

If you have no cluster yet, add --dev — Orkestra creates a kind cluster automatically:

ork run --dev

You will see:

INFO  CRD applied                crd=websites.demo.orkestra.io
INFO  CR applied                 name=hello-website namespace=default
INFO  Informer synced            crd=website
INFO  Workers started            crd=website  workers=3
INFO  Health server ready        addr=:8080

Step 3 — Reconciliation

Watch Orkestra’s output in the first terminal. You’ll see the reconcile event arrive and the Deployment get created.

Step 4 — Verify

kubectl get deployments
kubectl get pods

A Deployment named hello-website-deployment appears. Orkestra set owner references — deleting the Website CR will cascade-delete it.

Step 5 — Open the Control Center

In a second terminal:

ork control

Open http://localhost:8081 to see the live operator — CRD health, worker state, reconcile metrics, queue depth.

What the Katalog Looks Like

The katalog at katalog.yaml:

apiVersion: orkestra.orkspace.io/v1
kind: Katalog
metadata:
  name: hello-website

spec:
  crds:
    website:
      crdFile: ./crd.yaml
      crFiles:
        - ./cr.yaml

      operatorBox:
        default: true
        onCreate:
          deployments:
            - image: "{{ .spec.image }}"

crdFile points to the CRD definition. Orkestra reads it, infers the API types, and applies it to the cluster automatically when ork run starts. No separate kubectl apply -f crd.yaml step.

When the CR is applied, Orkestra resolves {{ .spec.image }} from the live CR and creates the Deployment.

Built-in Health Endpoints

While the operator is running:

# Health check for the website CRD
curl localhost:8080/katalog/website/health | jq

# Full detail — workers, queue, reconcile stats
curl localhost:8080/katalog/website | jq

# All managed CRDs
curl localhost:8080/katalog | jq

# Prometheus metrics
curl localhost:8080/metrics

Cleanup

# Delete the CR — cascades to the Deployment
kubectl delete -f examples/beginner/01-hello-website/cr.yaml

# Stop the operator
Ctrl+C

CLI Reference

Next Steps

• Writing Your First Katalog — build your own operator from scratch
• Basic Reconciliation — understand the full reconcile lifecycle
• Learning to Orkestrate — progression through the example packs