Go to Qiita Advent Calendar Top
LoginSignup
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@GL_TsukasainGitLab合同会社

Runnerの新しい登録ワークフロー、各種ランナータイプとタグ

Posted at

Runnerの新しい登録ワークフロー、各種ランナータイプとタグ

(トップページはこちら) - (GitLab Runnerを始める)

GitLab CI/CD を効果的に運用するには、Runner の適切な登録と管理が不可欠です。本記事では、GitLab 15.10 以降で導入された新しい Runner 登録ワークフローと、ジョブの実行を制御するタグの活用方法について解説します。

1. Runner 登録の新しいワークフロー

1.1 従来の方法からの移行

GitLab 16.0 で、Runner の登録方法が大きく変わりました。従来の登録トークン方式は非推奨となり、新しい認証トークン方式への移行が推奨されています。

1.2 新しい登録方法の利点

新しいワークフローには、以下のような利点があります。

セキュリティの向上

  • Runner の所有権記録が保持されます
  • 認証トークンは glrt- プレフィックスで識別可能です
  • トークンの追跡性が向上し、セキュリティリスクが低減します

運用の効率化

  • 同じ認証トークンを複数のホストで再利用できます
  • 各 Runner マネージャーには一意のシステム ID が付与されます
  • UI 上で同一 Runner として表示されるため、管理が容易になります

1.3 実際の登録手順

1.3.1 インスタンス Runner の作成

管理者権限を持つユーザーは、以下の手順でインスタンス Runner を作成できます。

  1. Admin Area > CI/CD > Runners に移動します
  2. Create instance runner を選択します
  3. オペレーティングシステムを選択します
  4. タグを設定します（詳細は 3 章を参照）
  5. Create runner をクリックします
  6. 表示された認証トークンをコピーします（短時間のみ表示されます）

1.3.2 コマンドラインでの登録

Linux 環境での登録例

# インタラクティブモード
sudo gitlab-runner register

# 非インタラクティブモード
sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "本番環境用Runner"

Docker コンテナでの登録例

docker run --rm -it \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  gitlab/gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "開発環境用Runner"

プロキシ環境での登録

プロキシ経由で接続する場合は、環境変数を設定します。

export HTTP_PROXY=http://proxy.example.com:3128
export HTTPS_PROXY=http://proxy.example.com:3128

sudo -E gitlab-runner register

2. Runner のスコープと種類

GitLab では、3 種類の Runner スコープが用意されています。それぞれの特性を理解し、用途に応じて使い分けることが重要です。

2.1 インスタンス Runner

すべてのプロジェクトで利用可能な Runner です。

特徴

  • GitLab インスタンス全体で共有されます
  • 公平使用キューアルゴリズムでジョブを処理します
  • 複数のプロジェクトで同様の要件がある場合に効率的です

適用シーン

  • 汎用的なビルド環境が必要な場合
  • 多数のプロジェクトで共通の CI/CD 処理を行う場合
  • リソースを効率的に活用したい場合

ジョブ割り当ての仕組み

公平使用キューは、実行中のジョブ数が最も少ないプロジェクトを優先します。これにより、特定のプロジェクトが Runner を独占することを防ぎます。

例えば、以下のジョブがキューにある場合を考えます。

  • プロジェクト A: ジョブ 1、ジョブ 2、ジョブ 3
  • プロジェクト B: ジョブ 4、ジョブ 5
  • プロジェクト C: ジョブ 6

複数のジョブが同時実行される場合、以下の順序で処理されます。

  1. ジョブ 1（プロジェクト A、実行中ジョブ数: 0）
  2. ジョブ 4（プロジェクト B、実行中ジョブ数: 0）
  3. ジョブ 6（プロジェクト C、実行中ジョブ数: 0）
  4. ジョブ 2（プロジェクト A、実行中ジョブ数: 1）
  5. ジョブ 5（プロジェクト B、実行中ジョブ数: 1）
  6. ジョブ 3（プロジェクト A、実行中ジョブ数: 2）

2.2 グループ Runner

グループ内のすべてのプロジェクトで利用可能な Runner です。

特徴

  • グループとそのサブグループ内のプロジェクトで共有されます
  • FIFO（先入れ先出し）キューでジョブを処理します
  • グループオーナーが管理します

適用シーン

  • 特定のチームやプロジェクトグループ専用の環境が必要な場合
  • グループ固有の設定やツールを使用する場合
  • アクセス制御を細かく管理したい場合

作成手順

  1. グループの Build > Runners に移動します
  2. Create group runner を選択します
  3. タグと説明を設定します
  4. 必要に応じて Run untagged を有効化します
  5. Create runner をクリックします

2.3 プロジェクト Runner

特定のプロジェクト専用の Runner です。

特徴

  • 1 つのプロジェクトに紐付けられます（複数プロジェクトで共有も可能）
  • FIFO キューでジョブを処理します
  • プロジェクトメンテナが管理します

適用シーン

  • 特定の認証情報が必要なデプロイジョブ
  • 大量の CI アクティビティがあるプロジェクト
  • セキュリティ要件が厳しいプロジェクト
  • 専用のハードウェアリソースが必要な場合

作成手順

  1. プロジェクトの Settings > CI/CD に移動します
  2. Runners セクションを展開します
  3. Create project runner を選択します
  4. タグと説明を設定します
  5. Create runner をクリックします

3. タグを使ったジョブ制御

タグは、特定の Runner でジョブを実行するための重要な仕組みです。適切なタグ戦略により、ジョブの実行環境を細かく制御できます。

3.1 タグの基本概念

タグの役割

  • ジョブと Runner をマッチングさせます
  • 実行環境の特性を表現します
  • 複数のタグを組み合わせて、より詳細な条件を指定できます

タグのマッチング規則

  • ジョブに指定されたすべてのタグを持つ Runner でのみ実行されます
  • タグが指定されていないジョブは、Run untagged が有効な Runner で実行されます

3.2 基本的なタグの使用例

# 基本的なタグの使用例
build-job:
  stage: build
  tags:
    - docker
    - linux
  script:
    - echo "Docker と Linux タグを持つ Runner で実行"

deploy-production:
  stage: deploy
  tags:
    - production
    - aws
  script:
    - echo "本番環境の AWS Runner で実行"
  environment: production

3.3 タグなしジョブの実行

Runner 作成時に Run untagged を有効にすると、タグが指定されていないジョブも実行できます。

# タグなしジョブの例
test-job:
  stage: test
  script:
    - echo "タグなしジョブを実行可能な Runner で実行"

注意点

  • タグなしジョブは、Run untagged が有効な Runner でのみ実行されます
  • セキュリティ上、本番環境の Runner では Run untagged を無効にすることを推奨します

3.4 複数タグの活用

複数のタグを組み合わせることで、より細かい制御が可能です。

# 複数タグの組み合わせ例
integration-test:
  stage: test
  tags:
    - docker
    - postgres
    - redis
  script:
    - echo "Docker、PostgreSQL、Redis が利用可能な Runner で実行"
  services:
    - postgres:latest
    - redis:latest

3.5 実践的なタグ戦略

実際の運用では、以下のようなタグ戦略が効果的です。

推奨されるタグの分類

  1. 実行環境: docker, shell, kubernetes
  2. OS: linux, windows, macos
  3. 用途: build, test, deploy
  4. 環境: development, staging, production
  5. リソース: gpu, high-memory, ssd
  6. 依存サービス: postgres, redis, mysql

実装例

variables:
  DOCKER_IMAGE: "ruby:3.1"

stages:
  - build
  - test
  - deploy

# ビルドジョブ: Docker Runner を使用
build:
  stage: build
  tags:
    - docker
    - linux
    - build
  script:
    - bundle install
    - bundle exec rake assets:precompile
  artifacts:
    paths:
      - public/assets/
    expire_in: 1 day

# テストジョブ: Docker + データベース環境
test:
  stage: test
  tags:
    - docker
    - linux
    - postgres
  services:
    - postgres:14
  variables:
    POSTGRES_DB: test_db
    POSTGRES_USER: test_user
    POSTGRES_PASSWORD: test_password
  script:
    - bundle exec rspec
  coverage: '/\(\d+\.\d+\%\) covered/'
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/coverage.xml

# ステージング環境へのデプロイ
deploy-staging:
  stage: deploy
  tags:
    - staging
    - shell
    - linux
  script:
    - ./deploy.sh staging
  environment:
    name: staging
    url: https://staging.example.com
    on_stop: stop-staging
  only:
    - develop

# ステージング環境の停止
stop-staging:
  stage: deploy
  tags:
    - staging
    - shell
    - linux
  script:
    - ./stop.sh staging
  environment:
    name: staging
    action: stop
  when: manual
  only:
    - develop

# 本番環境へのデプロイ
deploy-production:
  stage: deploy
  tags:
    - production
    - shell
    - linux
  script:
    - ./deploy.sh production
  environment:
    name: production
    url: https://example.com
  only:
    - main
  when: manual

4. 設定テンプレートを使った高度な登録

複雑な設定が必要な場合、設定テンプレートを使用できます。これにより、コマンドラインでは指定できない詳細な設定が可能になります。

4.1 設定テンプレートの基本

テンプレートの利点

  • コマンドライン引数では指定できない設定が可能です
  • 設定の再利用が容易になります
  • 複雑な設定を管理しやすくなります

注意事項

  • テンプレートには 1 つの [[runners]] セクションのみ含めることができます
  • グローバルオプションはサポートされていません
  • テンプレートの設定とコマンドライン引数が競合する場合、コマンドライン引数が優先されます

4.2 Kubernetes Executor の例

# template.toml
[[runners]]
  [runners.kubernetes]
  [runners.kubernetes.volumes]
    [[runners.kubernetes.volumes.empty_dir]]
      name = "cache_dir"
      mount_path = "/cache"
      medium = "Memory"

登録コマンドです。

sudo gitlab-runner register \
  --template-config /tmp/template.toml \
  --non-interactive \
  --url "https://gitlab.com" \
  --token "$RUNNER_TOKEN" \
  --name "k8s-runner" \
  --executor kubernetes

4.3 Docker サービスの設定例

統合テスト用に複数のサービスを含む Runner を設定する例です。

# services-template.toml
[[runners]]
  [runners.docker]
  [[runners.docker.services]]
    name = "mysql:latest"
  [[runners.docker.services]]
    name = "redis:latest"

登録コマンドです。

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com" \
  --token "$RUNNER_TOKEN" \
  --template-config /tmp/services-template.toml \
  --description "統合テスト用Runner" \
  --executor "docker" \
  --docker-image ruby:3.1

4.4 環境変数を使った設定

テンプレートファイルのパスを環境変数で指定することもできます。

# .gitlab-ci.yml での設定例
variables:
  TEMPLATE_CONFIG_FILE: "/path/to/template.toml"

この設定により、register コマンドで毎回ファイルパスを指定する必要がなくなります。

5. Runner の管理とメンテナンス

5.1 Runner のステータス管理

Runner は以下のステータスを持ちます。適切な監視により、問題を早期に発見できます。

ステータス 説明 対処方法
online 過去 2 時間以内に GitLab と通信し、ジョブを実行可能 正常な状態です
offline 2 時間以上 GitLab と通信しておらず、ジョブを実行不可 Runner の再起動や接続確認が必要です
stale 7 日間以上 GitLab と通信していない Runner の削除を検討してください
never_contacted 一度も GitLab と通信していない gitlab-runner run コマンドを実行してください

5.2 Runner の一時停止と再開

Runner を一時的に停止することができます。メンテナンス作業時などに有用です。

UI での操作

  1. Admin Area > CI/CD > Runners に移動します
  2. 対象の Runner を検索します
  3. Pause アイコンをクリックします

再開する場合

  • Resume アイコンをクリックします

注意点

  • 一時停止中の Runner は新しいジョブを受け付けません
  • 実行中のジョブは完了まで継続されます

5.3 Runner の削除

不要になった Runner は削除できます。

削除前の確認事項

  • Runner が他のプロジェクトで使用されていないか確認します
  • 実行中のジョブがないか確認します
  • 削除は永続的で、元に戻せません

削除手順

  1. Admin Area > CI/CD > Runners に移動します
  2. 対象の Runner の Delete runner アイコンをクリックします
  3. Permanently delete runner を選択します

削除後の処理

Runner を削除した後、ホストマシンの config.toml から設定を削除することを推奨します。

# Runner の登録解除
sudo gitlab-runner unregister --name "runner-name"

# または、すべての Runner を登録解除
sudo gitlab-runner unregister --all-runners

5.4 Runner のアップグレード

Runner のバージョンは定期的にアップグレードすることを推奨します。

アップグレードの確認

UI で Runner のバージョンステータスを確認できます。

  • Outdated - recommended: セキュリティ上の理由から、早急なアップグレードが推奨されます
  • Outdated - available: 新しいバージョンが利用可能ですが、緊急性は低いです

アップグレード手順（Linux）

# パッケージリストの更新
sudo apt-get update

# GitLab Runner のアップグレード
sudo apt-get install gitlab-runner

# バージョンの確認
gitlab-runner --version

5.5 メンテナンスノートの活用

Runner にメンテナンスノートを追加することで、管理情報を記録できます。

設定例

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "本番環境用Runner" \
  --maintenance-note "担当者: 山田太郎、連絡先: yamada@example.com"

活用シーン

  • 担当者の連絡先を記録します
  • メンテナンススケジュールを記録します
  • 特記事項や制約事項を記録します

6. 移行時の注意点

6.1 GitLab 17.0 以降での対応

GitLab 17.0 以降、登録トークンはデフォルトで無効化されています。

重要な変更点

  • 新規 Runner の登録には認証トークンが必須です
  • 既存の Runner は影響を受けません
  • 登録トークンを継続使用する場合は、明示的な有効化が必要です

継続して使用する場合（GitLab.com）

トップレベルグループの設定で有効化できます。

  1. グループの Settings > CI/CD に移動します
  2. Runners セクションを展開します
  3. Allow members of projects and groups to create runners with runner registration tokens を有効化します

継続して使用する場合（GitLab Self-Managed）

Admin Area で設定します。

  1. Admin Area > Settings > CI/CD に移動します
  2. Runners セクションを展開します
  3. Runner registration の設定を変更します

6.2 既存 Runner への影響

重要なポイント

  • 既存の Runner は引き続き動作します
  • 新規登録のみが影響を受けます
  • GitLab Runner Helm Chart を使用している場合は、設定の更新が必要です

移行計画の立案

段階的な移行を推奨します。

  1. フェーズ 1: 新規 Runner は認証トークン方式で登録します
  2. フェーズ 2: 既存 Runner の棚卸しを実施します
  3. フェーズ 3: 不要な Runner を削除します
  4. フェーズ 4: 残りの Runner を認証トークン方式で再登録します

6.3 Helm Chart での設定変更

GitLab Runner Helm Chart を使用している場合、Secret の設定を変更する必要があります。

従来の設定

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-runner-secret
type: Opaque
data:
  runner-registration-token: "REDACTED"
  runner-token: ""

新しい設定

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-runner-secret
type: Opaque
data:
  runner-registration-token: ""  # 空文字列にする（互換性のため残す）
  runner-token: "REDACTED"       # 認証トークンを設定

values.yaml の変更

# 以下のフィールドは認証トークン方式では使用されません
# これらの設定は UI または API で行います
# runnerRegistrationToken: ""
# locked: true
# tags: ""
# runUntagged: true
# protected: true

# 代わりに runnerToken を使用
runnerToken: "glrt-xxxxxxxxxxxxx"

注意事項

  • runner-registration-token は空文字列に設定できない環境もあります
  • その場合、任意の文字列を設定しても問題ありません（runner-token が優先されます）

6.4 既知の問題と回避策

Pod 名が表示されない問題

Helm Chart で新しいワークフローを使用すると、Runner 詳細ページに Pod 名が表示されません。この問題は既知の制限事項です。

トークンローテーション時の問題

複数の Runner マネージャーで同じ認証トークンを使用している場合、トークンローテーション時に最初の Runner マネージャーのみが新しいトークンを受け取ります。他の Runner マネージャーは手動で更新する必要があります。

回避策

  • 各 Runner マネージャーに個別の認証トークンを使用します
  • トークンローテーション後、すべての Runner マネージャーの設定を確認します

7. トラブルシューティング

7.1 よくあるエラーと対処法

7.1.1 エラー: Check registration token

エラーメッセージ

ERROR: Registering runner... failed
runner=xxxxx status=couldn't execute POST against https://gitlab.com/api/v4/runners:
403 Forbidden (check registration token)

原因

  • 登録トークンが無効です
  • GitLab インスタンスがトークンを認識できません
  • トークンの有効期限が切れています

対処法

  1. トークンが正しいか確認します
  2. トークンをコピー＆ペーストする際、余分な空白が含まれていないか確認します
  3. 管理者に登録が許可されているか確認します
  4. 新しいトークンを生成して再試行します

7.1.2 エラー: 410 Gone - runner registration disallowed

エラーメッセージ

ERROR: Registering runner... failed
runner=xxxxx status=couldn't execute POST against https://gitlab.com/api/v4/runners:
410 Gone - runner registration disallowed

原因

  • 登録トークンによる登録が無効化されています
  • GitLab 17.0 以降でデフォルト設定のままです

対処法

  1. 新しい認証トークン方式を使用します（推奨）
  2. または、管理者に登録トークンの有効化を依頼します

7.1.3 Runner が接続できない場合

確認項目

  1. URL の確認
# 正しい URL の例
https://gitlab.com
https://gitlab.example.com

# 誤った URL の例（プロジェクトパスを含めない）
https://gitlab.com/group/project
  1. ネットワーク接続の確認
# GitLab インスタンスへの接続確認
curl -I https://gitlab.com

# DNS 解決の確認
nslookup gitlab.com
  1. プロキシ設定

プロキシ経由で接続する場合は、環境変数を設定します。

export HTTP_PROXY=http://proxy.example.com:3128
export HTTPS_PROXY=http://proxy.example.com:3128
export NO_PROXY=localhost,127.0.0.1

sudo -E gitlab-runner register

永続的にプロキシを設定する場合は、config.toml に記述します。

[[runners]]
  environment = ["HTTP_PROXY=http://proxy.example.com:3128", "HTTPS_PROXY=http://proxy.example.com:3128"]

7.1.4 ジョブが Runner で実行されない場合

原因と対処法

  1. タグの不一致

    • ジョブのタグと Runner のタグが一致しているか確認します
    • Runner で Run untagged が有効になっているか確認します

  2. Runner が一時停止中

    • Runner のステータスを確認します
    • 必要に応じて Resume します

  3. Runner がオフライン

    • Runner のステータスを確認します
    • Runner プロセスが起動しているか確認します
# Runner の状態確認
sudo gitlab-runner status

# Runner の起動
sudo gitlab-runner start

7.2 ログの確認方法

問題の原因を特定するため、ログを確認します。

Runner のログ確認（Linux）

# systemd を使用している場合
sudo journalctl -u gitlab-runner -f

# ログファイルを直接確認
sudo tail -f /var/log/gitlab-runner/gitlab-runner.log

Docker コンテナのログ確認

# コンテナのログを確認
docker logs gitlab-runner -f

デバッグモードでの実行

より詳細なログを出力する場合は、デバッグモードで実行します。

sudo gitlab-runner --debug run

7.3 設定ファイルの確認

Runner の設定は config.toml に保存されています。

設定ファイルの場所

  • Linux: /etc/gitlab-runner/config.toml
  • macOS: /Users/gitlab-runner/.gitlab-runner/config.toml
  • Windows: C:\GitLab-Runner\config.toml

設定例

concurrent = 4
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "production-runner"
  url = "https://gitlab.com"
  token = "glrt-xxxxxxxxxxxxx"
  executor = "docker"
  [runners.docker]
    image = "alpine:latest"
    privileged = false
    volumes = ["/cache"]

8. まとめ

GitLab Runner の新しい登録ワークフローは、セキュリティと管理性を大幅に向上させます。認証トークン方式への移行により、Runner の所有権が明確になり、トークンの追跡が容易になりました。

8.1 重要なポイント

セキュリティ

  • 新規 Runner は認証トークン方式で登録してください
  • 認証トークンは glrt- プレフィックスで識別できます
  • トークンは短時間のみ UI に表示されるため、安全に保管してください

運用効率

  • タグを効果的に活用し、ジョブの実行環境を制御してください
  • Runner のスコープ（インスタンス、グループ、プロジェクト）を適切に選択してください
  • 定期的に Runner のステータスを確認し、不要な Runner は削除してください

移行計画

  • 既存の Runner は引き続き動作しますが、計画的に移行を進めてください
  • GitLab 17.0 以降では、登録トークンがデフォルトで無効化されています
  • Helm Chart を使用している場合は、設定の更新が必要です

8.2 次のステップ

短期的な対応（1〜2週間）

  1. 既存の登録トークンを使用している Runner を確認します
  2. 新しい認証トークン方式での Runner 作成を試します
  3. タグ戦略を見直し、命名規則を統一します

中期的な対応（1〜3ヶ月）

  1. 既存 Runner の棚卸しを実施します
  2. 不要な Runner を削除します
  3. Runner のアップグレード計画を立案します

長期的な対応（3〜6ヶ月）

  1. すべての Runner を認証トークン方式に移行します
  2. Runner の監視体制を整備します
  3. 定期的なメンテナンススケジュールを確立します

8.3 参考情報

公式ドキュメント

  • GitLab Runner のインストール方法
  • Executor の種類と選択基準
  • 高度な設定オプション

コミュニティリソース

  • GitLab フォーラムでの質問と回答
  • ベストプラクティスの共有
  • トラブルシューティング事例

GitLab CI/CD の効率的な運用には、適切な Runner 管理が不可欠です。本記事の内容を参考に、より安全で効率的な CI/CD 環境を構築してください。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?