Actions Runner Controller 시작하기

이 튜토리얼에서는 Actions Runner Controller(ARC)의 기본을 직접 체험해 볼 거예요. Kubernetes에서 GitHub Actions 러너를 효율적으로 관리하는 방법을 배울 수 있어요.

출처: 문서

본문

Prerequisites

ARC를 사용하려면 다음이 준비되어 있는지 확인하세요.

Kubernetes 클러스터
- 관리형 클라우드 환경에서는 AKS를 사용할 수 있어요. 자세한 내용은 Azure 문서의 Azure Kubernetes Service를 참고하세요.
- 로컬 설정에서는 minikube 또는 kind를 사용할 수 있어요. 자세한 내용은 minikube 문서의 minikube start와 kind 문서의 kind를 참고하세요.
Helm 3
- 자세한 내용은 Helm 문서의 Installing Helm을 참고하세요.
ARC 배포에 필수는 아니지만, 프로덕션 워크플로우에 ARC를 배포하기 전에 컨트롤러, 리스너, 임시 러너에서 로그를 수집하고 보존하는 방법을 구현했는지 확인하는 것이 좋아요.

Installing Actions Runner Controller

클러스터에 운영자(operator)와 사용자 정의 리소스 정의(CRD)를 설치하려면 다음을 수행하세요.
1. Helm 차트에서 NAMESPACE 값을 운영자 파드가 생성되기를 원하는 위치로 업데이트하세요. 이 네임스페이스는 Kubernetes API 서버에 대한 접근을 허용해야 해요.
2. Helm 차트를 설치하세요.
다음 예시는 차트의 최신 버전을 설치해요. 특정 버전을 설치하려면 설치하려는 차트 버전과 함께 --version 인수를 전달할 수 있어요. 릴리스 목록은 GitHub Container Registry에서 찾을 수 있어요.
```
NAMESPACE="arc-systems"
helm install arc \
    --namespace "${NAMESPACE}" \
    --create-namespace \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller
```
추가 Helm 구성 옵션은 ARC 문서의 values.yaml을 참고하세요.
ARC가 GitHub에 인증할 수 있게 하려면 러너 스케일 세트에 대한 인증 방법을 선택하세요. 저장소 또는 조직 수준에서 러너를 등록한다면 GitHub App으로 인증하는 것이 좋아요. 엔터프라이즈 수준에서 등록된 러너 스케일 세트는 personal access token(classic) 인증이 필요해요. 자세한 내용은 Authenticating ARC to the GitHub API 문서를 참고하세요.

Configuring a runner scale set

러너 스케일 세트를 구성하려면 ARC 구성의 값을 사용해서 터미널에서 다음 명령을 실행하세요.

명령을 실행할 때 다음 사항을 염두에 두세요.
- INSTALLATION_NAME 값을 신중하게 업데이트하세요. 워크플로우에서 runs-on의 값으로 설치 이름을 사용할 거예요. 자세한 내용은 Workflow syntax for GitHub Actions 문서를 참고하세요.
- 러너 파드가 생성되기를 원하는 위치로 NAMESPACE 값을 업데이트하세요.
- GITHUB_CONFIG_URL을 저장소, 조직 또는 엔터프라이즈의 URL로 설정하세요. 이것이 러너가 속하게 될 엔터티예요.
- 이 예시는 초기 설정을 짧게 유지하기 위해 personal access token(classic)을 사용해요. 저장소 또는 조직 러너 스케일 세트의 경우 가능하면 프로덕션 환경에서 GitHub App을 사용하세요.
- 저장소 및 조직 러너의 경우 GITHUB_PAT을 repo 및 admin:org 스코프가 있는 GitHub personal access token(classic)으로 설정하세요.
- 이 예시 명령은 Helm 차트의 최신 버전을 설치해요. 특정 버전을 설치하려면 설치하려는 차트 버전과 함께 --version 인수를 전달할 수 있어요. 릴리스 목록은 GitHub Container Registry에서 찾을 수 있어요.
  [!NOTE]
  - 보안 모범 사례로, 운영자 파드를 포함하는 네임스페이스와 다른 네임스페이스에 러너 파드를 만드세요.
  - 보안 모범 사례로, Kubernetes secret을 만들고 secret 참조를 전달하세요. CLI를 통해 secret을 일반 텍스트로 전달하면 보안 위험이 될 수 있어요. 자세한 내용은 Deploying runner scale sets with Actions Runner Controller 문서를 참고하세요.
```
INSTALLATION_NAME="arc-runner-set"
NAMESPACE="arc-runners"
GITHUB_CONFIG_URL="https://github.com/<your_enterprise/org/repo>"
GITHUB_PAT="<PAT>"
helm install "${INSTALLATION_NAME}" \
    --namespace "${NAMESPACE}" \
    --create-namespace \
    --set githubConfigUrl="${GITHUB_CONFIG_URL}" \
    --set githubConfigSecret.github_token="${GITHUB_PAT}" \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set
```
  추가 Helm 구성 옵션은 ARC 문서의 values.yaml을 참고하세요.

터미널에서 다음 명령을 실행해서 설치를 확인하세요.

helm list -A

다음과 유사한 출력이 보여야 해요.

NAME            NAMESPACE       REVISION        UPDATED                                 STATUS          CHART                                       APP VERSION
arc             arc-systems     1               2023-04-12 11:45:59.152090536 +0000 UTC deployed        gha-runner-scale-set-controller-0.4.0       0.4.0
arc-runner-set  arc-runners     1               2023-04-12 11:46:13.451041354 +0000 UTC deployed        gha-runner-scale-set-0.4.0                  0.4.0

매니저 파드를 확인하려면 터미널에서 다음 명령을 실행하세요.

kubectl get pods -n arc-systems

모든 것이 성공적으로 설치되었다면 파드의 상태가 Running으로 표시돼요.

NAME                                                   READY   STATUS    RESTARTS   AGE
arc-gha-runner-scale-set-controller-594cdc976f-m7cjs   1/1     Running   0          64s
arc-runner-set-754b578d-listener                       1/1     Running   0          12s

설치가 성공하지 않았다면 트러블슈팅 정보는 Troubleshooting Actions Runner Controller errors 문서를 참고하세요.

Using runner scale sets

이제 러너 스케일 세트 러너를 사용하는 간단한 테스트 워크플로우를 만들고 실행해 볼 거예요.

저장소에서 다음 예시와 유사한 워크플로우를 만드세요. runs-on 값은 자동 확장 러너 세트를 설치할 때 사용한 Helm 설치 이름과 일치해야 해요.

저장소에 워크플로우를 추가하는 방법에 대한 자세한 내용은 Quickstart for GitHub Actions 문서를 참고하세요.
```
name: Actions Runner Controller Demo
on:
  workflow_dispatch:

jobs:
  Explore-GitHub-Actions:
    # You need to use the INSTALLATION_NAME from the previous step
    runs-on: arc-runner-set
    steps:
    - run: echo "🎉 This job uses runner scale set runners!"
```
워크플로우를 저장소에 추가한 후 워크플로우를 수동으로 트리거하세요. 자세한 내용은 Manually running a workflow 문서를 참고하세요.

워크플로우가 실행되는 동안 생성되는 러너 파드를 보려면 터미널에서 다음 명령을 실행하세요.

kubectl get pods -n arc-runners -w

성공적인 출력은 다음과 유사해요.

NAMESPACE     NAME                                                  READY   STATUS    RESTARTS      AGE
arc-runners   arc-runner-set-rmrgw-runner-p9p5n                     1/1     Running   0             21s

Next steps

Actions Runner Controller는 GitHub Actions 러너를 효율적으로 관리하는 데 도움을 줄 수 있어요. 시작할 준비가 되셨나요? ARC로 다음 단계를 진행하기 위한 유용한 리소스는 다음과 같아요.

자세한 인증 정보는 Authenticating ARC to the GitHub API 문서를 참고하세요.
워크플로우에서 ARC 러너를 사용하는 데 도움이 필요하면 Using Actions Runner Controller runners in a workflow 문서를 참고하세요.
배포 정보는 Deploying runner scale sets with Actions Runner Controller 문서를 참고하세요.

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.

Actions Runner Controller 시작하기