GitLabのアップグレード手順

# はじめに

GitLabのリリースおよびメンテナンスポリシーは次のようになっていて、頻繁に新しいバージョンがリリースされます。

- メジャーバージョンを`年次`でリリースする
  - 毎年5月
- マイナーバージョンを`月次`でリリースする
- パッチは必要に応じてリリースする

そのため、追従頻度は人それぞれかと思いますが、メンテナンスの一環としてアップグレードを繰り返すことになります。
今回の記事ではGitLabのアップグレードの大まかな流れをまとめてみました。

:information_source: 
実際にアップグレードする際には、事前のデータバックアップや切り戻し手順の確認なども必要だと思いますが、このあたりは環境に依存しますので、省いています。

想定環境は次の通りです。
- オンプレミスのSelf-Managed型
- OS:Ubuntu
- GitLab Community EditionのLinux Package(Omnibus)

# アップグレードの流れ

## 事前準備

### アップグレードパスの確認

GitLabのアップグレードは段階を踏むことが大半となります。
そのため、事前準備としてアップグレードパスを確認する必要があります。

例えばVer16.1.2からVer16.4.1にアップグレードする場合、次の段階を踏みます。
- 16.1.2 ⇒ 16.1.5 ⇒ 16.3.5 ⇒ 16.4.1

具体的なパスについては、[こちらのサイト](https://gitlab-com.gitlab.io/support/toolbox/upgrade-path/?edition=ce)で確認することができます。

![upgrade-path1.JPG](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2396115/7938ec7b-5616-54e1-ccde-21710deb9f2f.jpeg)
![upgrade-path2.JPG](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2396115/642c2aea-8718-4e3b-d571-f1b978e11600.jpeg)

## アップグレード実施

段階ごとに次の手順を繰り返します。

### background migrationsの完了確認

GitLabのアップグレードでは、内部で使用しているデータベースのテーブル更新はパッケージ更新実施後に`background migrations`として内部でバッチ処理されます。

パッケージ更新完了後から新しいバージョンのUIに切り替わっていて、見た目の上ではアップグレードが完了しているように見えますが、実際には内部で処理中となっている場合があります。

次のバージョンへアップグレードする前にテーブル更新も完了している必要があるため、
バッチ処理の実行状況を次の手順で確認し、`Queued`が`0`になるまで待ちます。

1. （サイドバーなどから）Admin Areaに移動する
1. Monitoring > Background Migrationsに移動する
1. バッチのキュー状況・完了状況を確認する

![background-migrations.JPG](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2396115/ddee8fe2-0597-a24b-26cf-0ff043050280.jpeg)
![background-migrations2.JPG](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2396115/1b4778b9-9dc8-7fcc-fac4-1b867352cea8.jpeg)


### アップグレード実施

background migrationsの完了確認後、実際にアップグレードを実施します。
上述の通り、段階を踏む必要があるので、`apt install gitlab-ce=16.1.5-ce.0`のようにバージョンを指定してアップグレードを実施します。
後は自動的に処理されるので、完了するまで待ちます。

```
root:~# apt install gitlab-ce=16.1.5-ce.0
Reading package lists...

(中略)

gitlab Reconfigured!
Restarting previously running GitLab services
ok: run: alertmanager: (pid 15329) 0s
ok: run: gitaly: (pid 1570) 1063s
ok: run: gitlab-exporter: (pid 15340) 1s
ok: run: gitlab-kas: (pid 15311) 2s
ok: run: gitlab-workhorse: (pid 15320) 2s
ok: run: logrotate: (pid 15344) 0s
ok: run: nginx: (pid 15350) 1s
ok: run: node-exporter: (pid 15356) 0s
ok: run: postgres-exporter: (pid 15362) 0s
ok: run: postgresql: (pid 1541) 1065s
ok: run: prometheus: (pid 15370) 1s
ok: run: puma: (pid 15377) 0s
ok: run: redis: (pid 1546) 1066s
ok: run: redis-exporter: (pid 15385) 1s
ok: run: sidekiq: (pid 15392) 0s

     _______ __  __          __
    / ____(_) /_/ /   ____ _/ /_
   / / __/ / __/ /   / __ `/ __ \
  / /_/ / / /_/ /___/ /_/ / /_/ /
  \____/_/\__/_____/\__,_/_.___/
  

Upgrade complete! If your GitLab server is misbehaving try running
  sudo gitlab-ctl restart
before anything else.
If you need to roll back to the previous version you can use the database
backup made during the upgrade (scroll up for the filename).
```

# まとめ

以上がGitLabアップグレードの大まかな流れとなります。
特に複雑な工程ではないので、初回は事前検証などで作業準備に時間がかかると思いますが、一度実績を作ってしまえば、2回目以降の作業負荷はさほどではありません。
ご参考になれば。

# （おまけ）Ver16.1.2からVer16.4.1にアップグレードした時のコマンドメモ

```
# パッケージ一覧の最新化する
apt update

# gitlabのバージョンを確認する
gitlab-rake gitlab:env:info

# リポジトリで使用可能なgitlab-ceのパッケージ一覧を確認する
sudo apt-cache madison gitlab-ce

# 16.1.5にバージョンアップ
apt install gitlab-ce=16.1.5-ce.0

# gitlabのバージョンを確認する
gitlab-rake gitlab:env:info

# (GUIでの作業)
Admin Areaの`background_migrations`のQueuedが0になるまで待つ

# パッケージ一覧の最新化する（念のため）
apt update

# 16.3.5にバージョンアップ
apt install gitlab-ce=16.3.5-ce.0

# gitlabのバージョンを確認する
gitlab-rake gitlab:env:info

# (GUIでの作業)
Admin Areaの`background_migrations`のQueuedが0になるまで待つ

# パッケージ一覧の最新化する（念のため）
apt update

# OSにインストールされている各パッケージ（gitlab含む）を最新化する
apt upgrade

# gitlabのバージョンを確認する
gitlab-rake gitlab:env:info

# (GUIでの作業)
Admin Areaの`background_migrations`のQueuedが0になるまで待つ
```

# 参考情報

- [GitLab release and maintenance policy](https://docs.gitlab.com/ee/policy/maintenance.html)
- [Upgrading GitLab](https://docs.gitlab.com/16.4/ee/update/)
- [GitLab releases](https://about.gitlab.com/releases/categories/releases/)