Actions Runner Controller について
Actions Runner Controller (ARC) は、GitHub Actions のセルフホステッド ランナーを調整およびスケーリングする Kubernetes オペレーターです。 詳細については、Kubernetes ドキュメントの「オペレーター パターン」を参照してください。
ARC を使うと、リポジトリ、組織、またはエンタープライズで実行中のワークフローの数に基づいて自動的にスケーリングされるランナー スケール セットを作成できます。 制御されたランナーは一時的でコンテナーに基づく可能性があるため、新しいランナー インスタンスを迅速かつクリーンにスケールアップまたはスケールダウンすることができます。 自動スケーリングについて詳しくは、「セルフホステッド ランナーによる自動スケーリング」をご覧ください。
次の図は、ARC の自動スケール ランナー スケールセット モードのアーキテクチャを示しています。
注: 次の図をより大きなサイズで表示するには、アクション ランナー コントローラー リポジトリの「自動スケール ランナー スケール セット モード」のドキュメントを参照してください。
- Actions Runner Controller は提供された Helm チャートを使用してインストールされ、コントローラー マネージャー ポッドは指定された名前空間にデプロイされます。 新しい AutoScalingRunnerSet リソースは、提供された Helm チャートまたはカスタマイズされたマニフェスト ファイルを使用してデプロイされます。 AutoScalingRunnerSet コントローラーでは GitHub の API を呼び出して、ランナー スケール セットが属するランナー グループ ID をフェッチします。
- AutoScalingRunnerSet コントローラーでは、ランナー スケール セット リスナー リソースを作成する前に、もう 1 回 API を呼び出して、GitHub Actions サービスでランナー スケール セットをフェッチまたは作成します。
- ランナー スケールセット リスナー ポッドは、AutoScalingListener コントローラーによってデプロイされます。 このポッドで、リスナー アプリケーションは GitHub Actions サービスに接続して、HTTPS の長いポーリング接続を認証して確立します。 リスナーは、GitHub Actions サービスから
Job Available
メッセージを受信するまでアイドル状態のままになります。 - リポジトリからワークフロー実行がトリガーされると、GitHub Actions サービスによって、個々のジョブ実行がランナーまたはランナー スケールセットにディスパッチされます。ここで、
runs-on
キーはランナー スケールセットの名前またはセルフホステッド ランナーのラベルと一致します。 - ランナー スケールセット リスナーでは、
Job Available
メッセージを受信すると、必要な数にスケールアップできるかどうかを確認します。 できる場合、ランナー スケールセット リスナーではメッセージの受信確認を行います。 - ランナー スケールセット リスナーでは、サービス アカウントとそのアカウントにバインドされたロールを使用して、Kubernetes API を介して HTTPS 呼び出しを行い、必要なレプリカ数でエフェメラル RunnerSet リソースにパッチを適用します。
- エフェメラル RunnerSet では新しいランナーの作成を試み、EphemeralRunner コントローラーでは Just-In-Time (JIT) 構成トークンを要求してこれらのランナーを登録します。 コントローラーではランナー ポッドの作成を試みます。 ポッドの状態が
failed
の場合、コントローラーでは最大 5 回再試行します。 24 時間後、GitHub Actions サービスでは、ランナーがジョブが受け入れない場合、その割り当てを解除します。 - ランナー ポッドが作成されたら、ポッド内のランナー アプリケーションでは JIT 構成トークンを使用して、自身を GitHub Actions サービスに登録します。 その後、別の HTTPS の長いポーリング接続を確立して、実行する必要があるジョブの詳細を受け取ります。
- GitHub Actions サービスではランナー登録の受信確認を行い、ジョブ実行の詳細をディスパッチします。
- ジョブの実行全体を通じて、ランナーにより、ログとジョブの実行状態が GitHub Actions サービスに継続的に伝達されます。
- ランナーで正常にジョブが完了すると、EphemeralRunner コントローラーでは GitHub Actions サービスを使用して、ランナーを削除できるかどうかを確認します。 できる場合は、エフェメラル RunnerSet によってランナーが削除されます。
Actions Runner Controller コンポーネント
ARC は一連のリソースで構成され、その一部は ARC 専用に作成されます。 ARC の展開により、これらのカスタム リソースが Kubernetes クラスターに適用されます。 これが適用されると、セルフホステッド ランナーのコンテナーを含むポッドのセットが作成されます。 ARC を使用すると、GitHub は、これらのランナー コンテナーをセルフホステッド ランナーとして扱い、必要に応じてジョブを割り当てることができます。
ARC によってデプロイされる各リソースには、次で構成される名前が付けられます:
- インストール名。これは、Helm チャートをインストールするときに指定するインストール名です。
- リソース識別サフィックス。これは、リソースの種類を識別する文字列です。 この値を構成することはできません。
注: Kubernetes のバージョンによって、リソース名の長さの制限が異なります。 リソース名の長さの制限は、インストール名の長さとリソース識別サフィックスの長さを追加することによって計算されます。 リソース名が予約された長さを超える場合は、エラーが発生します。
gha-runner-scale-set-controller
に配置されたリソース
Template | リソースの種類 | 名前 | 予約された長さ | 説明 | メモ |
---|---|---|---|---|---|
deployment.yaml | 展開 | INSTALLATION_NAME-gha-rs-controller | 18 | controller-manager を実行しているリソース | このリソースによって作成されたポッドには、ReplicaSet サフィックスとポッド サフィックスがあります。 |
serviceaccount.yaml | ServiceAccount | INSTALLATION_NAME-gha-rs-controller | 18 | これは values.yaml の serviceAccount.create が真に設定されている場合に作成されます。 | 名前は values.yaml でカスタマイズできます |
manager_cluster_role.yaml | ClusterRole | INSTALLATION_NAME-gha-rs-controller | 18 | コントローラー マネージャーの ClusterRole | これは flags.watchSingleNamespace の値が空の場合に作成されます。 |
manager_cluster_role_binding.yaml | ClusterRoleBinding | INSTALLATION_NAME-gha-rs-controller | 18 | コントローラー マネージャーの ClusterRoleBinding | これは flags.watchSingleNamespace の値が空の場合に作成されます。 |
manager_single_namespace_controller_role.yaml | ロール | INSTALLATION_NAME-gha-rs-controller-single-namespace | 35 | コントローラー マネージャーの役割 | これは、flags.watchSingleNamespace の値が設定されている場合に作成されます。 |
manager_single_namespace_controller_role_binding.yaml | RoleBinding | INSTALLATION_NAME-gha-rs-controller-single-namespace | 35 | コントローラー マネージャーの RoleBinding | これは、flags.watchSingleNamespace の値が設定されている場合に作成されます。 |
manager_single_namespace_watch_role.yaml | ロール | INSTALLATION_NAME-gha-rs-controller-single-namespace-watch | 41 | 構成された名前空間のコントローラー マネージャーのロール | これは、flags.watchSingleNamespace の値が設定されている場合に作成されます。 |
manager_single_namespace_watch_role_binding.yaml | RoleBinding | INSTALLATION_NAME-gha-rs-controller-single-namespace-watch | 41 | 構成された名前空間のコントローラー マネージャーの RoleBinding | これは、flags.watchSingleNamespace の値が設定されている場合に作成されます。 |
manager_listener_role.yaml | ロール | INSTALLATION_NAME-gha-rs-controller-listener | 26 | 聞き手の役割 | これは常に作成されます。 |
manager_listener_role_binding.yaml | RoleBinding | INSTALLATION_NAME-gha-rs-controller-listener | 26 | リスナーの RoleBinding | これは常に作成され、serviceaccount.yaml で作成されるか values.yaml で設定されるサービスアカウントとリスナーロールをバインドします。 |
gha-runner-scale-set
に配置されたリソース
Template | リソースの種類 | 名前 | 予約された長さ | 説明 | メモ |
---|---|---|---|---|---|
autoscalingrunnerset.yaml | AutoscalingRunnerSet | INSTALLATION_NAME | 0 | スケール セットを使用する最上位レベルのリソース | 名前の長さは45文字以内です。 |
no_permission_service_account.yaml | ServiceAccount | INSTALLATION_NAME-gha-rs-no-permission | 21 | ランナー コンテナーにマウントされたサービス アカウント | コンテナモードが「kubernetes」でなく、template.spec.serviceAccountName が指定されていない場合に作成されます。 |
githubsecret.yaml | Secret | INSTALLATION_NAME-gha-rs-github-secret | 20 | GitHub API に対する認証に必要な値を含むシークレット | これは githubConfigSecret がオブジェクトの場合に作成されます。 文字列が指定されている場合、このシークレットは作成されません。 |
manager_role.yaml | ロール | INSTALLATION_NAME-gha-rs-manager | 15 | 自動スケール ランナー セットの名前空間内のリソースを調整できるようにするためにマネージャーに提供されるロール | これは常に作成されます。 |
manager_role_binding.yaml | RoleBinding | INSTALLATION_NAME-gha-rs-manager | 15 | manager_roleをマネージャー サービス アカウントにバインドします。 | これは常に作成されます。 |
kube_mode_role.yaml | ロール | INSTALLATION_NAME-gha-rs-kube-mode | 17 | フックに必要なアクセス許可を提供するロール | これは、コンテナ モードが「kubernetes」に設定され、template.spec.serviceAccount が提供されていない場合に作成されます。 |
kube_mode_serviceaccount.yaml | ServiceAccount | INSTALLATION_NAME-gha-rs-kube-mode | 17 | ランナー ポッドにバインドされたサービス アカウント。 | これは、コンテナ モードが「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 にあります。
独自のランナー イメージの作成
要件を満たす独自のランナー イメージを作成できます。 ランナー イメージは、以下の条件を満たしている必要があります。
- セルフホステッド ランナー アプリケーションを実行できる基本イメージを使用します。 詳しくは、「自己ホスト ランナーの概要」を参照してください。
- ランナー バイナリを
/home/runner/
の下に配置し、/home/runner/run.sh
を使用して起動する必要があります。 - Kubernetes モードを使用する場合は、ランナー コンテナー フックを
/home/runner/k8s
の下に配置する必要があります。
次の 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
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 ランナー イメージには、以下のソフトウェアがバンドルされています:
- ランナー バイナリ
- ランナー コンテナー フック
- Docker (Docker-in-Docker モードに必要)
詳細については、アクション リポジトリの ARC のランナー イメージ Dockerfile に関するページを参照してください。
アセットと解放
ARC は、2 つの Helm チャートと 1 つのコンテナー イメージとしてリリースされます。 Helm チャートは、Open Container Initiative (OCI) パッケージとしてのみ発行されます。 ARC は、GitHub Pages を介して tarball または Helm リポジトリを提供しません。
ARC の Helm チャートとコンテナー イメージの最新リリースは、GitHub Packages にあります:
gha-runner-scale-set-controller
Helm チャートgha-runner-scale-set
Helm チャートgha-runner-scale-set-controller
コンテナー イメージ
サポートされているランナー・イメージは、別のコンテナ・イメージとしてリリースされており、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.