Actions Runner Controller 사용 실행기 Scale Set 배포

실행기 Scale Set 배포하기

ARC가 실행 중이어야 실행기 Scale Set를 배포할 수 있습니다. 자세한 내용은 Actions Runner Controller에 대한 빠른 시작을(를) 참조하세요.

ARC의 Helm 차트를 사용하거나 필요한 매니페스트를 배포함으로써 실행기 Scale Set를 배포할 수 있습니다. 특히 ARC를 사용한 경험이 없는 경우, ARC의 Helm 차트를 사용하는 것이 선호되는 방법입니다.

참고 항목

보안을 위해 실행기 포드는 운영자 포드가 있는 네임스페이스가 아닌 다른 네임스페이스에 만듭니다.
보안을 위해 Kubernetes 비밀을 만들고 비밀 참조를 전달합니다. 비밀을 CLI에서 일반 텍스트로 전달하면 보안 위험이 발생할 수 있습니다.
격리된 상태로 프로덕션 워크로드를 실행하는 것이 좋습니다. GitHub Actions 워크플로는 임의 코드를 실행하도록 설계되었으며 프로덕션 워크로드에 공유된 Kubernetes 클러스터를 사용하면 보안 위험이 발생할 수 있습니다.
컨트롤러, 수신기 및 임시 실행기에서 로그를 수집하고 유지하는 방법을 구현했는지 확인하세요.

ARC 구성의 값을 사용하여 터미널에서 다음 명령을 실행하여 실행기 Scale Set를 구성하세요.

명령을 실행할 때 다음 사항에 유의하세요.
- INSTALLATION_NAME 값을 신중하게 업데이트하세요. 워크플로의 runs-on 값으로 설치 이름을 사용하세요.
- NAMESPACE 값을 실행기 Pod를 만들려는 위치로 업데이트하세요.
- GITHUB_CONFIG_URL 값을 리포지토리, 조직 또는 기업의 URL로 설정하세요. 실행기가 속하게 될 엔터티입니다.
- 이 예시 명령은 Helm 차트의 최신 버전을 설치합니다. 설치하려는 차트 버전과 함께 --version 인수를 전달하여 특정 버전을 설치할 수 있습니다. actions-runner-controller 리포지토리에서 릴리스 목록을 찾을 수 있습니다.
  Bash
```
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
```
```
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을(를) 참조하세요.

터미널에서 다음 명령을 실행하여 설치를 검사하세요.

Bash

helm list -A

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-systems     1               2023-04-12 11:46:13.451041354 +0000 UTC deployed        gha-runner-scale-set-0.4.0                  0.4.0

터미널에서 다음 명령을 실행하여 관리자 Pod를 검사하세요.

Bash

kubectl get pods -n arc-systems

kubectl get pods -n arc-systems

설치에 성공하면 Pod에 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

설치에 성공하지 못한 경우 문제 해결을 위해 Actions Runner Controller 오류 문제 해결에서 참조하세요.

고급 구성 옵션 사용

ARC는 몇 가지 고급 구성 옵션을 제공합니다.

실행기 Scale Set 이름 구성하기

참고 항목

실행기 Scale Set 이름은 해당 이름이 속한 실행기 그룹 내에서 고유합니다. 다른 실행기 그룹에 속해 있어야 동일한 이름의 여러 실행기 Scale Set를 배포할 수 있습니다.

INSTALLATION_NAME 정의 또는 values.yaml 파일 사본의 runnerScaleSetName 값 설정을 통해 실행기 Scale Set 이름을 구성할 수 있습니다.

## The name of the runner scale set to create, which defaults to the Helm release name
runnerScaleSetName: "my-runners"

helm install 명령에서 values.yaml 파일을 전달해야 합니다. 자세한 내용은 Helm 설치 문서를 참조하세요.

실행기 대상 선택하기

실행기 Scale Set는 리포지토리, 조직 또는 기업 수준에서 배포할 수 있습니다.

실행기 Scale Set를 특정 수준으로 배포하려면 values.yaml 복사본의 githubConfigUrl 값을 리포지토리, 조직 또는 기업 URL로 설정하세요.

다음 예시에서는 ARC를 구성하여 실행기를 octo-org/octo-repo에 추가하는 방법을 보여 줍니다.

githubConfigUrl: "https://github.com/octo-ent/octo-org/octo-repo"

추가 Helm 구성 옵션은 ARC 리포지토리의 values.yaml을(를) 참조하세요.

GitHub App을(를) 사용하여 인증하기

기업 수준 실행기를 사용하지 않는 경우 GitHub Apps을(를) 사용하여 GitHub API로 인증할 수 있습니다. 자세한 내용은 GitHub API에 ARC 인증을(를) 참조하세요.

참고 항목

디스크의 파일에서 일반 텍스트로 프라이빗 키를 노출하는 것과 관련된 보안 위험을 고려하면, Kubernetes 비밀을 만들고 대신 참조를 전달하는 것이 좋습니다.

Kubernetes 비밀을 만들거나 values.yaml 파일에 값을 지정할 수 있습니다.

옵션 1: Kubernetes 비밀 만들기(권장)

GitHub App을(를) 만든 후에는 Kubernetes 비밀을 만들고 values.yaml 파일 복사본에서 해당 비밀에 대한 참조를 전달합니다.

참고 항목

gha-runner-scale-set 차트가 설치된 동일한 네임스페이스에 비밀을 만듭니다. 이 예제에서 네임스페이스는 빠른 시작 설명서와 일치하기 위해 arc-runners입니다. 자세한 내용은 Actions Runner Controller에 대한 빠른 시작을(를) 참조하세요.

kubectl create secret generic pre-defined-secret \
  --namespace=arc-runners \
  --from-literal=github_app_id=123456 \
  --from-literal=github_app_installation_id=654321 \
  --from-file=github_app_private_key=private-key.pem

values.yaml복사본을 비밀 이름에 참조로 전달합니다.

githubConfigSecret: pre-defined-secret

옵션 2: `values.yaml` 파일의 값 지정하기

다른 방법으로, values.yaml 파일 사본의 app_id, installation_id, private_key 값을 지정할 수 있습니다.

## githubConfigSecret is the Kubernetes secret to use when authenticating with GitHub API.
## You can choose to use a GitHub App or a personal access token (classic)
githubConfigSecret:
  ## GitHub Apps Configuration
  ## IDs must be strings, use quotes
  github_app_id: "123456"
  github_app_installation_id: "654321"
  github_app_private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    HkVN9...
    ...
    -----END RSA PRIVATE KEY-----

추가 Helm 구성 옵션은 ARC 리포지토리의 values.yaml을(를) 참조하세요.

실행기 그룹을 사용하여 액세스 관리하기

실행기 그룹을 사용하여 실행기 Scale Set에 액세스할 수 있는 조직 또는 리포지토리를 제어할 수 있습니다. 그룹을 사용하여 자체 호스트형 실행기에 대한 액세스 관리에서 실행기 그룹에 대한 자세한 내용을 참조하세요.

실행기 그룹에 실행기 Scale Set를 추가하려면 미리 실행기 그룹을 만들어야 합니다. 그런 다음 values.yaml 파일 복사본에 runnerGroup 속성을 설정합니다. 다음 예시에서는 Octo-Group 실행기 그룹에 실행기 Scale Set를 추가합니다.

runnerGroup: "Octo-Group"

추가 Helm 구성 옵션은 ARC 리포지토리의 values.yaml을(를) 참조하세요.

아웃바운드 프록시 구성하기

컨트롤러와 실행기의 HTTP 트래픽이 아웃바운드 프록시를 통과하도록 하려면 Helm 차트에서 다음 속성을 설정하세요.

proxy:
  http:
    url: http://proxy.com:1234
    credentialSecretRef: proxy-auth # a Kubernetes secret with `username` and `password` keys
  https:
    url: http://proxy.com:1234
    credentialSecretRef: proxy-auth # a Kubernetes secret with `username` and `password` keys
  noProxy:
    - example.com
    - example.org

ARC는 익명 또는 인증된 프록시 사용을 지원합니다. 인증된 프록시를 사용하는 경우 credentialSecretRef 값을 Kubernetes 비밀을 참조하도록 설정해야 합니다. 다음 명령을 사용하여 프록시 자격 증명을 사용하고 비밀을 만들 수 있습니다.

참고 항목

Bash

  kubectl create secret generic proxy-auth \
    --namespace=arc-runners \
    --from-literal=username=proxyUsername \
    --from-literal=password=proxyPassword \

  kubectl create secret generic proxy-auth \
    --namespace=arc-runners \
    --from-literal=username=proxyUsername \
    --from-literal=password=proxyPassword \

추가 Helm 구성 옵션은 ARC 리포지토리의 values.yaml을(를) 참조하세요.

실행기 최대 및 최소 수 설정하기

maxRunners 및 minRunners 속성은 ARC 설정을 사용자 지정하는 다양한 옵션을 제공합니다.

참고 항목

ARC는 예약된 최대 및 최소 구성을 지원하지 않습니다. cron 작업 또는 다른 일정 솔루션을 사용하여 일정에 따라 구성을 업데이트할 수 있습니다.

예: 제한 없는 실행기 수

maxRunners 속성과 minRunners 속성을 모두 주석으로 처리하면 ARC는 실행기 확장 집합에 할당된 작업 수로 확장되고 활성 작업이 없는 경우 0으로 축소됩니다.

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
# maxRunners: 0

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
# minRunners: 0

예: 최소 실행기의 수

minRunners 속성을 임의의 숫자로 설정할 수 있으며 ARC는 항상 지정된 수의 실행기가 활성 상태이고 항상 실행기 확장 집합에 할당된 작업을 수행할 수 있는지 확인할 것입니다.

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
# maxRunners: 0

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 20

예: 실행기 최대 및 최소 수 설정하기

이 구성에서 Actions Runner Controller은(는) 최대 30 실행기까지 확장되고 작업이 완료되면 20 실행기까지 축소됩니다.

참고 항목

maxRunners 값이 주석 처리되지 않는 한 minRunners 값은 maxRunners 값을 초과할 수 없습니다.

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
maxRunners: 30

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 20

예: 작업 큐 드레이닝

특정 시나리오에서는 작업 큐를 드레이닝하여 문제를 해결하거나 클러스터에서 유지 관리를 수행할 수 있습니다. 두 속성을 모두 0(으)로 설정하면 새 작업을 사용할 수 있고 할당될 때 Actions Runner Controller이(가) 새 실행기 Pod를 만들지 않습니다.

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
maxRunners: 0

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 0

사용자 지정 TLS 인증서

참고 항목

Debian 배포를 기반으로 하지 않는 사용자 지정 실행기 이미지를 사용하는 경우 다음 지침이 작동하지 않습니다.

일부 환경에서는 사용자 지정 CA(인증 기관)에서 서명한 TLS 인증서가 필요합니다. 사용자 지정 인증 기관 인증서는 컨트롤러 또는 실행기 컨테이너와 함께 번들로 묶이지 않으므로 해당 신뢰 저장소에 삽입해야 합니다.

githubServerTLS:
  certificateFrom:
    configMapKeyRef:
      name: config-map-name
      key: ca.crt
  runnerMountPath: /usr/local/share/ca-certificates/

이렇게 하는 경우 Privacy Enhanced Mail(PEM) 형식을 사용하고 인증서 확장이 .crt인지 확인하세요. 다른 모든 항목은 무시됩니다.

컨트롤러는 다음 작업을 실행합니다.

certificateFrom 에 지정된 인증서를 포함하는 github-server-tls-cert 볼륨을 만듭니다.
runnerMountPath/<certificate name> 경로에 해당 볼륨을 탑재합니다.
NODE_EXTRA_CA_CERTS 환경 변수를 동일한 경로로 설정합니다.
RUNNER_UPDATE_CA_CERTS 환경 변수를 1(으)로 설정합니다(2.303.0 버전은 실행기에서 인증서를 호스트에서 다시 로드하도록 지시합니다).

ARC는 실행기 Pod 템플릿에 설정된 값을 관찰하고 덮어쓰지 않습니다.

추가 Helm 구성 옵션은 ARC 리포지토리의 values.yaml을(를) 참조하세요.

프라이빗 컨테이너 레지스트리 사용하기

경고

이 Actions Runner Controller 사용자 정의 옵션은 GitHub 지원의 지원 범위를 벗어날 수 있으며 잘못 구성된 경우 예기치 않은 동작이 발생할 수 있습니다.

GitHub 지원이(가) 어떤 도움이 되는지 자세한 내용은 Actions Runner Controller 지원을 참조하세요.

개인 컨테이너 레지스트리를 사용하려면 컨트롤러 이미지와 실행기 이미지를 개인 컨테이너 레지스트리에 복사해야 합니다. 그런 다음 해당 이미지에 대한 링크를 구성하고 imagePullPolicy 값과 imagePullSecrets 값을 설정합니다.

컨트롤러 이미지 구성하기

다음과 같이 values.yaml 파일 사본을 업데이트하고 image 속성을 설정할 수 있습니다.

image:
  repository: "custom-registry.io/gha-runner-scale-set-controller"
  pullPolicy: IfNotPresent
  # Overrides the image tag whose default is the chart appVersion.
  tag: "0.4.0"

imagePullSecrets:
  - name: <registry-secret-name>

수신기 컨테이너는 컨트롤러에 대해 정의된 imagePullPolicy을(를) 상속합니다.

실행기 이미지 구성하기

values.yaml 파일의 복사본을 업데이트하고 template.spec 속성을 설정하여 특정 사용 사례에 대한 실행기 Pod를 구성할 수 있습니다.

참고 항목

실행기 컨테이너의 이름은 runner이어야 합니다. 그렇지 않으면 GitHub에 연결하도록 제대로 구성되지 않습니다.

구성 예시는 다음과 같습니다.

template:
  spec:
    containers:
      - name: runner
        image: "custom-registry.io/actions-runner:latest"
        imagePullPolicy: Always
        command: ["/home/runner/run.sh"]
    imagePullSecrets:
      - name: <registry-secret-name>

추가 Helm 구성 옵션은 ARC 리포지토리의 values.yaml을(를) 참조하세요.

실행기 Pod에 대한 Pod 사양 업데이트

경고

이 Actions Runner Controller 사용자 정의 옵션은 GitHub 지원의 지원 범위를 벗어날 수 있으며 잘못 구성된 경우 예기치 않은 동작이 발생할 수 있습니다.

GitHub 지원이(가) 어떤 도움이 되는지 자세한 내용은 Actions Runner Controller 지원을 참조하세요.

실행기 Pod의 PodSpec을 완전히 사용자 지정할 수 있으며 컨트롤러는 지정한 구성을 적용합니다. 다음은 Pod 사양의 예시입니다.

template:
  spec:
    containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        command: ["/home/runner/run.sh"]
        resources:
          limits:
            cpu: 500m
            memory: 512Mi
        securityContext:
          readOnlyRootFilesystem: true
          allowPrivilegeEscalation: false
          capabilities:
            add:
              - NET_ADMIN

추가 Helm 구성 옵션은 ARC 리포지토리의 values.yaml을(를) 참조하세요.

수신기 Pod에 대한 Pod 사양 업데이트

경고

이 Actions Runner Controller 사용자 정의 옵션은 GitHub 지원의 지원 범위를 벗어날 수 있으며 잘못 구성된 경우 예기치 않은 동작이 발생할 수 있습니다.

GitHub 지원이(가) 어떤 도움이 되는지 자세한 내용은 Actions Runner Controller 지원을 참조하세요.

수신기 Pod의 PodSpec을 사용자 지정할 수 있으며 컨트롤러는 지정한 구성을 적용합니다. 다음은 Pod 사양의 예시입니다.

참고 항목

수신기 컨테이너의 listenerTemplate.spec.containers.name 값을 변경하지 않는 것이 중요합니다. 그렇지 않으면 지정하는 구성이 새 사이드카 컨테이너에 적용됩니다.

listenerTemplate:
  spec:
    containers:
    # If you change the name of the container, the configuration will not be applied to the listener,
    # and it will be treated as a sidecar container.
    - name: listener
      securityContext:
        runAsUser: 1000
      resources:
        limits:
          cpu: "1"
          memory: 1Gi
        requests:
          cpu: "1"
          memory: 1Gi

추가 Helm 구성 옵션은 ARC 리포지토리의 values.yaml을(를) 참조하세요.

컨테이너에 Docker-in-Docker 또는 Kubernetes 모드 사용하기

경고

이 Actions Runner Controller 사용자 정의 옵션은 GitHub 지원의 지원 범위를 벗어날 수 있으며 잘못 구성된 경우 예기치 않은 동작이 발생할 수 있습니다.

GitHub 지원이(가) 어떤 도움이 되는지 자세한 내용은 Actions Runner Controller 지원을 참조하세요.

컨테이너 작업 및 서비스 또는 컨테이너 작업을 사용하는 경우 containerMode 값을 dind 또는 kubernetes로 설정해야 합니다. 사용자 지정 컨테이너 모드를 사용하려면 containerMode를 주석으로 처리하거나 제거하고 원하는 구성을 template 섹션에 추가합니다. 컨테이너 모드 사용자 지정을 참조하세요.

컨테이너에서 작업 실행에서 컨테이너 작업 및 서비스에 대한 자세한 내용을 참조하세요.
Docker 컨테이너 작업 만들기에서 컨테이너 작업에 대한 자세한 내용을 참조하세요.

Docker-in-Docker 모드 사용하기

참고 항목

Docker-in-Docker 컨테이너에는 권한이 있는 모드가 필요합니다. 자세한 내용은 Kubernetes 설명서에서 Pod 또는 컨테이너 에 대한 보안 컨텍스트 구성을 참조하세요.

기본적으로 dind 컨테이너는 Docker 디먼을 루트로 실행하는 docker:dind 이미지를 사용합니다. 알려진 제한 사항을 인지하고 --privileged 모드로 Pod를 실행하는 경우 이 이미지를 docker:dind-rootless로 바꿀 수 있습니다. Docker-in-Docker 구성을 사용자 지정하는 방법을 알아보려면 컨테이너 모드 사용자 지정을 참조하세요.

Docker-in-Docker 모드는 Docker 컨테이너 내에서 Docker를 실행할 수 있는 구성입니다. ARC는 이 구성에서 만든 각 실행기 Pod에 대해 다음 컨테이너를 만듭니다.

init 컨테이너
runner 컨테이너
dind 컨테이너

Docker-in-Docker 모드를 사용하도록 설정하려면 다음과 같이 containerMode.type을(를) dind(으)로 설정합니다.

containerMode:
  type: "dind"

template.spec은(는) 다음 기본 구성으로 업데이트됩니다.

Kubernetes >= v1.29 버전의 경우, 사이드카 컨테이너를 사용하여 Docker 데몬을 실행합니다.

template:
  spec:
    initContainers:
      - name: init-dind-externals
        image: ghcr.io/actions/actions-runner:latest
        command: ["cp", "-r", "/home/runner/externals/.", "/home/runner/tmpDir/"]
        volumeMounts:
          - name: dind-externals
            mountPath: /home/runner/tmpDir
      - name: dind
        image: docker:dind
        args:
          - dockerd
          - --host=unix:///var/run/docker.sock
          - --group=$(DOCKER_GROUP_GID)
        env:
          - name: DOCKER_GROUP_GID
            value: "123"
        securityContext:
          privileged: true
        restartPolicy: Always
        startupProbe:
          exec:
            command:
              - docker
              - info
          initialDelaySeconds: 0
          failureThreshold: 24
          periodSeconds: 5
        volumeMounts:
          - name: work
            mountPath: /home/runner/_work
          - name: dind-sock
            mountPath: /var/run
          - name: dind-externals
            mountPath: /home/runner/externals
    containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        command: ["/home/runner/run.sh"]
        env:
          - name: DOCKER_HOST
            value: unix:///var/run/docker.sock
          - name: RUNNER_WAIT_FOR_DOCKER_IN_SECONDS
            value: "120"
        volumeMounts:
          - name: work
            mountPath: /home/runner/_work
          - name: dind-sock
            mountPath: /var/run
    volumes:
      - name: work
        emptyDir: {}
      - name: dind-sock
        emptyDir: {}
      - name: dind-externals
        emptyDir: {}

Kubernetes < v1.29 버전의 경우, 다음 구성이 적용됩니다.

template:
  spec:
    initContainers:
      - name: init-dind-externals
        image: ghcr.io/actions/actions-runner:latest
        command:
          ["cp", "-r", "/home/runner/externals/.", "/home/runner/tmpDir/"]
        volumeMounts:
          - name: dind-externals
            mountPath: /home/runner/tmpDir
    containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        command: ["/home/runner/run.sh"]
        env:
          - name: DOCKER_HOST
            value: unix:///var/run/docker.sock
        volumeMounts:
          - name: work
            mountPath: /home/runner/_work
          - name: dind-sock
            mountPath: /var/run
      - name: dind
        image: docker:dind
        args:
          - dockerd
          - --host=unix:///var/run/docker.sock
          - --group=$(DOCKER_GROUP_GID)
        env:
          - name: DOCKER_GROUP_GID
            value: "123"
        securityContext:
          privileged: true
        volumeMounts:
          - name: work
            mountPath: /home/runner/_work
          - name: dind-sock
            mountPath: /var/run
          - name: dind-externals
            mountPath: /home/runner/externals
    volumes:
      - name: work
        emptyDir: {}
      - name: dind-sock
        emptyDir: {}
      - name: dind-externals
        emptyDir: {}

template.spec 값은 자동으로 삽입되며 재정의할 수 없습니다. 이 설정을 사용자 지정하려면 containerMode.type을(를) 설정 해제한 다음 이 구성을 복사하여 values.yaml 파일 복사본에 직접 적용해야 합니다.

추가 Helm 구성 옵션은 ARC 리포지토리의 values.yaml을(를) 참조하세요.

Kubernetes 모드 사용하기

Kubernetes 모드에서 ARC는 실행기 컨테이너 후크를 사용하여 서비스, 컨테이너 작업 또는 작업을 실행하는 동일한 네임스페이스에 새 Pod를 만듭니다.

필수 구성 요소

Kubernetes 모드는 Runner Pod와 컨테이너 작업 Pod 간에 작업 데이터를 공유하는 두 가지 방법을 지원합니다. 동시 쓰기 액세스가 필요한 시나리오에 권장되는 옵션인 영구 볼륨을 사용하거나, 컨테이너 수명 주기 후크를 사용하여 RWX 볼륨을 사용하지 않고 Pod 간에 작업 파일 시스템을 복원하고 내보낼 수 있습니다. 수명 주기 후크 접근 방식은 로컬 스토리지를 활용하여 이식성과 성능을 향상시키며 공유 스토리지가 없는 클러스터에 적합합니다.

영구 볼륨을 사용하여 Kubernetes 모드 구성

Kubernetes 모드를 사용하려면 실행기 Pod가 클레임할 수 있는 영구 볼륨을 만들고 요청 시 이러한 볼륨을 자동으로 프로비전하는 솔루션을 사용해야 합니다. OpenEBS 같은 솔루션을 테스트를 위해 사용할 수 있습니다.

Kubernetes 모드를 사용하도록 설정하려면 values.yaml 파일에서 containerMode.type을(를) kubernetes(으)로 설정합니다.

containerMode:
  type: "kubernetes"
  kubernetesModeWorkVolumeClaim:
    accessModes: ["ReadWriteOnce"]
    storageClassName: "dynamic-blob-storage"
    resources:
      requests:
        storage: 1Gi

추가 Helm 구성 옵션은 ARC 리포지토리의 values.yaml을(를) 참조하세요.

컨테이너 수명 주기 후크를 사용하여 Kubernetes 모드 구성

Kubernetes 모드를 활성화하려면 컨테이너 수명 주기 후크를 사용해 containerMode.type 파일에서 kubernetes-novolume을 values.yaml로 설정합니다.

containerMode:
  type: "kubernetes-novolume"

참고 항목

          `kubernetes-novolume` 모드를 사용할 때, 수명 주기 후크 작업을 지원하기 위해 컨테이너는 `root`로 실행되어야 합니다.

Kubernetes 모드 문제 해결

Kubernetes 모드를 사용하도록 설정하는 경우 컨테이너 작업으로 구성되지 않은 워크플로는 다음과 유사한 오류와 함께 실패합니다.

Jobs without a job container are forbidden on this runner, please add a 'container:' to your job or contact your self-hosted runner administrator.

작업 컨테이너 없이 작업을 실행하려면 실행기 컨테이너에서 ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER를 false로 설정하세요. 실행기가 이 검사를 사용하지 않도록 설정합니다.

경고

컨테이너 없는 작업 실행을 허용하거나 kubernetes 또는 kubernetes-novolume 모드로 실행하면, 러너 Pod가 Kubernetes API 서버에서 Pod를 생성하고 비밀에 접근할 수 있는 상승된 권한을 갖게 될 수 있습니다. 이 기본값을 변경하기 전에 잠재적인 보안 영향을 신중하게 검토하는 것이 좋습니다.

  template:
    spec:
      containers:
        - name: runner
          image: ghcr.io/actions/actions-runner:latest
          command: ["/home/runner/run.sh"]
          env:
            - name: ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER
              value: "false"

컨테이너 모드 사용자 지정

gha-runner-scale-set Helm 차트에 대해 values.yaml의 containerMode을(를) 설정할 때 다음 값 중 하나를 사용할 수 있습니다.

dind 또는
kubernetes

containerMode에 설정한 값에 따라 구성이 자동으로 gha-runner-scale-set Helm 차트에 대한 values.yaml 파일의 template 섹션에 삽입됩니다.

dind구성을 참조하세요.
kubernetes구성을 참조하세요.

사양을 사용자 지정하려면 containerMode을(를) 주석 처리하거나 제거하고 template 섹션에 원하는 구성을 추가합니다.

예: `dind-rootless` 실행

dind-rootless 실행을 결정하기 전에 알려진 제한 사항을 인지하고 있는지 확인하세요.

Kubernetes >= v1.29 버전의 경우, 사이드카 컨테이너를 사용하여 Docker 데몬을 실행합니다.

## githubConfigUrl is the GitHub url for where you want to configure runners
## ex: https://github.com/myorg/myrepo or https://github.com/myorg
githubConfigUrl: "https://github.com/actions/actions-runner-controller"

## githubConfigSecret is the k8s secrets to use when auth with GitHub API.
## You can choose to use GitHub App or a PAT token
githubConfigSecret: my-super-safe-secret

## maxRunners is the max number of runners the autoscaling runner set will scale up to.
maxRunners: 5

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 0

runnerGroup: "my-custom-runner-group"

## name of the runner scale set to create. Defaults to the helm release name
runnerScaleSetName: "my-awesome-scale-set"

## template is the PodSpec for each runner Pod
## For reference: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec
template:
  spec:
    initContainers:
    - name: init-dind-externals
      image: ghcr.io/actions/actions-runner:latest
      command: ["cp", "-r", "/home/runner/externals/.", "/home/runner/tmpDir/"]
      volumeMounts:
        - name: dind-externals
          mountPath: /home/runner/tmpDir
    - name: init-dind-rootless
      image: docker:dind-rootless
      command:
        - sh
        - -c
        - |
          set -x
          cp -a /etc/. /dind-etc/
          echo 'runner:x:1001:1001:runner:/home/runner:/bin/ash' >> /dind-etc/passwd
          echo 'runner:x:1001:' >> /dind-etc/group
          echo 'runner:100000:65536' >> /dind-etc/subgid
          echo 'runner:100000:65536' >> /dind-etc/subuid
          chmod 755 /dind-etc;
          chmod u=rwx,g=rx+s,o=rx /dind-home
          chown 1001:1001 /dind-home
      securityContext:
        runAsUser: 0
      volumeMounts:
        - mountPath: /dind-etc
          name: dind-etc
        - mountPath: /dind-home
          name: dind-home
    - name: dind
      image: docker:dind-rootless
      args:
        - dockerd
        - --host=unix:///run/user/1001/docker.sock
      securityContext:
        privileged: true
        runAsUser: 1001
        runAsGroup: 1001
      restartPolicy: Always
      startupProbe:
        exec:
          command:
            - docker
            - info
        initialDelaySeconds: 0
        failureThreshold: 24
        periodSeconds: 5
      volumeMounts:
        - name: work
          mountPath: /home/runner/_work
        - name: dind-sock
          mountPath: /run/user/1001
        - name: dind-externals
          mountPath: /home/runner/externals
        - name: dind-etc
          mountPath: /etc
        - name: dind-home
          mountPath: /home/runner
    containers:
    - name: runner
      image: ghcr.io/actions/actions-runner:latest
      command: ["/home/runner/run.sh"]
      env:
        - name: DOCKER_HOST
          value: unix:///run/user/1001/docker.sock
      securityContext:
        privileged: true
        runAsUser: 1001
        runAsGroup: 1001
      volumeMounts:
        - name: work
          mountPath: /home/runner/_work
        - name: dind-sock
          mountPath: /run/user/1001
    volumes:
    - name: work
      emptyDir: {}
    - name: dind-externals
      emptyDir: {}
    - name: dind-sock
      emptyDir: {}
    - name: dind-etc
      emptyDir: {}
    - name: dind-home
      emptyDir: {}

Kubernetes < v1.29 버전의 경우, 다음 구성이 적용됩니다.

## githubConfigUrl is the GitHub url for where you want to configure runners
## ex: https://github.com/myorg/myrepo or https://github.com/myorg
githubConfigUrl: "https://github.com/actions/actions-runner-controller"

## githubConfigSecret is the k8s secrets to use when auth with GitHub API.
## You can choose to use GitHub App or a PAT token
githubConfigSecret: my-super-safe-secret

## maxRunners is the max number of runners the autoscaling runner set will scale up to.
maxRunners: 5

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 0

runnerGroup: "my-custom-runner-group"

## name of the runner scale set to create. Defaults to the helm release name
runnerScaleSetName: "my-awesome-scale-set"

## template is the PodSpec for each runner Pod
## For reference: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec
template:
  spec:
    initContainers:
    - name: init-dind-externals
      image: ghcr.io/actions/actions-runner:latest
      command: ["cp", "-r", "/home/runner/externals/.", "/home/runner/tmpDir/"]
      volumeMounts:
        - name: dind-externals
          mountPath: /home/runner/tmpDir
    - name: init-dind-rootless
      image: docker:dind-rootless
      command:
        - sh
        - -c
        - |
          set -x
          cp -a /etc/. /dind-etc/
          echo 'runner:x:1001:1001:runner:/home/runner:/bin/ash' >> /dind-etc/passwd
          echo 'runner:x:1001:' >> /dind-etc/group
          echo 'runner:100000:65536' >> /dind-etc/subgid
          echo 'runner:100000:65536' >> /dind-etc/subuid
          chmod 755 /dind-etc;
          chmod u=rwx,g=rx+s,o=rx /dind-home
          chown 1001:1001 /dind-home
      securityContext:
        runAsUser: 0
      volumeMounts:
        - mountPath: /dind-etc
          name: dind-etc
        - mountPath: /dind-home
          name: dind-home
    containers:
    - name: runner
      image: ghcr.io/actions/actions-runner:latest
      command: ["/home/runner/run.sh"]
      env:
        - name: DOCKER_HOST
          value: unix:///run/user/1001/docker.sock
      securityContext:
        privileged: true
        runAsUser: 1001
        runAsGroup: 1001
      volumeMounts:
        - name: work
          mountPath: /home/runner/_work
        - name: dind-sock
          mountPath: /run/user/1001
    - name: dind
      image: docker:dind-rootless
      args:
        - dockerd
        - --host=unix:///run/user/1001/docker.sock
      securityContext:
        privileged: true
        runAsUser: 1001
        runAsGroup: 1001
      volumeMounts:
        - name: work
          mountPath: /home/runner/_work
        - name: dind-sock
          mountPath: /run/user/1001
        - name: dind-externals
          mountPath: /home/runner/externals
        - name: dind-etc
          mountPath: /etc
        - name: dind-home
          mountPath: /home/runner
    volumes:
    - name: work
      emptyDir: {}
    - name: dind-externals
      emptyDir: {}
    - name: dind-sock
      emptyDir: {}
    - name: dind-etc
      emptyDir: {}
    - name: dind-home
      emptyDir: {}

실행기-컨테이너 후크 이해

실행기가 컨테이너 작업, 서비스 컨테이너 또는 Docker 작업을 사용하는 워크플로 실행을 감지하면 실행기-컨테이너 후크를 호출하여 새 Pod를 만듭니다. 실행기는 실행기-컨테이너 후크를 사용하여 Kubernetes API를 호출하고 실행기 Pod와 동일한 네임스페이스에 새 Pod를 만듭니다. 새로 만든 이 Pod는 컨테이너 작업, 서비스 컨테이너 또는 Docker 작업을 실행하는 데 사용됩니다. 자세한 내용은 runner-container-hooks 리포지토리를 참조하세요.

후크 확장 구성

ARC 버전 0.4.0을 기준으로 실행기-컨테이너 후크는 후크 확장을 지원합니다. 이를 사용하여 실행기-컨테이너 후크에서 만든 Pod를 구성할 수 있습니다. 예를 들어, 후크 확장을 사용하여 Pod에서 보안 컨텍스트를 설정할 수 있습니다. 실행기-컨테이너 후크에서 만든 Pod의 PodSpec을 업데이트하는 데 사용되는 YAML 파일을 후크 확장을 사용하여 지정할 수 있습니다.

후크 확장을 구성하는 두 가지 옵션이 있습니다.

사용자 지정 실행기 이미지에 저장합니다. 사용자 지정 실행기 이미지의 어디에나 YAML 파일에 PodSpec을 저장할 수 있습니다. 자세한 내용은 Actions Runner Controller을(를) 참조하세요.
ConfigMap에 저장합니다. PodSpec을 사용하여 구성 맵을 만들고 해당 구성 맵을 실행기 컨테이너에 탑재할 수 있습니다. 자세한 내용은 Kubernetes 설명서의 ConfigMaps를 참조하세요.

참고 항목

두 옵션 모두 실행기 컨테이너 사양에 ACTIONS_RUNNER_CONTAINER_HOOK_TEMPLATE 환경 변수가 실행기 컨테이너에 탑재된 YAML 파일의 경로를 가리키도록 설정해야 합니다.

예: 구성 맵을 사용하여 securityContext 설정

실행기 Pod와 동일한 네임스페이스에 구성 맵을 만듭니다. 예를 들면 다음과 같습니다.

apiVersion: v1
kind: ConfigMap
metadata:
  name: hook-extension
  namespace: arc-runners
data:
  content: |
    metadata:
      annotations:
        example: "extension"
    spec:
      containers:
        - name: "$job" # Target the job container
          securityContext:
            runAsUser: 1000

.metadata.labels 및 metadata.annotations 필드는 해당 키가 예약되지 않는 한 있는 그대로 추가됩니다. .metadata.name 및 metadata.namespace 필드는 재정의할 수 없습니다.
대부분의 PodSpec 필드는 지정된 템플릿에서 적용되며 Helm 차트 values.yaml 파일에서 전달된 값을 재정의합니다.
추가 볼륨을 지정하면 해당 볼륨은 실행기에서 지정한 기본 볼륨에 추가됩니다.
할당된 이름을 기준으로 spec.containers이(가) 병합됩니다.
- 컨테이너 이름이 $job인 경우:
  - spec.containers.name 및 spec.containers.image 필드는 무시됩니다.
  - spec.containers.env, spec.containers.volumeMounts 및 spec.containers.ports 필드는 후크에서 만든 기본 컨테이너 사양에 추가됩니다.
  - 나머지 필드는 제공된 대로 적용됩니다.
- 컨테이너의 이름이 $job이(가) 아닌 경우, Pod 정의에 필드가 그대로 추가됩니다.

메트릭 활성화

참고 항목

ARC에 대한 메트릭은 gha-runner-scale-set-0.5.0 버전을 기준으로 사용할 수 있습니다.

ARC는 실행기, 작업 및 워크플로 실행에 소요된 시간에 대한 메트릭을 내보낼 수 있습니다. 혼잡을 식별하고, ARC 배포의 상태를 모니터링하고, 사용 추세를 시각화하고, 다른 많은 사용 사례에서 리소스 소비를 최적화하기 위해 메트릭을 사용할 수 있습니다. 컨트롤러-관리자 및 수신기 Pod에서 메트릭을 Prometheus 형식으로 내보냅니다. 자세한 내용은 Prometheus 설명서의 표시 형식을 참조하세요.

ARC에 대한 메트릭을 활성화하려면 gha-runner-scale-set-controller 차트의 values.yaml 파일에서 metrics 속성을 구성합니다.

다음은 구성의 예입니다.

metrics:
  controllerManagerAddr: ":8080"
  listenerAddr: ":8080"
  listenerEndpoint: "/metrics"

참고 항목

metrics: 개체가 제공되지 않거나 주석 처리되는 경우 다음 플래그가 빈 값(, , )이 있는 컨트롤러-관리자 및 수신기 Pod에 적용됩니다: --metrics-addr, --listener-metrics-addr, --listener-metrics-endpoint. 이는 ARC에 대한 메트릭을 비활성화합니다.

이러한 속성이 구성되면 컨트롤러-관리자 및 수신기 Pod는 values.yaml 파일에 지정한 포트에 바인딩된 listenerEndpoint를 통해 메트릭을 내보냅니다. 위의 예시에서 엔드포인트는 /metrics, 포트는 :8080입니다. 이 엔드포인트를 사용하여 컨트롤러-관리자 및 수신기 Pod에서 메트릭을 스크래핑할 수 있습니다.

메트릭을 비활성화하려면 metrics: 개체와 해당 속성을 제거하거나 주석으로 처리하여 values.yaml 파일을 업데이트합니다.

ARC에 사용 가능한 메트릭

다음 표에서는 컨트롤러-관리자 및 수신기 Pod에서 내보낸 메트릭을 보여줍니다.

참고 항목

컨트롤러 관리자가 내보내는 메트릭은 컨트롤러 런타임과 관련이 있으며 GitHub이(가) 소유하지 않습니다.

Owner	메트릭	Type	설명
controller-manager	gha_controller_pending_ephemeral_runners	계기(gauge)	보류 중인 상태의 임시 실행기 수
controller-manager	gha_controller_running_ephemeral_runners	계기(gauge)	실행 중인 상태의 임시 실행기 수
controller-manager	gha_controller_failed_ephemeral_runners	계기(gauge)	실패한 상태의 임시 실행기 수
controller-manager	gha_controller_running_listeners	계기(gauge)	실행 상태의 수신기 수
수신기	gha_assigned_jobs	계기(gauge)	실행기 Scale Set에 할당된 작업 수
수신기	gha_running_jobs	계기(gauge)	실행 중이거나 실행할 큐에 대기 중인 작업 수
수신기	gha_registered_runners	계기(gauge)	실행기 Scale Set에 의해 등록된 실행기 수
수신기	gha_busy_runners	계기(gauge)	현재 작업을 실행 중인 등록된 실행기 수
수신기	gha_min_runners	계기(gauge)	실행기 Scale Set에 구성된 최소 실행기 수
수신기	gha_max_runners	계기(gauge)	실행기 Scale Set에 구성된 최대 실행기 수
수신기	gha_desired_runners	계기(gauge)	실행기 Scale Set에 의한 원하는(규모 업/다운 대상) 실행기 수
수신기	gha_idle_runners	계기(gauge)	작업을 실행하지 않는 등록된 실행기 수
수신기	gha_started_jobs_total	counter	수신기가 준비됨 이후 시작된 총 작업 수 [1]
수신기	gha_completed_jobs_total	counter	수신기가 준비됨 이후 완료된 총 작업 수 [1]
수신기	gha_job_startup_duration_seconds	histogram	실행기 Scale Set이 소유한 실행기에서 워크플로 작업이 시작되도록 대기하는 데 소요된 시간(초)
수신기	gha_job_execution_duration_seconds	histogram	실행기 Scale Set에서 워크플로 작업을 실행하는 데 소요된 시간(초)

          [1]: Listener metrics that have the counter type are reset when the listener pod restarts.

ARC 업그레이드

Helm을 사용하여 CRD를 업그레이드하거나 삭제하는 것은 지원되지 않으므로 Helm을 사용하여 ARC를 업그레이드할 수는 없습니다. 자세한 내용은 Helm 문서의 사용자 지정 리소스 정의를 참조하세요. ARC를 최신 버전으로 업그레이드하려면 다음 단계를 완료해야 합니다.

gha-runner-scale-set의 모든 설치를 제거합니다.
리소스 정리를 기다립니다.
ARC 제거합니다.
현재 설치한 버전에서 업그레이드된 버전으로 CRD가 변경된 경우 actions.github.com API 그룹과 연결된 모든 CRD를 제거합니다.
ARC를 다시 설치합니다.

자세한 내용은 실행기 Scale Set 배포를 참조하세요.

ARC를 업그레이드하고 싶지만 가동 중지 시간이 염려되는 경우 고가용성 구성으로 ARC를 배포하여 실행기를 항상 사용할 수 있도록 할 수 있습니다. 자세한 내용은 고가용성 및 자동 장애 조치(failover)를 참조하세요.

참고 항목

커뮤니티 지원 버전의 ARC에서 GitHub 지원 버전으로 전환하는 것은 상당한 아키텍처 변경입니다. GitHub 지원 버전은 많은 ARC 구성 요소 재설계를 수반합니다. 부분 소프트웨어 업그레이드가 아닙니다. 이러한 이유로 먼저 프로덕션 환경과 일치하는 스테이징 환경에서 새 버전을 테스트하는 것이 좋습니다. 이렇게 하면 프로덕션에 배포하기 전에 설정의 안정성이 보장됩니다.

카나리아 이미지 배포

기능을 릴리스하기 전에 컨트롤러 관리자 컨테이너 이미지의 카나리아 릴리스를 사용하여 테스트할 수 있습니다. 카나리아 이미지는 canary-SHORT_SHA 태그 형식으로 게시됩니다. 자세한 내용은 Container registry의 gha-runner-scale-set-controller을(를) 참조하세요.

참고 항목

Helm 차트를 로컬 파일 시스템에서 사용해야 합니다.
릴리스된 Helm 차트는 사용할 수 없습니다.

gha-runner-scale-set-controller values.yaml파일의 tag를 canary-SHORT_SHA로 업데이트합니다.
gha-runner-scale-set에 대한 Chart.yaml 파일에서 appVersion 필드를 canary-SHORT_SHA로 업데이트합니다.
업데이트된 Helm 차트 및 values.yaml 파일을 사용하여 ARC를 다시 설치합니다.

고가용성 및 자동 장애 조치(failover)

ARC는 고가용성(활성-활성) 구성으로 배포할 수 있습니다. 별도의 지역에 두 개의 고유한 Kubernetes 클러스터가 배포된 경우 두 클러스터에 ARC를 배포하고 동일한 runnerScaleSetName 기능을 사용하도록 실행기 확장 집합을 구성할 수 있습니다. 이렇게 하려면 각 실행기 Scale Set를 고유한 실행기 그룹에 할당해야 합니다. 예를 들어 하나의 실행기 Scale Set가 arc-runner-set에 속하고 다른 실행기 Scale Set가 runner-group-A에 속해 있는 한 각각 runner-group-B로 명명된 두 개의 실행기 Scale Set를 가질 수 있습니다. 그룹을 사용하여 자체 호스트형 실행기에 대한 액세스 관리에서 실행기 그룹에 실행기 Scale Set를 할당하는 방법에 대한 자세한 내용을 참조하세요.

두 실행기 Scale Set가 모두 온라인이면 할당된 작업이 임의로 분산됩니다(할당 경합). 작업 할당 알고리즘을 구성할 수 없습니다. 클러스터 중 하나가 중단되면 다른 클러스터의 실행기 Scale Set는 개입 또는 구성 변경 없이 정상적으로 작업을 계속 획득합니다.

조직에서 ARC 사용하기

Actions Runner Controller을(를) 단일 설치하면 하나 이상의 실행기 Scale Set를 구성할 수 있습니다. 이러한 실행기 Scale Set는 리포지토리, 조직 또는 기업에 등록할 수 있습니다. 실행기 그룹을 사용하여 이러한 실행기 Scale Set의 사용 권한 경계를 제어할 수도 있습니다.

모범 사례로 각 조직에 대한 고유한 네임스페이스를 만듭니다. 각 실행기 그룹 또는 각 실행기 Scale Set에 대한 네임스페이스를 만들 수도 있습니다. 각 네임스페이스에 필요한 만큼 실행기 Scale Set를 설치할 수 있습니다. 이렇게 하면 가장 높은 수준의 격리가 제공되고 보안이 향상됩니다. 인증에 GitHub Apps을(를) 사용하고 각 실행기 Scale Set에 대한 세분화된 권한을 정의할 수 있습니다.

법적 고지 사항

다음은 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 사용 실행기 Scale Set 배포

이 문서의 내용