Upgrading the Operator

Below are instructions to upgrade the GitLab Operator.

Prior to upgrading, it is strongly recommended to perform a backup.

Step 1: Upgrade to the latest available chart version

Before upgrading the Operator, ensure that the current instance of GitLab is upgraded to the latest available chart version by following the GitLab upgrade guide. These versions are outlined on the releases page under the Version mapping headings.

For example, if the current Operator version is release 0.4.0, perform the available chart upgrades in order: 5.5.3 -> 5.6.3 -> 5.7.0.

Step 2: Identify the desired Operator version

See our releases page for the full list of available versions of the GitLab Operator.

For example, if the current Operator version is release 0.4.0, you could upgrade to release 0.4.1.

Step 3: Install the desired version

The next step is to use kubectl to apply the manifest for the desired version of the Operator. 

VERSION=X.Y.Z
kubectl apply -f \
  https://gitlab.com/api/v4/projects/18899486/packages/generic/gitlab-operator/${VERSION}/gitlab-operator-kubernetes-${VERSION}.yaml

This command will apply any changes to the related manifests, including the new Deployment image to use.

Step 4: Confirm that the new version of the Operator becomes the leader

The Operator Deployment should create a new ReplicaSet with this change, which will spawn a new Operator pod. Meanwhile, the previous Operator pod will shut down, giving up its leader status. When this happens, the new Operator pod will become the leader.

Step 5: Update the chart version in the GitLab custom resource (CR)

In most cases, the available chart versions will not be identical between versions of the Operator. When the newer version of the Operator starts, it will try to reconcile the existing GitLab custom resource (CR). You will likely see an error such as: 

Configuration error detected: chart version 5.7.0 not supported; please use one of the following: 5.7.1, 5.6.4, 5.5.4

To address this, identify a valid version from that release’s available chart versions.

For example: when upgrading from Operator 0.4.0 to 0.4.1, update the GitLab CR to an available chart version closest to 5.7.0, which in this case is 5.7.1.

Step 6: Confirm that the Operator reconciles GitLab as expected

Watch the logs from the new Operator pod. You should see that it performs the upgrade to the chart version you defined.

To confirm that the upgrade was successful, get the status of the GitLab CR: 

$ kubectl get gitlabs -n gitlab-system
NAME     STATUS    VERSION
gitlab   Running   5.7.1

The status Running means that the Operator was able to reconcile the changes to the instance. The version should match the chart version specified after the Operator upgrade.

If you notice any errors, first reference our troubleshooting documentation. If the answer is not provided there, please check for an existing issue or open a new issue in our issue tracker.

Below are resources related to GitLab upgrades.