Architecture
An Orchard instance is a control plane that runs in a Kubernetes cluster and manages tenant workloads in the same cluster. Kubernetes is the source of truth for every resource that Orchard manages, so Orchard keeps a copy of cluster state for fast reads but always defers to the cluster when the two disagree.
Components
Section titled “Components”| Component | Purpose |
|---|---|
| Frontend | The SvelteKit dashboard. |
| Server | The NestJS API and control plane. |
| MCP server | The Model Context Protocol endpoint for agents. |
| Builders | BuildKit jobs that build images for tenant apps. |
| Control-plane Postgres | Orchard’s own database, run by CloudNativePG. |
| Redis | The event bus between server replicas, and a cache. |
| Registry | Stores the images that builders push. The installer deploys zot. |
| Object storage | Holds database backups and uploads. The installer deploys an S3-compatible store in the cluster. |
Backup proxy (r2-proxy) | Gives each database credentials for its own backups only. |
| Metrics and logs | VictoriaMetrics, VictoriaLogs, and Vector. |
Tenant apps and databases run in their own namespaces, separate from the control plane.
The one-command installer runs every component on one machine. With the Helm chart on a multi-node cluster, you can replace the registry, object storage, Redis, and storage with ones you operate. For the options, refer to Replace bundled components.
flowchart LR U[Browser / CLI / MCP] --> API[API server] API -->|reads| PG[(Control-plane<br/>Postgres)] API -->|writes| Q[Apply queue] Q -->|retry| K8S[Kubernetes API] INF[Engine informers] -->|watch| K8S INF -->|copy state| PG K8S --> NS[Tenant namespaces<br/>apps · databases · jobs] API -->|events via Redis| U
The Orchard Engine lists and watches the Kubernetes objects that Orchard manages, and keeps a copy in Postgres. Most reads come from this copy, so a page load does not call the Kubernetes API.
The Engine follows these rules:
- If the copy and the cluster disagree, the cluster is correct.
- A failed read does not mean that a resource is gone. Only a live
404response removes it. - A change made with
kubectlis adopted into Orchard. Security objects are the exception. Orchard restores its own version of default-deny network policies and records the change in the audit log.
Writes
Section titled “Writes”Most cluster writes go through an apply queue. The request records the desired state and returns. A worker applies the change and retries with backoff on a failure.
Events
Section titled “Events”Orchard sends state changes to the dashboard as server-sent events over Redis Streams. After a reconnect, the client replays from the last event it received. Without Redis, each server replica delivers only its own events.
Replicas and leases
Section titled “Replicas and leases”Background work that must not run twice, such as watching the cluster, uses a Kubernetes lease. Only the replica that holds the lease does that work, so the server can run more than one replica.
By default, each server pod serves the API and runs the queues. To run builds, notifications, and the apply queue in separate pods, set server.workers.enabled to true in the chart.
If the control plane stops
Section titled “If the control plane stops”Apps, databases, and routes are ordinary Kubernetes objects, so they do not depend on the Orchard server, frontend, or engine. If those stop, apps keep running and serving traffic, and CloudNativePG keeps managing database failover and backups. Builds, deploys, and other changes wait until Orchard is back. An upgrade of Orchard does not restart apps either. For more information, refer to Upgrade Orchard.
Related resources
Section titled “Related resources”- Security and isolation - Review what Orchard isolates between tenants and what they share.
- Scale the control plane - Run more replicas, autoscale, and move builds to worker pods.
- Configure logs and request data - Learn how the log store collects app and access logs.
- Concepts - Learn the terms that Orchard uses, such as organizations, projects, and apps.