新しいRunner登録ワークフローに移行する

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

このページには、今後の製品や機能に関する情報が記載されています。重要な点として、ここに示されているのは情報提供のみを目的とした情報であることにご注意ください。この情報だけに基づいて購入や計画の決定をなさらないようにしてください。製品や機能の開発、リリース、タイミングは、GitLab Inc.独自の裁量により変更が加えられたり遅延したりすることがあります。

GitLab 16.0では、新しいRunner作成ワークフローが導入され、Runner認証トークンを使用してRunnerを登録します。登録トークンを使用する従来のワークフローは推奨されません。代わりにRunner作成ワークフローを使用してください。

新しいワークフローの現在の開発状況については、エピック7663を参照してください。

新しいアーキテクチャの技術設計と理論については、次のGitLab Runnerトークンアーキテクチャを参照してください。

新しいRunner登録ワークフローに関して問題が発生した場合や懸念がある場合、または詳細情報が必要な場合は、フィードバックイシューでお知らせください。

新しいRunner登録ワークフロー

新しいRunner登録ワークフローでは、次のことを行います:

GitLab UIで直接、またはプログラムでRunnerを作成します。
Runner認証トークンを受信します。
この設定でRunnerを登録する場合は、登録トークンの代わりにRunner認証トークンを使用します。複数のホストに登録されているRunnerマネージャーは、GitLab UIの同じRunnerに表示されますが、識別システムIDが付きます。

新しいRunner登録ワークフローには、次の利点があります:

Runnerの所有権レコードを保持し、ユーザーへの影響を最小限に抑えました。
一意のシステムIDを追加すると、複数のRunnerで同じ認証トークンを再利用できるようになります。詳細については、GitLab Runner設定の再利用を参照してください。

計画された変更の推定時期

GitLab 15.10以降で、新しいRunner登録ワークフローを使用できます。

Runner登録ワークフローが中断しないようにする

GitLab 16.11以前では、従来のRunner登録ワークフローを使用できます。

GitLab 17.0以降、レガシーRunnerの登録トークンのワークフローは、インスタンスの管理者またはグループオーナーが無効にできます。詳細については、GitLab 17.0以降で登録トークンを使用するを参照してください。

新しいワークフローに移行せずにRunnerを登録すると、Runnerの登録トークンが中断し、gitlab-runner registerコマンドが410 Gone - runner registration disallowedエラーを返します。

ワークフローの中断を回避するには、次の操作を行います:

Runnerを作成し、認証トークンを取得します。
Runner登録ワークフローの登録トークンを、認証トークンに置き換えます。

GitLab 17.0以降で登録トークンを使用する

GitLab 17.0以降で登録トークンを引き続き使用するには、次のようにします:

GitLab.comでは、トップレベルグループ設定で従来のRunner登録プロセスを手動で有効化できます。
GitLab Self-Managedでは、管理者エリアの設定で従来のRunner登録プロセスを手動で有効化できます。

既存のRunnerへの影響

既存のRunnerは、GitLab 17.0にアップグレードした後も通常どおり動作します。この変更は、新しいRunnerの登録にのみ影響します。

GitLab Runner Helmチャートは、ジョブが実行されるたびに新しいRunnerポッドを生成します。これらのRunnerについては、従来のRunner登録を有効にすると、登録トークンを使用できます。

`gitlab-runner register`コマンド構文の変更

gitlab-runner registerコマンドは、登録トークンの代わりにRunner認証トークンを受け入れます。トークンは、管理者エリアのRunnersページから生成できます。Runner認証トークンは、glrt-プレフィックスで認識できます。

GitLab UIでRunnerを作成する場合は、設定値を指定します。これは以前、gitlab-runner registerコマンドでプロンプト表示されるコマンドラインオプションでした。

Runner認証トークンを次のように指定した場合:

--tokenコマンドラインオプションを指定すると、gitlab-runner registerコマンドは設定値を受け入れません。
--registration-tokenコマンドラインオプションを指定すると、gitlab-runner registerコマンドは設定値を無視します。

トークン	登録コマンド
Runner認証トークン	`gitlab-runner register --token $RUNNER_AUTHENTICATION_TOKEN`
Runner登録トークン（レガシー）	`gitlab-runner register --registration-token $RUNNER_REGISTRATION_TOKEN <runner configuration arguments>`

認証トークンのプレフィックスはglrt-です。

自動化ワークフローへの影響を最小限に抑えるため、従来の互換性のある登録処理は、従来のパラメータ--registration-tokenでRunner認証トークンが指定されている場合にトリガーされます。

GitLab 15.9のコマンド例:

gitlab-runner register \
    --non-interactive \
    --executor "shell" \
    --url "https://gitlab.com/" \
    --tag-list "shell,mac,gdk,test" \
    --run-untagged "false" \
    --locked "false" \
    --access-level "not_protected" \
    --registration-token "REDACTED"

GitLab 15.10以降では、Runnerの作成や、タグリスト、ロックされたステータス、アクセスレベルなどの属性の設定をUIで実行できます。GitLab 15.11以降では、glrt-プレフィックスが付いたRunner認証トークンが指定されている場合、これらの属性はregisterへの引数として受け入れられなくなりました。

新しいコマンドの例を次に示します:

gitlab-runner register \
    --non-interactive \
    --executor "shell" \
    --url "https://gitlab.com/" \
    --token "REDACTED"

オートスケールへの影響

GitLab Runner OperatorやGitLab Runner Helmチャートなどのオートスケールシナリオでは、UIで生成されたRunner認証トークンが登録トークンを置き換えます。つまり、ジョブごとにRunnerを作成する代わりに、同じRunner設定がジョブ全体で再利用されます。特定のRunnerは、Runnerプロセスが開始されたときに生成される一意のシステムIDによって識別できます。

プログラムによるRunnerの作成

GitLab 15.11以降では、POST /user/runners REST APIを使用して、認証済みユーザーとしてRunnerを作成できます。これは、Runner設定が動的であるか、再利用できない場合にのみ使用してください。Runner設定が静的な場合は、既存のRunnerのRunner認証トークンを再利用してください。

Runnerの作成と登録を自動化する方法については、チュートリアルRunnerの作成と登録の自動化を参照してください。

Helmチャートを使用してGitLab Runnerをインストールする

Runner登録トークンが無効になっている場合、いくつかのRunner設定オプションは、Runnerの登録中に設定できません。これらのオプションは、次の場合にのみ設定できます:

UIでRunnerを作成する場合。
user/runners REST APIエンドポイントを使用する場合。

そのシナリオでは、次の設定オプションはvalues.yamlでサポートされていません:

## If a runner authentication token is specified in runnerRegistrationToken, the registration will succeed, however the
## other values will be ignored.
runnerRegistrationToken: ""
locked: true
tags: ""
maximumTimeout: ""
runUntagged: true
protected: true

Kubernetes上のGitLab Runnerの場合、HelmデプロイはRunner認証トークンをRunnerワーカーポッドに渡し、Runner設定を作成します。GitLab 17.0以降、runnerRegistrationTokenトークンフィールドをGitLab.comに接続されているKubernetesホスト型Runnerで使用する場合、Runnerワーカーポッドは、作成時にレガシーAPI登録メソッドを使用しようとします。

無効なrunnerRegistrationTokenフィールドをrunnerTokenフィールドに置き換えます。secretsに保存されているRunner認証トークンも変更する必要があります。

従来のRunner登録ワークフローでは、フィールドは次のように指定されていました:

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-runner-secret
type: Opaque
data:
  runner-registration-token: "REDACTED" # DEPRECATED, set to ""
  runner-token: ""

新しいRunner登録ワークフローでは、代わりにrunner-tokenを使用する必要があります:

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-runner-secret
type: Opaque
data:
  runner-registration-token: "" # need to leave as an empty string for compatibility reasons
  runner-token: "REDACTED"

シークレット管理ソリューションでrunner-registration-tokenに空の文字列を設定できない場合は、任意の文字列に設定できます。この値は、runner-tokenが存在する場合は無視されます。

既知の問題

ポッド名がRunner詳細ページに表示されない

新しい登録ワークフローを使用してHelmチャートでRunnerを登録すると、ポッド名がRunner詳細ページに表示されません。詳細については、イシュー423523を参照してください。

Runner認証トークンがローテーション時に更新されない

複数のRunnerマネージャーに登録されている同じRunnerでのトークンローテーション

自動トークンローテーションを使用した新しいワークフローを介して複数のホストマシンにRunnerを登録すると、最初のRunnerマネージャーのみが新しいトークンを受信します。残りのRunnerマネージャーは無効なトークンを引き続き使用するため、接続が解除されます。新しいトークンを使用するには、これらのマネージャーを手動で更新する必要があります。

GitLab Operatorでのトークンローテーション

GitLab Operatorを使用して新しいワークフローでRunnerを登録する際に、カスタムリソース定義のRunner認証トークンはトークンローテーション中に更新されません。これは次の場合に発生します:

カスタムリソース定義によって参照されるシークレットで、Runner認証トークン（glrt-プレフィックス付き）を使用している。
Runner認証トークンに有効期限がある。Runner認証トークンの有効期限の詳細については、認証トークンのセキュリティを参照してください。

詳細については、イシュー186を参照してください。