{"meta":{"title":"Actions Runner Controller 오류 문제 해결","intro":"Actions Runner Controller 오류를 해결하는 방법을 알아봅니다.","product":"GitHub Actions","breadcrumbs":[{"href":"/ko/actions","title":"GitHub Actions"},{"href":"/ko/actions/tutorials","title":"자습서"},{"href":"/ko/actions/tutorials/use-actions-runner-controller","title":"Actions Runner 컨트롤러"},{"href":"/ko/actions/tutorials/use-actions-runner-controller/troubleshoot","title":"문제 해결"}],"documentType":"article"},"body":"# Actions Runner Controller 오류 문제 해결\n\nActions Runner Controller 오류를 해결하는 방법을 알아봅니다.\n\n## 로깅\n\n컨트롤러, 수신기 및 실행기를 포함하는 Actions Runner Controller(ARC) 리소스는 표준 출력(`stdout`)에 로그를 씁니다. 이러한 로그를 수집하고 저장하는 로깅 솔루션을 구현하는 것이 좋습니다. 로그가 사용 가능하면 문제 해결 및 디버깅 시 귀하나 GitHub 지원팀에 도움이 될 수 있습니다. 자세한 내용은 [로깅 아키텍처](https://kubernetes.io/docs/concepts/cluster-administration/logging/)를 참조하세요.\n\n## 리소스 레이블\n\nActions Runner Controller에서 생성하는 리소스에는 컨트롤러, 리스너, 실행기 팟을 식별하는 레이블이 추가됩니다. 이러한 레이블을 사용하여 리소스를 필터링하고 문제 해결에 도움을 줄 수 있습니다.\n\n### 컨트롤러 포드\n\n컨트롤러 Pod에 다음 레이블이 적용됩니다.\n\n```yaml\napp.kubernetes.io/component=controller-manager\napp.kubernetes.io/instance=<controller installation name>\napp.kubernetes.io/name=gha-runner-scale-set-controller\napp.kubernetes.io/part-of=gha-runner-scale-set-controller\napp.kubernetes.io/version=<chart version>\n```\n\n### 수신기 Pod\n\n다음 레이블은 수신기 Pod에 적용됩니다.\n\n```yaml\nactions.github.com/enterprise= # Will be populated if githubConfigUrl is an enterprise URL\nactions.github.com/organization= # Will be populated if githubConfigUrl is an organization URL\nactions.github.com/repository= # Will be populated if githubConfigUrl is a repository URL\nactions.github.com/scale-set-name= # Runners scale set name\nactions.github.com/scale-set-namespace= # Runners namespace\napp.kubernetes.io/component=runner-scale-set-listener\napp.kubernetes.io/part-of=gha-runner-scale-set\napp.kubernetes.io/version= # Chart version\n```\n\n### 러너 Pod\n\n실행기 pod에는 다음과 같은 레이블이 적용됩니다.\n\n```yaml\nactions-ephemeral-runner= # True | False\nactions.github.com/organization= # Will be populated if githubConfigUrl is an organization URL\nactions.github.com/scale-set-name= # Runners scale set name\nactions.github.com/scale-set-namespace= # Runners namespace\napp.kubernetes.io/component=runner\napp.kubernetes.io/part-of=gha-runner-scale-set\napp.kubernetes.io/version= # Chart version\n```\n\n## 컨트롤러와 러너 세트 리스너의 로그 확인\n\n다음 명령을 사용하면 컨트롤러 Pod의 로그를 확인할 수 있습니다.\n\n```bash copy\nkubectl logs -n <CONTROLLER_NAMESPACE> -l app.kubernetes.io/name=gha-runner-scale-set-controller\n```\n\n다음 명령을 사용하면 러너 설정 수신기의 로그를 확인할 수 있습니다.\n\n```bash copy\nkubectl logs -n <CONTROLLER_NAMESPACE> -l auto-scaling-runner-set-namespace=arc-systems -l auto-scaling-runner-set-name=arc-runner-set\n```\n\n##\n\n```\n          `master` 브랜치의 차트를 사용하여\n\n          `master` 분기 대신 최신 릴리스의 차트를 사용하는 것이 좋습니다. \n          `master` 분기는 매우 불안정하며 `master` 분기의 차트 가 지정된 시간에 작동하도록 보장할 수 없습니다.\n```\n\n## 수신자 Pod 문제 해결\n\n컨트롤러 Pod가 실행 중이지만 수신기 Pod가 아닌 경우 먼저 컨트롤러의 로그를 검사하고 오류가 있는지 확인합니다. 오류가 없고 러너 세트 리스너 파드가 아직 실행되지 않는 경우, 컨트롤러 파드가 클러스터의 Kubernetes API 서버에 액세스할 수 있는지 확인합니다.\n\n프록시가 구성되었거나 [Istio](https://istio.io/)와 같이 자동으로 삽입되는 사이드카 프록시를 사용하는 경우 컨트롤러 컨테이너(관리자)에서 Kubernetes API 서버로의 트래픽을 허용하도록 구성되었는지 확인합니다.\n\n자동 확장 러너 세트를 설치했지만 리스너 포드가 생성되지 않은 경우, 제공한 `githubConfigSecret`이 올바른지, 제공한 `githubConfigUrl`가 정확한지 확인합니다. 자세한 내용은 [GitHub API에 ARC 인증](/ko/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/authenticating-to-the-github-api) 및 [Actions Runner Controller 사용 실행기 Scale Set 배포](/ko/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller)을(를) 참조하세요.\n\n## 취소된 워크플로 실행 후 러너 Pod가 다시 생성됩니다.\n\n워크플로 실행이 취소되면 다음 이벤트가 발생합니다.\n\n* 취소 신호는 러너에게 직접 전송됩니다.\n* 실행기 애플리케이션이 중단될 경우, 해당 실행기 Pod 역시 함께 종료됩니다.\n* 다음 폴링에서 리스너가 취소 신호를 받습니다.\n\n육상 선수가 신호를 수신하는 시기와 청자가 신호를 수신하는 시점 사이에 약간의 지연이 있을 수 있습니다. 실행기 Pod의 종료가 시작되면, 수신기는 현재 상태를 확인하여 목표로 하는 실행기 수에 맞추기 위해 새로운 실행기를 생성합니다. 그러나 청취자는 취소 신호를 받을 때 러너 수를 줄이는 조치를 취합니다. 결국 수신기는 필요한 실행기의 개수로 축소되게 됩니다. 이 과정에서 추가적인 실행 단위들을 확인할 수 있습니다.\n\n## 오류: `Name must have up to n characters`\n\nARC는 특정 리소스의 생성된 이름을 다른 리소스에 대한 레이블로 사용합니다. 이 요구 사항으로 인해 ARC는 리소스 이름을 63자로 제한합니다.\n\n리소스 이름의 일부가 사용자에 의해 정의되므로 ARC는 설치 이름 및 네임스페이스에 사용할 수 있는 문자 수에 제한을 적용합니다.\n\n```bash\nError: INSTALLATION FAILED: execution error at (gha-runner-scale-set/templates/autoscalingrunnerset.yaml:5:5): Name must have up to 45 characters\n\nError: INSTALLATION FAILED: execution error at (gha-runner-scale-set/templates/autoscalingrunnerset.yaml:8:5): Namespace must have up to 63 characters\n```\n\n## 오류: `Access to the path /home/runner/_work/_tool is denied`\n\n영구 볼륨과 함께 Kubernetes 모드를 사용하는 경우 이 오류가 표시될 수 있습니다. 이 오류는 실행기 컨테이너가 루트가 아닌 사용자와 함께 실행 중이고 이로 인해 탑재된 볼륨과 권한이 일치하지 않는 경우에 발생합니다.\n\n다음 작업 중 하나를 따르면 이 문제를 해결할 수 있습니다.\n\n* `securityContext.fsGroup`를 지원하는 볼륨 형식을 사용합니다.\n  `hostPath` 볼륨은 이 속성을 지원하지 않지만 `local` 볼륨 및 기타 유형의 볼륨은 이 속성을 지원합니다. 러너 포드의 `fsGroup`을 러너의 GID와 일치하도록 업데이트합니다. 다음을 포함하도록 `gha-runner-scale-set` helm 차트 값을 업데이트하면 이 작업을 수행할 수 있습니다.\n  `VERSION`를, 사용하려는 버전의 `actions-runner` 컨테이너 이미지로 바꿉니다.\n\n  ```yaml copy\n  template:\n    spec:\n      securityContext:\n        fsGroup: 123\n      containers:\n        - name: runner\n          image: ghcr.io/actions/actions-runner:latest\n          command: [\"/home/runner/run.sh\"]\n  ```\n\n* 러너 포드의 `securityContext`을 업데이트하는 것이 실현 가능한 해결책이 아닌 경우, 다음과 같이 `initContainers`를 사용하여 마운트된 볼륨의 소유권을 변경하여 문제를 우회할 수 있습니다.\n\n  ```yaml copy\n  template:\n    spec:\n      initContainers:\n        - name: kube-init\n          image: ghcr.io/actions/actions-runner:latest\n          command: [\"sudo\", \"chown\", \"-R\", \"1001:123\", \"/home/runner/_work\"]\n      volumeMounts:\n        - name: work\n          mountPath: /home/runner/_work\n      containers:\n        - name: runner\n          image: ghcr.io/actions/actions-runner:latest\n          command: [\"/home/runner/run.sh\"]\n  ```\n\n## 오류: `failed to get access token for GitHub App auth: 401 Unauthorized`\n\nGitHub App에 대한 액세스 토큰을 얻으려고 할 때 `401 Unauthorized` 오류가 발생하는 것은 NTP(네트워크 시간 프로토콜) 드리프트의 결과일 수 있습니다. Kubernetes 시스템이 NTP 서버와 정확하게 동기화되고 있으며 상당한 시간 드리프트가 없는지 확인합니다. 시스템 시간이 GitHub의 시간보다 늦다면 여유가 조금 있겠지만 환경 시간이 몇 초 이상 빠르다면 GitHub App을 사용할 때 401 오류가 발생하게 됩니다.\n\n## 러너 그룹 제한\n\n하나의 러너 그룹에서 최대 10,000개의 자체 호스팅 러너를 가질 수 있습니다. 이 제한에 도달하면 새 실행기를 추가할 수 없습니다.\n\n## 실행기 업데이트\n\n> \\[!WARNING] 주요, 부 버전 또는 패치 릴리스를 포함하여 소프트웨어용으로 릴리스된 모든 업데이트는 사용 가능한 업데이트로 간주됩니다. 30일 이내에 소프트웨어 업데이트를 수행하지 않으면 GitHub Actions 서비스가 실행기의 큐에 작업을 추가하지 않습니다. 또한 중요한 보안 업데이트가 필요한 경우 GitHub Actions 서비스는 업데이트될 때까지 실행기의 큐에 작업을 추가하지 않습니다.\n\n실행기 소프트웨어 버전 및/또는 사용 중인 사용자 지정 실행기 이미지가 최신 버전을 실행하고 있는지 확인합니다.\n\n자세한 내용은 [자체 호스팅 실행기 참조](/ko/actions/reference/runners/self-hosted-runners)을(를) 참조하세요.\n\n## 법적 고지\n\n다음은 Apache-2.0 라이선스에서 <https://github.com/actions/actions-runner-controller/로부터> 일부 조정되었습니다.\n\n```text\nCopyright 2019 Moto Ishizawa\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```"}