About Actions Runner Controller

Legal notice

About Actions Runner Controller

Actions Runner Controller (ARC)는 GitHub Actions에 대한 자체 호스트형 실행기를 오케스트레이션하고 스케일링하는 Kubernetes 연산자입니다. 자세한 내용은 Kubernetes 문서의 작동 패턴을 참조하세요.

ARC를 사용하면 리포지토리, 조직 또는 엔터프라이즈에서 실행되는 워크플로 수에 따라 오토스케일링되는 실행기 확장 집합을 만들 수 있습니다. 제어된 실행기가 임시 실행기이거나 컨테이너 기반일 수 있으므로, 새 실행기 인스턴스는 신속하고 명확하게 스케일 업 또는 스케일 다운할 수 있습니다. 오토스케일링에 대한 자세한 내용은 자체 호스트형 실행기로 자동 스케일링을(를) 참조하세요.

The following diagram illustrates the architecture of ARC's autoscaling runner scale set mode.

1. Actions Runner Controller is installed using the supplied Helm charts, and the controller manager pod is deployed in the specified namespace. A new AutoScalingRunnerSet resource is deployed via the supplied Helm charts or a customized manifest file. The AutoScalingRunnerSet Controller calls GitHub's APIs to fetch the runner group ID that the runner scale set will belong to.
2. The AutoScalingRunnerSet Controller calls the APIs one more time to either fetch or create a runner scale set in the GitHub Actions service before creating the Runner ScaleSet Listener resource.
3. A Runner ScaleSet Listener pod is deployed by the AutoScalingListener Controller. In this pod, the listener application connects to the GitHub Actions Service to authenticate and establish an HTTPS long poll connection. The listener stays idle until it receives a Job Available message from the GitHub Actions Service.
4. When a workflow run is triggered from a repository, the GitHub Actions Service dispatches individual job runs to the runners or runner scale sets where the runs-on key matches the name of the runner scale set or labels of self-hosted runners.
5. When the Runner ScaleSet Listener receives the Job Available message, it checks whether it can scale up to the desired count. If it can, the Runner ScaleSet Listener acknowledges the message.
6. The Runner ScaleSet Listener uses a Service Account and a Role bound to that account to make an HTTPS call through the Kubernetes APIs to patch the Ephemeral RunnerSet resource with the number of desired replicas count.
7. The Ephemeral RunnerSet attempts to create new runners and the EphemeralRunner Controller requests a Just-in-Time (JIT) configuration token to register these runners. The controller attempts to create runner pods. If the pod's status is failed, the controller retries up to 5 times. After 24 hours the GitHub Actions Service unassigns the job if no runner accepts it.
8. Once the runner pod is created, the runner application in the pod uses the JIT configuration token to register itself with the GitHub Actions Service. It then establishes another HTTPS long poll connection to receive the job details it needs to execute.
9. The GitHub Actions Service acknowledges the runner registration and dispatches the job run details.
10. Throughout the job run execution, the runner continuously communicates the logs and job run status back to the GitHub Actions Service.
11. When the runner completes its job successfully, the EphemeralRunner Controller checks with the GitHub Actions Service to see if runner can be deleted. If it can, the Ephemeral RunnerSet deletes the runner.

Actions Runner Controller components

ARC consists of a set of resources, some of which are created specifically for ARC. An ARC deployment applies these resources onto a Kubernetes cluster. Once applied, it creates a set of Pods that contain your self-hosted runners' containers. With ARC, GitHub can treat these runner containers as self-hosted runners and allocate jobs to them as needed.

Each resource that is deployed by ARC is given a name composed of:

• An installation name, which is the installation name you specify when you install the Helm chart.
• A resource identification suffix, which is a string that identifies the resource type. This value is not configurable.

Resources deployed by gha-runner-scale-set-controller

Resources deployed by gha-runner-scale-set

About custom resources

ARC consists of several custom resource definitions (CRDs). For more information on custom resources, see Custom Resources in the Kubernetes documentation. You can find the list of custom resource definitions used for ARC in the following API schema definitions.

• actions.github.com/v1alpha1
• actions.summerwind.net/v1alpha1

Because custom resources are extensions of the Kubernetes API, they won't be available in a default Kubernetes installation. You will need to install these custom resources to use ARC. For more information on installing custom resources, see Quickstart for Actions Runner Controller.

Once the custom resources are installed, you can deploy ARC into your Kubernetes cluster. For information about deploying ARC, see Actions Runner Controller를 사용하여 실행기 확장 집합 배포.

About the runner container image

GitHub maintains a minimal runner container image. A new image will be published with every runner binaries release. The most recent image will have the runner binaries version and latest as tags.

This image contains the least amount of packages necessary for the container runtime and the runner binaries. To install additional software, you can create your own runner image. You can use ARC's runner image as a base, or use the corresponding setup actions. For instance, actions/setup-java for Java or actions/setup-node for Node.

You can find the definition of ARC's runner image in this Dockerfile and the definition of the base image in this Dockerfile.

Creating your own runner image

You can create your own runner image that meets your requirements. Your runner image must fulfill the following conditions.

• Use a base image that can run the self-hosted runner application. For more information, see 자체 호스트형 실행기 관리.

• The runner binary must be placed under /home/runner/ and launched using /home/runner/run.sh.

• If you use Kubernetes mode, the runner container hooks must be placed under /home/runner/k8s.

You can use the following example Dockerfile to start creating your own runner image.

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

Executing workflows

After installation and configuration are complete, you can use ARC to execute workflow runs. A workflow can be created in the same repository that can target a self hosted runner created by ARC. For more information about targeting workflows to run on self-hosted runners, see 워크플로에서 자체 호스트형 실행기 사용.

Using ARC runners in a workflow

ARC에서 만든 실행기를 타겟팅하기 위해 데 추가 레이블을 사용할 수 없습니다. 설치 중에 지정한 실행기 확장 집합의 설치 이름을 사용하거나 values.yaml 파일의 runnerScaleSetName 필드 값을 정의하여 사용할 수 있습니다. 이러한 실행기는 runs-on 대상으로 사용할 '단일 레이블'로 사용됩니다. For more information, see 워크플로에서 Actions Runner Controller 실행기 사용.

Scaling runners

You can scale runners statically or dynamically depending on your needs. For more information, see Actions Runner Controller를 사용하여 실행기 확장 집합 배포.

Software installed in the ARC runner image

The ARC runner image is bundled with the following software:

• Runner binaries
• Runner container hooks
• Docker (required for Docker-in-Docker mode)

For more information, see ARC's runner image Dockerfile in the Actions repository.

Assets and releases

ARC is released as two Helm charts and one container image. The Helm charts are only published as Open Container Initiative (OCI) packages. ARC does not provide tarballs or Helm repositories via GitHub Pages.

You can find the latest releases of ARC's Helm charts and container image on GitHub Packages:

• gha-runner-scale-set-controller Helm chart
• gha-runner-scale-set Helm chart
• gha-runner-scale-set-controller container image

The supported runner image is released as a separate container image, which you can find at actions-runner on GitHub Packages.

Legal notice

다음은 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.