GitLab Runner 문제 해결

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

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

note
중요 보안 릴리스는 귀하의 그룹 및 프로젝트에 대한 러너 등록 토큰을 재설정합니다. 자동화된 프로세스(등록 토큰의 값을 인코딩하는 스크립트)를 사용하여 러너를 등록하는 경우, 이 업데이트는 그 프로세스를 방해할 것입니다. 그러나 이전에 등록된 러너에는 영향을 주지 않아야 합니다.

일반적인 문제 해결 팁

로그 보기

GitLab Runner 서비스는 syslog에 로그를 전송합니다. 로그를 보려면 배포 문서를 참조하세요.
배포본에 journalctl 명령이 포함되어 있는 경우, 다음 명령을 사용하여 로그를 볼 수 있습니다:

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

서비스 재시작 

systemctl restart gitlab-runner.service

Docker 머신 보기 

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

모든 Docker 머신 삭제 

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

config.toml 변경 사항 적용 

systemctl restart gitlab-runner.service
docker-machine rm $(docker-machine ls -q) # Docker machine
journalctl --unit=gitlab-runner.service -f # 로그를 tail하여 잠재적인 오류 확인

GitLab 및 GitLab Runner 버전 확인

GitLab은 하위 호환성을 보장하는 것을 목표로 합니다.
그러나 첫 번째 문제 해결 단계로, GitLab Runner 버전이 GitLab 버전과 동일한지 확인해야 합니다.

coordinator는 무엇을 의미하나요?

coordinator는 작업 요청이 이루어지는 GitLab 설치입니다.

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

Windows에서 서비스로 실행될 때 로그는 어디에 저장되나요?

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

디버그 로깅 모드 활성화

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

명령 줄에서

터미널에서 루트로 로그인한 다음, 다음을 실행합니다.

caution
이 작업은 Shell executor를 사용하는 러너에서 수행해서는 안 됩니다. 왜냐하면 이 작업은 systemd 서비스를 재정의하고 모든 작업을 루트로 실행하기 때문입니다. 이로 인해 보안 위험이 발생하고 파일 소유권에 대한 변경이 이루어져 특권이 없는 계정으로 되돌리기 어렵게 됩니다.
gitlab-runner stop
gitlab-runner --debug run

GitLab Runner의 config.toml에서

디버그 로깅은 config.toml의 글로벌 섹션에서 log_level 설정을 debug로 설정하여 활성화할 수 있습니다. 다음 행을 config.toml의 가장 상단, concurrency 행 앞 또는 뒤에 추가하세요:

log_level = "debug"

Helm 차트에서

GitLab Runner가 GitLab Runner Helm 차트를 사용하여 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 실행자 러너를 위한 DNS 구성

Docker 실행자와 함께 GitLab Runner를 구성할 때, 호스트의 Runner 데몬은 GitLab에 접근할 수 있지만, 빌드된 컨테이너는 접근할 수 없는 문제가 발생할 수 있습니다. 이는 호스트에서 DNS가 구성되었지만 해당 구성들이 컨테이너에 전달되지 않을 때 발생할 수 있습니다.

예시:

GitLab 서비스와 GitLab Runner가 두 개의 서로 다른 네트워크에 존재하며, 두 가지 방식으로 연결되어 있습니다(예: 인터넷을 통해 또는 VPN을 통해). Runner가 GitLab 서비스를 찾기 위해 사용하는 라우팅 메커니즘이 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 서비스 간의 중간에 있는 서비스 때문입니다. 이 서비스는 별도의 자격 증명을 사용하며, Runner가 VPN을 통한 DNS 서비스를 사용했다면 이를 우회할 수 있습니다.

Docker에 사용할 DNS 서버를 지정할 수 있으며, 이는 Runner의 config.toml 파일의 [runners.docker] 섹션의 dns 구성 사용하여 할 수 있습니다.

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

x509: certificate signed by unknown authority 오류 발생

자체 서명된 인증서를 참조하세요.

/var/run/docker.sock에 접근할 때 Permission Denied 오류 발생

Docker 실행자를 사용하려면, 서버에 설치된 Docker 엔진에 연결하고 있습니다. 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을 확인하고 필요한 경우 호스트명 길이를 줄이세요.

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

다이얼링 환경 연결: ssh: 거부됨: 연결 실패 (열기 실패)

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

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

AWS IAM 역할을 생성한 후, IAM 콘솔에서 역할에는 Role ARN과 Instance Profile ARNs가 있습니다. Role Name이 아니라 Instance Profile 이름을 사용해야 합니다.

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

Java 프로젝트를 빌드할 때 Docker 실행자가 시간 초과 발생

이는 AUFS 스토리지 드라이버가 손상되어 발생하는 경우가 가장 많습니다: Java 프로세스가 컨테이너 내부에서 정지됨.

가장 좋은 해결책은 스토리지 드라이버를 OverlayFS(더 빠름) 또는 DeviceMapper(더 느림)로 변경하는 것입니다.

Docker 구성 및 실행에 대한 이 기사를 확인하세요.

또는 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일 때 발생합니다.

각 캐시 관련 config.toml 항목과 공급자별 키 및 값을 검토하세요.

잘못된 URL은 URL 구문 요구 사항을 따르지 않는 항목에서 구성될 수 있습니다.

또한, 헬퍼 image와 helper_image_flavor가 일치하고 최신인지 확인하세요.

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

오류: 경고: 빈 리포지토리를 복제한 것 같습니다.

git clone을 사용하여 HTTP(S)로 실행할 때(GitLab Runner 또는 수동 테스트) 다음과 같은 출력이 표시됩니다:

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

'repo'로 복제 중...
경고: 빈 리포지토리를 복제한 것 같습니다.

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 시스템에서, 그리고 아마도 대부분의 비-Unix 시스템(Windows 포함, GitLab Runner 바이너리를 제공하는 시스템)에서는 사용 시, 러너가 시작할 때 다음과 유사한 오류로 충돌합니다:

구성 로드 실패 OffPeakPeriods 값이 잘못됨: 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 머신에서 러너를 호스팅하고 구성 파일이 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 <다른 옵션 ...>

    또는 Windows를 사용하는 경우:

    C:\gitlab-runner> set ZONEINFO=C:\gitlab-runner\zoneinfo.zip
C:\gitlab-runner> gitlab-runner run <다른 옵션 ...>

    GitLab Runner를 시스템 서비스로 시작하는 경우, 서비스 구성 업데이트/오버라이드 방법은 서비스 관리자 소프트웨어에 따라 다르며(unix 시스템), 또는 시스템 설정을 통해 GitLab Runner 사용자에게 사용할 수 있는 환경 변수 목록에 ZONEINFO 변수를 추가해야 합니다(Windows).

왜 GitLab Runner의 인스턴스를 두 개 이상 실행할 수 없나요?

하나의 config.toml 파일을 공유하지 않는다면 가능합니다.

동일한 구성 파일을 사용하여 여러 인스턴스의 GitLab Runner를 실행하면 예상치 못한 동작과 디버깅하기 힘든 문제가 발생할 수 있습니다. 특정 config.toml 파일을 사용할 수 있는 GitLab Runner의 인스턴스는 하나만 있어야 합니다.

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

이 오류는 종종 쉘이 프로필을 로드할 때 발생하며, 해당 스크립트 중 하나가 오류를 유발하고 있습니다.

오류를 유발하는 것으로 알려진 dotfiles의 예:

  • .bash_logout
  • .condarc
  • .rvmrc

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

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

정리 단계 후 Runner가 갑자기 종료됨

CrowdStrike Falcon Sensor는 “컨테이너 드리프트 감지” 설정이 활성화된 경우 작업의 파일 정리 단계 후에 pods를 종료시키는 것으로 보고되었습니다. 작업이 완료될 수 있도록 하려면 이 설정을 비활성화해야 합니다.

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

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

아티팩트 업로드 중 SSL 검증이 성공할 수 있도록 작업이 끝날 때 시스템 시간을 유효한 날짜와 시간으로 되돌리세요. 아티팩트 파일의 생성 시간이 변경되었기 때문에, 이들은 자동으로 아카이브됩니다.

Helm 차트: ERROR .. Unauthorized

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

작업이 실행 중인 상태에서 helm uninstall 또는 helm upgrade로 Runner pod를 제거하면 작업이 완료될 때 다음과 같은 Unauthorized 오류가 발생할 수 있습니다:

ERROR: pod 정리 중 오류: Unauthorized
ERROR: 비밀 정리 중 오류: Unauthorized
ERROR: 작업 실패 (시스템 오류): Unauthorized

이는 Runner가 제거될 때 역할 바인딩이 제거되기 때문에 발생합니다. Runner pod는 작업이 완료될 때까지 계속 실행되며, 그런 후 Runner가 이를 삭제하려고 시도합니다. 역할 바인딩이 없으면 Runner pod는 더 이상 접근할 수 없습니다.

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

Elasticsearch 서비스 컨테이너 시작 오류 max virtual memory areas vm.max_map_count [65530]이 너무 낮습니다. 최소 [262144]로 증가시켜야 합니다.

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

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

docker+machine 실행기 준비 중 오류 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 ....

고유 인덱스가 이름을 찾을 수 없습니다

이 오류는 러너를 생성하거나 업데이트할 때 발생할 수 있으며

데이터베이스에 tags 테이블에 대한 고유 인덱스가 없을 경우 발생합니다.

GitLab UI에서는 Response not successful: Received status code 500 오류가 발생할 수 있습니다.

이 문제는 여러 주요 업그레이드를 거친 장기 실행 인스턴스에 영향을 줄 수 있습니다.

이 문제를 해결하려면:

  1. Rails 콘솔에서 테이블에 존재할 수 있는 중복 태그를 통합하기 위해 dedupe.rb 스크립트를 실행합니다.

  2. tags 테이블에 대한 고유 인덱스를 생성합니다:

    DROP INDEX IF EXISTS index_tags_on_name; -- 잘못된 인덱스일 수 있는 인덱스 삭제
CREATE UNIQUE INDEX index_tags_on_name ON tags USING btree (name);