Version-specific upgrade instructions (PREMIUM SELF)

NOTE: We're in the process of merging all the version-specific upgrade information into a single page. For more information, see epic 9581. For the latest Geo version-specific upgrade instructions, see the general upgrade page.

Review this page for upgrade instructions for your version. These steps accompany the general steps for upgrading Geo sites.

Upgrading to 15.1

Geo proxying was enabled by default for different URLs in 15.1. This may be a breaking change. If needed, you may disable Geo proxying.

If you are using SAML with different URLs, you must modify your SAML configuration and your Identity Provider configuration. For more information, see the Geo with Single Sign-On (SSO) documentation.

Upgrading to 14.9

Do not upgrade to GitLab 14.9.0. Instead, use 14.9.1 or later.

We've discovered an issue with Geo's CI verification feature that may cause job traces to be lost. This issue was fixed in the GitLab 14.9.1 patch release.

If you have already upgraded to GitLab 14.9.0, you can disable the feature causing the issue by disabling the geo_job_artifact_replication feature flag.

Upgrading to 14.2 through 14.7

There is an issue in GitLab 14.2 through 14.7 that affects Geo when the GitLab-managed object storage replication is used, causing blob object types to fail synchronization.

Since GitLab 14.2, verification failures result in synchronization failures and cause a resynchronization of these objects.

As verification is not yet implemented for files stored in object storage (see issue 13845 for more details), this results in a loop that consistently fails for all objects stored in object storage.

For information on how to fix this, see Troubleshooting - Failed syncs with GitLab-managed object storage replication.

Upgrading to 14.4

There is an issue in GitLab 14.4.0 through 14.4.2 that can affect Geo and other features that rely on cronjobs. We recommend upgrading to GitLab 14.4.3 or later.

Upgrading to 14.1, 14.2, 14.3

Multi-arch images

We found an issue where the Container Registry replication wasn't fully working if you used multi-arch images. In case of a multi-arch image, only the primary architecture (for example amd64) would be replicated to the secondary site. This has been fixed in GitLab 14.3 and was backported to 14.2 and 14.1, but manual steps are required to force a re-sync.

You can check if you are affected by running:

docker manifest inspect <SECONDARY_IMAGE_LOCATION> | jq '.mediaType'

Where <SECONDARY_IMAGE_LOCATION> is a container image on your secondary site. If the output matches application/vnd.docker.distribution.manifest.list.v2+json (there can be a mediaType entry at several levels, we only care about the top level entry), then you don't need to do anything.

Otherwise, for each secondary site, on a Rails application node, open a Rails console, and run the following:

list_type = 'application/vnd.docker.distribution.manifest.list.v2+json'

Geo::ContainerRepositoryRegistry.synced.each do |gcr|
  cr = gcr.container_repository
  primary = Geo::ContainerRepositorySync.new(cr)
  cr.tags.each do |tag|
    primary_manifest = JSON.parse(primary.send(:client).repository_raw_manifest(cr.path, tag.name))
    next unless primary_manifest['mediaType'].eql?(list_type)

    cr.delete_tag_by_name(tag.name)
  end
  primary.execute
end

If you are running a version prior to 14.1 and are using Geo and multi-arch containers in your Container Registry, we recommend upgrading to at least GitLab 14.1.

Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode

GitLab 13.9 through GitLab 14.3 are affected by a bug in which enabling GitLab Maintenance Mode causes Geo secondary site statuses to appear to stop upgrading and become unhealthy. For more information, see Troubleshooting - Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode.

Upgrading to GitLab 14.0/14.1

Primary sites cannot be removed from the UI

We found an issue where Primary sites cannot be removed from the UI.

This bug only exists in the UI and does not block the removal of Primary sites using any other method.

If you are running an affected version and need to remove your Primary site, you can manually remove the Primary site by using the Geo Sites API.