Skip to content

Document the update graph and image selection #439

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ecordell merged 1 commit into from
Sep 16, 2026
Merged

Document the update graph and image selection #439

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Loading