Actions Runner Controller 오류 트러블슈팅

Actions Runner Controller(ARC) 오류를 트러블슈팅하는 방법을 알려드릴게요. 로그를 확인하고, 리소스 레이블을 이해하고, 자주 발생하는 오류를 해결하는 방법을 배울 수 있어요.

출처: 문서

본문

Logging

Actions Runner Controller(ARC) 리소스(컨트롤러, 리스너, 러너 포함)는 표준 출력(stdout)에 로그를 기록해요. 이러한 로그를 수집하고 저장할 로깅 솔루션을 구현하는 것이 좋아요. 로그를 사용할 수 있으면 여러분이나 GitHub 지원팀이 트러블슈팅과 디버깅에 도움을 받을 수 있어요. 자세한 내용은 Kubernetes 문서의 Logging Architecture를 참고하세요.

Resources labels

Actions Runner Controller가 만든 리소스(컨트롤러, 리스너, 러너 파드 포함)에는 레이블이 추가돼요. 이 레이블을 사용해서 리소스를 필터링하고 트러블슈팅에 도움을 받을 수 있어요.

Controller pod

다음 레이블이 컨트롤러 파드에 적용돼요.

app.kubernetes.io/component=controller-manager
app.kubernetes.io/instance=<controller installation name>
app.kubernetes.io/name=gha-runner-scale-set-controller
app.kubernetes.io/part-of=gha-runner-scale-set-controller
app.kubernetes.io/version=<chart version>

Listener pod

다음 레이블이 리스너 파드에 적용돼요.

actions.github.com/enterprise= # Will be populated if githubConfigUrl is an enterprise URL
actions.github.com/organization= # Will be populated if githubConfigUrl is an organization URL
actions.github.com/repository= # Will be populated if githubConfigUrl is a repository URL
actions.github.com/scale-set-name= # Runners scale set name
actions.github.com/scale-set-namespace= # Runners namespace
app.kubernetes.io/component=runner-scale-set-listener
app.kubernetes.io/part-of=gha-runner-scale-set
app.kubernetes.io/version= # Chart version

Runner pod

다음 레이블이 러너 파드에 적용돼요.

actions-ephemeral-runner= # True | False
actions.github.com/organization= # Will be populated if githubConfigUrl is an organization URL
actions.github.com/scale-set-name= # Runners scale set name
actions.github.com/scale-set-namespace= # Runners namespace
app.kubernetes.io/component=runner
app.kubernetes.io/part-of=gha-runner-scale-set
app.kubernetes.io/version= # Chart version

Checking the logs of the controller and runner set listener

컨트롤러 파드의 로그를 확인하려면 다음 명령을 사용할 수 있어요.

kubectl logs -n <CONTROLLER_NAMESPACE> -l app.kubernetes.io/name=gha-runner-scale-set-controller

러너 세트 리스너의 로그를 확인하려면 다음 명령을 사용할 수 있어요.

kubectl logs -n <CONTROLLER_NAMESPACE> -l auto-scaling-runner-set-namespace=arc-systems -l auto-scaling-runner-set-name=arc-runner-set

Using the charts from the `master` branch

master 브랜치 대신 최신 릴리스의 차트를 사용하는 것이 좋아요. master 분기는 매우 불안정하며, master 분기의 차트가 특정 시점에 항상 작동한다고 보장할 수 없어요.

Troubleshooting the listener pod

컨트롤러 파드는 실행 중인데 리스너 파드가 실행되지 않는다면, 먼저 컨트롤러의 로그를 검사해서 오류가 있는지 확인하세요. 오류가 없는데 러너 세트 리스너 파드가 여전히 실행되지 않는다면, 컨트롤러 파드가 클러스터의 Kubernetes API 서버에 접근할 수 있는지 확인하세요.

프록시를 구성했거나 Istio 같은 자동으로 주입되는 사이드카 프록시를 사용한다면, 컨트롤러 컨테이너(manager)에서 Kubernetes API 서버로의 트래픽을 허용하도록 구성되어 있는지 확인하세요.

자동 확장 러너 세트를 설치했는데 리스너 파드가 생성되지 않는다면, 제공한 githubConfigSecret이 올바른지, 제공한 githubConfigUrl이 정확한지 확인하세요. 자세한 내용은 Authenticating ARC to the GitHub API 및 Deploying runner scale sets with Actions Runner Controller 문서를 참고하세요.

Runner pods are recreated after a canceled workflow run

워크플로우 실행이 취소되면 다음 이벤트가 발생해요.

취소 신호가 러너에게 직접 전송돼요.
러너 애플리케이션이 종료되고, 이것이 또한 러너 파드도 종료해요.
다음 폴링에서 취소 신호가 리스너에게 수신돼요.

러너가 신호를 수신하는 시점과 리스너가 신호를 수신하는 시점 사이에 약간의 지연이 있을 수 있어요. 러너 파드가 종료되기 시작하면 리스너는 자신의 상태에 따라 원하는 러너 수에 맞게 새 러너를 생성하려 해요. 그러나 리스너가 취소 신호를 수신하면 러너 수를 줄이기 위해 작동해요. 결국 리스너는 원하는 러너 수로 다시 축소돼요. 그 사이에 추가 러너가 보일 수 있어요.

Error: `Name must have up to n characters`

ARC는 특정 리소스의 생성된 이름을 다른 리소스의 레이블로 사용해요. 이 요구사항 때문에 ARC는 리소스 이름을 63자로 제한해요.

리소스 이름의 일부는 사용자가 정의하므로, ARC는 설치 이름과 네임스페이스에 사용할 수 있는 문자 수에 제한을 적용해요.

Error: INSTALLATION FAILED: execution error at (gha-runner-scale-set/templates/autoscalingrunnerset.yaml:5:5): Name must have up to 45 characters

Error: INSTALLATION FAILED: execution error at (gha-runner-scale-set/templates/autoscalingrunnerset.yaml:8:5): Namespace must have up to 63 characters

Error: `Access to the path /home/runner/_work/_tool is denied`

영구 볼륨과 함께 Kubernetes 모드를 사용한다면 이 오류가 보일 수 있어요. 이 오류는 러너 컨테이너가 비-root 사용자로 실행되고 있을 때 발생하며, 마운트된 볼륨과 권한 불일치를 일으켜요.

이를 해결하려면 다음 중 하나를 수행할 수 있어요.

securityContext.fsGroup을 지원하는 볼륨 유형을 사용하세요. hostPath 볼륨은 이 속성을 지원하지 않지만, local 볼륨과 다른 볼륨 유형은 지원해요. 러너 파드의 fsGroup을 러너의 GID와 일치하도록 업데이트하세요. gha-runner-scale-set Helm 차트 값을 업데이트해서 다음을 포함하면 됩니다. VERSION을 사용하려는 actions-runner 컨테이너 이미지의 버전으로 바꾸세요.
```
template:
  spec:
    securityContext:
      fsGroup: 123
    containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        command: ["/home/runner/run.sh"]
```

러너 파드의 securityContext를 업데이트하는 것이 실행 가능한 해결책이 아니라면, initContainers를 사용해서 마운트된 볼륨의 소유권을 변경하는 방식으로 문제를 해결할 수 있어요.

template:
  spec:
    initContainers:
      - name: kube-init
        image: ghcr.io/actions/actions-runner:latest
        command: ["sudo", "chown", "-R", "1001:123", "/home/runner/_work"]
    volumeMounts:
      - name: work
        mountPath: /home/runner/_work
    containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        command: ["/home/runner/run.sh"]

Error: `failed to get access token for GitHub App auth: 401 Unauthorized`

GitHub App에 대한 액세스 토큰을 얻으려고 할 때 401 Unauthorized 오류가 발생하는 것은 NTP(Network Time Protocol) 드리프트의 결과일 수 있어요. Kubernetes 시스템이 NTP 서버와 정확하게 동기화되고 있고 상당한 시간 드리프트가 없는지 확인하세요. 시스템 시간이 GitHub의 시간보다 뒤쳐져 있으면 더 많은 여유가 있지만, 환경이 몇 초 이상 앞서 있다면 GitHub App을 사용할 때 401 오류가 발생할 거예요.

Runner group limits

하나의 러너 그룹에 최대 10,000개의 자체 호스팅 러너를 가질 수 있어요. 이 한도에 도달하면 새 러너를 추가할 수 없게 돼요.

Runner updates

[!WARNING] 메이저, 마이너 또는 패치 릴리스를 포함한 소프트웨어에 대한 모든 업데이트 릴리스는 사용 가능한 업데이트로 간주돼요. 30일 이내에 소프트웨어 업데이트를 수행하지 않으면 GitHub Actions 서비스가 러너에 job을 큐잉하지 않아요. 또한 중요한 보안 업데이트가 필요한 경우 GitHub Actions 서비스는 업데이트될 때까지 러너에 job을 큐잉하지 않아요.

러너 소프트웨어 버전 및/또는 사용 중인 사용자 지정 러너 이미지가 최신 버전을 실행하고 있는지 검증하세요.

자세한 내용은 Self-hosted runners reference 문서를 참고하세요.

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 오류 트러블슈팅