Concepts

What is Orkestra?

Orkestra is a declarative operator runtime for Kubernetes. It turns CRDs into fully functional operators without controllers, reconcilers, or conversion code.

You declare what a CRD should do — create a Deployment and a Service, apply defaults, validate fields, convert between versions. Orkestra runs the operator. The code you would have written does not exist.

See Your CRD Is Enough for the full picture.

Do I need to write Go code?

No — for the common case.

Orkestra provides these capabilities declaratively, with no Go:

• Informers watching your exact GVK and version
• Workqueue with configurable depth, backoff, and rate limiting
• Worker pool with configurable concurrency
• Drift correction (reconcile: true on any template resource)
• Owner references and cascade deletion
• Kubernetes event emission
• Leader election
• Health endpoints and Prometheus metrics
• Multi-version CRD conversion
• Admission-time validation and mutation

Go hooks are available when you need them — external API calls, complex conditional logic, type-safe struct access. But hooks are additive. The declarative layer handles everything else.

How does Orkestra differ from Helm or Kustomize?

Different category entirely.

Orkestra is an operator runtime. Helm and Kustomize are deployment tools. They solve adjacent problems and compose naturally — you can use a Helm chart as a Katalog source in a Komposer.

What is a Katalog?

A Katalog is a YAML document that declares how Orkestra should manage one or more CRDs. It is not a Kubernetes CRD itself — it is a file.

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

spec:
  crds:
    website:
      apiTypes:
        group: demo.orkestra.io
        version: v1alpha1
        kind: Website
        plural: websites
      operatorBox:
        default: true
        onCreate:
          deployments:
            - image: "{{ .spec.image }}"
              replicas: "{{ .spec.replicas }}"
              reconcile: true

See the Katalog Schema for all available fields.

What is a Komposer?

A Komposer composes multiple Katalogs from different sources into one unified runtime configuration.

apiVersion: orkestra.orkspace.io/v1
kind: Komposer
metadata:
  name: platform-komposer

imports:
  registry:
    - url: ghcr.io/orkspace/orkestra-registry/postgres@v14
      oci: true
  files:
    - ./katalogs/website.yaml
  helm:
    - repo: https://charts.myorg.io
      chart: platform-crds
      version: 2.1.0

spec:
  crds:
    postgres:
      workers: 8      # override for production

The spec.crds inline block always wins on name conflict — it is the override mechanism. Platform teams publish Katalogs; application teams compose and override.

See the Komposer Schema for all options.

What is the OrkestraRegistry?

The OrkestraRegistry is two things:

1. The internal resource library (../pkg/orkestra-registry/) — Go implementations of Create, Update, Delete, and Resolve for every common Kubernetes resource type: Deployments, Services, Secrets, ConfigMaps, Jobs, CronJobs, Pods, ServiceAccounts. These are called by the reconciler when it processes declarative templates.

2. The public pattern registry (../orkspace/orkestra-registry) — versioned operator patterns distributed as OCI artifacts. Pull a Postgres operator pattern with one line in a Komposer. No binary. No deployment. Just a Katalog.

What is the super-operator model?

The super-operator model is the principle that each CRD gets a complete, isolated operator stack while sharing the runtime infrastructure.

In traditional frameworks, one-operator-per-CRD means one binary, one deployment, one informer factory, one leader election lease per CRD. The isolation is at the process level — expensive.

In Orkestra, one-operator-per-CRD means one informer, one queue, one worker pool, one reconciler per CRD — all inside a single process. The isolation is at the logic level. The runtime infrastructure (API server connection, informer factory, health server, leader election) is shared.

This gives you the isolation guarantee of the one-operator-per-CRD principle at a fraction of the resource cost.

Does Orkestra support multi-version CRDs?

Yes — with zero conversion code.

Each CRD version is a separate entry in the Katalog with its own complete operator stack. Each entry’s informer watches its specific GVK — the API server converts objects to the requested version before delivering them. Conversion rules are declared alongside reconcile templates:

- name: website-v1
  conversion:
    storageVersion: v1
    paths:
      - from: v1alpha1
        to: v1
        spec:
          image: "{{ .spec.image }}"
          seo:
            enabled: false   # v1alpha1 has no seo field — supply default

Production results: 62 conversions, 0 failures, sub-millisecond average latency.