Standardize upgrade path information
Summary
Currently, GitLab maintains the upgrade path information in several places, few known locations are:
- Omnibus: Make 16.3 minimum required version to upgrade t... (omnibus-gitlab#8103 - closed)
- Chart: Make 16.3/7.3 minimum required version to upgra... (gitlab-org/charts/gitlab#4895 - closed)
- Update
Gitlab::Database::MIN_SCHEMA_GITLAB_VERSION
in lib/gitlab/database.rb to the new required stop versions. Do not change Gitlab::Database::MIN_SCHEMA_VERSION. - Upgrade-path project: https://gitlab.com/gitlab-com/support/toolbox/upgrade-path
- GitLab docs: https://docs.gitlab.com/ee/update/#upgrade-paths
This potentially cause effort duplication and inconsistency.
Acceptance criteria
-
Decide the SSoT location for the information -
Update all projects to refer to the SSoT - This will be done by other issues:
Solution proposal
Initial thought
- One possible solution from #415993 (comment 1489427501) (credit to @Alexand and @mattkasa)
We can have
required_stops.yaml
ongitlab-org/gitlab
as a SSOT. To avoid the situation where the users have to do outbound API requests during installs to check the required stops, we can embed them into the Chart and Omnibus package during build/release phase of our CI.
We only need to know the latest required stop before the desired upgrade-to version.
For Omnibus,
We can fetch the latest required stop before the version we're building, then inject it into the
preinst
script as a new variable,LAST_REQUIRED_STOP=X.Y.Z
: https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/cf6d0013fcc8d2fa820cd840c280ead6fe0b1e07/config/templates/package-scripts/preinst.erb#L7. The thepreinst
script can fail if the current version is lower than the last required stop, and we can guide the user to check the list of required stops.
For Chart,
we already have a pre-upgrade Helm hook that does some min version checks for minimum chart and Postgres version. We could extend that to also check for
LAST_REQUIRED_STOP
. We could also inject theLAST_REQUIRED_STOP
from CI when we're releasing the Chart.
Direction we decided
Instead of using the LAST_REQUIRED_STOP
we decided to make use of the already existing MIN_VERSION
.
Instead of shipping the version within package, we initially decided to use the release tools to update these versions in the chart and omnibus. Example implementation: Maintain upgrade stop for Omnibus (release-tools!2925 - merged)