株式会社ネットワールドのエンジニアがお届けする技術情報ブログです。
各製品のエキスパートたちが旬なトピックをご紹介します。

GitとCI/CDに関する知識ゼロのSEが、GitLabでRunner (Docker) を登録するだけの話

2022/05/06 少しでも見やすく…と思い、ブログのスタイルを一部更新致しました。
2022/05/20 GitLabのデモ動画を作りました!このブログの末尾にリンクを張ったのでよろしければご視聴ください。 

皆様こんにちは。普段はセキュリティ商材を担当しているSEの小池と申します。

私の普段の業務はGitやCI/CDに無縁なのですが、会社から頂戴した「GitLabの技術ブログ書いておいて」というミッションを達成すべく、今回も頑張ってGitLabの技術をちまちま習得してまいります。

今回はついにCI/CDパイプラインの実行に向けて一歩踏み出します!
まずは序章としてDockerのコンテナでRunnerを起動してGitLabに登録する方法をご紹介いたします。

このブログの内容は以下の通りです。

本記事の対象の方

  • オンプレミス版 もしくは SaaS版のGitLabでRunner (Docker) を登録したい方。
  • オンプレミス版のGitLabでCI/CDパイプラインを試したいが、なにから手を付けるべきかわからない方。
  • SaaS版のGitLabで Specific Runner もしくは Group Runner を手軽に試したい方。

今回のブログのゴール

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

このブログのゴール
ご利用中のGitLab環境において、任意のスコープのRunner (Docker) を1つ登録する。

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

  • 本記事の内容はオンプレミス版 及び SaaS版のGitLabが対象となります。(GitLab社がDocker Hubに公開なさっているDocker Imageを用いて、任意のDockerホスト等でコンテナとして起動させたGitLabもこの記事の対象です。)
  • 本記事は GitLab Community Edition 14.7.3 における仕様をベースに記載しております。それ以外のエディションやバージョンではこの記事に記載の通りではない可能性がございます。
  • 本記事はGitLabがどういった製品なのかの説明はしておりません。製品説明につきましては弊社の製品ページ (こちら) をご参照ください。
  • 本記事はGitやCI/CDに関する知識ゼロのSEによるなんちゃって記事です。GitLabのディープな使用法についてはGitLabの公式オンラインドキュメント (こちら) をご参照ください。

GitLabのRunnerとは何か?

GitLabのCI/CDパイプラインはリポジトリのルートにある .gitlab-ci.yml というyamlファイルによって構成されます。
Runnerは .gitlab-ci.yml ファイル に記載された処理を実行するアプリケーションです。

Runnerはどうやって用意するのか?

Runnerは以下いずれかの方法で用意することが可能です

  • コンテナで起動する。
  • バイナリをダウンロードする。
  • rpm もしくは deb のリポジトリを使用する。
  • GitLab.comが提供するShared Runnerをそのまま使う。 (SaaS版のみ可)

サポートしているOS、アーキテクチャ、インストール要件、サポートしているコンテナオーケストレーション 等はGitLab Docsに記載されているので、そちらをご覧ください。
参考: https://docs.gitlab.com/runner/install/

今回の記事では、Dockerを使ってコンテナとして起動させたいと思います。

Runnerのスコープとは?

Runnerにはスコープというものがあり、それぞれそのRunnerを使える範囲 (プロジェクト、グループ、インスタンス) が異なります

スコープ 概要
Specific runners 特定のプロジェクトでのみ使用できるランナー。
Group runners グループ内にあるプロジェクトで使用できるランナー。
Shared runners インスタンスに存在する全プロジェクトで使用できるランナー。
GitLab.comではこのスコープのRunnerがあらかじめ複数存在するので、
それを利用することが可能です。

スコープによってRunnerの登録方法に用いるTokenが異なります。
(Runnerの準備の方法はスコープによって違いはありません。)

Dockerを用いて同じホスト上でGitLabとRunnerの両方をコンテナで起動させることは可能か?

GitLabをコンテナで起動している方もいらっしゃるかと存じます。
この様な環境でも、同じホスト上でRunnerをコンテナで起動させることは可能です。
GitLabの機能を試している方や、GitLabのRunnerのためのリソースを新たに確保できない場合は、一時的にこの方法でRunnerを登録して機能を検証していただければと存じます。

DockerでRunnerを用意・登録しよう!

本当なら、どのRunnerを実装するのがいいか、スコープはどうするか、AutoScallingはどうするか…などを検討する必要があります。
ですがこの記事ではとりあえずそのあたりをすっ飛ばし、検証用のRunnerを用意し、GitLabに登録します
Runnerの実装方法はいくつかあるのですが、その中でもおそらく一番お手軽なのがDockerを用いてコンテナとして起動させる方法です。 今回はその方法でRunnerを登録してみます。

Runnerのコンテナを稼働させるホストにDocker Engineをインストールする

Runnerをコンテナで動かすにあたり、Docker Engineが必要になります。
Runnerのコンテナを稼働させる環境にDocker Engineをインストールしてください。
参考:https://docs.gitlab.com/runner/install/docker.html#install-the-docker-image-and-start-the-container

Runnerをコンテナで起動させる

このブログでは、Runnerを登録するという目的を達成するために突き進みます。
2022/2/28時点のGitLab Docksによると、コンテナ起動させる際Runnerの設定フォルダを、ローカルシステムの任意パスか、docker volume create コマンドで作成したDocker Volumeにマウントさせるように記載があります。
参考:https://docs.gitlab.com/runner/install/docker.html#install-the-docker-image-and-start-the-container

ここではローカルシステムの任意パスをマウントさせる方法で進めてみます。

Runnerをコンテナとして起動させるホストにおいて、以下のコマンドを実行します。
(なお、もしGitLabをDocker Composeから起動させている場合は、docker-compose.yml にRunnerも追記して起動する方法も可能です。)

gitlab/gitlab-runner のタグは、以下のサイトをご参照ください。こだわりがなければlatestで問題ないと存じます。
参考:https://hub.docker.com/r/gitlab/gitlab-runner

$ sudo docker run -d --name <GitLab Runnerのコンテナ名> --restart always \
     -v <ローカル側の任意のパス>:/etc/gitlab-runner \
     -v /var/run/docker.sock:/var/run/docker.sock \
     gitlab/gitlab-runner<:latest 等>

GitLab Docsにサンプルとして載っているコマンド例だと、GitLab Runnerコンテナ名が gitlab-runner、ローカル側の任意パスが /srv/gitlab-runner/config、runnerイメージのタグが latest となっているため、以下のようになります。
なお、macOSの場合は /srv の代わりに /Users/Shared をお使いください。
参考:https://docs.gitlab.com/runner/install/docker.html#option-1-use-local-system-volume-mounts-to-start-the-runner-container

$ sudo docker run -d --name gitlab-runner --restart always \
     -v /srv/gitlab-runner/config:/etc/gitlab-runner \
     -v /var/run/docker.sock:/var/run/docker.sock \
     gitlab/gitlab-runner:latest

以下のコマンドを実行し、コンテナ gitlab-runner が起動したことを確認します。

$ sudo docker ps -a

Runnerの登録に必要なURLとTokenを確認する

先ほど起動したRunnerをGitLabに登録します。
この際、先ほど紹介したスコープをどれにするかによって手順が異なります。
Specific runners を登録したい場合は Specific runners に必要なURLとToken (SaaS版, オンプレミス版共通) を実施してください。
Group runners を登録したい場合は Group runners に必要なURLとToken (SaaS版, オンプレミス版共通) を実施してください。
Shared runners を登録したい場合は Shared runners に必要なURLとToken (オンプレミス版のみ) を実施してください。

Specific runners に必要なURLとToken (SaaS版, オンプレミス版共通)

GitLabのGUIに、今回のRunnerを登録させたいプロジェクトに対して Owner もしくは Maintainer ロールを持っているユーザーでサインインします。
サインイン後、Runnerを登録したいプロジェクトのページに行き、[設定] > [CI/CD] をクリックします。

[Runner] を展開し、[Specific runners] の [Register the runner with this URL:] のURLをコピーし、どこかにメモします。

続けて、[And this registration token:] のTokenをコピーし、どこかにメモします。

続けて GitLabにRunnerを登録する を実施してください。

Group runners に必要なURLとToken (SaaS版, オンプレミス版共通)

GitLabのGUIに、今回のRunnerを登録させたいグループに対して Owner ロールを持っているユーザーでサインインします。
サインイン後、Runnerを登録したいプロジェクトのページに行き、[設定] > [CI/CD] をクリックします。

[Runner] を展開し、[Group runners] の [Register the runner with this URL:] のURLをコピーし、どこかにメモします。

続けて、[And this registration token:] のTokenをコピーし、どこかにメモします。

続けて GitLabにRunnerを登録する を実施してください。

Shared runners に必要なURLとToken (オンプレミス版のみ)

GitLabのGUIに、このGitLabインスタンスに対して管理者権限を持っているユーザーでサインインします。
サインイン後、[Menu] > [Admin] をクリックします。

[概要] > [Runner] を開きます。
画面右上にある [Register an instance runner] をクリックし、[Registration token] をコピーし、どこかにメモします。

続いて任意のプロジェクトを開き、[設定] > [CI/CD] をクリックします。

[Runner] を展開し、[Specific runners] の [Register the runner with this URL:] のURLをコピーし、どこかにメモします。

続けて GitLabにRunnerを登録する を実施してください。

GitLabにRunnerを登録する

先ほど確認した登録用URLとTokenを用いて、GitLabにRunnerを登録します。

GitLab Docsでは、先ほど起動したRunnerとは別にRunnerコンテナを一時的に起動し、そこで gitlab-runner register のコマンドを実行する例が紹介されています。
参考:https://docs.gitlab.com/runner/register/index.html#docker
ただ、この方法だとGitLabをDocker Composeなどで起動している場合に名前解決などの問題が発生しやすいので、ここでは直接Runnerコンテナに入って登録コマンドを実行する方法をご紹介いたします。

まずは以下のコマンドで先ほど起動したRunnerコンテナに入ります。

$ sudo docker exec -it <先ほど起動したRunnerコンテナの名前> /bin/bash

先ほど起動したRunnerコンテナ名が gitlab-runner の場合は以下の通りとなります。

$ sudo docker exec -it gitlab-runner /bin/bash

Runnerコンテナに入ったら、以下のコマンドを実行します。

# gitlab-runner register

対話式のRunner登録が始まります。
GitLabのインスタンスURLの入力を求められますので、前の手順で確認した [Register the runner with this URL:] のURLを入力し、Enterキーを押下します。

# gitlab-runner register
Runtime platform                                    arch=amd64 os=linux pid=28 revision=c6e7e194 version=14.8.2
Running in system-mode.

Enter the GitLab instance URL (for example, https://gitlab.com/):
<前の手順で確認した Register the runner with this URL>

続けて、Tokenの入力を求められます。
ここで、前の手順で確認した [Registration token] の文字列を入力し、Enterキーを押下します。

Enter the registration token:
<前の手順で確認した Registration token>

続けて、Runnerの説明を設定します。
任意のRunner説明文字列を設定し、Enterキーを押下します。
(説明はRunner登録後にGitLabのGUIから変更することができます。)
ここでは例として TestRunner01 を入力して進みます。

Enter a description for the runner:
[1235d74d626e]: TestRunner01

続けて、タグを設定します。
任意のタグを設定し、Enterキーを押下します。
(タグはRunner登録後にGitLabのGUIから変更することができます。)
ここでは例として TestRunner を設定して進みます。

Enter tags for the runner (comma-separated):
TestRunner

続けて、メンテナンスノートを設定します。
任意の文言を設定し、Enterキーを押下します。
ここでは例として maintenance note を設定して進みます。

Enter optional maintenance note for the runner:
maintenance note

続けて、実行環境を指定します。
今回の場合は Docker を指定します。

Registering runner... succeeded                     runner=GR134894
Enter an executor: custom, docker, parallels, shell, ssh, virtualbox, docker+machine, docker-ssh+machine, docker-ssh, kubernetes:
docker

最後にデフォルトのDocker Imageを指定します。
これは、CI/CDパイプラインの内容が記載された .gitlab-ci.yml にイメージが明示的に指定されていなかった場合に使うイメージです。
ここでは例として ruby3.1.1 を指定します。

Enter the default Docker image (for example, ruby:2.7):
ruby3.1.1

最終的に以下の通りRunnerの登録に成功した旨のメッセージが出ることを確認します。

Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

続けて、GitLabのGUIからRunnerが登録されたことを確認します。

GitLabのGUIからRunnerの登録を確認

GitLabのGUIからRunnerの登録を確認します。
この際、どのスコープとして登録したかによって手順が異なります。
Specific runners を登録した場合は Specific runners の確認 を実施してください。
Group runners を登録した場合は Group runners の確認 を実施してください。
Shared runners を登録した場合は Shared runners の確認 を実施してください。

Specific runners の確認

GitLabのGUIに、Runnerを登録したプロジェクトに対して Owner もしくは Maintainer ロールを持っているユーザーでサインインします。
サインイン後、Runnerを登録したプロジェクトのページに行き、[設定] > [CI/CD] をクリックします。

[Runner] を展開し、[Available runners] の [specific] タイプのRunnerが表示されていることを確認します。
なお、GitLab.comの場合は↓の画面とは若干表示が異なります。

以上で Specific runners の登録は完了です。

Group runners の確認

GitLabのGUIに、Runnerを登録したグループに対して Owner ロールを持っているユーザーでサインインします。
サインイン後、Runnerを登録したプロジェクトのページに行き、[設定] > [CI/CD] をクリックします。

[Runner] を展開し、[Available runners] の [group] タイプのRunnerが表示されていることを確認します。
([プロジェクト] 列に利用不可と表示されていますが、このRunnerがGroupRunnerなのでこういう表示になります。)

以上で Group runners の登録は完了です。

Shared runners の確認

GitLabのGUIに、このGitLabインスタンスに対して管理者権限を持っているユーザーでサインインします。
サインイン後、[Menu] > [Admin] をクリックします。

[概要] > [Runner] > [Instance] タブを開きます。
一覧に先ほど登録したRunnerがあるか確認します。

以上で Shared runners の登録は完了です。

Runner登録時のエラーについて

Runner登録時に筆者が遭遇したエラー2つと、その回避方法について記載します。

登録時に出るかもしれないエラー1

ERROR: Registering runner... failed                 runner=GR134894 status=couldn't execute POST against https://<GitLabのRunner登録URL>/api/v4/runners: Post "https://<GitLab Runner登録URL>/api/v4/runners": x509: certificate relies on legacy Common Name field, use SANs instead
PANIC: Failed to register the runner. You may be having network problems.
原因

GitLabで使用している証明書にSANsが設定されていない。

回避方法

GitLab側で使用している証明書にSANsを指定してください。
以前プライベートCAで発行した証明書をGitLabに実装する手順をご紹介しておりますので、もしよろしければご参照ください。
参考:GitとCI/CDに関する知識ゼロのSEが、プライベートCAで発行した証明書を使ってGitLabにhttpsでアクセスするだけの話 - ネットワールド らぼ

登録時に出るかもしれないエラー2

ERROR: Registering runner... failed                 runner=GR134894 status=couldn't execute POST against https://<GitLabのRunner登録URL>/api/v4/runners: Post "https://<GiLabのRunner登録URL>/api/v4/runners": x509: certificate signed by unknown authority
PANIC: Failed to register the runner. You may be having network problems.
原因

GitLabで使用している証明書が "信頼できる認証局(CA)によって発行された証明書" として認識されていない。
プライベートCAで発行した証明書を使っている場合でも出る。

回避方法

プライベートCA 又は 信頼できるCAによって発行された証明書を使用している場合は、Runner登録のコマンドにオプションを指定することで回避できる可能性があります。
まず、Runnerの起動時にマウントしたDockerホスト側のディレクトリ (今回の例では /srv/gitlab-runner/config/ ) 配下に certs というディレクトリを作成します。
作成したディレクトリ certs 配下に、ルート証明書を置きます。
Runnerコンテナに入り、以下のコマンドで先ほど配置したルート証明書が参照できるか確認します。

# cat /etc/gitlab-runner/certs/<先ほど置いたルート証明書>

続けてgitlab-runner register コマンドを実行しますが、その際にオプション --tls-ca-file=/etc/gitlab-runner/certs/private-ca.crt を指定してください。

# gitlab-runner register --tls-ca-file=/etc/gitlab-runner/certs/private-ca.crt

最後に

この度はGitもCI/CDもよくわかっていないど素人SEによるGitLab検証ブログをお読みいただき、誠にありがとうございます。
このブログの目標は以下のとおりでしたが、皆さまはいかがでしたでしょうか。

このブログのゴール
ご利用中のGitLab環境において、任意のスコープのRunner (Docker) を1つ登録する。

この記事が「なんかよくわからんけどGitLabをとりあえず触りたい!」という方のお力になれば幸甚にございます。


GitLabに関するお問い合わせは、以下のフォームからお願い致します。
GitLab製品 お問い合わせ

2022/05/20追記
GitLab操作デモ動画 (基本編) を作っちゃいました。
つたない内容ではありますが、ご興味がおありでしたら是非ご視聴いただければと存じます。

www.youtube.com