DOCSEARCHbyAlgolia
Submit Docs

Orkestra Documentation

website·Indexed 29 days ago

https://orkestra.sh

Documentation for Orkestra, an open-source framework for Kubernetes operators. It features a central declaration system via katalog.yaml, a reconciler model, and tools for managing CRDs, Motifs, and E2E testing. The platform includes a CLI for cluster bootstrapping and a registry for publishing and managing Katalogs.

Tokens
331.1K
Snippets
1.8K
Records
2.4K
Agent score
45%

What's inside Orkestra

  1. Overview of Orkestra Schema Patterns

    Orkestra uses several patterns to define operator behavior and resource management:

    • Motif: A reusable resource primitive with parameterized inputs; it does not have a standalone runtime.
    • Katalog: The top-level operator definition, including CRDs, resources, status, and admission rules.
    • Komposer: Used to compose multiple Katalogs from files, Helm charts, or OCI registries.
    • E2E: Declarative end-to-end tests for a Katalog.
    • Simulate: In-memory reconciler verification that does not require a cluster.
    • Resources: Kubernetes built-in and custom resources declarable under onCreate, onReconcile, or onDelete.

  2. Overview of ork e2e behavioral verification

    ork e2e is a Kubernetes behavioral verification tool that validates the state of a cluster by spinning up a real environment, installing workloads, and watching the API server to assert GVK (Group Version Kind) state. It is agnostic to the installation mechanism; it can verify workloads created via Orkestra operators, Helm charts, controller-runtime reconcilers, or kubectl apply. This allows developers to prove that a deployment actually works (behavioral verification) rather than relying solely on signatures or manifests.

  3. Overview of the Orkestra Super-Operator Model

    Orkestra is a framework that makes Kubernetes operators declarative. Instead of writing Go code, scaffolding controllers, and managing build pipelines for every Custom Resource Definition (CRD), developers define their operators in a Katalog.

    In the 'super-operator' model, each CRD still functions as a fully isolated operator with its own informer, worker pool, workqueue, health endpoints, and metrics. However, they share a common orchestration infrastructure (the runtime) that manages their lifecycle, dependency order, and observability, eliminating the need for separate binaries and deployments for every CRD.

  4. Overview of Orkestra declarative operators

    Orkestra is a runtime that allows developers to create Kubernetes operators without writing imperative code (e.g., Go). Instead of writing a reconciler loop, developers define a 'Katalog'—a declarative mapping that translates the desired state in a Custom Resource (CR) spec into the actual state of Kubernetes child resources. The runtime provides the necessary infrastructure (informers, workqueues, worker pools, and health endpoints) automatically for every CRD.

  5. Overview of Orkestra Control Center architecture

    The Control Center (cmd/controlcenter) is a lightweight Go web server using embedded HTML templates. It functions by connecting to one or more Orkestra runtimes via their /katalog HTTP API to display running components. For CRDs where serve.enabled: true is configured, it connects to a companion gateway's Gateway API to provide a form-based interface for creating new instances.

  6. Overview of Orkestra testing tools

    Orkestra provides a layered testing strategy designed to push as much verification as possible to local, cluster-less tools that run in milliseconds. Only the final stage (ork e2e) requires a real Kubernetes cluster to test system behaviors like TLS, pod scheduling, and finalizer sequencing.
    ToolWhat it testsNeeds clusterSpeed
    ork serve playIntent delivery chain (target resolution, token check, CR construction, provenance, admission, response)Noms
    ork gateAdmission rules against a pre-built CRNoms
    ork gate runFull local gateway for ork serve apply round-tripsNoms
    ork webhook playWebhook intake (branch filters, watch patterns, content fetch, delivery chain)Noms
    ork simulateReconciliation (full operatorBox against in-memory cluster)Noms
    ork simulate --envtestReconciler against real kube-apiserver + etcdNo~3–5s
    ork e2eSystem behavior (real cluster, scheduling, webhooks)Yesmins

  7. Overview of Orkestra Control Center

    The Orkestra Control Center is a web UI used to monitor one or more Orkestra runtime instances. It aggregates data directly from runtime APIs without requiring additional instrumentation or custom metrics. It provides several views:

    • Control Center: A global view of all Katalogs across configured runtimes.
    • Control Panel: Per-Katalog drill-down showing CRD cards, worker pools, queue pressure, and error rates.
    • CRD Detail: Deep dive into specific CRDs, including worker state, RBAC permissions, dependencies, and admission metrics.
    • Resources: A live list of actual objects being reconciled for a specific CRD.
    • CR Detail: Single CR view showing status fields, conditions, and child Kubernetes resources grouped by kind.
    • Generated Docs: Live documentation derived from the running operator covering API shape, reconcile mode, RBAC, and more.

  8. Overview of Kubernetes Expression Language (KEL)

    KEL is not a standalone language with its own parser or grammar, but a library of composable functions integrated into Go's text/template engine. It provides a standardized vocabulary for expressing Kubernetes operational knowledge, allowing users to reason about the state of Kubernetes objects (like health, readiness, and timing) directly within template expressions. Because it uses the Go template engine, KEL expressions can be evaluated consistently across reconcilers, admission webhooks, E2E test runners, and CLIs.

  9. Overview of Orkestra E2E testing

    An E2E test in Orkestra is a declarative YAML file used to test a Katalog. It allows developers to define what resources to apply, which cluster to use, and the expected state of the system without needing a Go-based test framework. The test lifecycle typically involves creating a cluster, applying CRDs and CRs, verifying resource states via checkpoints, and cleaning up.

  10. Overview of the Orkestra Super-Operator Model

    Orkestra implements a 'super-operator' model that decouples the operator pattern from the requirement of one binary per CRD. Instead of deploying dozens of separate processes (operator sprawl), Orkestra provides a shared runtime that hosts isolated operator stacks for each CRD. Each CRD receives its own dedicated informer, workqueue, worker pool, reconciler, health endpoint, and Prometheus metrics, ensuring failure isolation while reducing operational overhead.

  11. Overview of the Orkestra Operator Autoscaler

    The Operator Autoscaler is a built-in Orkestra subsystem that dynamically adjusts an operator's performance parameters—specifically worker count, queue depth, and resync interval. It operates as a runtime-native 'mini-controller' inside the operator process, meaning it requires no external controllers, Deployments, or CRDs.

    Autoscaling is declarative: users define the conditions (when) and the actions (how), and Orkestra applies overrides instantly. When conditions are no longer met, the system automatically restores the baseline values declared in the CRD. The autoscaler prevents oscillation by enforcing cooldown periods and operates without requiring an Orkestra restart.

  12. Overview of Orkestra Notes

    Notes are the template vocabulary of an Orkestra Katalog. They are pure functions available inside every {{ }} expression, allowing developers to reason about CR field values rather than just copying them. All notes must be pure (same input always produces same output), safe (nil/empty input never panics), and stateless (no I/O or side effects).
    status:
  fields:
    - path: image
      value: "{{ fullImage }}"          # user-defined note
    - path: ready
      value: "{{ allReplicasReady .children.deployments.api }}"  # built-in note