From cde955a53597f4f4aba11cfb579e684eb4355f80 Mon Sep 17 00:00:00 2001 From: ivanauth Date: Wed, 8 Jul 2026 20:55:40 -0400 Subject: [PATCH] Document the update graph and image selection Explain where the update-graph ConfigMap comes from and what it does, and clarify how the graph's imageName field relates to the image and baseImage fields on SpiceDBCluster, including the precedence between them. Signed-off-by: ivanauth --- README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/README.md b/README.md index 43aca94a..5bb2246d 100644 --- a/README.md +++ b/README.md @@ -230,3 +230,18 @@ spec: config: image: ghcr.io/authzed/spicedb:v1.11.0-prerelease ``` + +### The Update Graph + +Update channels are defined by an update graph, which the operator reads from the file passed to its `--config` flag. +In the [default deployment](config/operator.yaml), this file is provided by the `update-graph` ConfigMap, which is generated from [update-graph.yaml](config/update-graph.yaml). +The operator watches this file and picks up changes without a restart, and new releases of the operator ship with an updated graph that includes new SpiceDB versions. + +Each channel in the graph lists the SpiceDB versions available for a datastore engine and the edges between versions that are known to be safe to update between, including any required migrations and phased rollouts. +When updating a cluster, the operator walks these edges from the current version to the target version instead of jumping directly, so that required intermediate steps are not skipped. + +The top-level `imageName` field in the graph defines the default image repository (`ghcr.io/authzed/spicedb`) that the tag or digest for each version is appended to; it is not a way to pin a specific version. +To pull SpiceDB from a different registry (such as an internal mirror) while still following update channels, set `.spec.baseImage` on the `SpiceDBCluster`, or run the operator with the `--base-image` flag to change the default for all clusters, rather than editing the graph. +Setting `.spec.config.image` to a specific tag or digest instead opts the cluster out of update channels entirely, as described in [Force Override](#force-override). + +If more than one of these is set, the operator picks the image repository in this order: `.spec.config.image`, then `.spec.baseImage`, then the `--base-image` flag, then `imageName` from the update graph.