자체 서명 인증서 또는 사용자 정의 인증 기관
세부 정보: Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed
- 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
GitLab 서버를 대상으로 하는 자체 서명 인증서 지원되는 옵션
이 섹션은 GitLab 서버만 사용자 정의 인증서가 필요한 상황을 가리킵니다. 다른 호스트(예: 프록시 다운로드가 활성화되지 않은 객체 저장 서비스)도 사용자 정의 인증 기관(CA)을 필요로 하는 경우 다음 섹션을 참조하세요.
GitLab Runner는 다음 옵션을 지원합니다:
-
기본값 - 시스템 인증서 읽기: GitLab Runner는 시스템 인증서 저장소를 읽고 시스템에 저장된 인증 기관(CA)를 사용하여 GitLab 서버를 확인합니다.
-
사용자 정의 인증서 파일 지정: 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 시스템의 경우
root로 실행되는 GitLab Runner에서는/etc/gitlab-runner/certs/gitlab.example.com.crt. - *nix 시스템의 경우
root로 실행되지 않는 GitLab Runner에서는~/.gitlab-runner/certs/gitlab.example.com.crt. - 다른 시스템의 경우
./certs/gitlab.example.com.crt. GitLab Runner를 Windows 서비스로 실행하는 경우 이 방법은 작동하지 않습니다. 대신 사용자 정의 인증서 파일을 지정하세요.
- *nix 시스템의 경우
참고:
-
GitLab 서버 인증서가 CA에 의해 서명되었으면 CA 인증서를 사용하세요 (GitLab 서버 서명 인증서가 아님). 중간 인증서도 연결에 추가해야 할 수 있습니다. 예를 들어 기본, 중간 및 루트 인증서가 있는 경우 모두 하나의 파일에 넣을 수 있습니다:
-----BEGIN CERTIFICATE----- (기본 SSL 인증서: your_domain_name.crt) -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- (중간 인증서) -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- (루트 인증서) -----END CERTIFICATE----- - 기존 러너의 인증서를 업데이트하는 경우, 다시 시작하세요.
- 이미 HTTP로 구성된 러너가 있는 경우
config.toml에서 GitLab 인스턴스 경로를 새 HTTPS URL로 업데이트하세요. - 인증서의 확인을 건너뛰려면
.gitlab-ci.yml파일의variables:섹션에서 CI 변수GIT_SSL_NO_VERIFY를true로 설정하는 것은 임시적이고 보안 상 취약한 해결책입니다.
Git 클론
러너는 CI_SERVER_TLS_CA_FILE을 사용하여 누락된 인증서를 삽입하여 CA 체인을 빌드합니다. 이를 통해 git clone 및 아티팩트를 공개 신뢰 인증서를 사용하지 않는 서버와 작동할 수 있게 됩니다.
이 접근 방식은 안전하지만, 러너는 단일 신뢰 지점이 됩니다.
Docker 및 Kubernetes 엑스큐터에 대한 TLS 인증서 신뢰
컨테이너에 인증서를 등록하는 경우에 고려해야 할 두 가지 맥락이 있습니다.
- 사용자 이미지는 사용자 스크립트를 실행하는 데 사용됩니다. 사용자 스크립트에 인증서를 신뢰해야 하는 시나리오의 경우, 사용자는 이미지 자체에 매우 의존적이므로 각 시나리오별로 인증서를 설치하는 방법에 대해 소유권을 가져야 합니다. 러너는 각 시나리오에 대해 어떻게 인증서를 설치해야 하는지 알 수 없습니다.
-
러너 도우미 이미지는 Git, 아티팩트, 캐시 작업을 처리하는 데 사용됩니다.
다른 CI/CD 단계에 대한 인증서를 신뢰해야 하는 시나리오의 경우, 사용자는 특정 위치(예:
/etc/gitlab-runner/certs/ca.crt)에 인증서 파일을 제공하기만 하면 됩니다. Docker 컨테이너가 자동으로 사용자를 위해 설치합니다.
사용자 스크립트에 대한 인증서 신뢰
빌드 스크립트가 TLS를 통해 동료와 통신해야 하고 자체 서명된 인증서 또는 사용자 정의 Certificate Authority를 사용해야 하는 경우, 사용자 스크립트를 실행하는 Docker 컨테이너에는 기본적으로 인증서 파일이 설치되어 있지 않으므로 빌드 작업에서 인증서를 설치해야 할 수 있습니다. 예를 들어, 사용자 지정 캐시 호스트 사용, 보조 git clone 수행 또는 wget와 같은 도구를 통해 파일을 가져오는 경우가 있습니다.
인증서를 설치하려면:
-
해당 파일을 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에서 매핑된 파일(e.gca.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 """ -
Alpine의 경우:
[[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에 인증서 파일을 매핑할 수 있습니다. 러너 도우미 이미지는 이 사용자 정의 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에 인증서 파일을 제공하려면:
-
네임스페이스에 쿠버네티스 시크릿으로 인증서를 저장합니다:
kubectl create secret generic <SECRET_NAME> --namespace <NAMESPACE> --from-file=<CERT_FILE> -
시크릿을 러너에서 볼륨으로 마운트하고,
<SECRET_NAME>및<LOCATION>을 적절한 값으로 대체합니다: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는 컨테이너 내에서 인증서가 저장된 디렉터리입니다.mount_path로/etc/gitlab-runner/certs/를 사용하고 인증서 파일을ca.crt로 한 경우, 인증서는 컨테이너 내에서/etc/gitlab-runner/certs/ca.crt에 있습니다. -
작업의 일환으로 매핑된 인증서 파일을 시스템 인증서 저장소에 설치합니다. 예를 들어 우분투 컨테이너에서:
script: - cp /etc/gitlab-runner/certs/ca.crt /usr/local/share/ca-certificates/ - update-ca-certificates
쿠버네티스 실행기의 ENTRYPOINT를 지원하는 도우미 이미지의 알려진 문제로
매핑된 인증서 파일이 자동으로 시스템 인증서 저장소에 설치되지 않습니다.
문제 해결
일반 SSL 문제 해결 문서를 참조하세요.
또한 러너 단에서 GitLab 인증서를 디버깅하는 데 tlsctl 도구를 사용할 수 있습니다.
개인 레지스트리에서 실행기 이미지를 가져올 때 x509: certificate signed by unknown authority 오류 발생
이 오류는 실행기가 예약된 호스트 또는 러너의 Docker 호스트에서 개인 레지스트리에서 사용된 인증서를 신뢰하지 않을 때 발생합니다. 오류를 해결하려면 해당 운영 체제에 따라 시스템의 신뢰 저장소에 관련 루트 인증 기관 또는 인증서 체인을 추가하고 컨테이너 서비스를 다시 시작하세요. GitLab 러너 버전 및 Docker 호스트 환경에 따라 러너 기능 플래그 FF_RESOLVE_FULL_TLS_CHAIN도 FALSE로 설정해야 할 수 있습니다.
작업 중 apt-get: not found 오류 발생
러너가 실행하는 모든 작업 전에 pre_build_script 명령들이 실행됩니다. 사용자 스크립트에 인증서를 설치할 때 특정 배포에 특화된 명령을 추가하면, CI 작업이 다른 배포를 기반으로 하는 이미지를 사용할 경우 해당 배포에 기반한 작업에서 오류가 발생할 수 있습니다.
예를 들어 CI 작업 중 일부가 우분투 기반 이미지를 사용하고 일부가 알파인 기반 이미지를 사용하면 우분투 명령을 추가하면 알파인 기반 이미지를 사용하는 작업에서 apt-get: not found 오류가 발생합니다. 이를 해결하려면:
- 사용하는 배포에 비의존적인 방식으로
pre_build_script를 작성하세요. - 호환 이미지를 사용하기 위해 tags를 사용하세요.
도움말