Actions Runner Controller について

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

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

次の図は、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 の例を使用して、独自のランナーイメージの作成を開始できます。

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 にあります:

サポートされているランナー・イメージは、別のコンテナ・イメージとしてリリースされており、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.

Actions Runner Controller について

この記事の内容