Actions Runner Controller 정보

법적 고지

Actions Runner Controller 정보

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

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

다음 다이어그램에서는 ARC의 자동 스케일링 실행기 ScaleSet 모드의 아키텍처를 보여 줍니다.

1. Actions Runner Controller은(는) 제공된 Helm 차트를 사용하여 설치되고 컨트롤러 관리자 Pod는 지정된 네임스페이스에 배포됩니다. 새로운 AutoScalingRunnerSet 리소스는 제공된 Helm 차트 또는 사용자 지정된 매니페스트 파일을 통해 배포됩니다. AutoScalingRunnerSet 컨트롤러는 GitHub의 API를 호출하여 실행기 확장 집합이 속할 실행기 그룹 ID를 가져옵니다.
2. AutoScalingRunnerSet 컨트롤러는 Runner ScaleSet 수신기 리소스를 만들기 전에 GitHub Actions 서비스에서 실행기 확장 집합을 가져오거나 만들기 위해 API를 한 번 더 호출합니다.
3. Runner ScaleSet 수신기 Pod는 AutoScalingListener 컨트롤러에 의해 배포됩니다. 이 Pod에서 수신기 애플리케이션은 GitHub Actions 서비스에 연결하여 HTTPS 롱 폴 연결을 인증하고 설정합니다. 수신기는 GitHub Actions 서비스에서 Job Available 메시지를 받을 때까지 유휴 상태로 유지됩니다.
4. 워크플로 실행이 리포지토리에서 트리거되면 GitHub Actions 서비스는 runs-on 키가 실행기 확장 집합의 이름 또는 자체 호스팅 실행기의 레이블과 일치하는 실행기 또는 실행기 확장 집합에 개별 작업 실행을 디스패치합니다.
5. Runner ScaleSet 수신기가 Job Available 메시지를 받으면 원하는 개수까지 확장할 수 있는지 여부를 검사합니다. 가능하다고 확인되면 Runner ScaleSet 수신기가 메시지를 승인합니다.
6. Runner ScaleSet 수신기는 서비스 계정 및 해당 계정에 바인딩된 역할을 사용하여 Kubernetes API를 통해 HTTPS 호출을 수행하고 필요한 복제본(replica) 개수로 Ephemeral RunnerSet 리소스를 패치합니다.
7. Ephemeral RunnerSet은 새 실행기를 만들려고 시도하고 EphemeralRunner 컨트롤러는 이러한 실행기를 등록하기 위해 JIT(Just-In-Time) 구성 토큰을 요청합니다. 컨트롤러가 실행기 Pod를 만들려고 시도합니다. Pod의 상태가 failed인 경우 컨트롤러는 최대 5번 다시 시도합니다. 24시간 후에 GitHub Actions 서비스는 실행기가 작업을 수락하지 않으면 작업을 할당 취소합니다.
8. 실행기기 Pod가 만들어지면 Pod의 실행기 애플리케이션은 JIT 구성 토큰을 사용하여 GitHub Actions 서비스에 등록합니다. 그런 다음 다른 HTTPS 롱 폴 연결을 설정하여 실행해야 하는 작업 세부 정보를 받습니다.
9. GitHub Actions 서비스는 실행기 등록을 승인하고 작업 실행 세부 정보를 디스패치합니다.
10. 실행기는 작업 실행 동안 로그 및 작업 실행 상태를 GitHub Actions 서비스에 지속적으로 통신합니다.
11. 실행기가 작업을 성공적으로 완료하면 EphemeralRunner 컨트롤러는 GitHub Actions 서비스로 실행기를 삭제할 수 있는지 확인합니다. 가능한 경우 Ephemeral RunnerSet은 실행기를 삭제합니다.

Actions Runner Controller 구성 요소

ARC는 리소스 집합으로 구성되며, 그 중 일부는 ARC용으로 특별히 생성됩니다. ARC 배포는 이러한 리소스를 Kubernetes 클러스터에 적용합니다. 적용되면 자체 호스팅 실행기의 컨테이너를 포함하는 Pod 집합을 만듭니다. ARC를 사용하면 GitHub에서 이러한 실행기 컨테이너를 자체 호스팅 실행기로 처리하고 필요에 따라 작업을 할당할 수 있습니다.

ARC에서 배포하는 각 리소스에는 다음으로 구성된 이름이 지정됩니다.

• 설치 이름: Helm 차트를 설치할 때 지정하는 설치 이름입니다.
• 리소스 식별 접미사: 리소스 유형을 식별하는 문자열입니다. 이 값은 구성할 수 없습니다.

gha-runner-scale-set-controller에 의해 배포된 리소스

gha-runner-scale-set에 의해 배포된 리소스

사용자 지정 리소스 정보

ARC는 여러 CRD(사용자 지정 리소스 정의)로 구성됩니다. 사용자 지정 리소스에 대한 자세한 내용은 Kubernetes 설명서의 사용자 지정 리소스를 참조하세요. 다음 API 스키마 정의에서 ARC에 사용되는 사용자 지정 리소스 정의 목록을 찾을 수 있습니다.

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

사용자 지정 리소스는 Kubernetes API의 확장 프로그램이므로 기본 Kubernetes 설치에서는 사용할 수 없습니다. ARC를 사용하려면 이러한 사용자 지정 리소스를 설치해야 합니다. 사용자 지정 리소스 설치에 대한 자세한 내용은 "Actions Runner Controller에 대한 빠른 시작"을 참조하세요.

사용자 지정 리소스가 설치되면 Kubernetes 클러스터에 ARC를 배포할 수 있습니다. ARC 배포에 대한 자세한 내용은 "Actions Runner Controller를 사용하여 실행기 확장 집합 배포"을 참조하세요.

실행기 컨테이너 이미지 정보

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 실행기 사용"을 참조하세요.

실행기 크기 조정

필요에 따라 실행기를 정적으로 또는 동적으로 확장할 수 있습니다. 자세한 내용은 "Actions Runner Controller를 사용하여 실행기 확장 집합 배포"을 참조하세요.

ARC 실행기기 이미지에 설치된 소프트웨어

ARC 실행기 이미지는 다음 소프트웨어와 함께 번들로 제공됩니다.

• 실행기 이진 파일
• 실행기 컨테이너 후크
• Docker(Docker-in-Docker 모드에 필요)

자세한 내용은 작업 리포지토리에서 ARC의 실행기 이미지 Dockerfile 을 참조하세요.

자산 및 릴리스

ARC는 두 개의 Helm 차트와 하나의 컨테이너 이미지로 릴리스됩니다. Helm 차트는 OCI(Open Container Initiative) 패키지로만 게시됩니다. ARC는 GitHub Pages을(를) 통해 tarball 또는 Helm 리포지토리를 제공하지 않습니다.

GitHub Packages에서 ARC의 Helm 차트 및 컨테이너 이미지의 최신 릴리스를 찾을 수 있습니다.

• 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.