glab-runner-controller

glab-runner-controller

GitLab Runner コントローラーとその認証トークンを管理します。

⚠️ 実験的機能

ステータス： 実験的（管理者のみ）

• この機能は、事前の通知なく動作しなくなったり、削除されたりする場合があります
• 自己責任でご利用ください
• GitLab の管理者権限が必要です
• 参照先：https://docs.gitlab.com/policy/development_stages_support/

機能

Runner コントローラーは、インフラストラクチャ内の GitLab Runner のオーケストレーションを管理します。このスキルでは、次のコマンドを使用できます。

• Runner コントローラーの作成と設定
• コントローラーの詳細と接続ステータスの確認
• コントローラーのライフサイクル管理（一覧表示、取得、更新、削除）
• コントローラーのスコープ管理（インスタンスレベルまたは Runner レベル）
• 認証トークンの生成とローテーション
• 侵害されたトークンの失効

よく使われるワークフロー

Runner コントローラーの作成

# Create with default settings
glab runner-controller create

# Create with description
glab runner-controller create --description "Production runners"

# Create enabled controller
glab runner-controller create --description "Prod" --state enabled

状態：

• disabled - コントローラーは存在しますが、無効です
• enabled - コントローラーは有効です（デフォルト）
• dry_run - テストモードです（実際の Runner は実行されません）

コントローラーの一覧表示と確認

# List all controllers
glab runner-controller list

# List with pagination
glab runner-controller list --page 2 --per-page 50

# Output as JSON
glab runner-controller list --output json

# Get one controller with status details
glab runner-controller get 42

glab runner-controller get 42 --output json

コントローラーの更新

# Update description
glab runner-controller update 42 --description "Updated name"

# Change state
glab runner-controller update 42 --state disabled

# Update both
glab runner-controller update 42 --description "Prod" --state enabled

コントローラーの削除

# Delete with confirmation prompt
glab runner-controller delete 42

# Delete without confirmation
glab runner-controller delete 42 --force

スコープ管理

Runner コントローラーのスコープによって、コントローラーが評価できる対象が決まります。

スコープの一覧表示

# List all scopes for controller 42
glab runner-controller scope list 42

# JSON output
glab runner-controller scope list 42 --output json

スコープの追加

# Allow the controller to evaluate all instance runners
glab runner-controller scope create 42 --instance

# Allow the controller to evaluate a specific runner
glab runner-controller scope create 42 --runner 5

# Add multiple runner scopes
glab runner-controller scope create 42 --runner 5 --runner 10
glab runner-controller scope create 42 --runner 5,10

スコープの削除

# Remove the instance-level scope
glab runner-controller scope delete 42 --instance

# Remove a specific runner-level scope
glab runner-controller scope delete 42 --runner 5 --force

注： 古いドキュメントや例では、glab runner-controller runner ... サブコマンドが使われている場合があります。現在ユーザーが使用するのは、glab runner-controller scope ... と glab runner-controller get です。

トークン管理のワークフロー

トークンのライフサイクル

セキュリティのベストプラクティスに従う場合、通常のトークンのライフサイクルは 作成 → ローテーション → 失効 です。

1. トークンの作成

# Create token for controller 42
glab runner-controller token create 42

# Create with description
glab runner-controller token create 42 --description "production"

# Output as JSON (for automation)
glab runner-controller token create 42 --output json

重要： トークンの値は作成時に一度だけ表示されるため、すぐに保存してください。

2. トークンの一覧表示

# List all tokens for controller 42
glab runner-controller token list 42

# List as JSON
glab runner-controller token list 42 --output json

# Paginate
glab runner-controller token list 42 --page 1 --per-page 20

3. トークンのローテーション

ローテーションすると新しいトークンが生成され、古いトークンは無効になります。

# Rotate token 1 (with confirmation)
glab runner-controller token rotate 42 1

# Rotate without confirmation
glab runner-controller token rotate 42 1 --force

# Rotate and output as JSON
glab runner-controller token rotate 42 1 --force --output json

使用例：

• 定期的なローテーション（セキュリティポリシーへの準拠）
• トークン侵害への対応
• 従業員の退職前のキーのローテーション

4. トークンの失効

# Revoke token 1 (with confirmation)
glab runner-controller token revoke 42 1

# Revoke without confirmation
glab runner-controller token revoke 42 1 --force

失効するタイミング：

• トークンが侵害または漏えいした場合
• コントローラーを廃止した場合
• アクセスが不要になった場合

トークンセキュリティのベストプラクティス

1. 定期的にローテーションする - 定期的なローテーション（例：90 日ごと）を設定します
2. 説明を付ける - トークンの用途と所有者を記録します
3. 侵害された場合はすぐに失効させる
4. トークンをバージョン管理にコミットしない
5. 自動化には --output json を使用する（トークンの値を安全に解析します）

判断ツリー：コントローラーの状態の選択

Do you need the controller active?
├─ Yes → --state enabled
├─ Testing configuration? → --state dry_run
└─ No (maintenance/setup) → --state disabled

トラブルシューティング

「Permission denied」または「403 Forbidden」：

• Runner コントローラーのコマンドには GitLab の管理者権限が必要です
• 管理者ユーザーとして認証されていることを確認してください
• glab auth status を実行して、現在のユーザーを確認してください

「Runner controller not found」：

• glab runner-controller list でコントローラー ID を確認してください
• コントローラーが削除されている可能性があります
• 正しい GitLab インスタンスにアクセスできることを確認してください

トークンの作成に失敗する：

• コントローラーが存在し、有効になっていることを確認してください
• 管理者権限を確認してください
• GitLab インスタンスのバージョンを確認してください（実験的機能の使用には、最近のバージョンが必要な場合があります）

トークンをローテーションしても古いトークンが使える：

• トークンの無効化が反映されるまで、数秒かかる場合があります
• 10～30 秒待ってから、もう一度テストしてください
• コントローラーの状態を確認してください（無効なコントローラーではトークンの検証は行われません）

コントローラーを削除できない：

• コントローラーにアクティブな Runner があるか確認してください
• 先に Runner を廃止する必要がある場合があります
• --force を使用して強制的に削除できます（⚠️ 破壊的な操作）

実験的機能を使用できない：

• glab のバージョンを確認してください：glab version（最近の glab ビルドが必要です）
• GitLab インスタンスで機能フラグが有効になっているか確認してください
• GitLab インスタンスのバージョンが Runner コントローラーに対応していることを確認してください

関連スキル

CI/CD とランナー：

• glab-ci - CI/CD パイプラインとジョブを表示および管理します
• glab-job - 個別のジョブを再試行、キャンセルし、ログを表示します
• glab-runner - 個別のランナーを管理します（一覧表示、割り当て、ジョブ、マネージャー、更新、削除）

リポジトリ管理：

• glab-repo - リポジトリを管理します（ランナーコントローラーはインスタンスレベルです）

認証：

• glab-auth - ログインと認証を管理します

コマンドリファレンス

コマンド構文と利用可能なすべてのフラグについては、以下を参照してください。

• references/commands.md