• 要約
• 提案
  • 現在のランナー登録フローと新しいランナー登録フローの比較
  • 登録トークンの代わりに認証トークンを使用
  • 移行期間
  • 多くのマシンでランナー認証トークンを再利用
    • system_id 。
  • CI ジョブにおけるランナーの識別
• 利点
• 詳細
  • レガシーランナーの取り扱い
  • ci_runner_machines レコードの有効期限
  • 必要な適応
    • ci_runner_machines テーブルへのマイグレーション
    • REST API
    • GraphQLCiRunner タイプ
    • 古いランナーのクリーンアップ
  • APIによるランナー作成
• 実装計画
  • ステージ1 - 非推奨
  • ステージ 2 -gitlab-runner を準備。system_id
  • ステージ 2a - GitLab Runner Helm チャートと GitLab Runner オペレータを準備します。
  • ステージ3 - データベースの変更
  • ステージ4 - UIからのランナーの作成
  • ステージ5 - 任意の登録トークン無効化
  • ステージ6 - エンフォースメント
  • ステージ 7 - 撤去
• FAQ
• ステータス
• 誰

次ページ GitLab Runnerトークンアーキテクチャ

要約

GitLab Runnerは、信頼性の高い並行環境でCI/CDジョブを実行するGitLab CI/CDのコアコンポーネントです。Rubyプログラムとしてサービスが始まって以来、Runnerは登録トークン（ランダムに生成された文字列）を使ってGitLabインスタンスに登録されます。登録トークンは、与えられたスコープ（インスタンス、グループ、プロジェクト）で一意です。登録トークンは、ランナーを登録した側が、そのランナーが登録されているインスタンス、グループ、プロジェクトに対する管理アクセス権を持っていることを証明します。

このアプローチは初期にはうまく機能しましたが、対象者が増えるにつれて、いくつかの既知の大きなイシューが明らかになり始めました：

これらのイシューを考慮すると、ランナーを GitLab インスタンスに接続する方法を再設計し、トレーサビリティ、セキュリティ、パフォーマンスを保証できるようにすることが重要です。

私たちはこの新しい仕組みを “next GitLab Runner Token architecture “と呼んでいます。

提案

この提案では、登録トークンを不要にすることで、_スコープごとの単一のトーク_ンと_トークンの保管という_アドレスに対応します。ランナーの作成は GitLab Runners settings ページで、認証されたユーザーのコンテキストで、指定されたスコープに対して行われます。このページでは、既存のgitlab-runner register コマンドを使って、サポートされている環境で新しく作成した Runner を設定する手順を提供します。

登録トークンがなくなったことで、残りの懸念はイシューではなくなりました。

現在のランナー登録フローと新しいランナー登録フローの比較

登録トークンの代わりに認証トークンを使用

この提案では、GitLab UIで作成されたRunnerには、glrt- （GitLabRunnerToken）をプレフィックスとする認証トークンが割り当てられます。 この接頭辞により、既存のregister コマンドが現在の登録トークン (--registration-token) の_代わりに_認証トークンを使うことができるようになり、既存のワークフローに最小限の調整を加えるだけで済みます。認証トークンは、意図しない再利用を防ぐため、作成フローの完了後にユーザーに一度だけ表示されます。

ランナーは GitLab UI を通して事前に作成されるため、ランナー作成フォームで公開されている引数を指定すると、register コマンドは失敗します。例としては、--tag-list 、--run-untagged 、--locked、--access-level が挙げられます。これらは管理者やオーナーが作成時に決定すべきセンシティブなパラメータだからです。ランナー設定は、既存のregister 。このコマンドは、--registration-token の引数に登録トークンと認証トークンのどちらを指定するかによって、2つの異なる動作をします：

移行期間

移行期間中、レガシートークン（”登録トークン”）はGitLab Runnerの設定ページに表示され続け、gitlab-runner register コマンドによって gitlab-runner register受け入れられます。gitlab-runner register とはいえ、従来のワークフローは UI では推奨されません。ユーザーは UI で Runner を作成し、その結果得られた認証トーク gitlab-runner registerンをコマンドでgitlab-runner register 使用するという新しいフローに誘導さ gitlab-runner registerれます。このアプローチにより、ランナーのデプロイを担当するユーザーの混乱を減らすことができます。

多くのマシンでランナー認証トークンを再利用

既存のオートスケーリングモデルでは、新しいジョブが実行されるたびに新しいRunnerが作成されます。このため、Runnerが取り残され、古くなる状況が多く発生します。

提案モデルでは、ci_runners テーブルエントリーは、ユーザーが複数のマシンで再利用できる設定を記述し、各マシンのランナー状態（例えば、IPアドレス、プラットフォーム、アーキテクチャ）は、別のテーブル（ci_runner_machines ）に移動されます。ランナーアプリケーションの起動時や設定の保存時には、一意のシステム識別子が自動的に生成されます。こ れ に よ り 、ラ ン ナ ー が 使 用 さ れ て い る マ シ ン を 区 別 す る こ と が で き ま す 。

system_id の値は、コマンドライン出力、CI ジョブログ、GitLab UI でランナーを識別するために使用される短いランナートークンを補完します。

ランナーの作成にはユーザーの操作が必要であることを考えると、最終的にはスコープごとに登録できる CI ランナーのプランごとの上限を引き下げることができるはずです。

system_id 。

gitlab-runner インストールには、常に一意のシステム識別子が割り当てられるようにしています。この ID は、/etc/machine-id (Linux の場合) のような既存のマシン識別子から導き出され、プライバシーのためにハッシュ化されます。この場合、s_ が先頭に付きます。ID が利用できない場合、代わりにランダムな文字列が使用されます。この場合、r_ が先頭に付きます。

この一意なIDはgitlab-runner プロセスを識別し、config.toml ファイル内のすべてのランナーに対するPOST /api/v4/jobs リクエストで送られます。

このIDはgitlab-runner の起動時と設定がディスクに保存される時の両方で生成され、保存されます。しかし、config.toml のルートにIDを保存する代わりに、その隣にある新しいファイル -.runner_system_id- に保存します。この新しいファイルの目的は、config.toml ファイルの手動コピーによって ID が再利用される可能性を低くすることです。

s_cpwhDr7zFz4xBJujFeEM

CI ジョブにおけるランナーの識別

ユーザーがジョブを実行したマシンを特定するために、CIジョブのコンテキストで一意の識別子を可視化する必要があります。最初の方法として、GitLab Runner はビルドログに一意なシステム識別子を含めます。

Runnerは異なる一意なシステム識別子で再利用される可能性があるため、一意なシステムIDをデータベースに保存する必要があります。これにより、一意のシステム ID がランナートークンを持つ GitLab Runner のsystem_id 値にマップされることが保証されます。新しいci_runner_machines テーブルは、それぞれのユニークな Runner Manager に関する情報を保持し、その Runner が最後にいつ接続したのか、どのような種類の Runner だったのかという情報を保持します。

長期的には、関連するフィールドはci_runners からci_runner_machines に移動される予定です。しかし、削除のマイルストーンまでは、ci_runner_machines に一致するレコードが存在しない場合の予備として、ci_runners に残しておく必要があります。想定されるシナリオは、テーブルが作成されてもランナーが GitLab インスタンスに ping していない場合です（ランナーがオフラインの場合など）。

さらに、ci_runners に以下のカラムを追加しましょう：

• 誰がランナーを作成したかを記録するためのcreator_id 列；
• ci_runners 、ランナーが従来のregister メソッドで作成されたのか、新しいUIベースのメソッドで作成されたのかを示すregistration_type 列挙型カラム。設定可能な値は:registration_token および:authenticated_userです。これにより、古いランナーのクリーンアップ・サービスがクリーンアップするランナーを決定することができ、将来的な用途が明らかにならない可能性があります。

CREATE TABLE ci_runners (
  ...
  creator_id bigint
  registration_type int8
)

新しいp_ci_runner_machine_builds テーブルは、ci_runner_machines とci_builds テーブルを結合し、これらのテーブルに負担がかからないようにします。既存のレコードを更新するよりも、contacted_at 。

CREATE TABLE p_ci_runner_machine_builds (
    partition_id bigint DEFAULT 100 NOT NULL,
    build_id bigint NOT NULL,
    runner_machine_id bigint NOT NULL
)
PARTITION BY LIST (partition_id);

CREATE TABLE ci_runner_machines (
    id bigint NOT NULL,
    system_xid character varying UNIQUE NOT NULL,
    contacted_at timestamp without time zone,
    version character varying,
    revision character varying,
    platform character varying,
    architecture character varying,
    ip_address character varying,
    executor_type smallint,
    config jsonb DEFAULT '{}'::jsonb NOT NULL
);

利点

• ユーザーが概念を理解しやすい：2種類のトークンの代わりに、1種類のトークン（Runnerごとの認証トークン）があります。2種類のトークンがあると、イシューについて議論するときに誤解が生じます；
• Runnerは、監査ログを使用して、常にそれを作成したユーザーまでトレースすることができます；
• CIランナーの主張は作成時に知られており、ランナーから変更することはできません（例えば、access_level/protected フラグを変更するなど）。しかし、認証されたユーザーは GitLab UI からこれらの設定を編集することができます；
• ci_runner テーブルに触れることなく、古いランナーのクリーンアップがより簡単になりました。

詳細

提案するアプローチでは、移行期間中に現在の登録トークン方式と並行して使用できる、ランナーを設定する明確な方法を作成します。このアイデアは、Runnerが新しいRunnerを登録するために単一の「神のような」トークンを活用するAPIコールを行うことを避けることです。

新しいワークフローは以下のようになります：

1. ユーザーはRunner設定ページ（インスタンス、グループ、またはプロジェクトレベル）を開きます；
2. ユーザーは新しいランナーに関する詳細（説明、タグ、保護、ロックなど）を入力します；

3. ユーザーはCreate をクリックします。その結果、以下のようになります：

   1. ci_runners テーブルに新しい Runner（および対応するglrt- 接頭辞付き認証トークン）が作成されます；
   2. サポートされるさまざまなデプロイメントシナリオ（たとえば、Shell、docker-compose 、Helmチャートなど）を使用して、マシン上でこの新しいランナーを設定する方法をユーザーに提示します。この情報には、ユーザーが一度だけ使用できるトークンが含まれており、同じランナーを複数回登録することは（不可能ではありませんが）推奨されないため、UIはユーザーに値を再度表示しないことを明確にします。

4. ユーザーは、意図したデプロイシナリオの指示（register コマンド）をコピー＆ペーストし、以下のアクションを実行します：

   1. 命令の新しいgitlab-runner register コマンドを実行すると、gitlab-runner は、指定されたランナートークンでPOST /api/v4/runners/verify への呼び出しを実行します；
   2. POST /api/v4/runners/verify GitLabエンドポイントがトークンを検証すると、config.toml ファイルに設定が入力されます；
   3. Runner がジョブのために ping するたびに、それぞれのci_runner_machines レコードが Runner の最新情報で「upsert」されます（Runner heartbeats のために行うように、Redis キャッシュが前面に表示されます）。

移行期間の一環として、管理者とトップレベルのグループオーナーにインスタンス／グループレベルの設定（allow_runner_registration_token ）を提供し、従来の登録トークン機能を無効にし、新しいワークフローのみを使用するよう強制します。gitlab-runner register コマンドがPOST /api/v4/runners エンドポイントをヒットし、登録トークンで新しい Runner を登録しようとすると、HTTP 410 Gone ステータスコードが返されます。

インスタンス設定はグループに継承されます。つまり、インスタンスメソッドでレガシー登録メソッドが無効になっている場合、子孫のグループ/プロジェクトはレガシー登録メソッドを強制的に防ぐことができます。

登録トークンのワークフローは、コンセプトが安定し、顧客が新しいワークフローにマイグレーションした後、将来のメジャーリリースで非推奨となり（gitlab-runner register コマンドで非推奨の通知が出力されます）、削除される予定です。

レガシーランナーの取り扱い

レガシーバージョンの GitLab Runner はリクエストに一意なシステム ID を送信しませんし、一意なシステム ID を扱うために Workhorse のロジックを変更することもありません。これは、レガシーな登録システムが削除され、Runner が新しいバージョンにアップグレードされた後に改善される可能性があります。

そのようなレガシー Runner からのジョブ ping は<legacy> system_xid フィールド値を含むci_runner_machines レコードになります。

一意なシステム ID を使わないということは、同じトークンを持つすべての接続されたランナーに通知されるということです。理想的ではありませんが、それ自体はイシューではありません。

ci_runner_machines レコードの有効期限

新しいレコードは2つの状況で作成されます：

• ランナーがgitlab-runner register コマンドの一部としてPOST /api/v4/runners/verify エンドポイントを呼び出したとき、指定されたランナートークンの先頭にglrt- が付いている場合。これにより、フロントエンドはユーザーが正常に登録を完了したかどうかを判断し、適切なアクションを取ることができます；
• GitLab が新しいジョブに対して ping を行い、token+system_id にマッチするレコードがまだ存在しない場合。

ci_runner_machines のレコードは時間が経過すると消去されるため、それぞれの Runner からの最後のコンタクトから 7 日後に自動的に消去されます。

必要な適応

ci_runner_machines テーブルへのマイグレーション

ci_runner_machines の詳細が必要な場合、ci_runner_machines に一致するフィールドが見つからなければ、ci_runner の既存のフィールドにフォールバックする必要があります。

REST API

ランナートークンを受け取るAPIエンドポイントは、ランナートークンと一緒に送信されるオプションのsystem_id パラメータも受け取るように変更されるべきです(多くの場合、リクエストボディのJSONパラメータとして)。

GraphQLCiRunner タイプ

CiRunner 型 はci_runners モデルを忠実に反映しています。つまり、ipAddress 、architectureName、executorName などの機械情報は、提案されたアプローチでは特異値ではなくなります。当面はこの事実を受け入れ、カンマで区切られた一意な値のリストを返すようにしましょう。それぞれのCiRunner フィールドは、ci_runner_machines エントリーの値を返さなければなりません（存在しない場合は、ci_runner レコードにフォールバックします）。

古いランナーのクリーンアップ

古いランナーをクリーンアップする機能は、ci_runners レコードの代わりに、ci_runner_machines レコードをクリーンアップするように変更する必要があります。

登録トークンのサポートが廃止された後のある時点で、登録トークンで作成された古いランナーをクリーンアップするためのバックグラウンドマイグレーションを作成したいと思います（ci_runners テーブルに作成された enum カラムを活用します）。

APIによるランナー作成

自動化されたランナー作成は、新しい GraphQL 変異と既存のPOST /runners REST API エンドポイントを通じて可能です。REST APIエンドポイントの違いは、登録トークンの代わりにスコープ（インスタンス、グループ、プロジェクト）を持つ作成者からのリクエストを受け付けるように変更されている点です。これらのエンドポイントは、指定されたスコープでランナーの作成が許可されているユーザーのみが利用できます。

実装計画

ステージ1 - 非推奨

ステージ 2 -gitlab-runner を準備。system_id

ステージ 2a - GitLab Runner Helm チャートと GitLab Runner オペレータを準備します。

ステージ3 - データベースの変更

ステージ4 - UIからのランナーの作成

ステージ5 - 任意の登録トークン無効化

ステージ6 - エンフォースメント

ステージ 7 - 撤去

FAQ

ユーザーマニュアルに従ってください。

ステータス

ステータスRFC.

誰

提案

DRI

ドメインの専門家