---
stage: Verify
group: Runner Core
info: To determine the technical writer assigned to the Stage/Group associated with this page, see <https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments>
title: GitLab 러너 문제 해결
---

{{< details >}}

- 계층:  Free, Premium, Ultimate
- 제공:  GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

이 섹션은 GitLab 러너 문제 해결 시 도움이 될 수 있습니다.

## 일반적인 문제 해결 팁 {#general-troubleshooting-tips}

### 로그 보기 {#view-the-logs}

GitLab 러너 서비스는 syslog에 로그를 보냅니다. 로그를 보려면 배포판 설명서를 참조하세요. 배포판에 `journalctl` 명령이 포함되어 있으면 이 명령을 사용하여 로그를 볼 수 있습니다:

```shell
journalctl --unit=gitlab-runner.service -n 100 --no-pager
docker logs gitlab-runner-container # Docker
kubectl logs gitlab-runner-pod # Kubernetes
```

### 서비스 다시 시작 {#restart-the-service}

```shell
systemctl restart gitlab-runner.service
```

### Docker 머신 보기 {#view-the-docker-machines}

```shell
sudo docker-machine ls
sudo su - && docker-machine ls
```

### 모든 Docker 머신 삭제 {#delete-all-docker-machines}

```shell
docker-machine rm $(docker-machine ls -q)
```

### `config.toml`에 변경 사항 적용 {#apply-changes-to-configtoml}

```shell
systemctl restart gitlab-runner.service
docker-machine rm $(docker-machine ls -q) # Docker machine
journalctl --unit=gitlab-runner.service -f # Tail the logs to check for potential errors
```

## GitLab 및 GitLab 러너 버전 확인 {#confirm-your-gitlab-and-gitlab-runner-versions}

GitLab은 [하위 호환성을 보장](../_index.md#gitlab-runner-versions)하려고 합니다. 그러나 첫 번째 문제 해결 단계로 GitLab 러너 버전이 GitLab 버전과 동일한지 확인해야 합니다.

## `coordinator`은(는) 무엇을 의미합니까? {#what-does-coordinator-mean}

`coordinator`은 작업이 요청되는 GitLab 설치입니다.

즉, 러너는 `coordinator`(GitLab API를 통한 GitLab 설치)에서 작업을 요청하는 격리된 에이전트입니다.

## Windows에서 서비스로 실행할 때 로그는 어디에 저장됩니까? {#where-are-logs-stored-when-run-as-a-service-on-windows}

- GitLab 러너가 Windows의 서비스로 실행 중이면 시스템 이벤트 로그를 생성합니다. 이를 보려면 이벤트 뷰어를 열고(실행 메뉴에서 `eventvwr.msc`을(를) 입력하거나 "이벤트 뷰어" 검색). 그런 다음 **Windows Logs > Application**으로 이동합니다. **소스** 러너 로그는 `gitlab-runner`입니다. Windows Server Core를 사용 중인 경우 이 PowerShell 명령을 실행하여 마지막 20개의 로그 항목을 가져옵니다: `get-eventlog Application -Source gitlab-runner -Newest 20 | format-table -wrap -auto`.

## 디버그 로깅 모드 활성화 {#enable-debug-logging-mode}

> [!warning]
> 디버그 로깅은 심각한 보안 위험이 될 수 있습니다. 출력에는 작업에 사용 가능한 모든 변수 및 기타 비밀의 내용이 포함됩니다. 비밀을 제3자에게 전송할 수 있는 로그 수집을 비활성화해야 합니다. 마스킹된 변수를 사용하면 비밀을 작업 로그 출력에서 보호할 수 있지만 컨테이너 로그에서는 보호할 수 없습니다.

### 명령줄에서 {#in-the-command-line}

터미널에서 root로 로그인한 후 다음을 실행합니다.

> [!warning]
> 이것은 [Shell 실행기](../executors/shell.md)가 있는 러너에서는 수행하지 않아야 합니다. `systemd` 서비스를 다시 정의하고 모든 작업을 root로 실행하기 때문입니다. 이는 보안 위험을 초래하며 파일 소유권 변경으로 인해 권한이 없는 계정으로 되돌리기 어렵습니다.

```shell
gitlab-runner stop
gitlab-runner --debug run
```

### GitLab 러너 `config.toml`에서 {#in-the-gitlab-runner-configtoml}

[`config.toml`의 글로벌 섹션](../configuration/advanced-configuration.md#the-global-section)에서 디버그 로깅을 활성화할 수 있으며 `log_level` 설정을 `debug`로 설정합니다. `config.toml`의 맨 위에 다음 줄을 추가하고, concurrent 줄 앞/뒤에 추가합니다:

```toml
log_level = "debug"
```

### Helm 차트에서 {#in-the-helm-chart}

GitLab 러너가 [GitLab 러너 Helm 차트](../install/kubernetes.md) 를 사용하여 Kubernetes 클러스터에 설치된 경우, 디버그 로깅을 활성화하려면 [`values.yaml` 사용자 정의](../install/kubernetes.md#configure-gitlab-runner-with-the-helm-chart)에서 `logLevel` 옵션을 설정합니다:

```yaml
## Configure the GitLab Runner logging level. Available values are: debug, info, warn, error, fatal, panic
## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration/#the-global-section
##
logLevel: debug
```

## GitLab 러너 로그의 상관 ID {#correlation-ids-in-gitlab-runner-logs}

GitLab 러너는 GitLab과의 상호 작용을 추적하기 위해 각 API 요청에 대해 상관 ID를 생성합니다.

GitLab의 API 응답에 `X-Request-Id` 헤더에 상관 ID가 포함되면 값(일반적으로 ULID 형식)이 로그에 사용됩니다. 응답에 상관 ID가 포함되지 않으면 GitLab 러너는 요청에 대해 생성한 UUID를 사용합니다(대시 없는 소문자 16진수 형식). 폴백 상관 ID는 요청이 GitLab 워크호스에 도달하지 않았음을 나타냅니다. 이 문제는 중간 홉(예: WAF, CDN, 로드 밸런서 또는 프록시)에서 발생했을 가능성이 높습니다.

상관 ID를 사용하여 구성 요소 간의 로그 항목을 일치시키고 요청 흐름을 추적할 수 있습니다. GitLab 러너 로그에서 `correlation_id` 필드를 검색하고 GitLab 서버 로그에서 해당 ID를 검색하여 이벤트를 연관시킵니다.

예제 로그 항목:

```plaintext
# Valid correlation ID (ULID format from GitLab API response)
Appending trace to coordinator...ok correlation_id=01KKDQ7P6TRW7Z6P2PWG5808EK job=101162491 status=202 Accepted

# Fallback correlation ID (lowercase hex UUID without dashes, generated by runner)
WARNING: Appending trace to coordinator... job failed correlation_id=21fe32aee0e146c194640b075c95ec7c job=101162868 status=403 Forbidden
```

## Docker 실행기 러너에 대해 DNS 구성 {#configure-dns-for-a-docker-executor-runner}

Docker 실행기를 사용하여 GitLab 러너를 구성하면 호스트 러너 데몬이 액세스할 수 있어도 Docker 컨테이너가 GitLab에 액세스하지 못할 수 있습니다. DNS가 호스트에서 구성되었지만 이러한 구성이 컨테이너에 전달되지 않을 때 발생할 수 있습니다.

**예**:

GitLab 서비스 및 GitLab 러너는 두 가지 방식으로 연결된 두 개의 서로 다른 네트워크(예: 인터넷 및 VPN을 통해)에 있습니다. 러너의 라우팅 메커니즘은 VPN을 통한 DNS 서비스 대신 기본 인터넷 서비스를 통해 DNS를 쿼리할 수 있습니다. 이 구성으로 인해 다음 메시지가 생성됩니다:

```shell
Created fresh repository.
++ echo 'Created fresh repository.'
++ git -c 'http.userAgent=gitlab-runner 16.5.0 linux/amd64' fetch origin +da39a3ee5e6b4b0d3255bfef95601890afd80709:refs/pipelines/435345 +refs/heads/master:refs/remotes/origin/master --depth 50 --prune --quiet
fatal: Authentication failed for 'https://gitlab.example.com/group/example-project.git/'
```

이 경우 인증 실패는 인터넷과 GitLab 서비스 사이의 서비스로 인해 발생합니다. 이 서비스는 별도의 자격 증명을 사용하므로 러너가 VPN을 통한 DNS 서비스를 사용하면 우회할 수 있습니다.

`dns` 구성을 `[runners.docker]` 섹션 [러너의 `config.toml` 파일](../configuration/advanced-configuration.md#the-runnersdocker-section)에서 사용하여 Docker에 사용할 DNS 서버를 알릴 수 있습니다.

```toml
dns = ["192.168.xxx.xxx","192.168.xxx.xxx"]
```

## `x509: certificate signed by unknown authority`을(를) 보고 있습니다. {#im-seeing-x509-certificate-signed-by-unknown-authority}

자세한 내용은 [자체 서명 인증서](../configuration/tls-self-signed.md)를 참조하세요.

## `Permission Denied`을(를) 받으면 `/var/run/docker.sock` {#i-get-permission-denied-when-accessing-the-varrundockersock}

Docker 실행기를 사용하려고 하고 서버에 설치된 Docker 엔진에 연결 중입니다. `Permission Denied` 오류를 볼 수 있습니다. 가장 가능성 높은 원인은 시스템이 SELinux를 사용한다는 것입니다(CentOS, Fedora 및 RHEL에서 기본적으로 활성화됨). 시스템의 SELinux 정책을 확인하여 가능한 거부를 확인하세요.

## Docker-machine 오류: `Unable to query docker version: Cannot connect to the docker engine endpoint.` {#docker-machine-error-unable-to-query-docker-version-cannot-connect-to-the-docker-engine-endpoint}

이 오류는 머신 프로비저닝과 관련이 있으며 다음 이유로 인한 것일 수 있습니다:

- TLS 실패가 있습니다. `docker-machine`이(가) 설치되면 일부 인증서가 유효하지 않을 수 있습니다. 이 문제를 해결하려면 인증서를 제거하고 러너를 다시 시작하세요:

  ```shell
  sudo su -
  rm -r /root/.docker/machine/certs/*
  service gitlab-runner restart
  ```

  러너가 다시 시작되면 인증서가 비어 있음을 등록하고 인증서를 다시 만듭니다.

- 호스트명이 프로비저닝된 머신에서 지원되는 길이보다 깁니다. 예를 들어 Ubuntu 머신은 `HOST_NAME_MAX`에 대해 64자 제한이 있습니다. 호스트명은 `docker-machine ls`로 보고됩니다. 러너 구성에서 `MachineName`를 확인하고 필요한 경우 호스트명 길이를 줄입니다.

> [!note]
> 이 오류는 Docker이 머신에 설치되기 전에 발생했을 수 있습니다.

## `dialing environment connection: ssh: rejected: connect failed (open failed)` {#dialing-environment-connection-ssh-rejected-connect-failed-open-failed}

이 오류는 Docker 자동 스케일러가 SSH를 통해 터널링되는 연결일 때 대상 시스템의 Docker 데몬에 도달할 수 없을 때 발생합니다. 대상 시스템에 SSH로 연결할 수 있고 `docker info`과(와) 같은 Docker 명령을 성공적으로 실행할 수 있는지 확인합니다.

## 자동으로 확장된 러너에 AWS 인스턴스 프로필 추가 {#adding-an-aws-instance-profile-to-your-autoscaled-runners}

AWS IAM 역할을 생성한 후 IAM 콘솔에서 역할에 **Role ARN** 및 **Instance Profile ARNs**이 있습니다. **Instance Profile** 이름을 사용해야 하고, **not** **Role Name**을(를) 사용하지 않아야 합니다.

`[runners.machine]` 섹션에 다음 값을 추가합니다: `"amazonec2-iam-instance-profile=<instance-profile-name>",`

## Docker 실행기는 Java 프로젝트를 빌드할 때 시간 초과 {#the-docker-executor-gets-timeout-when-building-java-project}

이는 대부분 손상된 `aufs` 저장소 드라이버로 인해 발생합니다:  [Java 프로세스는 컨테이너 내부에서 중단됩니다](https://github.com/moby/moby/issues/18502). 최선의 해결책은 [저장소 드라이버](https://docs.docker.com/engine/storage/drivers/select-storage-driver/)를 OverlayFS(더 빠름) 또는 DeviceMapper(더 느림)로 변경하는 것입니다.

[Docker 구성 및 실행](https://docs.docker.com/engine/daemon/) 에 대한 이 문서를 확인하거나 [systemd로 제어 및 구성](https://docs.docker.com/engine/daemon/proxy/#systemd-unit-file)에 대한 이 문서를 확인하세요.

## 아티팩트를 업로드할 때 411을 받음 {#i-get-411-when-uploading-artifacts}

이는 GitLab 러너가 `Transfer-Encoding: chunked`을(를) 사용하기 때문이며 이는 초기 버전의 NGINX(<https://serverfault.com/questions/164220/is-there-a-way-to-avoid-nginx-411-content-length-required-errors>)에서 손상되었습니다.

NGINX를 최신 버전으로 업그레이드합니다. 자세한 내용은 이 문제를 참조하세요: <https://gitlab.com/gitlab-org/gitlab-runner/-/issues/1031>

## 다른 아티팩트 업로드 오류를 보고 있습니다. 어떻게 추가로 디버깅할 수 있습니까? {#i-am-seeing-other-artifact-upload-errors-how-can-i-further-debug-this}

아티팩트는 GitLab 러너 프로세스를 우회하여 빌드 환경에서 GitLab 인스턴스로 직접 업로드됩니다. 예를 들어:

- Docker 실행기를 사용하면 Docker 컨테이너에서 업로드가 발생합니다.
- Kubernetes 실행기를 사용하면 빌드 포드의 빌드 컨테이너에서 업로드가 발생합니다.

빌드 환경에서 GitLab 인스턴스로의 네트워크 경로는 GitLab 러너에서 GitLab 인스턴스로의 경로와 다를 수 있습니다.

아티팩트 업로드를 활성화하려면 업로드 경로의 모든 구성 요소가 빌드 환경에서 GitLab 인스턴스로의 POST 요청을 허용하는지 확인합니다.

기본적으로 아티팩트 업로더는 업로드 URL과 업로드 응답의 HTTP 상태 코드를 기록합니다. 이 정보는 어떤 시스템이 오류를 야기했는지 또는 아티팩트 업로드를 차단했는지 이해하기에 충분하지 않습니다. 아티팩트 업로드 문제를 해결하려면 [디버그 로깅 활성화](https://docs.gitlab.com/ci/variables/#enable-debug-logging)를 사용하여 업로드 시도를 통해 업로드 응답의 헤더와 본문을 확인합니다.

> [!note]
> 아티팩트 업로드 디버그 로깅의 응답 본문 길이는 512바이트로 제한됩니다. 민감한 데이터가 로그에 노출될 수 있으므로 디버깅 목적으로만 로깅을 활성화합니다.

업로드가 GitLab에 도달했지만 오류 상태 코드(예: 성공하지 못한 응답 상태 코드 생성)로 실패하는 경우 GitLab 인스턴스 자체를 조사합니다. 일반적인 아티팩트 업로드 문제는 [GitLab 설명서](https://docs.gitlab.com/administration/cicd/job_artifacts_troubleshooting/#job-artifact-upload-fails-with-error-500)를 참조하세요.

## `No URL provided, cache will not be download`/`uploaded` {#no-url-provided-cache-will-not-be-downloaduploaded}

이 오류는 GitLab 러너 도우미가 유효하지 않은 URL을 받거나 원격 캐시에 액세스할 사전 서명된 URL이 없을 때 발생합니다. 각 [캐시 관련 `config.toml` 항목](../configuration/advanced-configuration.md#the-runnerscache-section) 및 공급자별 키와 값을 검토합니다. 유효하지 않은 URL은 URL 구문 요구 사항을 따르지 않는 모든 항목에서 구성될 수 있습니다.

또한 도우미 `image` 및 `helper_image_flavor`이(가) 일치하고 최신 상태인지 확인합니다.

자격 증명 구성에 문제가 있으면 진단 오류 메시지가 GitLab 러너 프로세스 로그에 추가됩니다.

## 오류: `warning: You appear to have cloned an empty repository.` {#error-warning-you-appear-to-have-cloned-an-empty-repository}

`git clone`을(를) 실행할 때 HTTP(s)를 사용하고 (GitLab 러너 또는 테스트용으로 수동으로) 다음 출력을 볼 수 있습니다:

```shell
$ git clone https://git.example.com/user/repo.git

Cloning into 'repo'...
warning: You appear to have cloned an empty repository.
```

GitLab 서버 설치의 HTTP 프록시 구성이 올바르게 수행되었는지 확인합니다. 자체 구성이 있는 HTTP 프록시를 사용할 때 **GitLab Unicorn socket**이 아닌 **GitLab Workhorse socket**으로 요청이 프록시되는지 확인합니다.

Git 프로토콜은 HTTP(S)를 통해 GitLab 워크호스에 의해 해결되므로 이것이 **main entrypoint** GitLab입니다.

Linux 패키지 설치를 사용 중이지만 번들된 NGINX 서버를 사용하지 않으려면 [번들되지 않은 웹 서버 사용](https://docs.gitlab.com/omnibus/settings/nginx/#use-a-non-bundled-web-server)을(를) 참조하세요.

GitLab 레시피 리포지토리에는 Apache 및 NGINX에 대한 [웹 서버 구성 예](https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server)가 있습니다.

소스에서 설치된 GitLab을 사용 중인 경우 위의 설명서 및 예를 참조하세요. 모든 HTTP(S) 트래픽이 **GitLab 워크호스**를 통해 가는지 확인합니다.

[사용자 문제의 예](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/1105)를 참조하세요.

## 오류: `zoneinfo.zip: no such file or directory` `Timezone` 또는 `OffPeakTimezone`를 사용할 때 오류 {#error-zoneinfozip-no-such-file-or-directory-error-when-using-timezone-or-offpeaktimezone}

`[[docker.machine.autoscaling]]` 기간을 설명하는 시간대를 구성할 수 있습니다. 이 기능은 대부분의 Unix 시스템에서 즉시 작동해야 합니다. 그러나 일부 Unix 시스템 및 대부분의 비 Unix 시스템(예: GitLab 러너 바이너리를 사용할 수 있는 Windows)에서는 러너가 오류로 시작 시 충돌할 수 있습니다:

```plaintext
Failed to load config Invalid OffPeakPeriods value: open /usr/local/go/lib/time/zoneinfo.zip: no such file or directory
```

오류는 Go의 `time` 패키지로 인해 발생합니다. Go는 IANA 시간대 데이터베이스를 사용하여 지정된 시간대의 구성을 로드합니다. 대부분의 Unix 시스템에서 이 데이터베이스는 이미 잘 알려진 경로(`/usr/share/zoneinfo`, `/usr/share/lib/zoneinfo`, `/usr/lib/locale/TZ/`) 중 하나에 있습니다. Go의 `time` 패키지는 이 세 경로 모두에서 시간대 데이터베이스를 찾습니다. 이들 중 찾지 못하면 머신에 Go 개발 환경이 구성되어 있으면 `$GOROOT/lib/time/zoneinfo.zip` 파일로 폴백됩니다.

이러한 경로가 없는 경우(예: 프로덕션 Windows 호스트) 위의 오류가 발생합니다.

시스템이 IANA 시간대 데이터베이스를 지원하지만 기본적으로 사용할 수 없는 경우 설치를 시도할 수 있습니다. Linux 시스템의 경우 예를 들어 다음과 같이 수행할 수 있습니다:

```shell
# on Debian/Ubuntu based systems
sudo apt-get install tzdata

# on RPM based systems
sudo yum install tzdata

# on Linux Alpine
sudo apk add -U tzdata
```

시스템이 _기본_ 방식으로 이 데이터베이스를 제공하지 않는 경우 다음 단계를 따라 `OffPeakTimezone`을(를) 작동시킬 수 있습니다:

1. [`zoneinfo.zip`](https://gitlab-runner-downloads.s3.amazonaws.com/latest/zoneinfo.zip) 다운로드. 버전 v9.1.0부터 태그된 경로에서 파일을 다운로드할 수 있습니다. 그 경우 `latest`를 `zoneinfo.zip` 다운로드 URL의 태그 이름(예: `v9.1.0`)으로 바꿔야 합니다.

1. 이 파일을 알려진 디렉터리에 저장합니다. 우리는 `config.toml` 파일이 있는 동일한 디렉터리를 사용하는 것을 제안합니다. 예를 들어 Windows 머신에서 러너를 호스팅하고 구성 파일이 `C:\gitlab-runner\config.toml`에 저장된 경우 `zoneinfo.zip`을(를) `C:\gitlab-runner\zoneinfo.zip`에 저장합니다.

1. `ZONEINFO` 환경 변수를 `zoneinfo.zip` 파일의 전체 경로로 설정합니다. `run` 명령을 사용하여 러너를 시작하는 경우 다음과 같이 할 수 있습니다:

   ```shell
   ZONEINFO=/etc/gitlab-runner/zoneinfo.zip gitlab-runner run <other options ...>
   ```

   또는 Windows를 사용하는 경우:

   ```powershell
   C:\gitlab-runner> set ZONEINFO=C:\gitlab-runner\zoneinfo.zip
   C:\gitlab-runner> gitlab-runner run <other options ...>
   ```

   GitLab 러너를 시스템 서비스로 시작하는 경우 서비스 구성을 업데이트하거나 재정의해야 합니다:

   - Unix 시스템에서 서비스 관리자 소프트웨어를 통해 설정을 수정합니다.
   - Windows에서 `ZONEINFO` 변수를 시스템 설정을 통해 GitLab 러너 사용자가 사용할 수 있는 환경 변수 목록에 추가합니다.

## GitLab 러너의 인스턴스를 두 개 이상 실행할 수 없는 이유는 무엇입니까? {#why-cant-i-run-more-than-one-instance-of-gitlab-runner}

할 수 있지만 동일한 `config.toml` 파일을 공유하지 않습니다.

동일한 구성 파일을 사용하여 GitLab 러너의 여러 인스턴스를 실행하면 예상치 못한 디버깅하기 어려운 동작이 발생할 수 있습니다. GitLab 러너의 단일 인스턴스만 한 번에 특정 `config.toml` 파일을 사용할 수 있습니다.

## 작업은 시작 전에 지연을 경험합니다. {#jobs-experience-delays-before-starting}

일부 프로젝트의 작업이 시작 전에 상당한 지연을 경험하는 반면 다른 프로젝트의 작업은 즉시 실행되는 경우 장기 폴링 문제가 발생할 수 있습니다.

**Symptoms:**

- 작업은 대기 중이지만 실행을 시작하는 데 비정상적으로 오래 걸립니다(일반적으로 GitLab 인스턴스 장기 폴링 시간 초과와 일치).
- 일부 러너는 고착된 것으로 보이지만 다른 러너는 일반적으로 작업을 처리합니다.
- GitLab 러너 로그는 `CONFIGURATION: Long polling issues detected`을(를) 표시합니다.

**Cause:**

이 문제는 GitLab 러너 워커가 GitLab으로의 장기 폴링 요청에 고착되어 다른 작업이 신속하게 처리되는 것을 방지할 때 발생합니다. 이러한 문제는 구성에 따라 성능 병목 상태부터 완전한 교착 상태까지 다양합니다. 문제는 GitLab Workhorse `apiCiLongPollingDuration` 설정(기본값:으로 제어되는 GitLab CI/CD 장기 폴링 기능과 관련이 있습니다:  50초).

**Solution:**

이러한 문제는 여러 구성 시나리오에서 발생할 수 있습니다. 원인, 구성 예 및 해결책에 대한 포괄적인 정보는 고급 구성 설명서의 [장기 폴링 문제](../configuration/advanced-configuration.md#long-polling-issues) 섹션을 참조하세요.

## `Job failed (system failure): preparing environment:` {#job-failed-system-failure-preparing-environment}

이 오류는 종종 셸의 [프로필 로드](../shells/_index.md#shell-profile-loading) 때문이며 스크립트 중 하나가 실패를 야기합니다.

`dotfiles` 중 알려진 실패의 예:

- `.bash_logout`
- `.condarc`
- `.rvmrc`

SELinux도 이 오류의 원인이 될 수 있습니다. SELinux 감사 로그를 확인하여 이를 확인할 수 있습니다:

```shell
sealert -a /var/log/audit/audit.log
```

## 러너는 `Cleaning up` 단계 후 갑자기 종료 {#runner-abruptly-terminates-after-cleaning-up-stage}

CrowdStrike Falcon Sensor는 "컨테이너 드리프트 감지" 설정이 활성화되었을 때 작업의 `Cleaning up files` 단계 후 포드를 종료하는 것으로 보고되었습니다. 작업이 완료될 수 있도록 하려면 이 설정을 비활성화해야 합니다.

## 작업이 `remote error: tls: bad certificate (exec.go:71:0s)`로 인해 실패합니다. {#job-fails-with-remote-error-tls-bad-certificate-execgo710s}

이 오류는 아티팩트를 생성하는 작업 중에 시스템 시간이 크게 변경될 때 발생할 수 있습니다. 시스템 시간 변경으로 인해 SSL 인증서가 만료되어 러너가 아티팩트를 업로드하려고 할 때 오류가 발생합니다.

SSL 검증이 아티팩트 업로드 중에 성공할 수 있도록 하려면 시스템 시간을 작업 끝에 유효한 날짜 및 시간으로 변경합니다. 아티팩트 파일의 생성 시간도 변경되었으므로 자동으로 보관됩니다.

## Helm 차트: `ERROR .. Unauthorized` {#helm-chart-error--unauthorized}

Helm으로 배포된 러너를 제거하거나 업그레이드하기 전에 GitLab에서 일시 중지하고 모든 작업이 완료될 때까지 기다립니다.

작업이 실행 중인 동안 `helm uninstall` 또는 `helm upgrade`로 러너 포드를 제거하면 작업이 완료될 때 `Unauthorized` 오류와 유사한 오류가 발생할 수 있습니다:

```plaintext
ERROR: Error cleaning up pod: Unauthorized
ERROR: Error cleaning up secrets: Unauthorized
ERROR: Job failed (system failure): Unauthorized
```

이는 러너가 제거될 때 역할 바인딩이 제거되기 때문에 발생할 가능성이 높습니다. 러너 포드는 작업이 완료될 때까지 계속되고 러너가 삭제를 시도합니다. 역할 바인딩이 없으면 러너 포드는 더 이상 액세스할 수 없습니다.

자세한 내용은 [이 문제](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues/225)를 참조하세요.

## Elasticsearch 서비스 시작 오류 `max virtual memory areas vm.max_map_count [65530] is too low` {#elasticsearch-service-startup-error-max-virtual-memory-areas-vmmax_map_count-65530-is-too-low}

Elasticsearch 서비스 컨테이너를 시작할 때 다음과 유사한 오류가 발생할 수 있습니다:

- `max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]`

Elasticsearch에는 Elasticsearch가 실행되는 인스턴스에 설정해야 하는 `vm.max_map_count` 요구 사항이 있습니다. 플랫폼에 따라 이 값을 올바르게 설정하는 방법에 대해 [Elasticsearch 설명서](https://www.elastic.co/docs/deploy-manage/deploy/self-managed/install-elasticsearch-docker-prod)를 참조하세요.

## 오류: `Preparing the "docker+machine" executor ERROR: Preparation failed: exit status 1` {#error-preparing-the-dockermachine-executor-error-preparation-failed-exit-status-1}

이 오류는 Docker 머신이 실행기 가상 머신을 성공적으로 생성할 수 없을 때 발생할 수 있습니다. 오류에 대한 자세한 내용을 얻으려면 `config.toml`에서 정의한 것과 동일한 `MachineOptions`로 가상 머신을 수동으로 만듭니다.

예: `docker-machine create --driver=google --google-project=GOOGLE-PROJECT-ID --google-zone=GOOGLE-ZONE ...`.

## 오류: `No unique index found for name` {#error-no-unique-index-found-for-name}

이 오류는 러너를 생성하거나 업데이트할 때 발생할 수 있으며 데이터베이스에 `tags` 테이블에 대한 고유 인덱스가 없습니다. GitLab UI에서 `Response not successful: Received status code 500` 오류를 받을 수 있습니다.

이 문제는 장시간에 걸쳐 여러 주요 업그레이드를 거친 인스턴스에 영향을 미칠 수 있습니다. 이 문제를 해결하려면 [`gitlab:db:deduplicate_tags` Rake 작업](https://docs.gitlab.com/administration/raketasks/maintenance/#check-the-database-for-duplicate-cicd-tags)으로 테이블의 중복 태그를 통합합니다. 자세한 내용은 [Rake 작업](https://docs.gitlab.com/administration/raketasks/)을(를) 참조하세요.

## 오류: `Not authorized to perform sts:AssumeRoleWithWebIdentity` {#error-not-authorized-to-perform-stsassumerolewithwebidentity}

러너의 Kubernetes ServiceAccount 리소스에 대해 IAM 역할을 구성했지만 러너 로그에 `sts:AssumeRoleWithWebIdentity`을(를) 수행할 수 없다고 표시되면 다음 오류를 받을 수 있습니다:

```plaintext
{"error":"Not authorized to perform sts:AssumeRoleWithWebIdentity","level":"error","msg":"error while generating S3 pre-signed URL","time":"2025-10-15T18:07:20Z"}
```

이 문제는 IAM 역할의 신뢰할 수 있는 엔터티 구성의 `StringLike` 또는 `StringEquals` 조건에 `https://`을(를) 포함할 때 발생합니다.

이 문제를 해결하려면 OIDC URL에서 `https://`을(를) 제거합니다:

```json
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
  "StringLike": {
    "oidc.eks.<AWS_REGION>.amazonaws.com/id/<OIDC_ID>:sub": "system:serviceaccount:<NAMESPACE>:<SERVICE_ACCOUNT>"
  }
}
```
