Skip to content
Install

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.

ComponentPurpose
FrontendThe SvelteKit dashboard.
ServerThe NestJS API and control plane.
MCP serverThe Model Context Protocol endpoint for agents.
BuildersBuildKit jobs that build images for tenant apps.
Control-plane PostgresOrchard’s own database, run by CloudNativePG.
RedisThe event bus between server replicas, and a cache.
RegistryStores the images that builders push. The installer deploys zot.
Object storageHolds 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 logsVictoriaMetrics, 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 server reads from Postgres and writes through a queue. The Orchard Engine copies cluster state into Postgres.

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 404 response removes it.
  • A change made with kubectl is 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.

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.

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.

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.

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.