Quickstart for Actions Runner Controller

Introduction

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

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

You can set up ARC on Kubernetes using Helm, then create and run a workflow that uses runner scale sets. For more information about runner scale sets, see Actions Runner Controller를 사용하여 실행기 확장 집합 배포.

Prerequisites

In order to use ARC, ensure you have the following.

A Kubernetes cluster
- For a managed cloud environment, you can use AKS. For more information, see Azure Kubernetes Service in the Azure documentation.
- For a local setup, you can use minikube or kind. For more information, see minikube start in the minikube documentation and kind in the kind documentation.
  
  참고 항목
  
  OpenShift clusters are currently unsupported.
Helm 3
- For more information, see Installing Helm in the Helm documentation.
While it is not required for ARC to be deployed, we recommend ensuring you have implemented a way to collect and retain logs from the controller, listeners, and ephemeral runners before deploying ARC in production workflows.

Installing Actions Runner Controller

To install the operator and the custom resource definitions (CRDs) in your cluster, do the following.
1. In your Helm chart, update the NAMESPACE value to the location you want your operator pods to be created. This namespace must allow access to the Kubernetes API server.
2. Install the Helm chart.
The following example installs the latest version of the chart. To install a specific version, you can pass the --version argument along with the version of the chart you wish to install. You can find the list of releases in the GitHub Container Registry.
Bash
```
NAMESPACE="arc-systems"
helm install arc \
    --namespace "${NAMESPACE}" \
    --create-namespace \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller
```
```
NAMESPACE="arc-systems"
helm install arc \
    --namespace "${NAMESPACE}" \
    --create-namespace \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller
```
For additional Helm configuration options, see values.yaml in the ARC documentation.
To enable ARC to authenticate to GitHub, generate a personal access token (classic). For more information, see GitHub API에 인증.

Configuring a runner scale set

To configure your runner scale set, run the following command in your terminal, using values from your ARC configuration.

When you run the command, keep the following in mind.
- Update the INSTALLATION_NAME value carefully. You will use the installation name as the value of runs-on in your workflows. For more information, see GitHub Actions에 대한 워크플로 구문.
- Update the NAMESPACE value to the location you want the runner pods to be created.
- Set GITHUB_CONFIG_URL to the URL of your repository, organization, or enterprise. This is the entity that the runners will belong to.
- This example command installs the latest version of the Helm chart. To install a specific version, you can pass the --version argument with the version of the chart you wish to install. You can find the list of releases in the GitHub Container Registry.
  참고 항목
  - 보안을 위해 실행기 포드는 운영자 포드가 있는 네임스페이스가 아닌 다른 네임스페이스에 만듭니다.
  - 보안을 위해 Kubernetes 비밀을 만들고 비밀 참조를 전달합니다. 비밀을 CLI에서 일반 텍스트로 전달하면 보안 위험이 발생할 수 있습니다. For more information, see Actions Runner Controller를 사용하여 실행기 확장 집합 배포.
  Bash
```
INSTALLATION_NAME="arc-runner-set"
NAMESPACE="arc-runners"
GITHUB_CONFIG_URL="http://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
```
```
INSTALLATION_NAME="arc-runner-set"
NAMESPACE="arc-runners"
GITHUB_CONFIG_URL="http://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
```
  For additional Helm configuration options, see values.yaml in the ARC documentation.

From your terminal, run the following command to check your installation.

Bash

helm list -A

helm list -A

You should see an output similar to the following.

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

To check the manager pod, run the following command in your terminal.

Bash

kubectl get pods -n arc-systems

kubectl get pods -n arc-systems

If everything was installed successfully, the status of the pods shows as 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

If your installation was not successful, see Actions Runner Controller 오류 문제 해결 for troubleshooting information.

Using runner scale sets

Now you will create and run a simple test workflow that uses the runner scale set runners.

In a repository, create a workflow similar to the following example. The runs-on value should match the Helm installation name you used when you installed the autoscaling runner set.

For more information on adding workflows to a repository, see GitHub Actions용 빠른 시작.

YAML

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!"

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!"

Once you've added the workflow to your repository, manually trigger the workflow. For more information, see 워크플로 수동 실행.

To view the runner pods being created while the workflow is running, run the following command from your terminal.

Bash

kubectl get pods -n arc-runners

kubectl get pods -n arc-runners

A successful output will look similar to the following.

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

Next steps

Actions Runner Controller can help you efficiently manage your GitHub Actions runners. Ready to get started? Here are some helpful resources for taking your next steps with ARC:

For detailed authentication information, see GitHub API에 인증.
For help using ARC runners in your workflows, see 워크플로에서 Actions Runner Controller 실행기 사용.
For deployment information, see Actions Runner Controller를 사용하여 실행기 확장 집합 배포.

Legal notice

다음은 Apache-2.0 라이선스에서 http://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.

이 문서의 내용