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

トップ > GitLab > GitとCI/CDに関する知識ゼロのSEが、GitLabでRunner (Docker) を登録するだけの話 (2022/09/26 改訂)

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

GitLab

2022/06/13　Windows OSにRunnerをインストールする方法についてはこちらのブログでご紹介しております。
2022/09/26　Group Runner登録に必要なTokenと、Shared Runner登録に必要なTokenの確認方法を15.3.1-eeの仕様に更新致しました。　 2022/11/07　コンテナが利用するデフォルトイメージの設定をalpine:3.16.2に変更致しました。　

皆様こんにちは。普段はセキュリティ商材を担当している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 Enterprise Edition 15.3.1-ee における仕様をベースに記載しております。それ以外のエディションやバージョンではこの記事に記載の通りではない可能性がございます。
  • 本記事は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に記載されているので、そちらをご覧ください。
参考: Install GitLab Runner | GitLab

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

Runnerのスコープとは？

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

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

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

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

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

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

本当なら、どのRunnerを実装するのがいいか、スコープはどうするか、AutoScalingはどうするか…などを検討する必要があります。
ですがこの記事ではとりあえずそのあたりをすっ飛ばし、検証用のRunnerを用意し、GitLabに登録します。

Runnerの実装方法はいくつかあるのですが、その中でもおそらく一番お手軽なのがDockerを用いてコンテナとして起動させる方法です。
今回はその方法でRunnerを登録してみます。

具体的にはGitLab Docsの以下のURLにある Install the Docker image and start the container の、Option 1: Use local system volume mounts to start the Runner container でRunnerを作成し登録します。
GitLab Docsの方も併せてご参照ください。
参考：Run GitLab Runner in a container | GitLab

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

Runnerをコンテナで動かすにあたり、Docker Engineが必要になります。
Runnerのコンテナを稼働させる環境にDocker Engineをインストールしてください。
参考：Run GitLab Runner in a container | GitLab

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

このブログでは、Runnerを登録するという目的を達成するために突き進みます。

2022/2/28時点のGitLab Docsによると、Runnerをコンテナで起動させる際の設定フォルダを、ローカルシステムの任意パスか、docker volume create コマンドで作成したDocker Volumeにマウントさせるように記載があります。
参考：Run GitLab Runner in a container | GitLab

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

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

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

$ 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 をお使いください。
参考：Run GitLab Runner in a container | GitLab 

$ 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] を展開し、[Specific runners] の [Register the runner with this URL:] のURLをコピーし、どこかにメモします。
(登録に使用するURLは Specific runners, Group runners, Shared runners とも共通であり、且つ、URLの文字列を簡単にコピーできる場所がここしかないため、この Specific runners のURLをコピーしてください。)

続けて、Runnerを登録したいグループのページを開き、[CI/CD] > [Runner] をクリックします。

[Register a group runner] をクリックし、[Registration token] をコピーし、どこかにメモします。
(下図のようにコピーするアイコンボタンがあるので、それをクリックしてください。)

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

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

GitLabのGUIに、このGitLabインスタンスに対して管理者権限を持っているユーザーでサインインします。

サインイン後、[メニュー] > [管理者] をクリックします。

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

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

[Runner] を展開し、[Specific runners] の [Register the runner with this URL:] のURLをコピーし、どこかにメモします。
(登録に使用するURLは Specific runners, Group runners, Shared runners とも共通であり、且つ、URLの文字列を簡単にコピーできる場所がここしかないため、この Specific runners のURLをコピーしてください。)

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

GitLabにRunnerを登録する

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

GitLab Docsでは、先ほど起動したRunnerとは別にRunnerコンテナを一時的に起動し、そこで gitlab-runner register のコマンドを実行する例が紹介されています。
参考：Registering runners | GitLab

ただ、この方法だと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キーを押下します。 

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＞

Register the runner with this URL が https://gitlab.example.com/の場合はこうなります。

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/):
https://gitlab.example.com/

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

～略～
Enter the registration token:
＜前の手順で確認した Registration token＞

Registration token が AbixxxxxxxxxxxxxxA5tの場合はこうなります。

～略～
Enter the registration token:
AbixxxxxxxxxxxxxxA5t

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

Enter the GitLab instance URL (for example, https://gitlab.com/):
https://gitlab.example.com/
Enter the registration token:
AbixxxxxxxxxxxxxxA5t
Enter a description for the runner:
[Runnerの説明文字列を任意に設定します。空欄可。]

ここでは例として TestRunner01 を入力して進みます。

Enter the GitLab instance URL (for example, https://gitlab.com/):
https://gitlab.example.com/
Enter the registration token:
AbixxxxxxxxxxxxxxA5t
Enter a description for the runner:
TestRunner01

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

～略～
Enter tags for the runner (comma-separated):
[Runnerに付与したいタグを入力します。空欄可。]

ここでは例として TestRunner を設定して進みます。

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

続けて、メンテナンスノートを設定します。
任意の文言を設定し、Enterキーを押下します。

～略～
Enter optional maintenance note for the runner:
[メンテナンスノートを任意に指定します。空欄可。]

ここでは例として maintenance note を設定して進みます。

～略～
Enter optional maintenance note for the runner:
maintenance note

続けて、実行環境を指定します。
なお、選択可能なエクゼキューターの種類の順番は毎回変わります。以下の通りでなくても気になさらないでください。 

～略～
Enter an executor: docker-ssh+machine, custom, docker-ssh, parallels, shell, ssh, virtualbox, docker, docker-windows, docker+machine, kubernetes:
＜使いたいエクゼキューターを指定します＞

今回の場合は docker を指定します。

～略～
Enter an executor: docker-ssh+machine, custom, docker-ssh, parallels, shell, ssh, virtualbox, docker, docker-windows, docker+machine, kubernetes:
docker

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

～略～
Enter the default Docker image (for example, ruby:2.7):
＜Runnerでデフォルトで使用するイメージ＞

ここでは例として alpine:3.16.2 を指定します。

～略～
Enter the default Docker image (for example, ruby:2.7):
alpine:3.16.2

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

～略～
Runner registered successfully. Feel free to start it, but if it's running already the config chould 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] を展開し、[利用可能な Specific Runner] の一覧に先ほど登録したRunnerが表示されていることを確認します。

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

Group runners の確認

GitLabのGUIに、Runnerを登録したグループに対して Owner ロールを持っているユーザーでサインインします。

サインイン後、Runnerを登録したプロジェクトのページに行き、[設定] > [CI/CD] をクリックします。

[Group] タブを開き、先ほど登録したRunnerが表示されていることを確認します。

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

Shared runners の確認

GitLabのGUIに、このGitLabインスタンスに対して管理者権限を持っているユーザーでサインインします。

サインイン後、[メニュー] > [管理者] をクリックします。

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

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

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

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

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

ERROR: Registering runner... failed    runner=<RunnerID> 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=<RunnerID> status=couldn't execute POST against https://<GitLab Runner登録URL>/api/v4/runners: Post "https://<GitLab 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製品 お問い合わせ

今までのGitLabの検証ブログはこちらです。
GitLab カテゴリーの記事一覧 - ネットワールド らぼ

GitLab操作デモ動画 (基本編) を作ってみました。(音声の録音は自宅でiPhoneのボイスメモ使うという超低クオリティですが…。)
つたない内容ではありますが、ご興味がおありでしたら是非ご視聴いただければと存じます。

www.youtube.com