【Omnibus GitLab】サーバーアップデートに関する注意点・エラー対処法

GitLabサーバーのアップグレードしてますか？
古いバージョンのまま放置されてる方も多いのではないでしょうか？

GIGAZINE：1Tbpsを超えるDDoS攻撃にGitLabサーバーが悪用されていると判明

脆弱性があるGitLabサーバーを悪用されるケースもあるらしいので、
なるべく早めに最新バージョンにしましょう。

3部構成で、GitLabのアップグレード手順をまとめます。

• 1.【Omnibus GitLab】アップグレード手順（Ver.11 ~ Ver.12.10.14まで）
• 2.【Omnibus GitLab】アップグレード手順（Ver.13 ~ Ver.14.6.2まで）
• 3.【Omnibus GitLab】サーバーアップグレードの注意点・エラー対処法

今回は、サーバーアップグレードの注意点・エラー対処法です。

この記事では、私が実際に対処したエラーについて書き記しています。
一人でも多くの方の助けになれますように。。

注意点・エラー対処法

1. here are unfinished transactions remaining. You might consider running yum-complete-transaction, or "yum-complete-transaction --cleanup-only" and "yum history redo last", first to finish them. If those don't work you'll have to try removing/installing packages by hand (maybe package-cleanup can help).

終了していないトランザクションが残っている場合に表示されます。
下記コマンドを入力すれば、解決できるはずです。

sudo yum-complete-transaction

2. Ruby, Gitのバージョンアップについて

Omnibusパッケージを用いて、GitLabの環境構築を行なった場合
GitLabで必要となるRuby, Gitのバージョンは、アップグレードの度に自動で上がっていきます。
なので、別途Ruby, Gitのバージョンアップコマンドを入力する必要はありません。

参考資料
https://forum.gitlab.com/t/gitlab-upgrade-upgrading-git/51639

3. PostgreSQLのバージョンアップについて

PostgreSQLもRuby, Gitと同様に、Omnibusパッケージを用いて、GitLabの環境構築を行なっている場合は、GitLabのバージョンを上げるたびに、PostgreSQLのバージョンも上がっていきます。

しかし、repmgr や Geoを使っている場合、自動でバージョンアップされません。
従って、手動でバージョンアップを行う必要があります。

参考資料
https://gitlab-docs.creationline.com/omnibus/package-information/postgresql_versions.html
https://gitlab-docs.creationline.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server

4. GitLab Runnerのバージョンアップについて

GitLab RunnerはRuby, Gitとは異なり、Omnibusパッケージを使用していても自動ではアップデートされません。
従って、手動でバージョンアップを行う必要があります。

下記の記事を参考にしてください。
https://docs.gitlab.com/runner/install/linux-manually.html

5. Ver.13.5以降で502エラーから復帰しなくなった場合

GitLabサーバーのアップグレードを行うと、普通、１〜２分間502エラーが発生してすぐに復帰します。
これは、アップグレードに伴って、サーバー裏で色々とゴニョゴニョしてるから起こることです。

しかし、Ver.13.5にアップグレードすると、502エラーから復帰できないことがあります。
これは、GitLabバージョン13.5リリースに伴い、ある仕様が変更されたからです。

要約すると、バージョン13.5から Workhorse socketのデフォルトパスが、「/var/opt/gitlab/workhorse/socket」から「/var/opt/gitlab/workhorse/sockets/socket」に変更されました。ということです。

これが原因で、ずっと502エラーが出ています。
このエラーを解消するには、nginxの設定ファイルを以下の通り変更しましょう

変更前

upstream gitlab-workhorse {
  server unix:/var/opt/gitlab/gitlab-workhorse/socket fail_timeout=0;
}

変更後

upstream gitlab-workhorse {
  server unix:/var/opt/gitlab/gitlab-workhorse/sockets/socket fail_timeout=0;
}

最後に、Nginxを再起動すれば502エラーが解消されるはずです。

解消されない場合は、こちらも試してみてください。

参考資料
https://qiita.com/LuckyRetriever/items/509f3a3564370eca3772

6. Ver.13系からVer14系のアップグレードに失敗する場合

GitLabバージョン13からバージョン14に上げようとすると、
以下のエラーメッセージが出て失敗する場合があります。

* unicorn['worker_processes'] has been deprecated since 13.10 and was removed in 14.0. Starting with GitLab 14.0, Unicorn is no longer supported and users must switch to Puma, following https://docs.gitlab.com/ee/administration/operations/puma.html.
Deprecations found. Please correct them and try again.

このエラーは、「GitLabバージョン14からunicornが廃止され、pumaを使うようになったよ。でも、まだあなたの設定ファイルではunicornを使うように記述されているから直してからアップグレードしてね。」という意味です。

それでは、pumaを使うように直していきましょう。

a. 設定ファイルを開く

sudo vim /etc/gitlab/gitlab.rb

b. unicornをpumaに置き換える

下記のように、unicornを利用しているところを全てpumaに置き換えてください。
unicornの下にpumaの設定値が存在しているはずです。

################################################################################
## GitLab Unicorn
##! Tweak unicorn settings.
##! Docs: https://docs.gitlab.com/omnibus/settings/unicorn.html
################################################################################
！！！！コメントアウトする！！！！
# unicorn['enable'] = true
# unicorn['worker_timeout'] = 60
###! Minimum worker_processes is 2 at this moment
###! See https://gitlab.com/gitlab-org/gitlab-ce/issues/18771
 unicorn['worker_processes'] = 3

### Advanced settings
# unicorn['listen'] = 'localhost'
# unicorn['port'] = 8080
# unicorn['socket'] = '/var/opt/gitlab/gitlab-rails/sockets/gitlab.socket'
# unicorn['pidfile'] = '/opt/gitlab/var/unicorn/unicorn.pid'
# unicorn['tcp_nopush'] = true
# unicorn['backlog_socket'] = 1024

################################################################################
## GitLab Puma
##! Tweak puma settings. You should only use Unicorn or Puma, not both.
##! Docs: https://docs.gitlab.com/omnibus/settings/puma.html
################################################################################
!!!! unicornの設定をpumaに変更する。 !!!!
 puma['enable'] = true
 puma['ha'] = false
 puma['worker_timeout'] = 60
 puma['worker_processes'] = 3
 puma['min_threads'] = 1
 puma['max_threads'] = 16

### Advanced settings
 puma['listen'] = '127.0.0.1'
 puma['port'] = 8080
 puma['socket'] = '/var/opt/gitlab/gitlab-rails/sockets/gitlab.socket'
 puma['pidfile'] = '/opt/gitlab/var/puma/puma.pid'
 puma['state_path'] = '/opt/gitlab/var/puma/puma.state'

c. gitlab設定ファイルを再読み込みする

sudo gitlab-ctl reconfigure

6. バックグラウンドマイグレーションが中々終わらない場合【Ver.13まで】

RailsコンソールやTerminalでバックグラウンドマイグレーションが完了しているか
毎回新規アップデートの前は確認すると思います。
本来であれば、マイグレーション自体はそこまで長い時間はかからないものです。
しかし、たまにマイグレーションが正常終了せず、残ったままになる場合があります。
そんなときは、下記の手順を試してみてください。

【この手順は、GitLabバージョン13以前に有効です。】

a. Railsコンソールを開く

sudo gitlab-rails c

b. コンソール上でコマンド実行

scheduled_queue = Sidekiq::ScheduledSet.new

pending_job_classes = scheduled_queue.select { |job| job["class"] == "BackgroundMigrationWorker" }.map { |job| job["args"].first }.uniq

pending_job_classes.each { |job_class| Gitlab::BackgroundMigration.steal(job_class) }

参考資料
https://docs.gitlab.com/ee/update/#what-do-i-do-if-my-background-migrations-are-stuck

7. バックグラウンドマイグレーションが中々終わらない場合【Ver.14以降】

GitLabバージョン14から、バックグラウンドマイグレーションの方法が変更になりました。
データベースのテーブル構造を変更し、GitLabの開発者が作成したマイグレーションのバッチ処理を一旦テーブルへ格納するようになります。
そして、その格納したレコードからバッチ処理を１つずつ処理していくようになります。

もし、そのバッチ処理が滞ってしまった場合の解決方法です。
【この手順は、GitLabバージョン14以降に有効です。】

a. PostgreSQLコンソールを表示

sudo gitlab-psql

b. バッチ管理テーブルを検索

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

ここで、もし詰まっているマイグレーションがあれば下記のように表示されます。
もし、何も表示されない場合はcの手順をスキップして、dの手順に進んでください。

            job_class_name             | table_name | column_name |           job_arguments
---------------------------------------+------------+-------------+------------------------------------
 CopyColumnUsingBackgroundMigrationJob | events     | id          | [["id"], ["id_convert_to_bigint"]]

c. 詰まっているマイグレーションを再実行

bの手順で取得したマイグレーションを再実行していきましょう。
下記コマンドに、必要な値を入れて実行してください。（それぞれDBのカラム名と紐づいています）

sudo gitlab-rake gitlab:background_migrations:finalize[<job_class_name>,<table_name>,<column_name>,'<job_arguments>']

例（bの検索結果）：
sudo gitlab-rake gitlab:background_migrations:finalize[CopyColumnUsingBackgroundMigrationJob,events,id,'[["id"]\, ["id_convert_to_bigint"]]']

d. 全体マイグレーションを再実行

sudo gitlab-rake db:migrate

e. GitLabを再構築

sudo gitlab-ctl reconfigure

参考資料
https://docs.gitlab.com/ee/user/admin_area/monitoring/background_migrations.html
https://docs.gitlab.com/ee/user/admin_area/monitoring/background_migrations.html#check-the-status-of-background-migrations

8. VACUUM FULL 【Ver.15のみ】

GitLabバージョン14系から15系にアップデートするにあたって、
merge_request_diff_commitsテーブルの構成が変更になりました。

その理由は、データベースの容量を大幅に削減するためです。
このテーブルには、MRの作成者とコミッターの名前とメールアドレスが含まれています。
しかし、それらのデータのほとんどが重複しているデータです。
（名前やメールアドレスって頻繁に変わる値ではないですよね。なのに、毎回同じ名前、メールアドレスを１行毎INSERTしてる。つまり無駄が多い。）
従って、ユーザーの名前、メールアドレスの情報を持った別のテーブル（merge_request_diff_commit_users）を作成し
そこから外部参照させることで重複排除を行い容量削減するという意図らしいです。

Ver.15系にアップグレード後、重複データは論理削除のような形でDBの中で生き残り続けています。
そのままでは容量を圧迫したままになるので、下記コマンドを実行して綺麗にしましょう。

#1.psqlを開く
gitlab-psql

#2. 論理削除を完全に消去
VACUUM FULL merge_request_diff_commits;

注意点

VACUUM FULLコマンドは、実行するとテーブルがロックされます。
そして、コマンド完了に時間がかかります。（テーブルサイズ次第）
従って、コマンド実行する際は、あまり他の人が使ってない時間にするか、事前にメンテナンス予定を全員に周知してから行うようにしましょう。

参考資料
https://docs.gitlab.com/ee/update/#1450
https://gitlab.com/gitlab-org/gitlab/-/issues/331823

9. phpファイルへのアクセスが404エラーになる場合

以下のようなログが出て、.phpファイルへのアクセスが404になる場合

FastCGI sent in stderr: "Primary script unknown" while reading response header from upstream

nginxの設定値にphp-fpmを通る設定がないか確認しましょう

10. GitLabがたまに500エラーで落ちる問題【Ver.14.7以降】

Ver14.7以降で、500エラーが定期的に起こるようになり、/var/log/gitlab/gitlab-rails/production.logを確認して以下のようなエラーログが出ている方は、おそらくGitalyのせいでエラーになっています。

fork/exec /tmp/gitaly-git-exec-path-289452710/git: no such file or directory"

エラー詳細

GitLab 14.7から、GitLab内部で使われているGitalyのシンボリックリンクがtmpディレクトリ配下に配置されるようになりました。
しかし、大抵のLinuxでは10日置きにtmpディレクトリ配下にあるファイルなどを削除してしまいます。
それが原因で本来なら消されるべきでないGitalyのシンボリックリンクも削除されてしまい、Git操作が不能になり500エラーになっていました。

解決策

A. Ver14.10にアップグレード

Ver14.10では、この問題が既に修正されています。

Ver14.10アップグレード前に、Ver14.9の最新版にする必要があります。
事前に、公式アップグレードガイドを読むようにしましょう。

B. シンボリックリンクを削除させない設定をする

/etc/tmpfiles.d/配下にconfファイルを作成しましょう。
公式ドキュメントに書かれているコマンドを使っても構いません。
この設定を行うことで、Gitalyのシンボリックリンクは削除されないようになります。

sudo printf "x /tmp/gitaly-%s-*\n" hooks git-exec-path >/etc/tmpfiles.d/gitaly-workaround.conf

参考文献

https://docs.gitlab.com/ee/update/#1470
https://gitlab.com/gitlab-org/gitlab/-/issues/360241
https://gitlab.com/gitlab-org/gitaly/-/issues/4113
https://docs.gitlab.com/ee/update/#1470

11. 上記以外のエラーが出た場合

GitLabのバージョンアップをしていると、未知のエラーに遭遇する時もあると思います。
そんなときは下記の手順を踏んで、焦らず１歩ずつ解決していきましょう。

a. ログ確認

よくわからないエラーが出た時は、まずログを確認しましょう。
大抵の場合、何のファイルにアクセスできない、ファイルがそもそも無いなどエラーの原因を教えてくれます。

cat /var/log/gitlab/gitlab-workhorse/current

cat /var/log/gitlab/gitlab-rails/production.log

b. GitLabの現状確認

GitLabのシステムが綺麗に立ち上がっているか確認するのも大事です。

sudo gitlab-ctl status

全て問題がない場合は、下記のような表示なるはずです。[Ver. 14以降]

run: gitaly: (pid 304) 71693s; run: log: (pid 17948) 105602s
run: gitlab-workhorse: (pid 306) 71693s; run: log: (pid 18295) 105557s
run: logrotate: (pid 24) 3292s; run: log: (pid 18306) 105556s
run: postgresql: (pid 335) 71692s; run: log: (pid 17958) 105601s
run: puma: (pid 34) 7192s; run: log: (pid 18289) 105558s
run: redis: (pid 30) 71691s; run: log: (pid 17941) 105603s
run: sidekiq: (pid 305) 71691s; run: log: (pid 18292) 105557s

もし、１つでもrunの部分がdownになっている場合は一度GitLabを止めて
再度起動し直してみてください。

sudo gitlab-ctl stop

sudo gitlab-ctl start

or 

sudo gitlab-ctl restart

c. GitLab再構築

GitLabの構成を再構築するのも良いかもしれません。

sudo gitlab-ctl reconfigure

不具合がある場合、結果の最後にエラーメッセージを出してくれるので
そこからエラーの原因特定ができるかもしれません。

最後に

以上が、私が実際にGitLabのアップグレード中に体験したエラー対処法や注意点のまとめです。
これからも、アップグレードを行っていく中で目についたものがあれば追記していきます。

もし、ご不明点や質問などあればコメント欄にお願いします。
ご拝読いただきありがとうございました。