ワークロードと環境を考える
ワーカー、エクゼキューター、オートスケール機能
インスタンスレベルの共有ランナーの設定
ランナーの監視
- Grafanaダッシュボード設定のヒント
- Kubernetes上のRunnerを監視するための考慮事項

シェア・ランナーのフリート計画とオペレーション

このガイドには、共有サービスモデルでランナーのフリート規模を拡大するためのベストプラクティスが記載されています。

共有ランナーのフリートをホストする場合、あなたのランナーを考慮し、十分に計画されたインフラストラクチャが必要です：

コンピューティング能力
ストレージ容量
ネットワークの帯域幅とスループット
ジョブの種類（プログラミング言語、OSプラットフォーム、依存ライブラリを含む）。

このガイドを使用して、組織の要件に基づいたGitLab Runnerデプロイ戦略を策定してください。

このガイドでは、どのようなインフラを使うべきかについて具体的な推奨はしていません。しかし、毎月何百万ものCI/CDジョブを処理しているGitLab.comのランナーフリート運用の経験から得たインサイトを提供しています。

ワークロードと環境を考える

Runnerをデプロイする前に、ワークロードと環境の要件を検討してください。

GitLabにオンボードする予定のチームのリストを作成してください。
組織で使われているプログラミング言語、ウェブフレームワーク、ライブラリのカタログを作成します。例えば、Go、C++、PHP、Java、Python、JavaScript、React、Node.js。
各チームが1日1時間あたりに実行できるCI/CDジョブの数を見積もりましょう。
コンテナを使用してもアドレスできないビルド環境要件がチームにあるかどうかを検証します。
そのチーム専用のRunnerを持つことが最適なビルド環境要件があるチームがあるかどうかを検証します。
予想される需要をサポートするために必要なコンピュート容量を見積ります。

異なるランナー・フリートをホストするために、異なるインフラスタックを選択することもできます。例えば、あるランナーは公開クラウドに、あるランナーはオンプレミスにデプロイする必要があるかもしれません。

Runnerフリート上のCI/CDジョブのパフォーマンスは、フリートの環境に直接関係します。大量のリソースを必要とするCI/CDジョブを実行する場合、フリートは共有コンピューティングプラットフォーム上でホスティングすることは推奨されません。

ワーカー、エクゼキューター、オートスケール機能

gitlab-runner 実行ファイルは CI/CD ジョブを実行します。各 Runner はジョブの実行要求を受け取り、事前に定義された設定に従って処理する孤立したプロセスです。分離されたプロセスとして、各ランナーはジョブを実行するための “サブプロセス”（”ワーカー “とも呼ばれます）を作成することができます。

同時実行と制限

同時実行：ホストシステム上で設定されたランナーをすべて使用する場合に、同時に実行できるジョブの数を設定します。
制限：ジョブを同時に実行するためにランナーが作成できるサブプロセスの数を設定します。

この制限は、（Docker MachineやKubernetesのような）オートスケーリングランナーでは、オートスケールしないランナーとは異なります。

オートスケールしないランナーでは、limit 、ホストシステム上のランナーの容量を定義します。
オートスケールするランナーでは、limit は、合計で実行するランナーの数です。

基本設定: 1 Runner, 1 Worker

最も基本的な設定では、GitLab Runnerソフトウェアをサポートされているアーキテクチャとオペレーションシステムにインストールします。例えば、Ubuntu Linuxが動作するx86-64仮想マシン(VM) 。

インストールが完了したら、runner registrationコマンドを一度だけ実行し、shell Executorを選択します。次に、ランナーconfig.toml ファイルを編集して、同時実行を1に設定します。

concurrent = 1

[[runners]]
  name = "instance-level-runner-001"
  url = ""
  token = ""
  executor = "shell"

このランナーが処理できる GitLab CI/CD ジョブは、ランナーをインストールしたホストシステム上で直接実行されます。あたかもターミナルでCI/CDジョブのコマンドを実行しているようなものです。この場合、登録コマンドを1回だけ実行したので、config.toml ファイルには[[runners]] セクションが1つだけ含まれます。concurrencyの値を1に設定したと仮定すると、このシステムでRunnerプロセスのCI/CDジョブを実行できるRunner “worker “は1つだけです。

中間設定：1ランナー、複数ワーカー

同じマシン上に複数のランナーワーカーを登録することもできます。この場合、Runnerのconfig.toml ファイルには、複数の[[runners]] セクションがあります。追加ランナー・ワーカーのすべてがShell Executorを使用するように登録され、グローバル設定オプションの値concurrentを3に更新すると、このホストで同時に実行できるジョブの上限は3つに等しくなります。

concurrent = 3

[[runners]]
  name = "instance_level_shell_001"
  url = ""
  token = ""
  executor = "shell"

[[runners]]
  name = "instance_level_shell_002"
  url = ""
  token = ""
  executor = "shell"

[[runners]]
  name = "instance_level_shell_003"
  url = ""
  token = ""
  executor = "shell"

同じマシン上に多数の Runner Worker を登録でき、それぞれが独立したプロセスです。各ワーカーの CI/CD ジョブのパフォーマンスは、ホストシステムの計算能力に依存します。

オートスケーリング設定：1つ以上のランナーマネージャー、複数のワーカー

GitLab Runner がオートスケーリング用に設定されている場合、ランナーを他のランナーのマネージャーとして動作するように設定することができます。これにはdocker-machine またはkubernetes のエクゼキュータを使います。このようなマネージャーのみの設定では、Runner エージェント自身は CI/CD ジョブを実行しません。

Docker Machineエクゼキュータ

RunnerマネージャはDockerでオンデマンドの仮想マシンインスタンスをプロビジョニングします。
これらの VM 上で、GitLab Runner は.gitlab-ci.yml ファイルで指定したコンテナイメージを使って CI/CD ジョブを実行します。
様々なマシンでCI/CDジョブのパフォーマンスをテストする必要があります。
速度やコストに基づいてコンピュートホストを最適化することを検討すべきです。

Kubernetesエクゼキュータ

Runnerマネージャは、ターゲットKubernetesクラスタ上でポッドをプロビジョニングします。
CI/CDジョブは複数のコンテナで構成される各ポッド上で実行されます。
ジョブの実行に使用されるポッドは通常、ランナーマネージャーをホストするポッドよりも多くの計算リソースとメモリリソースを必要とします。

GitLab Runner 設定の再利用

同じ認証トークンと異なるsystem_id 値で登録された Runner は、一つの Runner にグループ化されます。グループ化されたRunnerは、複数のRunner Managerによって異なるジョブを実行するために再利用することができます。

system_id は、GitLab Runner アプリケーションが起動し、設定が保存されるたびに生成され、ランナーが使用されているマシンを識別します。system_id はconfig.tomlと同じフォルダーの.runner_system_id ファイルに保存されます。

インスタンスレベルの共有ランナーの設定

オートスケーリング設定（ランナーが「ランナーマネージャー」として機能する）でインスタンスレベルの共有ランナーを使用することは、効率的で効果的な開始方法です。

VMやポッドをホストするインフラスタックのコンピュートキャパシティは、以下によって決まります：

ワークロードと環境を検討する際に把握した要件。
Runnerフリートをホストするために使用する技術スタック。

CI/CDワークロードの実行を開始し、時間の経過とともにパフォーマンスを分析した後、コンピューティング容量を調整する必要があるでしょう。

インスタンスレベルの共有ランナーをオートスケーリングエグゼキューターで使用する設定の場合、最低でも2つのランナーマネージャーで開始することをお勧めします。

長期的に必要となるランナー・マネージャーの総数は、以下によって異なります：

ランナーマネージャーをホストするスタックのコンピュートリソース。
各ランナーマネージャーに対して設定する同時実行数。
各マネージャーが時間毎、日毎、月毎に実行する CI/CD ジョブによって生成される負荷。

例えば、GitLab.comでは現在7つのRunnerマネージャをDocker Machine Executorで実行しています。各CI/CDジョブはGoogle Cloud Platform(GCP) n1-standard-1 VMで実行されます。この設定で、月に数百万のジョブを処理しています。GitLab.comのconfig.toml 設定ファイルのスニペットを見ることができます。

ランナーの監視

ランナーフリートを大規模にオペレーションするために不可欠なステップは、GitLabに含まれるランナーモニタリング機能をセットアップして使うことです。

以下の表は、GitLab Runnerのメトリクスをまとめたものです。このリストには、Go固有のプロセス・メトリクスは含まれていません。Runnerのこれらのメトリクスを見るには、ここに書かれているようにコマンドを実行してください。

メトリクス名	説明
`gitlab_runner_api_request_statuses_total`	ランナー、エンドポイント、ステータスで分割された API リクエストの総数。
`gitlab_runner_autoscaling_machine_creation_duration_seconds`	マシン作成時間のヒストグラム。
`gitlab_runner_autoscaling_machine_states`	このプロバイダの状態ごとのマシン数。
`gitlab_runner_concurrent`	同時実行設定の値。
`gitlab_runner_errors_total`	キャッチしたエラーの数。このメトリクスは、ログ行を追跡するカウンターです。このメトリクスには、`level` というラベルが含まれます。設定可能な値は、`warning` および`error`です。このメトリクスを設定する場合は、`rate()` または`increase()` を使用してください。言い換えると、警告やエラーの割合が増加していることに気づいたら、これはさらなる調査が必要なイシューを示唆している可能性があります。
`gitlab_runner_jobs`	これは、現在実行されているジョブの数を示しています（ラベルのスコープは異なります）。
`gitlab_runner_job_duration_seconds`	ジョブの継続時間のヒストグラム。
`gitlab_runner_jobs_total`	実行されたジョブの合計が表示されます。
`gitlab_runner_limit`	リミット設定の現在値です。
`gitlab_runner_request_concurrency`	新しいジョブに対する現在の同時リクエスト数。
`gitlab_runner_request_concurrency_exceeded_total`	設定された`request_concurrency` の制限を超えた超過リクエストの数。
`gitlab_runner_version_info`	異なるビルド統計フィールドによってラベル付けされた、一定の`1` 値を持つメトリクス。
`process_cpu_seconds_total`	ユーザーとシステムの合計 CPU 時間（秒）。
`process_max_fds`	開いているファイル記述子の最大数。
`process_open_fds`	開いているファイル記述子の数。
`process_resident_memory_bytes`	常駐メモリサイズ（バイト）。
`process_start_time_seconds`	unixエポックからのプロセスの開始時間（秒）。
`process_virtual_memory_bytes`	バイト単位の仮想メモリサイズ。
`process_virtual_memory_max_bytes`	利用可能な仮想メモリの最大量（バイト）。

Grafanaダッシュボード設定のヒント

この公開リポジトリには、GitLab.comのRunnerフリートオペレーションに使用しているGrafanaダッシュボードのソースコードがあります。

私たちは GitLab.com のために多くのメトリクスを追跡しています。クラウドベースの CI/CD の大規模なプロバイダーとして、私たちは問題をデバッグできるように、システムに対する多くの異なるビューが必要です。ほとんどの場合、自己管理ランナーフリートは、私たちがGitLab.comで追跡しているような大量のメトリクスを追跡する必要はありません。

ここでは、ランナーフリート（Runner fleet）をモニターするために使うことを推奨する、いくつかの重要なダッシュボードを紹介します。

Runnerで開始されたジョブ：

選択した時間間隔のランナーフリートで実行されたジョブの合計の概要を表示します。
使用状況の傾向を表示します。このダッシュボードは、最低でも毎週分析する必要があります。

このデータをジョブ期間などの他のメトリクスと関連付けることで、CI/CD ジョブのパフォーマンスに関する内部 SLO のサービスを継続するために、設定の変更や容量のアップグレードが必要かどうかを判断できます。

ジョブ期間：

Runnerフリートのパフォーマンスとスケーリングを分析します。

ランナーの能力

実行中のジョブ数をリミット値または同時実行数で割った値を表示します。
追加のジョブを実行するキャパシティがまだあるかどうかを判断します。

Kubernetes上のRunnerを監視するための考慮事項

OpenShift や EKS、GKE などの Kubernetes プラットフォームを使用してランナーフリートをホストする場合、Grafana ダッシュボードのセットアップには異なるアプローチが必要です。

Kubernetes では、ランナー CI/CD ジョブ実行ポッドが頻繁に作成および削除される可能性があります。このような場合、Runner Managerポッドの監視を計画し、潜在的に以下を実装する必要があります：

ゲージ：異なるソースから同じメトリクスを集約して表示します。
カウンタ：rate またはincrease 関数を適用する際にカウンターをリセットします。