Requirements

Shepherd is a single Go binary with the UI embedded in it, and it keeps no state outside PostgreSQL. The list is genuinely short.

To…You need
Deploy on Kubernetes
the intended way		 Kubernetes 1.32+, Helm 3 or 4, and PostgreSQL 16 or newer that the cluster can reach (the test suites run 16, the dev and e2e stacks 18; older majors are untested). The chart needs no CRDs by default.
  • An older cluster is refused at install: the chart declares the floor in kubeVersion. A very old helm refuses to render it offline too, because helm template takes its Kubernetes version from the binary.
  • Why 1.32: it is the lowest version the chart’s Kubernetes test suite proves (its Gateway API router needs 1.32), and it covers the optional CloudNativePG path (Database, 1.29+). Chart 0.18 and older accepted 1.29.
  • metrics.serviceMonitor.enabled needs the Prometheus Operator's CRDs; route.enabled and receiver.enabled need the Gateway API CRDs; cnpg.enabled needs CloudNativePG’s and externalSecrets.enabled the External Secrets Operator’s.
Run Shepherd anywhere else The same PostgreSQL and somewhere to run one container. Shepherd is stateless, so nothing else is needed — but the fleet it manages is a Kubernetes concern, so this is mainly useful for development.
Run the receiver tier
optional		 The Gateway API CRDs, v1.4 or newer on the Standard channel, and an implementation that runs a Gateway (tested with NGINX Gateway Fabric). A CNI that enforces NetworkPolicy — the receiver accepts traffic only from your gateway's pods, and without enforcement that rule does nothing. See Receiver tier.
Run collectors Grafana Alloy v1.20.1 — the version whose component schema this build validates against, pinned in deploy/versions.env. Alloy needs remotecfg support.
Build from source Go 1.27.2 (per go.mod), Node 26 and pnpm 12, Docker (the Go suite starts real Postgres via testcontainers), and Helm for the chart tests.

Two configuration values are mandatory and the server refuses to start without them: database.url and security.encryption_key (a base64-encoded 32 bytes). The encryption key protects git credentials and the OIDC client secret at rest — keep it, because a replacement key cannot decrypt what the old one wrote.