GitLab Runner 문제 해결

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-Managed

이 섹션은 GitLab Runner를 문제 해결하는 데 도움을 줄 수 있습니다.

참고: 중요 보안 업데이트는 귀하의 그룹 및 프로젝트에 대해 러너 등록 토큰을 재설정할 것입니다. 러너를 등록하기 위해 값의 인코딩을 하는 스크립트(자동화된 프로세스)를 사용하는 경우, 이 업데이트로 그 프로세스가 중단될 것입니다. 그러나, 이전에 등록된 러너에는 영향을 끼치지 않아야 합니다.

일반 문제 해결 팁

로그 보기:

  • tail -100 /var/log/syslog (Debian)
  • tail -100 /var/log/messages (RHEL)
  • docker logs gitlab-runner-container (Docker)
  • kubectl logs gitlab-runner-pod (Kubernetes)

서비스 재시작:

  • service gitlab-runner restart

도커 머신 보기:

  • sudo docker-machine ls
  • sudo su - && docker-machine ls

모든 도커 머신 삭제:

  • docker-machine rm $(docker-machine ls -q)

config.toml를 수정한 후:

  • service gitlab-runner restart
  • docker-machine rm $(docker-machine ls -q)
  • tail -f /var/log/syslog (Debian)
  • tail -f /var/log/messages (RHEL)

GitLab 및 GitLab Runner 버전 확인

GitLab은 하위 호환성을 보장하기 위해 노력합니다. 그러나 먼저 문제 해결 단계로서, GitLab Runner 버전이 GitLab 버전과 동일한지 확인해야 합니다.

coordinator란 무엇을 의미합니까?

coordinator는 작업을 요청하는 GitLab 설치입니다.

다시 말해, 러너는 coordinator(GitLab 설치)로부터 작업을 요청하는 격리된 에이전트입니다(GitLab API를 통해).

Windows 서비스로 실행될 때 로그가 저장되는 위치는 어디입니까?

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

디버그 로깅 모드 활성화

경고: 디버그 로깅은 심각한 보안 리스크가 될 수 있습니다. 결과에는 작업에 사용 가능한 모든 변수 및 기타 비밀이 포함됩니다. 제3자에게 비밀번호를 전달할 수 있는 로그 집계를 비활성화해야 합니다. 마스크된 변수의 사용은 작업 로그 출력에서 보호되도록 하지만 컨테이너 로그에는 보호되지 않습니다.

명령줄에서

터미널에서 root로 로그인한 상태에서 다음을 실행합니다: 

gitlab-runner stop
gitlab-runner --debug run

GitLab Runner config.toml에서

전역 섹션의 config.toml에서 log_level 설정을 debug로 설정함으로써 디버그 로깅을 활성화할 수 있습니다. 다음 줄을 config.toml의 맨 위에 추가합니다(동시성 라인 이전/이후): 

log_level = "debug"

Helm 차트에서

Kubernetes 클러스터에 GitLab Runner를 설치한 경우, values.yaml 사용자 정의에서 logLevel 옵션을 설정함으로써 디버그 로깅을 활성화할 수 있습니다: 

## GitLab Runner 로깅 레벨 구성. 사용 가능한 값: debug, info, warn, error, fatal, panic
## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section
##
logLevel: debug

Docker executor 러너의 DNS 구성

Docker executor를 사용하여 GitLab Runner를 구성할 때, 호스트에서 Runner 데몬이 GitLab에 액세스할 수 있지만 빌드된 컨테이너는 액세스할 수 없는 문제가 발생할 수 있습니다. 이는 호스트에서 DNS가 구성되어 있지만 해당 구성이 컨테이너로 전달되지 않을 때 발생할 수 있습니다.

예시:

GitLab 서비스와 GitLab Runner가 서로 다른 네트워크에 존재하고 두 가지 방법(인터넷 및 VPN을 통해)으로 브릿지된 두 가지 네트워크가 있는 경우. Runner가 GitLab 서비스를 찾기 위해 사용하는 라우팅 메커니즘이 DNS를 쿼리하는 경우, 컨테이너의 DNS 구성은 VPN을 통해 DNS 서비스를 사용해야 한다는 것을 알지 못하고 인터넷을 통해 제공된 DNS를 기본값으로 사용할 수 있습니다. 이 구성으로 인해 다음과 같은 메시지가 표시됩니다: 

새 저장소 생성.
++ echo '새 저장소 생성.'
++ 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: 'https://gitlab.example.com/group/example-project.git/'을(를) 위한 인증에 실패했습니다.

이 경우, 인증 실패는 인터넷과 GitLab 서비스 사이의 서비스에 의해 발생합니다. 이 서비스는 러너가 VPN을 통해 DNS 서비스를 사용하도록 우회하고자 시도한 경우부터 시작됩니다.

config.toml 파일의 [runners.docker] 섹션에서 dns 구성을 사용하여 Docker에게 사용할 DNS 서버를 알려줄 수 있습니다. 

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

x509: certificate signed by unknown authority 오류가 표시됩니다.

자체 서명된 인증서에 대해서는 여기를 참조하세요.

/var/run/docker.sock에 액세스할 때 Permission Denied 오류가 발생합니다.

Docker executor를 사용하려면 서버에 설치된 Docker Engine에 연결해야 합니다. Permission Denied 오류가 표시되면 시스템이 기본적으로 CentOS, Fedora 및 RHEL에서 활성화된 SELinux를 사용하고 있을 가능성이 가장 큽니다. 가능한 거부 사항에 대한 시스템의 SELinux 정책을 확인하세요.

Docker-machine 오류: Unable to query docker version: Cannot connect to the docker engine endpoint.

이 오류는 머신 프로비저닝과 관련이 있으며 다음과 같은 이유로 발생할 수 있습니다:

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

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

    러너가 재시작되면 인증서가 비어 있는 것으로 확인하고 재생성합니다.

  • 호스트 이름이 프로비저닝된 머신에서 지원되는 길이를 초과합니다. 예를 들어 Ubuntu 머신은 HOST_NAME_MAX에 64자 제한이 있습니다. 호스트 이름은 docker-machine ls로 보고됩니다. 필요에 따라 실행 구성의 MachineName에서 호스트 이름 길이를 줄이세요.

참고: 이 오류는 Docker가 머신에 설치되기 전에 발생할 수 있습니다.

dialing environment connection: ssh: rejected: connect failed (open failed) 오류

이 오류는 Docker 자동 스케일러가 SSH를 통해 터널링된 상태에서 대상 시스템에서 Docker 데몬에 연결할 수 없을 때 발생할 수 있습니다. 대상 시스템에 SSH로 연결하고 docker info와 같은 Docker 명령을 성공적으로 실행할 수 있는지 확인하세요.

autoscaled 러너에 AWS 인스턴스 프로필 추가하기

AWS IAM 역할을 생성한 후 IAM 콘솔에서 역할에는 Role ARN 및 인스턴스 프로필 ARN이 있습니다. 인스턴스 프로필 이름을 사용해야 하며 역할 이름을 사용해서는 안 됩니다.

다음 값을 [runners.machine] 섹션에 추가하세요: "amazonec2-iam-instance-profile=<인스턴스 프로필 이름>",

Java 프로젝트 빌드 중 Docker executor가 타임아웃이 발생합니다

가장 가능성이 높은 이유는 손상된 AUFS 스토리지 드라이버 때문입니다: 컨테이너 내에서 Java 프로세스가 중단됨. 가장 좋은 해결책은 저장 드라이버를 OverlayFS(빠름) 또는 DeviceMapper(느림)로 변경하는 것입니다.

Docker 구성 및 실행에 대한 기사나 systemd로 제어 및 구성에 대한 기사를 확인하세요.

아티팩트를 업로드할 때 411 오류가 발생합니다

이 오류는 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.

No URL provided, cache will not be download/uploaded 오류

이는 작업에 대해 캐싱이 구성되었지만 GitLab 러너 도우미가 원격 캐시에 액세스할 수 있는 미리 서명된 URL이나 잘못된 URL이 없을 때 발생합니다. 각 캐시 관련 ‘config.toml’ 항목 및 특정 공급자 키와 값을 검토하세요. 잘못된 URL은 URL 구문 요구 사항을 따르지 않는 항목에서 생성할 수 있습니다.

또한 도우미 이미지 및 helper_image_flavor가 일치하고 최신 상태인지 확인하세요.

인증 구성에 문제가 있는 경우 GitLab 러너 프로세스 로그에 진단 오류 메시지가 추가됩니다.

오류: warning: You appear to have cloned an empty repository.

HTTP(s)를 사용하여 git clone을 실행하고 다음 내용이 표시되는 경우(예: GitLab 러너를 사용하거나 테스트를 위해 수동으로): 

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

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

GitLab 서버 설치의 HTTP 프록시 구성이 올바르게 수행되었는지 확인하세요. 특히 독자적인 구성을 사용하는 경우 GitLab 요청이 GitLab Unicorn 소켓이 아니라 GitLab Workhorse 소켓으로 프록시되도록 확인하세요.

HTTP(S)를 통해 Git 프로토콜이 해결되기 때문에 GitLab Workhorse가 이를 처리하므로 이것이 GitLab의 주요 진입점입니다.

Linux 패키지 설치를 사용하면서 번들된 NGINX 서버를 사용하지 않으려면 번들되지 않은 웹 서버 사용 도구를 참조하세요.

GitLab Recipes 저장소에는 Apache 및 NGINX에 대한 웹 서버 구성 예제가 있습니다.

소스에서 설치한 GitLab을 사용하고 있다면 위의 설명 및 예제를 읽고 모든 HTTP(S) 트래픽이 GitLab Workhorse를 통해 전송되도록 확인하세요.

사용자 이슈 예제를 확인하려면 여기에 들어가세요.

오류: zoneinfo.zip: no such file or directory를 사용하여 Timezone 또는 OffPeakTimezone 사용 시 발생하는 오류

[[docker.machine.autoscaling]] 기간에 설명된 시간대를 구성하는 것이 가능합니다. 이 기능은 대부분의 Unix 시스템에서 기본적으로 작동해야 합니다. 그러나 일부 Unix 시스템 및 아마도 Windows를 포함한 대부분의 비-Unix 시스템(우리가 GitLab Runner 이진 파일을 제공하는 시스템 포함)에서 사용 시, 실행 중에 다음과 유사한 오류로 러너가 시작할 때 충돌할 수 있습니다. 

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 시스템의 경우, 다음과 같이 수행할 수 있습니다. 

# Debian/Ubuntu 기반 시스템의 경우
sudo apt-get install tzdata

# RPM 기반 시스템의 경우
sudo yum install tzdata

# Linux Alpine의 경우
sudo apk add -U tzdata

시스템이 이 데이터베이스를 기본적으로 제공하지 않는 경우, 다음 단계를 따라 OffPeakTimezone을 작동시킬 수 있습니다.

  1. zoneinfo.zip을 다운로드합니다. 버전 v9.1.0부터는 태그 된 경로에서 파일을 다운로드할 수 있습니다. 이 경우 zoneinfo.zip 다운로드 URL에서 latest를 태그명(예: v9.1.0)으로 대체해야 합니다.

  2. 이 파일을 잘 알려진 디렉터리에 저장합니다. config.toml 파일이 있는 디렉터리를 사용하는 것을 권장합니다. 예를 들어, Windows 머신에서 Runner를 호스팅하고 구성 파일이 C:\gitlab-runner\config.toml에 저장되어 있는 경우, zoneinfo.zip 파일을 C:\gitlab-runner\zoneinfo.zip에 저장합니다.

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

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

    Windows를 사용하는 경우: 

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

    GitLab Runner를 시스템 서비스로 시작하는 경우, 서비스 구성을 업데이트/재정의해야 합니다(유닉스 시스템) 또는 Windows의 시스템 설정을 통해 GitLab Runner 사용자의 환경 변수 목록에 ZONEINFO 변수를 추가해야 합니다.

왜 GitLab Runner의 여러 인스턴스를 실행할 수 없을까요?

가능합니다. 그러나 동일한 config.toml 파일을 공유하지 않아야 합니다.

동일한 구성 파일을 사용하여 GitLab Runner의 여러 인스턴스를 실행하면 예기치 않은 결과 및 디버깅이 어렵게 발생할 수 있습니다. 한 번에 한 개의 GitLab Runner 인스턴스만 특정 config.toml 파일을 사용할 수 있습니다.

Job failed (system failure): preparing environment:

이 오류는 종종 셸이 프로필을 로드하고 스크립트 중 하나가 실패하는 것으로 인해 발생합니다.

오류를 유발하는 알려진 닷 파일 예시:

  • .bash_logout
  • .condarc
  • .rvmrc

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

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

Cleaning up 단계 후 러너가 갑자기 종료됨

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

remote error: tls: bad certificate (exec.go:71:0s)로 작업이 실패함

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

아티팩트 업로드 중 SSL 확인을 성공시키기 위해, 작업의 끝에 시스템 시간을 다시 유효한 날짜와 시간으로 변경하세요. 아티팩트 파일의 생성 시간도 변경되었기 때문에, 이러한 파일들이 자동으로 아카이빙됩니다.

Helm 차트: ERROR .. Unauthorized

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

작업이 실행 중일 때 helm uninstall 또는 helm upgrade로 러너 팟을 제거하는 경우 다음과 같은 Unauthorized 오류가 작업 완료 시 발생할 수 있습니다. 

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

이는 러너를 제거하면 역할 연결이 제거되어 발생하는 것으로 보입니다. 작업이 완료될 때까지 러너 팟은 계속 유지되며, 그런 다음 러너는 해당 팟을 삭제하려고 시도합니다. 러너 팟은 더 이상 엑세스할 수 없게 됩니다.

자세한 내용은 이 문제를 참조하세요.

Elasticsearch 서비스 컨테이너 시작 오류 max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]

Elasticsearch에는 실행되는 인스턴스에 설정해야 하는 vm.max_map_count 요구 사항이 있습니다.

플랫폼에 따라 이 값을 올바르게 설정하는 방법은 Elasticsearch 문서를 참조하세요.

Preparing the "docker+machine" executor ERROR: Preparation failed: exit status 1 Will be retried in 3s

이 오류는 Docker 머신이 실행자 가상 머신을 성공적으로 생성하지 못할 때 발생할 수 있습니다. 오류에 대한 자세한 정보를 얻으려면 config.toml에서 정의한 MachineOptions와 동일한 가상 머신을 수동으로 만들어보세요.

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