このバージョンの GitHub Enterprise サーバーはこの日付をもって終了となりました: 2024-09-25. 重大なセキュリティの問題に対してであっても、パッチリリースは作成されません。 パフォーマンスの向上、セキュリティの向上、新機能の向上を図るために、最新バージョンの GitHub Enterprise サーバーにアップグレードしてください。 アップグレードに関するヘルプについては、GitHub Enterprise サポートにお問い合わせください。

Actions Runner Controller について

独自のランナーをホストして、GitHub Actionsワークフロー中でジョブの実行に使われる環境をカスタマイズできます。

この記事の内容

法的通知

Actions Runner Controller について

Actions Runner Controller (ARC) は、GitHub Actions のセルフホステッド ランナーを調整およびスケーリングする Kubernetes オペレーターです。 詳細については、Kubernetes ドキュメントの「オペレーター パターン」を参照してください。

ARC を使うと、リポジトリ、組織、またはエンタープライズで実行中のワークフローの数に基づいて自動的にスケーリングされるランナー スケール セットを作成できます。 制御されたランナーは一時的でコンテナーに基づく可能性があるため、新しいランナー インスタンスを迅速かつクリーンにスケールアップまたはスケールダウンすることができます。 自動スケーリングについて詳しくは、「セルフホステッド ランナーによる自動スケーリング」をご覧ください。

次の図は、ARC の自動スケール ランナー スケールセット モードのアーキテクチャを示しています。

Note

次の図をより大きなサイズで表示するには、アクション ランナー コントローラー リポジトリの「自動スケール ランナー スケール セット モード」のドキュメントを参照してください。

ARC の自動スケール ランナースケール セット モードを示す図。

  1. Actions Runner Controller は提供された Helm チャートを使用してインストールされ、コントローラー マネージャー ポッドは指定された名前空間にデプロイされます。 新しい AutoScalingRunnerSet リソースは、提供された Helm チャートまたはカスタマイズされたマニフェスト ファイルを使用してデプロイされます。 AutoScalingRunnerSet コントローラーでは GitHub の API を呼び出して、ランナー スケール セットが属するランナー グループ ID をフェッチします。
  2. AutoScalingRunnerSet コントローラーでは、ランナー スケール セット リスナー リソースを作成する前に、もう 1 回 API を呼び出して、GitHub Actions サービスでランナー スケール セットをフェッチまたは作成します。
  3. ランナー スケールセット リスナー ポッドは、AutoScalingListener コントローラーによってデプロイされます。 このポッドで、リスナー アプリケーションは GitHub Actions サービスに接続して、HTTPS の長いポーリング接続を認証して確立します。 リスナーは、GitHub Actions サービスから Job Available メッセージを受信するまでアイドル状態のままになります。
  4. リポジトリからワークフロー実行がトリガーされると、GitHub Actions サービスによって、個々のジョブ実行がランナーまたはランナー スケールセットにディスパッチされます。ここで、runs-on キーはランナー スケールセットの名前またはセルフホステッド ランナーのラベルと一致します。
  5. ランナー スケールセット リスナーでは、Job Available メッセージを受信すると、必要な数にスケールアップできるかどうかを確認します。 できる場合、ランナー スケールセット リスナーではメッセージの受信確認を行います。
  6. ランナー スケールセット リスナーでは、サービス アカウントとそのアカウントにバインドされたロールを使用して、Kubernetes API を介して HTTPS 呼び出しを行い、必要なレプリカ数でエフェメラル RunnerSet リソースにパッチを適用します。
  7. エフェメラル RunnerSet では新しいランナーの作成を試み、EphemeralRunner コントローラーでは Just-In-Time (JIT) 構成トークンを要求してこれらのランナーを登録します。 コントローラーではランナー ポッドの作成を試みます。 ポッドの状態が failed の場合、コントローラーでは最大 5 回再試行します。 24 時間後、GitHub Actions サービスでは、ランナーがジョブが受け入れない場合、その割り当てを解除します。
  8. ランナー ポッドが作成されたら、ポッド内のランナー アプリケーションでは JIT 構成トークンを使用して、自身を GitHub Actions サービスに登録します。 その後、別の HTTPS の長いポーリング接続を確立して、実行する必要があるジョブの詳細を受け取ります。
  9. GitHub Actions サービスではランナー登録の受信確認を行い、ジョブ実行の詳細をディスパッチします。
  10. ジョブの実行全体を通じて、ランナーにより、ログとジョブの実行状態が GitHub Actions サービスに継続的に伝達されます。
  11. ランナーで正常にジョブが完了すると、EphemeralRunner コントローラーでは GitHub Actions サービスを使用して、ランナーを削除できるかどうかを確認します。 できる場合は、エフェメラル RunnerSet によってランナーが削除されます。

Actions Runner Controller コンポーネント

ARC は一連のリソースで構成され、その一部は ARC 専用に作成されます。 ARC の展開により、これらのカスタム リソースが Kubernetes クラスターに適用されます。 これが適用されると、セルフホステッド ランナーのコンテナーを含むポッドのセットが作成されます。 ARC を使用すると、GitHub は、これらのランナー コンテナーをセルフホステッド ランナーとして扱い、必要に応じてジョブを割り当てることができます。

ARC によってデプロイされる各リソースには、次で構成される名前が付けられます:

  • インストール名。これは、Helm チャートをインストールするときに指定するインストール名です。
  • リソース識別サフィックス。これは、リソースの種類を識別する文字列です。 この値を構成することはできません。

Note

Kubernetes のバージョンによって、リソース名の長さの制限が異なります。 リソース名の長さの制限は、インストール名の長さとリソース識別サフィックスの長さを追加することによって計算されます。 リソース名が予約された長さを超える場合は、エラーが発生します。

gha-runner-scale-set-controller に配置されたリソース

Templateリソースの種類Name予約された長さ説明メモ
deployment.yaml展開INSTALLATION_NAME-gha-rs-controller18controller-manager を実行しているリソースこのリソースによって作成されたポッドには、ReplicaSet サフィックスとポッド サフィックスがあります。
serviceaccount.yamlServiceAccountINSTALLATION_NAME-gha-rs-controller18これは values.yaml の serviceAccount.create が真に設定されている場合に作成されます。名前は values.yaml でカスタマイズできます
manager_cluster_role.yamlClusterRoleINSTALLATION_NAME-gha-rs-controller18コントローラー マネージャーの ClusterRoleこれは flags.watchSingleNamespace の値が空の場合に作成されます。
manager_cluster_role_binding.yamlClusterRoleBindingINSTALLATION_NAME-gha-rs-controller18コントローラー マネージャーの ClusterRoleBindingこれは flags.watchSingleNamespace の値が空の場合に作成されます。
manager_single_namespace_controller_role.yamlロールINSTALLATION_NAME-gha-rs-controller-single-namespace35コントローラー マネージャーの役割これは、flags.watchSingleNamespace の値が設定されている場合に作成されます。
manager_single_namespace_controller_role_binding.yamlRoleBindingINSTALLATION_NAME-gha-rs-controller-single-namespace35コントローラー マネージャーの RoleBindingこれは、flags.watchSingleNamespace の値が設定されている場合に作成されます。
manager_single_namespace_watch_role.yamlロールINSTALLATION_NAME-gha-rs-controller-single-namespace-watch41構成された名前空間のコントローラー マネージャーのロールこれは、flags.watchSingleNamespace の値が設定されている場合に作成されます。
manager_single_namespace_watch_role_binding.yamlRoleBindingINSTALLATION_NAME-gha-rs-controller-single-namespace-watch41構成された名前空間のコントローラー マネージャーの RoleBindingこれは、flags.watchSingleNamespace の値が設定されている場合に作成されます。
manager_listener_role.yamlロールINSTALLATION_NAME-gha-rs-controller-listener26聞き手の役割これは常に作成されます。
manager_listener_role_binding.yaml RoleBindingINSTALLATION_NAME-gha-rs-controller-listener26リスナーの RoleBindingこれは常に作成され、serviceaccount.yaml で作成されるか values.yaml で設定されるサービスアカウントとリスナーロールをバインドします。

gha-runner-scale-set に配置されたリソース

Templateリソースの種類Name予約された長さ説明メモ
autoscalingrunnerset.yamlAutoscalingRunnerSetINSTALLATION_NAME0スケール セットを使用する最上位レベルのリソース名前の長さは45文字以内です。
no_permission_service_account.yamlServiceAccountINSTALLATION_NAME-gha-rs-no-permission21ランナー コンテナーにマウントされたサービス アカウントコンテナモードが「kubernetes」でなく、template.spec.serviceAccountName が指定されていない場合に作成されます。
githubsecret.yamlSecretINSTALLATION_NAME-gha-rs-github-secret20GitHub API に対する認証に必要な値を含むシークレットこれは githubConfigSecret がオブジェクトの場合に作成されます。 文字列が指定されている場合、このシークレットは作成されません。
manager_role.yamlロールINSTALLATION_NAME-gha-rs-manager15自動スケール ランナー セットの名前空間内のリソースを調整できるようにするためにマネージャーに提供されるロールこれは常に作成されます。
manager_role_binding.yamlRoleBindingINSTALLATION_NAME-gha-rs-manager15manager_roleをマネージャー サービス アカウントにバインドします。これは常に作成されます。
kube_mode_role.yamlロールINSTALLATION_NAME-gha-rs-kube-mode17フックに必要なアクセス許可を提供するロールこれは、コンテナ モードが「kubernetes」に設定され、template.spec.serviceAccount が提供されていない場合に作成されます。
kube_mode_serviceaccount.yamlServiceAccountINSTALLATION_NAME-gha-rs-kube-mode17ランナー ポッドにバインドされたサービス アカウント。これは、コンテナ モードが「kubernetes」に設定され、template.spec.serviceAccount が提供されていない場合に作成されます。

カスタム リソースについて

ARC は、いくつかのカスタム リソース定義 (CRD) で構成されます。 カスタム リソースの詳細については、Kubernetes ドキュメントの「Custom Resources (カスタム リソース)」を参照してください。 ARC に使用されるカスタム リソース定義の一覧については、次の API スキーマ定義を参照してください。

カスタム リソースは Kubernetes API の拡張機能であるため、既定の Kubernetes インストールでは使用できません。 ARC を使用するには、これらのカスタム リソースをインストールする必要があります。 カスタム リソースのインストールの詳細については、「アクション ランナー コントローラーのクイック スタート」を参照してください。

カスタム リソースがインストールされたら、Kubernetes クラスターに ARC をデプロイできます。 ARC の配置については、「アクション ランナー コントローラーを使用してランナー スケール セットをデプロイする」を参照してください。

ランナー コンテナー イメージについて

GitHub では、最小限のランナー コンテナー イメージが保持されます。 ランナー バイナリがリリースされるたびに、新しいイメージが発行されます。 最新のイメージには、ランナー バイナリのバージョンと latest タグが含まれます。

このイメージには、コンテナー ランタイムとランナー バイナリに必要な最小量のパッケージが含まれています。 追加のソフトウェアをインストールするには、独自のランナー イメージを作成します。 ARC のランナー イメージをベースとして使用することも、対応するセットアップ アクションを使用することもできます。 たとえば、Java の場合は actions/setup-java、Node の場合は actions/setup-node です。

ARC のランナー イメージの定義はこちらの Dockerfile に、基本イメージの定義はこちらの Dockerfile にあります。

独自のランナー イメージの作成

要件を満たす独自のランナー イメージを作成できます。 ランナー イメージは、以下の条件を満たしている必要があります。

次の Dockerfile の例を使用して、独自のランナー イメージの作成を開始できます。

Dockerfile
FROM mcr.microsoft.com/dotnet/runtime-deps:6.0 as build

# Replace value with the latest runner release version
# source: https://github.com/actions/runner/releases
# ex: 2.303.0
ARG RUNNER_VERSION=""
ARG RUNNER_ARCH="x64"
# Replace value with the latest runner-container-hooks release version
# source: https://github.com/actions/runner-container-hooks/releases
# ex: 0.3.1
ARG RUNNER_CONTAINER_HOOKS_VERSION=""

ENV DEBIAN_FRONTEND=noninteractive
ENV RUNNER_MANUALLY_TRAP_SIG=1
ENV ACTIONS_RUNNER_PRINT_LOG_TO_STDOUT=1

RUN apt update -y && apt install curl unzip -y

RUN adduser --disabled-password --gecos "" --uid 1001 runner \
    && groupadd docker --gid 123 \
    && usermod -aG sudo runner \
    && usermod -aG docker runner \
    && echo "%sudo ALL=(ALL:ALL) NOPASSWD:ALL" > /etc/sudoers \
    && echo "Defaults env_keep += \"DEBIAN_FRONTEND\"" >> /etc/sudoers

WORKDIR /home/runner

RUN curl -f -L -o runner.tar.gz https://github.com/actions/runner/releases/download/v${RUNNER_VERSION}/actions-runner-linux-${RUNNER_ARCH}-${RUNNER_VERSION}.tar.gz \
    && tar xzf ./runner.tar.gz \
    && rm runner.tar.gz

RUN curl -f -L -o runner-container-hooks.zip https://github.com/actions/runner-container-hooks/releases/download/v${RUNNER_CONTAINER_HOOKS_VERSION}/actions-runner-hooks-k8s-${RUNNER_CONTAINER_HOOKS_VERSION}.zip \
    && unzip ./runner-container-hooks.zip -d ./k8s \
    && rm runner-container-hooks.zip

USER runner

ワークフローの実行

インストールと構成が完了したら、ARC を使用してワークフローを実行できます。 ワークフローは、ARC によって作成されたセルフホステッド ランナーをターゲットにできる同じリポジトリに作成できます。 自己ホストランナー上で実行するワークフローのターゲット設定の詳細については、「ワークフローでのセルフホストランナーの利用」を参照してください。

ワークフローでの ARC ランナーの使用

ARC によって作成されたランナーをターゲットにするのに追加のラベルを使用することはできません。 できるのは、インストール時に指定したランナー スケール セットのインストール名を使用するか、values.yaml ファイル内に runnerScaleSetName フィールドの値を定義することだけです。 これらは、runs-on ターゲットとして使用する "単一ラベル" として使用されます。詳細については、「ワークフローでの Actions Runner Controller の使用」を参照してください。

ランナーのスケーリング

ランナーは、ニーズに応じて静的または動的にスケーリングできます。 詳しくは、「アクション ランナー コントローラーを使用してランナー スケール セットをデプロイする」をご覧ください。

ARC ランナー イメージにインストールされているソフトウェア

ARC ランナー イメージには、以下のソフトウェアがバンドルされています:

詳細については、アクション リポジトリの ARC のランナー イメージ Dockerfile に関するページを参照してください。

アセットと解放

ARC は、2 つの Helm チャートと 1 つのコンテナー イメージとしてリリースされます。 Helm チャートは、Open Container Initiative (OCI) パッケージとしてのみ発行されます。 ARC は、GitHub Pages を介して tarball または Helm リポジトリを提供しません。

ARC の Helm チャートとコンテナー イメージの最新リリースは、GitHub Packages にあります:

サポートされているランナー・イメージは、別のコンテナ・イメージとしてリリースされており、GitHub Packages の actions-runner で見つけることができます。

Apache-2.0 ライセンスのもとで https://github.com/actions/actions-runner-controller/ から一部を引用しています。

Copyright 2019 Moto Ishizawa

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.