- 지원되는 옵션 For Self-signed certificates targeting the GitLab server
- Docker 및 Kubernetes 엑스큐터용 TLS 인증서 신뢰
- Troubleshooting
Self-signed certificates or custom Certification Authorities
- GitLab Runner 0.7.0에서 소개되었습니다.
GitLab Runner은 TLS 피어를 확인하기 위해 사용될 인증서를 구성하는 두 가지 옵션을 제공합니다:
-
GitLab 서버에 대한 연결: 자세한 내용은 GitLab 서버를 대상으로 하는 자체 서명 인증서의 지원되는 옵션 섹션에 설명된대로 인증서 파일을 지정할 수 있습니다.
이는 러너를 등록할 때
x509: certificate signed by unknown authority문제를 해결합니다.기존 러너의 경우 작업을 확인하려고 할 때도 같은 오류가 러너 로그에 표시됩니다:
https://hostname.tld/api/v4/jobs/request에 대한 POST를 실행할 수 없습니다: Post https://hostname.tld/api/v4/jobs/request: x509: certificate signed by unknown authority -
사용자 스크립트, 캐시 서버 또는 외부 Git LFS 리포지터리와 같은 다른 시나리오도 포함하는 보다 일반적인 방법: 도커 및 쿠버네티스 실행기용 TLS 인증서 신뢰 섹션에 설명된대로 인증서를 지정하고 컨테이너에 설치할 수 있습니다.
인증서가 없는 Git LFS 작업에 관한 예상 작업 로그 오류:
LFS: Get https://object.hostname.tld/lfs-dev/c8/95/a34909dce385b85cee1a943788044859d685e66c002dbf7b28e10abeef20?X-Amz-Expires=600&X-Amz-Date=20201006T043010Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=svcgitlabstoragedev%2F20201006%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=012211eb0ff0e374086e8c2d37556f2d8ca4cc948763e90896f8f5774a100b55: x509: certificate signed by unknown authority
지원되는 옵션 For Self-signed certificates targeting the GitLab server
이 섹션은 GitLab 서버만 사용자 지정 인증서가 필요한 상황을 가리킵니다. 다른 호스트(예: 프록시 다운로드 활성화되지 않은 오브젝트 스토리지 서비스)도 사용자 지정 CA(Certificate Authority) 인증서가 필요한 경우, 다음 섹션(도커 및 쿠버네티스 실행기용 TLS 인증서 신뢰)을 참조하세요.
GitLab Runner은 다음 옵션을 지원합니다:
-
기본값 - 시스템 인증서를 읽기: GitLab Runner는 시스템 인증서 리포지터리를 읽고 GitLab 서버를 시스템에 저장된 인증 기관(CA)와 대조합니다.
-
사용자 지정 인증서 파일 지정: GitLab Runner는 등록시 (
gitlab-runner register --tls-ca-file=/path)와config.toml의[[runners]]섹션에서tls-ca-file옵션을 노출합니다. 이를 사용하여 사용자 지정 인증서 파일을 지정할 수 있습니다. 이 파일은 러너가 GitLab 서버에 액세스하려고 할 때마다 읽힐 것입니다. GitLab Runner를 Helm 차트로 사용 중이라면 GitLab에 액세스하기 위한 사용자 정의 인증서 제공에 설명된대로 인증서를 구성해야 합니다. -
PEM 인증서 읽기: GitLab Runner는 미리 정의된 파일에서 PEM 인증서 (DER 형식은 지원되지 않음)를 읽습니다:
- *nix 시스템에서 GitLab Runner를
root로 실행하면/etc/gitlab-runner/certs/gitlab.example.com.crt. - *nix 시스템에서 GitLab Runner를
root로 실행하지 않으면~/.gitlab-runner/certs/gitlab.example.com.crt. - 다른 시스템에서는
./certs/gitlab.example.com.crt. Windows 서비스로 GitLab Runner를 실행 중이라면 작동하지 않습니다. 대신 사용자 지정 인증서 파일을 지정하세요.
- *nix 시스템에서 GitLab Runner를
-
GitLab 서버 인증서가 CA 인증서에 의해 서명된 경우, GitLab 서버에 서명된 인증서가 아닌 CA 인증서를 사용하세요. 중간 인증서를 체인에 추가해야 할 수도 있습니다. 예를 들어, 기본, 중간 및 루트 인증서가 있는 경우 이 모두를 하나의 파일에 넣을 수 있습니다:
-----BEGIN CERTIFICATE----- (기본 SSL 인증서: your_domain_name.crt) -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- (중간 인증서) -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- (루트 인증서) -----END CERTIFICATE----- - 기존 러너의 인증서를 업데이트하는 경우 다시 시작해야 합니다.
- 이미 HTTP를 통해 Runner를 구성한 경우
config.toml에서 GitLab 인스턴스 경로를 새로운 HTTPS URL로 업데이트하세요. - 인증서 검증을 건너뛰기 위해
.gitlab-ci.yml파일의variables:섹션에서 CI 변수GIT_SSL_NO_VERIFY를true로 설정하는 임시 및 무보안한 해결책으로 사용하세요.
Git 클론
러너(runner)는 CI_SERVER_TLS_CA_FILE을 사용하여 빌드 CA 체인을 구축하여 빠진 인증서를 삽입합니다.
이를 통해 git clone 및 아티팩트가 공개 신뢰 인증서를 사용하지 않는 서버와 작동할 수 있게 됩니다.
이 접근 방식은 안전하지만, 러너(runner)를 단일 신뢰 지점으로 만듭니다.
Docker 및 Kubernetes 엑스큐터용 TLS 인증서 신뢰
컨테이너에 인증서를 등록하는 경우 고려해야 할 두 가지 상황이 있습니다.
- 사용자 스크립트를 실행하는 데 사용되는 사용자 이미지입니다. 사용자 스크립트의 인증서를 신뢰할 필요가 있는 시나리오의 경우 이미지 자체에 매우 의존적이기 때문에, 각 가능한 시나리오에서 인증서를 설치하는 방법을 러너(runner)가 알 수 없습니다. 따라서 사용자가 인증서를 어떻게 설치할지에 대한 책임을 져야 합니다.
- Git, 아티팩트 및 캐시 작업을 처리하는 데 사용되는 러너(runner) 헬퍼 이미지입니다.
다른 CI/CD 단계에 대한 인증서를 신뢰해야 하는 시나리오의 경우 사용자는 특정 위치(예:
/etc/gitlab-runner/certs/ca.crt)에 인증서 파일을 제공하면 됩니다. Docker 컨테이너는 이를 사용자를 위해 자동으로 설치합니다.
사용자 스크립트용 인증서 신뢰
빌드 스크립트가 TLS를 통해 동료들과 통신해야 하고 자체 서명 인증서 또는 사용자 지정 CA에 의존해야 하는 경우, 사용자 스크립트를 실행하는 Docker 컨테이너에는 기본적으로 인증서 파일이 설치되어 있지 않습니다. 이를 사용하려면 빌드 작업에서 인증서를 설치해야 할 수 있습니다.
인증서 설치 방법:
-
해당 파일을 Docker 볼륨으로 매핑하여 스크립트를 실행할 Docker 컨테이너에서 이를 볼 수 있게 합니다. 이를
config.toml파일의[runners.docker]내에서 볼륨을 추가하여 수행합니다. 예를 들어:-
Linux:
[[runners]] name = "docker" url = "https://example.com/" token = "TOKEN" executor = "docker" [runners.docker] image = "ubuntu:latest" # 볼륨 디렉터리에 ca.crt 파일의 경로 추가 volumes = ["/cache", "/path/to-ca-cert-dir/ca.crt:/etc/gitlab-runner/certs/ca.crt:ro"]
-
-
Linux 전용:
pre_build_script에서 매핑된 파일 (예:ca.crt)을 다음과 같이 사용합니다:- Docker 컨테이너 내의
/usr/local/share/ca-certificates/ca.crt로 복사합니다. -
update-ca-certificates --fresh를 실행하여 설치합니다. 예를 들어 (명령어는 사용 중인 배포판에 따라 다를 수 있음):-
Ubuntu에서:
[[runners]] name = "docker" url = "https://example.com/" token = "TOKEN" executor = "docker" # 각 작업 전에 CA 인증서를 복사하고 설치합니다 pre_build_script = """ apt-get update -y > /dev/null apt-get install -y ca-certificates > /dev/null cp /etc/gitlab-runner/certs/ca.crt /usr/local/share/ca-certificates/ca.crt update-ca-certificates --fresh > /dev/null """ -
알파인에서:
[[runners]] name = "docker" url = "https://example.com/" token = "TOKEN" executor = "docker" # 각 작업 전에 CA 인증서를 복사하고 설치합니다 pre_build_script = """ apk update >/dev/null apk add ca-certificates > /dev/null rm -rf /var/cache/apk/* cp /etc/gitlab-runner/certs/ca.crt /usr/local/share/ca-certificates/ca.crt update-ca-certificates --fresh > /dev/null """
-
- Docker 컨테이너 내의
GitLab 서버 CA 인증서만 필요한 경우, CI_SERVER_TLS_CA_FILE 변수에 저장된 파일에서 얻을 수 있습니다:
curl --cacert "${CI_SERVER_TLS_CA_FILE}" ${URL} -o ${FILE}
기타 CI/CD 단계용 인증서 신뢰
Linux에서는 인증서 파일을 /etc/gitlab-runner/certs/ca.crt에 매핑하고, Windows에서는 C:\GitLab-Runner\certs\ca.crt에 매핑합니다.
러너(runner) 헬퍼 이미지는 해당 사용자 정의 ca.crt 파일을 시작할 때 설치하고, 클론 및 아티팩트 업로드 등의 작업에서 사용합니다.
Docker
-
Linux:
[[runners]] name = "docker" url = "https://example.com/" token = "TOKEN" executor = "docker" [runners.docker] image = "ubuntu:latest" # 볼륨 디렉터리에 ca.crt 파일의 경로 추가 volumes = ["/cache", "/path/to-ca-cert-dir/ca.crt:/etc/gitlab-runner/certs/ca.crt:ro"] -
Windows:
[[runners]] name = "docker" url = "https://example.com/" token = "TOKEN" executor = "docker" [runners.docker] image = "mcr.microsoft.com/windows/servercore:21H2" # ca.crt 파일을 보관하는 디렉터리를 볼륨 디렉터리에 추가 volumes = ["c:\\cache", "c:\\path\\to-ca-cert-dir:C:\\GitLab-Runner\\certs:ro"]
Kubernetes
Kubernetes에서 실행 중인 작업에 인증서 파일을 제공하려면 다음을 수행하세요:
-
네임스페이스에서 Kubernetes 시크릿으로 인증서를 저장합니다:
kubectl create secret generic <SECRET_NAME> --namespace <NAMESPACE> --from-file=<CERT_FILE> -
알맞은 값을 사용하여 러너에 대한 시크릿을 볼륨으로 사용합니다:
gitlab-runner: runners: config: | [[runners]] [runners.kubernetes] namespace = "{{.Release.Namespace}}" image = "ubuntu:latest" [[runners.kubernetes.volumes.secret]] name = "<SECRET_NAME>" mount_path = "<LOCATION>"mount_path는 컨테이너 내 인증서가 저장된 디렉터리입니다. 러너는/etc/gitlab-runner/certs/를mount_path로 사용하고, 인증서 파일이ca.crt이면 컨테이너 내에서/etc/gitlab-runner/certs/ca.crt에서 인증서를 사용할 수 있습니다. -
작업의 일부로 매핑된 인증서 파일을 시스템 인증서 리포지터리에 설치합니다.
예를 들어, Ubuntu 컨테이너에서:script: - cp /etc/gitlab-runner/certs/ca.crt /usr/local/share/ca-certificates/ - update-ca-certificates
Kubernetes 엑스큐터가 헬퍼 이미지의 ENTRYPOINT를 처리하는 방식의 알려진 문제 때문에 매핑된 인증서 파일이 자동으로 시스템 인증서 리포지터리에 설치되지 않습니다.
Troubleshooting
일반 SSL troubleshooting 문서를 참조하십시오.
또한, tlsctl 도구를 사용하여 Runner의 엔드에서 GitLab 인증서를 디버그할 수 있습니다.
x509: certificate signed by unknown authority 개인 레지스트리에서 실행자 이미지를 가져오려고 시도할 때 발생하는 오류
이 오류는 실행자가 스케줄하는 Docker 호스트 또는 Kubernetes 노드가 개인 레지스트리에서 사용하는 인증서를 신뢰하지 않을 때 발생합니다. 이 오류를 해결하려면 해당 루트 인증 기관 또는 인증서 체인을 시스템의 신뢰 리포지터리에 추가한 다음 컨테이너 서비스를 다시 시작하십시오. GitLab Runner 버전 및 Docker 호스트 환경에 따라서는 러너 피처 플래그 FF_RESOLVE_FULL_TLS_CHAIN을 FALSE로 설정해야 할 수도 있습니다.
작업 중 apt-get: not found 오류
pre_build_script 명령은 러너가 실행하는 모든 작업 전에 실행됩니다. 사용자 스크립트용 인증서를 설치할 때 ‘apk’ 또는 ‘apt-get’과 같이 특정 배포판에 특화된 명령을 추가하면 CI 작업이 다른 배포판을 기반으로 하는 이미지를 사용하는 경우 작업이 실패할 수 있습니다.
예를 들어, 일부 CI 작업이 Ubuntu 기반 이미지를 실행하고 일부가 Alpine 기반 이미지를 실행하고 있고 Ubuntu 명령을 추가하는 경우, Alpine 기반 이미지를 사용하는 작업에서 apt-get: not found 오류가 발생합니다. 이를 해결하려면 다음 중 하나를 수행하십시오:
-
pre_build_script을 배포판에 상관없이 작동하도록 작성하십시오. - 호환되는 이미지를 사용하도록 러너에게만 작업을 수행하도록 tags를 사용하십시오.
도움말