GitLab Runner 문제 해결

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

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

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

일반 해결 방법 팁

로그 보기:

  • 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를 서비스로 실행하는 경우 시스템 이벤트 로그가 생성됩니다. 이를 보려면 이벤트 뷰어를 열고(실행 메뉴에서 eventvwr.msc를 입력하거나 “이벤트 뷰어”를 검색합니다) Windows 로그 > 응용 프로그램으로 이동합니다. Runner 로그의 Source는 gitlab-runner입니다. Windows Server Core를 사용하는 경우 다음 PowerShell 명령을 실행하여 마지막 20개 로그 항목을 얻을 수 있습니다: get-eventlog Application -Source gitlab-runner -Newest 20 | format-table -wrap -auto.

디버그 로깅 모드 활성화

caution
디버그 로깅은 심각한 보안 위험을 초래할 수 있습니다. 출력에는 작업에서 사용 가능한 모든 변수 및 기타 비밀이 포함됩니다. 제3자에게 비밀을 전송할 수 있는 모든 로그 집계를 비활성화해야 합니다. 가령 마스킹된 변수 사용으로 작업 로그 출력에는 비밀이 보호되지만 컨테이너 로그에는 보호되지 않습니다.

명령 줄에서

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

caution
Shell executor를 사용하는 러너에 대해 이 작업을 수행해서는 안 됩니다. 이는 systemd 서비스를 재정의하고 모든 작업을 root로 실행하기 때문에 보안 위험을 야기하며 파일 소유권 변경으로 일반 계정으로 되돌리기가 어려워집니다.
gitlab-runner stop
gitlab-runner --debug run

GitLab Runner의 config.toml에서

전역 섹션의 config.toml에서 log_level 설정을 debug로 설정하여 디버그 로깅을 활성화할 수 있습니다. 다음 줄을 config.toml의 맨 위에 추가하고 concurrent 라인 전/후에 추가합니다. 

log_level = "debug"

Helm 차트에서

만일 GitLab Runner가 Helm Chart를 사용하여 Kubernetes 클러스터에 설치되었다면, values.yaml 사용자 정의에서 logLevel 옵션을 사용하여 디버그 로깅을 활성화할 수 있습니다. 

## GitLab Runner 로깅 수준 설정. 가능한 값은: debug, info, warn, error, fatal, panic
## 참조: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section
##
logLevel: debug

Docker executor 러너를 위한 DNS 구성

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

예시:

GitLab 서비스와 GitLab Runner가 두 가지 다른 네트워크에 존재하며(예: 인터넷 및 VPN을 통해 브리지된 네트워크), 러너가 GitLab 서비스를 찾는 라우팅 메커니즘이 VPN을 통해 DNS를 쿼리할 경우 컨테이너의 DNS 구성은 VPN을 통해 DNS 서비스를 사용하도록 알지 못하고 기본적으로 인터넷을 통해 제공된 DNS를 사용하게 됩니다. 이 구성은 다음 메시지를 유발합니다: 

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 서비스를 사용했다면 이 서비스는 별도의 자격 증명을 사용하는 것인데, 이는 러너가 회피할 수 있었을 것입니다.

러너의 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 오류가 발생할 수 있습니다. 가장 가능성이 높은 원인은 시스템이 SELinux를 사용하는 경우(기본적으로 CentOS, Fedora 및 RHEL에서 활성화)입니다. 가능한 거부 사항을 찾기 위해 시스템에서 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을 확인하고 필요한 경우 호스트 이름 길이를 줄입니다.

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

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

이 오류는 Docker 오토스케일러가 대상 시스템의 Docker 데몬에 연결하지 못할 때 발생할 수 있습니다. 연결이 SSH를 통해 터널링될 때 보입니다. 대상 시스템으로 SSH 연결하고 성공적으로 Docker 명령을 실행할 수 있는지 확인하세요. 예를 들어 docker info를 실행합니다.

AWS 인스턴스 프로필을 자동 확장 러너에 추가하기

AWS IAM 역할을 작성한 후 IAM 콘솔에서 역할은 Role ARN 및 Instance Profile ARNs을 가집니다. Role Name이 아닌 Instance Profile 이름을 사용해야 합니다.

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

Java 프로젝트를 빌드할 때 Docker executor가 타임아웃되는 문제

이는 아마도 끊어진 AUFS 리포지터리 드라이버 때문일 가능성이 가장 높습니다: Java process hangs on inside container. 가장 좋은 해결책은 storage driver 을 OverlayFS(빠름) 또는 DeviceMapper(느림)로 변경하는 것입니다.

configuring and running Docker 에 대한 이 기사를 확인하거나 control and configure with systemd에 대한 이 기사를 확인하십시오.

아티팩트를 업로드할 때 411 오류가 발생하는 문제

이 문제는 GitLab Runner가 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

URL이 제공되지 않았으므로 캐시를 다운로드/업로드할 수 없음

작업에 대해 캐싱이 구성되어 있지만 GitLab Runner 헬퍼에는 원격 캐시에 액세스하기 위한 미리 서명된 URL이나 잘못된 URL이 없을 때 발생합니다. 각 cache-related config.toml entry 및 공급업체별 키 및 값에 대해 검토하십시오. 유효하지 않은 URL은 URL 구문 요구 사항을 따르지 않는 항목에서 구성될 수 있습니다.

또한 헬퍼 image 및 helper_image_flavor가 일치하고 최신 상태인지 확인하십시오.

자격 증명 구성에 문제가 있는 경우, GitLab Runner 프로세스 로그에 진단 오류 메시지가 추가됩니다.

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

HTTP(s)를 사용하여 git clone을 실행할 때( GitLab Runner 또는 테스트를 위해 매뉴얼으로) 다음 출력이 표시되는 경우: 

$ 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 요청이 GitLab Workhorse 소켓이 아닌 GitLab Unicorn 소켓으로 프록시되지 않도록 해야 합니다.

HTTP(S)를 통한 Git 프로토콜은 GitLab Workhorse에 의해 해석되므로 이것이 GitLab의 주요 진입점입니다.

리눅스 패키지 설치를 사용하고 있지만 묶인 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 시스템에서) 사용할 때 시작할 때 러너가 다음과 유사한 오류로 중단될 수 있습니다: 

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 패키지는 이 세 경로에 있는 모든 TimeZone 데이터베이스를 찾습니다. 그 중 어느 것도 찾지 못하면서 시스템이 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를 시스템 서비스로 시작하는 경우 서비스 설정을 업데이트/재정의해야 합니다(유닉스 시스템) 또는 시스템 설정을 통해 GitLab Runner 사용자에게 사용 가능한 환경 변수 디렉터리에 ZONEINFO 변수를 추가하여 설정하세요 (Windows).

왜 GitLab Runner를 하나 이상의 인스턴스로 실행할 수 없을까요?

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

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

작업 실패 (시스템 실패): 환경 준비 중:

이 오류는 종종 쉘에서 프로필을 로드하고 있는데, 이러한 스크립트 중 하나가 실패의 원인이 될 수 있습니다.

실패의 원인이 될 수 있는 도트 파일(dotfiles)의 예시:

  • .bash_logout
  • .condarc
  • .rvmrc

또한 SELinux가 이 오류의 주범이 될 수 있습니다. SELinux 감사 로그를 확인하여 이를 확인할 수 있습니다: 

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

Cleaning up 단계 이후 Runner가 갑자기 종료됨

“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

이는 러너가 제거될 때 역할(Role) 바인딩이 제거되기 때문으로 추측됩니다. 러너 포드는 작업이 완료될 때까지 계속되고, 그런 다음 러너는 이를 삭제하려고 합니다.
역할 바인딩이 없으면 러너 포드는 더 이상 액세스할 수 없습니다.

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

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 문서를 참조하세요.

docker+machine executor 준비 중 오류: 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 ....