Installation and Upgrades

Where Deployment Models is about which topology to run, this capability is about the mechanics of getting a Control Plane or Data Plane running and keeping it current — the same deployments/ manifests, used differently.

A first install is applying the namespace, Postgres, and Deployment manifests for a plane (deployments/k8s/cp or deployments/k8s/dp) into a cluster, with configuration supplied entirely through environment variables on the container — database connection string, external endpoint, OIDC issuer/client/audience, and (for the Data Plane) a connector-credential encryption key sourced from a Kubernetes Secret rather than inlined in the manifest. deployments/kind-config.yaml and the top-level docker-compose.yml (Postgres, Memgraph, NATS) exist to make that same first-install flow reproducible on a laptop for development.

An upgrade is an image tag bump on the existing Deployment, not a separate procedure. Each plane's container entrypoint (control-plane/scripts/entrypoint.sh, data-plane/scripts/entrypoint.sh) runs every migrations/*.up.sql file against DATABASE_URL on every container start, in filename order, before starting the Go binary — so rolling to a new image version replays the full forward-migration history against whatever schema state the database is already in. Each plane carries its own migration set (control-plane/migrations, data-plane/migrations), versioned as numbered up/down SQL pairs. Notably, the entrypoint script continues past a failed migration statement rather than aborting the boot (|| true on each psql call) — a deliberate tolerance for a migration that has already been applied in a prior run, but also one an operator upgrading a deployment should be aware of: a migration failure will not stop the new version from starting.

Rollback, correspondingly, is a matter of pointing the Deployment back at the previous image tag; the corresponding .down.sql files exist per migration for a database-level rollback, but nothing in the entrypoint or the plane binaries runs them automatically — reverting schema changes is a manual step an operator runs against DATABASE_URL directly.

Both plane images bake in docs/corpus/ — the Canonical Documentation Corpus — at build time (see the control-plane/Dockerfile and its Data Plane counterpart), which is what lets air-gapped and private-cloud installs have working in-product documentation with no outbound network access from the moment the plane starts, frozen at exactly the version deployed until the next upgrade.