1 初めに

GitLabを使ってCICDを実装することになった際、shared runnerの経験はありましたが
今回は、project(specific)runnerでdocker executorを用いることになりました。
更に、dockerをそのまま使えばよいものをpodmanを使用するという内容だったので、過去試してきたものを活用しながら実装方法の備忘録として残していきたいと思います。

2 環境

GitLab (SaaS版 Freeプラン)　

ホストOS
Windows10

仮想環境
VMware Workstation Pro (For Windows) 17.6.1

ゲストOS
Red Hat Enterprise Linux release 9.5

3 前提条件

・RedHatアカウントを登録済みであること
・インストールするGitLabRunnerのバージョンが15.1以上であること

4 方法

4.1 環境準備

4.1.1 RHEL環境の準備

昨年VMwareを用いてRHELをインストールしてみたので、今回はそちらの環境を使用していきます。
対象の記事は以下の通りです。

やり方はたくさんあると思うので、自分のやりやすい方法でご用意いただければと思います。

4.1.2 GitLabSaaSの利用準備

こちらも過去実施しているため、再利用します。
GitLabSaaSの登録をし、Gitのプロジェクト作成まで実施します。
完全に新規での作成であれば、プロジェクト作成までは以下を参考いただければと思います。
※少し古いのでUIなどは変更されてる可能性があります。

既にプロジェクトなどを作成したことがある場合は以下に記載します。

プロジェクト作成

今回は、他検証用のプロジェクトと分けるためにグループも一緒に作成していきます。
ログインするとホーム画面に遷移するので、画面左側のメニュー欄から「グループ」を押下します。

グループ画面に遷移するので、画面右側にある「新しいグループ」を押下します。

新しいグループ画面に遷移した後、「グループを作成」を押下します。
※ちなみに「グループをインポート」は、作成済みのグループなどをコピーして作ったりするのに使えます。

グループ作成画面に遷移します。
必要箇所に任意の内容を入力し、一番下までスクロールすると「グループを作成」ボタンがあるので押下します。
今回は以下の設定内容にしました。

グループ名:cicd-test
グループURL:デフォルト
表示レベル：非公開

無事作成されると、グループの画面に遷移します。
「グループxxxは正常に作成されました」と表示されていることを確認します。
作成したグループの下にプロジェクトを作成していくので、画面右側にある「プロジェクトを作成」を押下します。

新しいプロジェクトの作成画面に遷移します。
作成方法がいくつかありますが、今回は「空のプロジェクトの作成」を押下します。

空のプロジェクトの作成画面に遷移します。
必要箇所に任意の内容を記入して、一番下までスクロールすると「プロジェクトを作成」ボタンがあるので押下します。
今回は以下の設定内容にしました。
プロジェクト名：gitrub-runner-test
プロジェクトのURL：デフォルト
表示レベル：非公開
プロジェクトの設定：リポジトリを初期化し…

無事作成されると、プロジェクトのホーム画面に遷移します。
「xxxプロジェクトは正常に作成されました」と表示されていることを確認します。

4.1.3 GitLab Runnerの設定・登録

GitLabRunnerとは、GitLabと連携してパイプラインの指示通りに実際にジョブを実行するアプリケーションです。
Runnerにもいくつか種類があるのですが、今回はProject Runnerというものを利用します。
自前のサーバ(仮想・物理は問わない)にRunnerをインストールして、GitLabと連携することで実行する方法です。

まず、GitLab側でRunnerの設定をしていきます。
プロジェクト画面の左側にあるメニュー欄から、「設定」→「CI/CD」を選択します。

設定画面に遷移した後「Runner」タブを選択し展開します。
今回はProject Runnerを使用していきたいのですが、インスタンスタブのRunnerが有効化されている状態なので、一旦無効にします。
※有効の状態だと、仮にProjectの方がうまく動いてない場合にインスタンスタブの方を使用して動かすため、うまくいってると錯覚してしまうので切りました。

インスタンスタブを押下し、「このプロジェクトのインスタンスRunnerを有効にする」のチェックを押下します。

以下のように無効になっていることを確認してください。

利用可能なRunner欄の右側にある「プロジェクトRuneerを作成」を押下します。

Runnerの作成画面に遷移します。タグ付けや保護の設定などできます。
今回はお試しなので細かい設定はせず作成します。
「タグのないジョブの実行」にチェックを入れ、一番下までスクロールし「Runnerを作成」を押下します。

Runnerの登録画面に遷移します。
Runnerを動かしたいプラットフォームにインストールをしていきます。
既にしている場合は特に必要ないですが、まだであれば対象のプラットフォームを選択した状態で、
「GitLab Runnerをインストールするにはどうすればいいですか？」を押下するとインストールコマンドが表示されます。

今回はLinux上で動かしたいため、Linuxのコマンドを参照します。

GitLabRunnerのインストール

以下がGitLab公式のコマンドです。こちらで実施していきます。
RHELなどインストールしたい環境の画面に切り替えて作業していきます。

LinuxでのRunnerインストール

#1 Download the binary for your system
sudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64

#2 Give it permission to execute
sudo chmod +x /usr/local/bin/gitlab-runner

#3 Create a GitLab Runner user
sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash

#4 Install and run as a service
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start

まずはRunnerをダウンロードします。
この時設定不備で「sudoers ファイル内にありません」となったため、
以下参考にして対処してから実行しました。

実行すると以下のようにプロンプトが表示されます。

[testuser@localhost ~]$ sudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 91.2M  100 91.2M    0     0  2906k      0  0:00:32  0:00:32 --:--:-- 3566k

無事インストールされると、フォルダが作成されるので#2で実行権限を付与していきます。

sudo chmod +x /usr/local/bin/gitlab-runner

その後はRunner用のユーザーを作成します。

sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash

ここまできたら、インストールを実施し完了後にサービスを起動させます。

sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
または
sudo /usr/local/bin/gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner

Runtime platform                                    arch=amd64 os=linux pid=4604 revision=dbac4904 version=18.6.3

sudo gitlab-runner start

念の為、アクティブになっているか確認してみたところ動いていそうです。

GitLab Runnerの登録

インストールができたため、GitLabに認識してもらうために登録の作業を実施します。
GitLab側に表示されている、ステップ1のコマンドを実行します。

Runner登録コマンド

gitlab-runner register  
--url https://gitlab.com  
--token xxxx

ステップ1を実行すると2に記載の通り、プロンプトが表示されます。
すべての問いに回答すると「config.toml」という設定ファイルが作成されます。
今回は以下のように設定しました。
※以下以外はデフォルトのままで、入力せずEnterキーを押しています。

Enter an executor : docker
Enter the default Docker image : ruby3.3

[testuser@localhost bin]$ gitlab-runner register  --url https://gitlab.com  --token <token>
Runtime platform                                    arch=amd64 os=linux pid=5303 revision=dbac4904 version=18.6.3
WARNING: Running in user-mode.                     
WARNING: The user-mode requires you to manually start builds processing: 
WARNING: $ gitlab-runner run                       
WARNING: Use sudo for system-mode:                 
WARNING: $ sudo gitlab-runner...                   
                                                   
Enter the GitLab instance URL (for example, https://gitlab.com/):
[https://gitlab.com]: 
Verifying runner... is valid                        correlation_id=9a624c51f37dd5cb-ATL runner=nzgYHLXC9
Enter a name for the runner. This is stored only in the local config.toml file:
[localhost.localdomain]: 
Enter an executor: ssh, virtualbox, docker+machine, kubernetes, docker-autoscaler, instance, custom, shell, parallels, docker, docker-windows:
docker
Enter the default Docker image (for example, ruby:3.3):
ruby:3.3
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!
 
Configuration (with the authentication token) was saved in "/home/testuser/.gitlab-runner/config.toml"

この後、ステップ3のコマンドを実行してもよいですが、ジョブをまだ登録していないのでRunner自体は動作しても、パイプラインは動かないので実施しなくても大丈夫です。

ここまで完了したら、一番下までスクロールすると表示される「Runnerを表示する」を押下します。

Runnerの設定画面に遷移します。
先程まで空だったところに、登録したRunnerが表示されるようになりました！

4.1.4 .gitlab-ci.ymlの作成

Runnerの登録ができたら、パイプラインを試していきます。
どのような流れで実行していくかを指示・設定するファイルが「.gitlab-ci.yml」です。
このファイルに色々記載することでパイプラインの構築が可能になります。
今回は簡単なテストファイルを作成したいと思います。

プロジェクト画面の左側にあるメニュー一覧から、「ビルド」→「パイプライン」を押下します。

パイプライン画面に遷移すると、以下画像のように選択肢が表示されます。
今回は「テストテンプレートを試す」を押下します。

すると、テスト用のテンプレートが記載された「.gitlab-ci.yml」が表示されます。
YAML形式で実行したいコマンドなどを記述していきます。
テストファイルの全容は以下折りたたみの通りです。

テスト用.gitlab-ci.yml

# This file is a template, and might need editing before it works on your project.
# This is a sample GitLab CI/CD configuration file that should run without any modifications.
# It demonstrates a basic 3 stage CI/CD pipeline. Instead of real tests or scripts,
# it uses echo commands to simulate the pipeline execution.
#
# A pipeline is composed of independent jobs that run scripts, grouped into stages.
# Stages run in sequential order, but jobs within stages run in parallel.
#
# For more information, see: https://docs.gitlab.com/ee/ci/yaml/#stages
#
# You can copy and paste this template into a new `.gitlab-ci.yml` file.
# You should not add this template to an existing `.gitlab-ci.yml` file by using the `include:` keyword.
#
# To contribute improvements to CI/CD templates, please follow the Development guide at:
# https://docs.gitlab.com/development/cicd/templates/
# This specific template is located at:
# https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Getting-Started.gitlab-ci.yml

stages:          # List of stages for jobs, and their order of execution
  - build
  - test
  - deploy

build-job:       # This job runs in the build stage, which runs first.
  stage: build
  script:
    - echo "Compiling the code..."
    - echo "Compile complete."

unit-test-job:   # This job runs in the test stage.
  stage: test    # It only starts when the job in the build stage completes successfully.
  script:
    - echo "Running unit tests... This will take about 60 seconds."
    - sleep 60
    - echo "Code coverage is 90%"

lint-test-job:   # This job also runs in the test stage.
  stage: test    # It can run at the same time as unit-test-job (in parallel).
  script:
    - echo "Linting code... This will take about 10 seconds."
    - sleep 10
    - echo "No lint issues found."

deploy-job:      # This job runs in the deploy stage.
  stage: deploy  # It only runs when *both* jobs in the test stage complete successfully.
  environment: production
  script:
    - echo "Deploying application..."
    - echo "Application successfully deployed."

変更を加えたりしてもよいですが、このまま実行します。
画面一番下までスクロールすると表示される「変更をコミットする」を押下します。

すると、コミットされたことをトリガーにしてパイプラインが実行されます。
特に問題なければ、すべて成功するはずですが…今のままでは失敗します。

(ちなみに全て問題なく実行されると以下のように表示されます。)

再度RHEL側に戻ってpodmanの設定をしていきましょう！

4.1.5 podmanのDocker互換ソケットの有効化

Docker executorなのでDockerをインストールすれば早いのですが、今回はpodmanを用いる事が目標です。
前提としてDocker executorの場合、Dockerデーモンに接続するように作られています。
ですが、Podmanはデーモンレスが売りなので普通に考えたら難しい…。
そこで今回試すのが、PodmanのDocker互換ソケットです。ざっくりいうと、PodmanがDockerのふりをするための窓口のイメージです。
podmanをインストールする際同梱されているのですが自動で有効化されないため、手動で起動する必要があります。
これを起動した状態で、Runnerの設定ファイルであるconfig.tomlの中でDockerデーモンでなく、互換ソケットを見るようにすることで、Docker専用のツールなどに対してDockerを使用していると思わせたままpodmanを使う、ということができるようになるようです。

早速試していきます。まずはpodmanをインストールします。
自分の場合はRHEL9なので、RedHatのリポジトリを使用する方法で実施します。
AppStream リポジトリに含まれているので、以下でインストール可能です。

$ sudo dnf install podman

もしアカウント認証がまだの場合は以下のコマンドを実施し、認証完了してから上記コマンドを再度試してみてください。

#1 Red Hat アカウントで登録
$ sudo subscription-manager register

#2 サブスクリプションのアタッチ(RHEL9の場合は#1の時点で使える場合がある)
$ sudo subscription-manager attach --auto

#3 登録の確認
$ sudo subscription-manager status

問題なくインストールできたら、互換ソケットを有効化します。

$ systemctl --user enable --now podman.socket

# 作成後ソケットが作成されていることを確認
$ ls /run/user/<uid>/podman/podman.sock
/run/user/<uid>/podman/podman.sock

ソケットが有効化されてることが確認できたら、環境変数を設定します。
DOCKER_HOSTが「Docker クライアントがどのソケットに接続するか」を指定する環境変数なので、
デフォルトでunix:///var/run/docker.sockとなっているところを、互換ソケットを見るように変更します。

export DOCKER_HOST=unix:///run/user/$UID/podman/podman.sock

この状態で再度パイプラインを実行してみましょう！
先程失敗したパイプラインを手動実行して確認します。

プロジェクト画面の左側メニュー欄から、「ビルド」→「パイプライン」を押下します。

パイプラインの画面に遷移した後、ステータス項目の部分(以下の画像でいうと「失敗」の部分)を押下します。

パイプラインの詳細画面に遷移した後、画面右側にある「再試行」を押下します。
すると、パイプラインが実行されるので完了するまで待ちます。リアルタイムで実行状態が更新されない事もあるので、その場合はブラウザの更新ボタンで読み込みなおすとよいと思います。
ジョブ名部分(build-job,unit-test-jobなど)を押下すると、実行中のログなども見ることができます。

今回は無事成功しました！

5.最後に
今回は、Docker executorのRunnerをPodmanで使用できるかを試しました。
前提で指定している通り、GitLabRunnerのバージョン15.1以上から上記のソケットを使えるようになったようなので、古いバージョンで試す場合は注意してください。

過去Shared Runnerを利用してみましたが、少しレベルアップして自前のRunnerを利用するということができて無事想定通りの動きができてよかったです。あの時はSpecificRunnerだったのにいつのまにかProject Runnerに名前が変わっていて時の流れとITのアップデートの速さを実感しました。
まだまだ試験レベルなので、今後は運用レベルでの実装もできるように勉強していきます。
また、GitLab以外のサービスと連携した自動化の仕組みなども作れそうなので考えていきたいと思います。

少し長くなりましたがここまで読んでいただきありがとうございました。

6.参照資料