GitLab System Admin - Hands-On Lab: Upgrading GitLab Omnibus
Estimated time to complete: 30 minutes
Objectives
The objective of this lab is to demonstrate how to upgrade a GitLab instance.
Task A. View your current GitLab version
-
Navigate to your GitLab instance and sign in as the root user.
-
In the left sidebar, select Help > Help.
-
At the top of the page, you will see your full GitLab version. For this lab, you will see
17.4.1-ee.
Task B. View the available GitLab versions
Updates to GitLab Omnibus are completed through your package manager, by installing the Omnibus package that corresponds to your GitLab version. To view the versions of GitLab available for your package, you can SSH onto your instance and view package versions for your package manager.
-
SSH into your GitLab instance.
-
Run the command
sudo apt-get upgradeto update your packages. -
Run the command
sudo apt-cache madison gitlab-ee. -
For this lab, locate version
17.5.0-ee.0. Take note of this version, we will be upgrading to this version of GitLab.
Task C. Run the upgrade
With our target GitLab version identified, we can now run an upgrade of GitLab.
-
If you haven’t already, SSH onto your GitLab instance.
-
Take a backup of your instance using
sudo gitlab-backup create. -
Navigate to
https://gitlab-com.gitlab.io/support/toolbox/upgrade-path/. -
Input your current GitLab version (
17.4.1) and your target version (17.5.0). -
Ensure that Edition is set to Enterprise, and Distro is set to Ubuntu.
-
Select
Go!.
In the upgrade path, you will see only a single step is required, which is to install 17.5.0. Let’s complete this process.
-
On your GitLab instance, run the command
sudo apt-get install gitlab-ee=17.5.0-ee.0. -
Wait for the installation to complete. Once it does, navigate to your instance in your web browser.
You should be met with a message HTTP 502: Waiting for GitLab to boot. Wait at this screen until the boot completes and you are navigated back to your GitLab instance.
Task D. Validate the upgrade
At this point, you have been redirected to the login page of your instance. To validate your upgrade, complete the following steps:
-
Authenticate to your GitLab instance as the root user.
-
In the left sidebar, select Admin.
-
In the left sidebar, select Monitoring > Background migrations.
-
Review the table for any migrations in the Queued section. These migrations need to complete before you complete any additional upgrades. Once they complete, they will show in the Finished tab.
As an example, after this upgrade you will likely see the migration
BackfillIssuesCorrectWorkItemTypeId: issues. Try to find this migration in either the Queued or Finished tab. -
To validate your version, in the left sidebar, select Help. In the resulting menu, you should now see version
17.5.
Lab Guide Complete
You have completed this lab exercise. You can view the other lab guides for this course.
Suggestions?
If you’d like to suggest changes to the GitLab System Admin Basics Hands-on Guide, please submit them via merge request.
a4c83fb3)
