Release versions

Status: Proposed Issue: https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/work_items/2369 Parent: none

Goal

An administrator chooses one GitLab version, or a channel of GitLab versions, and the Operator runs the chart of every component in that release as the GitLab release manifest records it: the GitLab chart, and the Siphon and Orbit charts once they are modules of the manifest. A chart version is named only to override the manifest.

Child specs:

  • GitLabCore versions: how a GitLabCore selects a GitLab version, and what its status reports.
  • Add-on versions: how a Siphon and an Orbit follow the release of their GitLabCore, and how an upgrade waits for them.

Requirements

  • A release selects, for each resource, the chart its record in the release manifest lists as the module of that resource: gitlab-chart for a GitLabCore, and the Siphon and Orbit modules for a Siphon and an Orbit.
  • RELEASE_MANIFEST_URL points the Operator at the published manifest or at a mirror of it. It must be an https:// URL unless RELEASE_MANIFEST_ALLOW_HTTP is set. With ENABLE_DYNAMIC_CHART_PULL=false, versions resolve against the records of the bundled charts.
  • A manifest that cannot be reached for now fails no installed GitLabCore, Siphon, or Orbit, and sets no Upgradeable=False. Each keeps running, and is repaired, on the chart in its status. The channels resolve against the index listed before, and UpgradeVersionsListed=False says so.
  • A GitLabCore, a Siphon, or an Orbit that is not installed yet, and whose chart needs the manifest out of reach, reports Initialized=False with reason ReleaseManifestUnavailable, and retries.
  • A GitLabCore, a Siphon, or an Orbit whose chart the image does not bundle pulls it from an OCI registry under DYNAMIC_CHART_REPOSITORY, oci://registry.gitlab.com by default. A value that is not an oci:// prefix fails the start of the Operator. A registry over plain HTTP is reached only with DYNAMIC_CHART_ALLOW_HTTP set.
  • A pulled GitLab chart renders only once its provenance verifies. A pulled Siphon or Orbit chart, and any bundled chart, renders without verification.

Out of scope

  • Updating the Implemented specs whose behavior this capability changes: GitLabCore reconciler, Unattended upgrades, and Version reference. They describe what the Operator does today, and the merge request that implements a requirement updates them.
  • Modules other than the GitLab, Siphon, and Orbit charts.
  • Distributing the manifest as an OCI artifact, and verifying a signature of the manifest.
  • Pulling charts from a Helm repository served with an index.yaml.
  • Verifying pulled Siphon and Orbit charts, until they publish signed artifacts.

FAQ

  • Why GitLab versions rather than chart versions? Administrators think in GitLab versions, and each add-on has a chart version of its own. The release manifest records which versions of every module ship together, so one GitLab version selects all of them.
  • Why not derive the chart from the GitLab version? The two share an offset for the major and the minor, but a chart-only security release shifts the patch for a minor. The manifest records the exact chart each release shipped with.
  • Why pull charts from OCI registries only? The manifest lists the releases, so the index of a Helm repository would only map a version to a download URL. A tag in an OCI repository names the chart directly, carries its provenance, and mirrors with the tools a disconnected cluster already uses for images.
  • Why are pulled Siphon and Orbit charts not verified? Neither publishes signed charts yet. Requiring a signature would keep add-ons from following any release whose chart the image does not bundle.
  • Why does a manifest out of reach set no condition on an installed resource? Whoever alerts on Upgradeable would be paged for a network blip, as with the chart repository. The status names the charts in use, so nothing that runs needs the manifest. A lasting outage shows in UpgradeVersionsListed and in a status that stops moving.