Version Map Reference¶
The GitlabVersionMap named default is the single cluster-scoped resource that maps GitLab application versions to GitLab Helm chart versions. The operator always looks it up by the name default.
Current default ladder¶
The ladder covers all required upgrade stops from GitLab 17.3 through 19.x. Each entry corresponds to a stop through which every upgrade path must pass.
apiVersion: k8s.bnerd.com/v1alpha1
kind: GitlabVersionMap
metadata:
name: default
spec:
versions:
"17.3.0":
chartVersion: "8.3.0"
"17.5.5":
chartVersion: "8.5.5"
"17.8.7":
chartVersion: "8.8.7"
"17.11.7":
chartVersion: "8.11.8"
"18.2.8":
chartVersion: "9.2.8"
"18.5.7":
chartVersion: "9.5.7"
"18.8.10":
chartVersion: "9.8.11"
"18.11.6":
chartVersion: "9.11.7"
"19.1.1":
chartVersion: "10.1.1"
aliases:
latest: "19.1.1"
stable: "18.11.6"
"17": "17.11.7"
"18": "18.11.6"
"19": "19.1.1"
Upgrade path at a glance¶
17.3.0 (chart 8.3.0)
↓
17.5.5 (chart 8.5.5) ← required stop
↓
17.8.7 (chart 8.8.7) ← required stop
↓
17.11.7 (chart 8.11.8) ← required stop
↓
18.2.8 (chart 9.2.8) ← major version jump; chart 8→9
↓
18.5.7 (chart 9.5.7) ← required stop
↓
18.8.10 (chart 9.8.11) ← required stop
↓
18.11.6 (chart 9.11.7) ← required stop (stable alias)
↓
19.1.1 (chart 10.1.1) ← major version jump; chart 9→10; external S3 mandatory
(latest alias)
Never skip a required stop
GitLab enforces upgrade stops via irreversible database migrations. Skipping a stop will cause GitLab to refuse to start. Follow the ladder one step at a time. See Version Management for the full upgrade procedure.
Aliases¶
| Alias | Resolves to | Notes |
|---|---|---|
latest |
19.1.1 |
The latest qualified release |
stable |
18.11.6 |
The last stable 18.x release |
"17" |
17.11.7 |
Latest 17.x stop |
"18" |
18.11.6 |
Latest 18.x stop |
"19" |
19.1.1 |
Latest 19.x stop |
Using an alias is convenient but be aware that the alias target changes when the map is updated. Set spec.version to an explicit version string (e.g. "18.11.6") if you need a deterministic, pinned upgrade.
Adding a new version¶
When a new GitLab release is qualified for your platform:
Add the entry:
Update the alias if this becomes the new stable:
Editing the map does not automatically upgrade running instances. Instances are only upgraded when spec.version on the GitlabInstance is changed to the new version string.
Chart version mapping background¶
The GitLab Helm chart version follows a separate numbering scheme from the GitLab application. The mapping is maintained in the official GitLab chart documentation. The default map in this operator tracks the required upgrade stops only — not every patch release.
| Chart major | GitLab major | Notes |
|---|---|---|
| 8.x | 17.x | |
| 9.x | 18.x | |
| 10.x | 19.x | Bundled MinIO removed; external S3 mandatory |