Operatorを使用したGitLabインスタンスのアップグレード

プラン: Free、Premium、Ultimate
提供形態: GitLab Self-Managed

GitLab Operatorを使用すると、GitLab OperatorでインストールされたGitLabインスタンスをアップグレードできます。

前提条件

GitLab Operatorでアップグレードする前に:

アップグレードする前に必要な情報を参照してください。
GitLabのバージョンに必要なGitLab Operatorのバージョンを特定します。GitLabのバージョン、GitLab Helmチャートのバージョン、およびGitLab Operatorのバージョンのマッピングについては、GitLab Operatorのリリースを参照してください。

GitLab Operatorを使用したGitLabのアップグレード

GitLab OperatorでGitLabをアップグレードするには:

ワークフローを妨げないように、アップグレード中にメンテナンスモードをオンにすることを検討して、ユーザーが書き込み操作を実行できないように制限します。
ターゲットのGitLabバージョンと同じバージョンにGitLab Runnerをアップグレードします。
GitLab Operatorをアップグレードします。
GitLab Operatorを使用してGitLabをアップグレードします。

アップグレード後:

有効になっている場合は、メンテナンスモードをオフにします。
アップグレードヘルスチェックを実行します。

GitLab Operatorのアップグレード

GitLab Operatorをアップグレードするには:

バックアップを実行します。
kubectlを使用して必要なバージョンをインストールし、必要なバージョンのGitLab 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
```
このコマンドは、使用する新しいデプロイイメージを含む、関連するマニフェストに対するすべての変更を適用します。
新しいバージョンのGitLab Operatorがリーダーになることを確認します。GitLab Operatorのデプロイは、この変更で新しいReplicaSetを作成し、新しいGitLab Operatorのポッドを起動する必要があります。一方、以前のGitLab Operatorのポッドはシャットダウンし、リーダーのステータスを放棄します。この状態になると、新しいGitLab Operatorのポッドがリーダーになります。
GitLabカスタムリソース（CR）のチャートのバージョンを更新します。ほとんどの場合、利用可能なチャートのバージョンは、GitLab Operatorのバージョン間で同一ではありません。新しいバージョンのGitLab Operatorが起動すると、既存のGitLabカスタムリソース（CR）のリコンサイルを試みます。次のようなエラーが表示される場合があります:
```
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
```
これに対処するには、そのリリースで利用可能なチャートのバージョンから有効なバージョンを特定します。たとえば、Operator 0.4.0から0.4.1にアップグレードする場合は、GitLab CRを利用可能なチャートのバージョン（5.7.0に最も近いバージョン）に更新します。この場合、5.7.1です。
GitLab OperatorがGitLabを予期どおりに調整することを確認します。新しいOperatorポッドからのログをチェックして、Operatorポッドが定義されたチャートのバージョンにアップグレードされたかどうかを確認します。
アップグレードが成功したことを確認するには、GitLab CRのステータスを取得します:
```
$ kubectl get gitlabs -n gitlab-system
NAME     STATUS    VERSION
gitlab   Running   5.7.1
```
ステータスRunningは、GitLab Operatorがインスタンスへの変更を調整できたことを意味します。バージョンは、GitLab Operatorのアップグレード後に指定されたチャートのバージョンと一致する必要があります。

トラブルシューティング

エラーが発生した場合は、まずトラブルシューティングドキュメントを参照してください。そこに回答がない場合は、既存のイシューを確認するか、イシュートラッカーで新しいイシューを開いてください。

GitLab Operatorを使用してGitLabをアップグレードする

GitLab Operatorは、ゼロダウンタイムアプローチを使用してGitLabをアップグレードします。その結果、GitLabと基盤となるチャートのバージョンは、一度に1つのマイナーリリースずつ更新する必要があります。

2.6.0および2.5.1より前のOperatorリリースでは、有効なアップグレードパスは適用されませんでした。

GitLabカスタムリソースのspec.chart.versionフィールドを新しいバージョンに更新します。例:

apiVersion: apps.gitlab.com/v1beta1
kind: GitLab
metadata:
  name: gitlab
spec:
  chart:
-   version: "5.0.6"
+   version: "5.1.1"
    values:
      ...

変更したGitLabカスタムリソースをクラスターに適用します:

kubectl -n gitlab-system apply -f mygitlab.yaml

次のメッセージが表示されるはずです:

gitlab.apps.gitlab.com/gitlab created

コントローラーのログで進行状況を監視できます。例:

$ kubectl -n gitlab-system logs deployment/gitlab-controller-manager -c manager -f
2021-09-14T20:59:12.342Z        INFO    controllers.GitLab      Reconciling GitLab    {"gitlab": "gitlab-system/gitlab"}
2021-09-14T20:59:12.344Z        DEBUG   controllers.GitLab      version information   {"gitlab": "gitlab-system/gitlab", "upgrade": true, "current version": "", "desired version": "5.0.6"}
2021-09-14T20:59:18.168Z        INFO    controllers.GitLab      reconciling Webservice and Sidekiq Deployments (paused) {"gitlab": "gitlab-system/gitlab"}
...

上記のアップグレード手順に従ってログエントリが表示されます。クラスター内のGitLabカスタムリソースステータスを表示することもできます:

$ kubectl -n gitlab-system get gitlab
NAME     STATUS        VERSION
gitlab   Preparing     5.2.4

アプリケーションの準備が完了し、新しいバージョンにアップグレードされると、STATUS列に反映されます。

$ kubectl -n gitlab-system get gitlab
NAME     STATUS      VERSION
gitlab   Running     5.2.4

GitLabオブジェクト自体のステータス条件は、アプリケーションに関するより詳細な情報を示しています。

GitLab OperatorがGitLabをアップグレードする方法

コントローラーの調整ループの開始時に、GitLab Operatorは現在のバージョンが必要なバージョンと一致するかどうかを確認します。

これらのバージョンが一致する場合、通常の調整ループが実行され、カスタムリソース（CR）仕様で提供された設定を満たすオブジェクトが存在することが保証されます。
これらのバージョンが一致しない場合でも、通常の調整ループは実行されますが、アップグレードを処理するために追加のロジックブランチが実行されます。

アップグレード中:

コントローラーはすべてのデプロイを調整します。WebserviceとSidekiqのデプロイは調整されますが、一時停止されます。新しいデプロイが再開されるまで、古いポッドは起動したままになります。
移行前が実行され、マイグレーションジョブが実行されますが、デプロイ後のマイグレーションはスキップされます。
コントローラーは、WebserviceとSidekiqのデプロイを再開します。
コントローラーは、新しいWebserviceとSidekiqのポッドが実行されるのを待ちます。
移行後が実行され、デプロイ後の移行をスキップせずに移行ジョブが実行されます。
コントローラーは、WebserviceとSidekiqデプロイでローリングアップデートを実行します。
コントローラーは、再起動されたWebserviceとSidekiqポッドが実行されるのを待ちます。

今後の調整ループでは、目的のバージョン（spec.chart.versionから）が現在のバージョン（status.versionから）と一致するため、このロジックブランチはスキップされます。