자체 서명 인증서 또는 사용자 정의 인증 기관
- GitLab Runner 0.7.0에서 소개되었습니다.
GitLab Runner는 TLS 피어를 확인하기 위해 사용할 인증서를 구성하는 두 가지 옵션을 제공합니다:
-
GitLab 서버에 대한 연결: 인증서 파일은 GitLab 서버를 대상으로 하는 자체 서명 인증서의 지원되는 옵션 섹션에 설명된 대로 지정할 수 있습니다.
이는 러너를 등록할 때
x509: certificate signed by unknown authority문제를 해결합니다.기존 러너의 경우 작업을 확인하려고 할 때 Runner 로그에서 동일한 오류를 볼 수 있습니다:
https://hostname.tld/api/v4/jobs/request에 대한 POST를 실행할 수 없습니다. https://hostname.tld/api/v4/jobs/request: x509: certificate signed by unknown authority -
캐시 서버 또는 외부 Git LFS 리포지터리에 연결하는 사용자 스크립트와 같은 다른 시나리오를 포함한 보다 일반적인 접근 방식: 인증서를 지정하고 컨테이너에 설치할 수 있습니다. 이에 대한 자세한 내용은 Docker 및 Kubernetes executor에 대한 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 서버만 사용자 정의 인증서가 필요한 상황을 참조합니다. 기타 호스트(e.g. 프록시 다운로드가 활성화되어 있지 않은 객체 리포지터리)에도 사용자 정의 인증 기관 (CA)이 필요한 경우 다음 섹션을 참조하십시오.
GitLab Runner는 다음과 같은 옵션을 지원합니다:
-
기본값 - 시스템 인증서 읽기: GitLab Runner는 시스템 인증서 리포지터리를 읽고 GitLab 서버를 시스템에 저장된 인증 기관(CA)로 확인합니다.
-
사용자 정의 인증서 파일 지정: GitLab Runner는 등록 시 (
gitlab-runner register --tls-ca-file=/path) 및config.toml의[[runners]]섹션의tls-ca-file옵션을 노출합니다. 이를 통해 사용자 정의 인증서 파일을 지정할 수 있습니다. 이 파일은 Runner가 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. GitLab Runner를 Windows 서비스로 실행하는 경우 이 방법은 작동하지 않습니다. 대신 사용자 정의 인증서 파일을 지정하십시오.
- *nix 시스템에서 GitLab Runner를
-
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을 사용하여 누락된 인증서를 삽입하여 공개적으로 신뢰되지 않는 인증서를 사용하는 서버와 함께 git clone 및 artifact를 작동할 수 있습니다.
이 접근 방식은 안전하지만 러너를 일부 신뢰할 수 있는 지점으로 만듭니다.
Docker 및 Kubernetes executor에 대한 TLS 인증서 신뢰
컨테이너에 인증서를 등록하는 경우 고려해야 할 두 가지 컨텍스트가 있습니다:
- 사용자 이미지는 사용자 스크립트를 실행하는 데 사용됩니다. 사용자 스크립트에서 인증서를 신뢰해야 하는 시나리오를 포함하는 경우 특정 이미지에 인증서를 설치하는 방법에 대해 사용자가 직접 책임져야 하며, 러너는 각 가능한 시나리오에 대해 인증서를 설치할 방법을 알 수 없습니다.
-
러너 도움말 이미지는 Git, artifact 및 캐시 작업을 처리하는 데 사용됩니다.
다른 CI/CD 단계에 대한 인증서를 신뢰하는 시나리오를 포함하는 경우 사용자는 특정 위치(예:
/etc/gitlab-runner/certs/ca.crt)에 인증서 파일을 제공하면 되며, Docker 컨테이너가 사용자를 위해 자동으로 설치합니다.
사용자 스크립트용 인증서 신뢰
빌드 스크립트가 TLS를 통해 동료와 통신하고 자체 서명 인증서 또는 사용자 정의 인증 기관을 신뢰해야 하는 경우, 빌드 작업에서 인증서를 설치해야 합니다.
사용자 스크립트를 실행하는 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를 사용하여 맵핑된 파일 (예: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 """ -
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 파일을 시작할 때 설치하고, 클론 및 아티팩트 업로드와 같은 작업 수행 시 사용합니다.
도커
-
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"]
쿠버네티스
쿠버네티스에서 작동 중인 작업에 인증서 파일을 제공하려면:
-
네임스페이스내의 쿠버네티스 시크릿으로 인증서를 저장합니다:
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에서 사용할 수 있습니다. -
작업의 일환으로 시스템 인증서 리포지터리에 매핑된 인증서 파일을 설치합니다. 예를 들어, Ubuntu 컨테이너에서:
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 오류가 발생하는 경우
러너(runner)가 실행하는 모든 작업 이전에 pre_build_script 명령이 실행됩니다. 사용자 스크립트에 인증서를 설치하는 명령과 같이 특정 배포에 특화된 명령(apk 또는 apt-get과 같은)을 추가하면, 서로 다른 배포에 기반한 이미지를 사용하는 CI 작업에서 호스트도 서로 다른 경우, CI 작업이 실패할 수 있습니다.
예를 들어, 일부 CI 작업이 Ubuntu 기반 이미지를 실행하고 일부가 Alpine 기반 이미지를 실행하는 경우, Ubuntu 명령을 추가하면 Alpine 기반 이미지의 작업에서 apt-get: not found 오류가 발생합니다. 이를 해결하려면:
- 배포에 관계없이 작동하는
pre_build_script를 작성하세요. - 호환되는 이미지를 사용하기 위해 tags를 사용하세요.
도움말