GitとCI/CDに関する知識ゼロのSEが、コンテナで起動したGitLabをアップグレードする話

2022/06/09　同年5/25に公開した記事の内容に不足があったので、追記して公開しなおしました。

皆様こんにちは。SEの小池と申します。

私はGitLabのお勉強のために、お手軽検証環境としてコンテナでGitLabを利用しております。
起動も環境構成もお手軽にできてしまうので重宝していたのですが、実は結構前に作ったやつでバージョンがやや古くなってきました・・・。
古いバージョンでブログを書くことに気が引けるので、ついに重い腰を上げてDockerイメージから起動しているGitLabのバージョンを上げます。

本記事の対象の方
今回のブログのゴール
このブログをお読みいただくにあたっての事前ご連絡事項
全体の流れ
Step1 : アップグレードパスを確認する
Step2 : バージョン固有のアップグレード手順を確認する
- 14.6.1>14.9.5 アップグレード時の手順概要
- 14.9.5>14.10.4 アップグレード時の手順概要
Step3 : 既存GitLabのバックアップを取得する
Step4 : バージョン固有手順を実施する
Step5 : バックグラウンド移行を実施する
Step6 : バッチバックグラウンド移行のステータスを確認する
Step7 : GitLabのコンテナを停止する
Step8 : GitLabのコンテナを削除する
Step9 : 新しいバージョンのGitLabイメージをPullする
Step10 : docker-compose.yml やコンテナ起動コマンドの見直し
- コンテナ起動コマンドの修正例
- Docker Composeのymlファイル修正例
Step11 : 新しいイメージを使ってGitLabのコンテナを起動
Step12 : Runner registration tokenの確認と既存Runnerの動作確認
Step13 : ターゲットのバージョンになるまで手順を繰り返す
最後に

本記事の対象の方

DockerイメージでGitLabを使っていて、それをアップグレードなさりたい方。
(今回のブログでは GitLab Enterprise Edition (Ultimate) を 14.6.1 から 14.10.4 に上げます。)
オンプレミス版のGitLabのアップグレード手順の情報を収集なさっている方。

今回のブログのゴール

このブログのゴールはこちらです。

今回のゴール

Dockerイメージで利用しているGitLabをアップグレードする。

このブログをお読みいただくにあたっての事前ご連絡事項

本記事はDocker Hubから入手したイメージで起動した GitLab Enterprise Edition (Ultimate) コンテナを 14.6.1 から 14.10.4 にアップグレードする手順を検証し掲載しています。それ以外のエディションやバージョンではこの記事に記載の通りではない可能性がございます。
本記事で紹介する手順は、筆者の環境に依存する手順です。手順はバージョンや設定によって異なるため、実際にご利用中のGitLabでアップグレードをご検討なさる際は GitLab Docs をご参照いただきながらアップグレード計画を策定してください。
本記事のGitLabのGUIは日本語にローカライズした状態で掲載しております。それ以外の言語をご利用の方は適宜読み替えてください。
本記事はGitやCI/CDに関する知識ゼロのSEによるなんちゃって記事です。GitLabのディープな使用法についてはGitLabの公式オンラインドキュメント (こちら) をご参照ください。

全体の流れ

この記事では、Dockerのコンテナで起動しているGitLab14.6.1を以下の流れで14.10.4にアップグレードします。

アップグレードパスを確認する
バージョン固有のアップグレード手順を確認する
既存GitLabのバックアップを取得する
バージョン固有手順を実施する
バックグラウンド移行を実施する
バッチバックグラウンド移行のステータスを確認する
GitLabのコンテナを停止する
GitLabのコンテナを削除する
新しいバージョンのGitLabイメージをPullする
docker-compose.yml やコンテナ起動コマンドの見直し
新しいイメージを使ってGitLabのコンテナを起動する
Runner registration tokenの確認と既存Runnerの動作確認
ターゲットのバージョンになるまで手順を繰り返す

まず、アップグレードパスの確認やバージョン固有のアップグレード手順を確認します。
Self-Managed (オンプレ) のGitLabをアップグレードする場合、これらの確認はコンテナで起動しているか否かにかかわらず必須です。
主にアップグレードパスのヘルパーや、GitLab Docsのアップグレードの章を参照して必要な手順を確認していきます。
参考 : Upgrade Path, Upgrading GitLab | GitLab

バックアップ以降の実際のアップグレード手順の大筋は、GitLab DocsにあるコンテナでGitLabを起動している場合のアップグレード手順に従います。
それに加えて、前の手順で確認したバージョン固有の追加手順等を実施します。
参考 : GitLab Docker images | GitLab

また、現行で14.0以降を使用している場合は、事前にバックグラウンド移行 (Background migrations) とバッチバックグラウンド移行 (Batched background migrations) を両方とも完了させておく必要があります。
参考 : Upgrading GitLab | GitLab

このブログで紹介しているアップグレード手順について
このブログで紹介している手順は筆者の検証環境に依存する手順です。
現行のバージョンやターゲットのバージョン、利用している環境や設定によってアップグレード方法は異なります。実際にご利用中のGitLabでアップグレードをなさる際は、GitLab Docsをご参照いただきながらアップグレード計画を策定してください。

Step1 : アップグレードパスを確認する

アップグレードを複数段階に分ける必要があるか否かを、メーカーの便利ツール Upgrade Path planning helper を使って確認します。
延々GitLab Docsとにらめっこした挙句、結局よくわかんなくてサポートに問い合わせた結果、このツールを使えと一蹴されたのは私です。

ブラウザでこのUpgrade Path planning helperにアクセスすると、以下のような画面が表示されます。
ここで、現在のバージョン、ターゲットバージョン、エディション、環境の指定等をし、[GO!] をクリックします。

すると、必要なアップグレードパスを具体的に提示してくれます。
下図の点線赤枠部分がアップグレードパスです。
今回の場合はいったん14.9.5に上げ、そこから14.10.4に上げる、2段階の作業が必要となります。

さらに、ターゲットパスに表示された各バージョンをクリックすると、バージョン別のアップグレードノートが表示されます。
今回の場合は現行機が 14.6.1 なので、14.6.7 以降のアップグレードノートに目を通して影響の有無等を確認します。

なお、バージョンによってはこのように特にアップグレードノートがない場合もあります。

また、今回は現行機のバージョンが14.6.1のため、アップグレードに際し事前にバックグラウンド移行 (Background migrations) と バッチバックグラウンド移行 (Batched background migrations) を実施する必要があります。
参考 : Upgrading GitLab | GitLab

これらの詳細については、当該画面の赤枠部分 [CHECK MIGRATIONS BEFORE EACH UPGRADE] をクリックするとGitLab Docsに飛ぶことができますので、その内容を確認します。

コンテナで起動しているGitLabで実行するコマンド
2022/06/07現在、GitLab Docsのバックグラウンド移行及びバッチバックグラウンド移行に関する説明には、コンテナでGitLabを起動している場合のコマンド例が載っておりません。
今回の例のようにコンテナでGitLabを起動している場合は、docker exec -itコマンドなどでGitLabのコンテナに入った後、こちらのGitLab DocsのFor Omnibus installations:に記載されているコマンドを実行してください。

以上がアップグレードパスの確認になります。

Step2 : バージョン固有のアップグレード手順を確認する

続いて、GitLab Docsでバージョン固有のアップグレード手順があるか確認します。
前の手順でアップグレードノートは確認致しましたが、場合によってはGitLab Docsの方にしか記載されていない情報もあるので、確認することをお勧めいたします。
参考 : Upgrading GitLab | GitLab

今回の場合は現行機が 14.6.1 でターゲットが14.10.4なので、14.7.0、14.8.0、14.9.0、14.10.0 を確認します。

Step1 と Step2 の確認により、このブログの場合においては14.6.1>14.9.5>14.10.4のアップグレードに際し、ベースとなるアップグレード手順に加えて以下を実施することとしました。

バージョン固有のアップグレード手順について
このブログで記載しているバージョン固有のアップグレード手順は、筆者の環境に依存するものです。環境の構成や設定によって追加の手順が必要になったり作業の順番が異なるため、あくまでもこのブログ固有のアップグレードの流れであることをご理解ください。

`14.6.1`>`14.9.5` アップグレード時の手順概要

14.6.1時点のRunnerのトークンをメモする (バージョン固有の影響の確認用) 。
バックグラウンド移行 (Background migrations) を事前に実施する。
バッチバックグラウンド移行 (Batched background migrations) のステータスを事前に確認する。
アップグレードを実施する。
アップグレード後に既存Runnerが使用可能か確認する。

`14.9.5`>`14.10.4` アップグレード時の手順概要

バックグラウンド移行 (Background migrations) を事前に実施する。
バッチバックグラウンド移行 (Batched background migrations) のステータスを事前に確認する。
アップグレードを実施する。

おおよそやることが確定したので、次の章から実際にアップグレードを実施していきます。

Step3 : 既存GitLabのバックアップを取得する

ここからは実際にアップグレード作業を実施していきます。
まず、既存のGitLabのバックアップを取得します。
この章の手順は以下のGitLab Docsに従います。
参考 : GitLab Docker images | GitLab

既存のGitLabコンテナを起動後、Dockerホストで以下のコマンドを実行します。

sudo docker exec -t <既存のGitLabのコンテナ名> gitlab-backup create

たくさん出力が表示されますが、最終的に以下のような出力で完了します。
取得したバックアップファイルは /var/opt/gitlab/backups/ の下にあります。

一番最後の Warning で、gitlab.rb と gitlab-secrets.json については機密情報を含むためこのバックアップに含まれない旨、および、リストアにこれらのファイルが必要なので手動でバックアップするように記載されています。

言われるがままにこれらのファイルのバックアップを取得するのですが、例外のケースがあります。
もし、GitLabのコンテナ起動時に GITLAB_OMNIBUS_CONFIG を使って環境構成に必要な変数を全て引数で渡していて、gitlab.rb は一切手動変更していないのであれば、gitlab.rb の手動バックアップは不要だそうです。
参考 : GitLab Docker images | GitLab

この時点で取得したバックアップは以下の通りとなります。

バックアップファイル (/var/opt/gitlab/backups/の下に生成された.tarファイル)
gitlab.rb (/etc/gitlab/配下にあるファイルを手動でバックアップ)
gitlab-secrets.json (/etc/gitlab/配下にあるファイルを手動でバックアップ)

なお、これらのバックアップはあくまでも保険のためであり、バージョンアップ作業で直接これらは使用しません。

Step4 : バージョン固有手順を実施する

Step1, 2で確認したバージョン固有手順を実施します。
この記事においては、バージョン固有手順は14.6.1>14.9.5の時のみ存在し、14.9.5>14.10.4の時は特にありません。

14.6.1から14.9.5にアップグレードするにあたり、グループとプロジェクトのRunner registration tokenが変更されるとの記載がありました。

If upgrading from a version earlier than 14.6.5, 14.7.4, or 14.8.2, please review the Critical Security Release: 14.8.2, 14.7.4, and 14.6.5 blog post. Updating to 14.7.4 or later will reset runner registration tokens for your groups and projects.

参考 : Upgrading GitLab | GitLab

ただ、登録のためのトークンが変わっても既に登録しているRunnerについては影響ないとのことです。

However, it should have no affect on previously registered runners.

参考 : GitLab Critical Security Release: 14.8.2, 14.7.4, and 14.6.5 | GitLab

アップグレードされたのかの確認の指標にもなるので、14.6.1時点のregistration tokenをメモしておきました。バージョンアップ後に、グループとプロジェクトのRunner registration tokenが変更されたのかを確認してみようと思います。

表1. アップグレード前 (14.6.1) のRunner registration token
Runnerの登録レベル	14.6.1 時点	14.9.5 時点
インスタンス	qQVxxxxxxxxxxxxxxi5F	アップグレード後に確認
任意のグループ	-KaxxxxxxxxxxxxxxuZ8
任意のプロジェクト	PdPxxxxxxxxxxxxxxP1y

この記事においてはバージョン固有手順は以上です。

Step5 : バックグラウンド移行を実施する

GitLab Docsに記載のあるバックグラウンド移行 (Background migrations) を実施します。
参考 : Upgrading GitLab | GitLab

まず、docker exec -it 等のコマンドでGitLabのコンテナに入ります。

sudo docker exec -it <既存のGitLabのコンテナ名> /bin/bash

その後、GitLab Docs の "For Omnibus installations:" 欄に記載されているコマンドを、冒頭のsudoを除外して実行します。

gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'

gitlab-rails runner -e production 'puts Gitlab::Database::BackgroundMigrationJob.pending.count'

どちらも正常終了すると0 (ゼロ) が出力されます。

バックグラウンド移行 (Background migrations) は以上です。

Step6 : バッチバックグラウンド移行のステータスを確認する

GitLab Docsに記載のあるバッチバックグラウンド移行 (Batched background migrations) を実施します。

まず、現在のステータスを確認します。
確認はGUIでもコマンドでも可能ですので、お好きな方でご確認ください。

GUIで確認する場合は、GitLabに管理者権限のあるユーザーでサインインし、[Menu]>[Admin]を開きます。

[監視]>[Background Migrations]を開きます。
この画面ですべてのMigrations ジョブのステータスが Finished になっていることを確認してください。
なお、下図の1枚目の例のようにMigrations ジョブが0件の場合でも問題ありません。

コマンドで確認する場合は、GitLabのコンテナに入り以下のコマンドを実行します。

gitlab-psql

続けて以下のコマンドを実行します。

select job_class_name, table_name, column_name, job_arguments from batched_background_migrations where status <> 3;

バッチバックグラウンド移行のジョブのうち、ステータスが Finished 以外のジョブ一覧が表示されます。
この結果が0件であれば問題ありません。

バッチバックグラウンド移行のジョブが全て Finished になっていない場合は、それに応じた追加手順が必要です。
こちらのGitLab Docsをご参照いただきながらご対応ください。
参考 : Upgrading GitLab | GitLab

バッチバックグラウンド移行 (Batched background migrations) のステータス確認は以上です。

Step7 : GitLabのコンテナを停止する

既存のGitLabコンテナを停止します。
停止コマンドは Docker Compose の利用有無などで変わりますので、ご利用の環境における停止コマンドで停止してください。

Step8 : GitLabのコンテナを削除する

停止したGitLabのコンテナを削除します。

sudo docker rm <既存のGitLabのコンテナ名 もしくは コンテナID>

Step9 : 新しいバージョンのGitLabイメージをPullする

今回のターゲットパスは14.6.1>14.9.5>14.10.4なので、まずは14.9.5をPullします。
タグの詳細はDocker HubのGitLabのページをご参照ください。
参考 : Docker Hub

sudo docker pull gitlab/gitlab-ee:14.9.5-ee.0

続けて後で必要になるので14.10.4もPullしておきます。

sudo docker pull gitlab/gitlab-ee:14.10.4-ee.0

Step10 : `docker-compose.yml` やコンテナ起動コマンドの見直し

取得した新しいバージョンのGitLabのイメージで起動するようにdocker-compose.ymlやコンテナ起動コマンドを見直します。
このブログの場合は２段階でアップグレードするので、まずは14.9.5を指定します。
以下に修正例を載せます。

コンテナ起動コマンドの修正例

GitLab Docsにあるこちらのdocker runコマンドを使用している場合。
10行目のイメージ指定で、14.9.5のイメージを使用するように変更する場合はこのようになります。

sudo docker run --detach \
  --hostname gitlab.example.com \
  --publish 443:443 --publish 80:80 --publish 22:22 \
  --name gitlab \
  --restart always \
  --volume $GITLAB_HOME/config:/etc/gitlab \
  --volume $GITLAB_HOME/logs:/var/log/gitlab \
  --volume $GITLAB_HOME/data:/var/opt/gitlab \
  --shm-size 256m \
  gitlab/gitlab-ee:14.9.5-ee.0

変更 : GitLab Docker images | GitLab

Docker Composeのymlファイル修正例

GitLab Docsにあるこちらのdocker-compose.ymlを使用している場合。
4行目のイメージ指定で、14.9.5のイメージを使用するように変更します。

version: '3.6'
services:
  web:
    image: 'gitlab/gitlab-ee:14.9.5-ee.0'
    restart: always
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'https://gitlab.example.com'
        # Add any other gitlab.rb configuration here, each on its own line
    ports:
      - '80:80'
      - '443:443'
      - '22:22'
    volumes:
      - '$GITLAB_HOME/config:/etc/gitlab'
      - '$GITLAB_HOME/logs:/var/log/gitlab'
      - '$GITLAB_HOME/data:/var/opt/gitlab'
    shm_size: '256m'

参考 : GitLab Docker images | GitLab

Step11 : 新しいイメージを使ってGitLabのコンテナを起動

新しいイメージを使ってGitLabのコンテナを起動します。

ステータスがhealthyで起動したことを確認後、GUIにサインインしましょう。
GUIにサインインしたら、右上のヘルプアイコンから[ヘルプ]をクリックすると現在のバージョンが確認できます。

おおー、ちゃんと14.9.5になってますね！！

めでたく14.9.5にアップグレードできました。
ここから14.10.4に上げる前に、アップグレードノートに記載されていたRunnerの件で少々確認を実施します。

Step12 : Runner registration tokenの確認と既存Runnerの動作確認

アップグレードノートに記載があった通り、14.6.1>14.9.5の影響でグループとプロジェクトのRunner registration tokenが変更されているはずなので、それを確認してみました。
参考 : Upgrading GitLab | GitLab

表2. アップグレード前後 (14.6.1 >14.9.5) のRunner registration token
Runnerの登録レベル	14.6.1 時点	14.9.5 時点
インスタンス	qQVxxxxxxxxxxxxxxi5F	qQVxxxxxxxxxxxxxxi5F
任意のグループ	-KaxxxxxxxxxxxxxxuZ8	GR1xxxxxxxxxxxxxxxxxxxxxxxzjs
任意のプロジェクト	PdPxxxxxxxxxxxxxxP1y	GR1xxxxxxxxxxxxxxxxxxxxxxxsKc

結果は上記の通りで、確かにアップグレードノートに記載があった通り、アップグレード前後 (14.6.1>14.9.5) でグループとプロジェクトのRunner registration tokenが変わっていました。

また、こちらのドキュメントには古いトークンで登録済のRunnerについては問題なく動作すると記載があったので、試しに14.6.1時代にプロジェクトに登録したRunner (Specific) がきちんと動作するか確認します。
参考 : GitLab Critical Security Release: 14.8.2, 14.7.4, and 14.6.5 | GitLab

GUIから見る限り、Specific Runnerの登録は解除されずに残っていました。