docs: document upgradeChannel and version probe#216
Conversation
| | Condition | Reason | Meaning | | ||
| |---|---|---| | ||
| | `VersionInSync` | `VersionMatch` | All replicas report the same version as the image | | ||
| | `VersionInSync` | `VersionMismatch` | Replicas are running different versions (typically during a rolling upgrade) | |
There was a problem hiding this comment.
It is suppressed during upgrades. This may happen if a mutable image tag has been specified. For example, latest or only a major version 26.3
There was a problem hiding this comment.
Updated. Table now says VersionMismatch is suppressed during a planned rolling upgrade, and surfaces when a mutable tag (latest / bare 26.3) pins replicas to different patches of the same tag
| | `VersionUpgraded` | `MinorUpdateAvailable` | A newer patch is available in the same `major.minor` line | | ||
| | `VersionUpgraded` | `MajorUpdateAvailable` | A newer `major.minor` is available within the chosen channel | | ||
| | `VersionUpgraded` | `VersionOutdated` | The running version is older than every release in the selected channel | | ||
| | `VersionUpgraded` | `WrongReleaseChannel` | The configured `upgradeChannel` does not match any upstream channel (e.g. typo) | |
There was a problem hiding this comment.
No, this means that the chosen image does not match the specified upgradeChannel
There was a problem hiding this comment.
Updated. The description now says the running image does not belong to the selected upgradeChannel, with the 26.5 + upgradeChannel: lts example I observed locally
| | `VersionUpgraded` | `UpToDate` | The cluster is on the latest version available in the selected channel | | ||
| | `VersionUpgraded` | `MinorUpdateAvailable` | A newer patch is available in the same `major.minor` line | | ||
| | `VersionUpgraded` | `MajorUpdateAvailable` | A newer `major.minor` is available within the chosen channel | | ||
| | `VersionUpgraded` | `VersionOutdated` | The running version is older than every release in the selected channel | |
There was a problem hiding this comment.
Better to say that the chosen version is out of date and won't get any fixes
There was a problem hiding this comment.
Rephrased to highlight the consequence: the running version is out of date and will no longer receive fixes from the selected channel, typically because the major line was dropped from lts/stable upstream
| | `lts` | Tracks the upstream `lts` channel — long-term support releases. Receives major upgrades less frequently, with longer support windows. | | ||
| | `25.8` (or any `<major>.<minor>`) | Pins the channel to a specific major.minor line. Major upgrades beyond it are not proposed even if a newer version exists upstream. | | ||
|
|
||
| A cluster left on the default (empty) channel is the safest choice for production: the operator will only flag patch-level updates, and never surprises you with a major version jump even if you redeploy the operator. |
There was a problem hiding this comment.
Doubtful comment. I'd expect that pinning the exact release maj.min is better for production, as it also checks that replicas are deployed within the expected major release, especially if image hash is used instead of human-readable tags
There was a problem hiding this comment.
Good point. Flipped the recommendation. The paragraph now favors pinning to an explicit <major>.<minor> for production (catches drift via WrongReleaseChannel, important when image is referenced by digest), with empty default suitable for development.
2 participants
Adds a "Version probe and upgrade channel" section to the configuration guide covering
spec.upgradeChannel,spec.versionProbeTemplate, theVersionInSync/VersionUpgradedstatus conditions, and the operator-wide--version-update-interval/--disable-version-update-checksflags.Why
The operator does two version-related things that currently have no documentation:
Jobto detect the running ClickHouse / Keeper version (spec.versionProbeTemplate).spec.upgradeChanneland theVersionUpgradedstatus condition).A search for
upgradeChannelorversionProbeunderdocs/returns no matches, meaning users currently need to readapi/v1alpha1/clickhousecluster_types.go,internal/upgrade/, andcmd/main.goto understand these features, accepted release channel values, status condition meanings, and how to disable upgrade checks in air-gapped environments.What
Adds a new
## Version probe and upgrade channelsection todocs/guides/configuration.mdx, placed between## Additional portsand## ClickHouse settings, with four subsections:upgradeChannelvalues (empty,lts,stable, andmajor.minor), including the CRD validation pattern and guidance on when to use each option.VersionInSync(VersionMatch,VersionMismatch,VersionPending,VersionProbeFailed) andVersionUpgraded(UpToDate,MinorUpdateAvailable,MajorUpdateAvailable,VersionOutdated,WrongReleaseChannel,UpgradeCheckFailed), based onapi/v1alpha1/conditions.go.spec.versionProbeTemplateexample showing tolerations, node selectors,ttlSecondsAfterFinished, and container resource overrides.--version-update-interval(default24h) and--disable-version-update-checksflags for tuning or disabling upgrade checks, including air-gapped deployments.No code or chart changes. Documentation only.