자체 서명 인증서 또는 사용자 정의 인증 기관
- GitLab Runner 0.7.0에 도입됨
GitLab Runner는 TLS 피어를 확인하기 위해 사용되는 인증서를 구성하는 두 가지 옵션을 제공합니다.
-
GitLab 서버에 연결하는 경우: 인증서 파일은 GitLab 서버를 대상으로 하는 자체 서명 인증서의 지원되는 옵션 섹션에 설명된대로 지정할 수 있습니다.
이는 Runner를 등록할 때
x509: certificate signed by unknown authority문제를 해결합니다.기존 Runner의 경우, 작업을 확인하려고 할 때 Runner 로그에서 동일한 오류를 볼 수 있습니다:
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옵션을 노출합니다. 이를 통해 사용자 정의 인증서 파일을 지정할 수 있습니다. 이 파일은 Runner가 GitLab 서버에 액세스할 때마다 읽힙니다. GitLab Runner Helm 차트를 사용하는 경우, 사용자 정의 인증서로 GitLab에 액세스하도록 구성해야 합니다. -
PEM 인증서 읽기 : GitLab Runner는 미리 정의된 파일에서 PEM 인증서를 읽습니다 (DER 형식은 지원되지 않음):
- *nix 시스템에서
root로 실행되는 경우/etc/gitlab-runner/certs/gitlab.example.com.crt. - *nix 시스템에서 비-
root로 실행되는 경우~/.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----- - 기존 Runner의 인증서를 업데이트하는 경우, 다시 시작하십시오.
- 이미 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는 각 가능한 시나리오에서 어떻게 인증서를 설치해야 하는지 알 수 없습니다.
-
Runner 헬퍼 이미지는 Git, 아티팩트 및 캐시 작업을 처리하는 데 사용됩니다.
다른 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 전용: 매핑된 파일(e.g
ca.crt)을pre_build_script에서 사용하여:- 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로 인증서 파일을 매핑할 수 있습니다. 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> -
시크릿을 runner에 볼륨으로 마운트하고 적절한
<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-certificatesKubernetes 실행기의 헬퍼 이미지
ENTRYPOINT의 처리에 대한 알려진 문제로 인해 매핑된 인증서 파일이 자동으로 시스템 인증서 저장소에 설치되지 않습니다.
문제 해결
일반 SSL 문제 해결 문서를 참조하세요.
또한, tlsctl 도구를 사용하여 러너(Runner)의 끝단에서 GitLab 인증서를 디버그할 수 있습니다.
x509: certificate signed by unknown authority가 개인 레지스트리에서 실행자 이미지를 가져오려는 동안 발생하는 문제
이 오류는 러너가 실행자(executors)를 예약하는 Docker 호스트 또는 Kubernetes 노드가 개인 레지스트리에서 사용된 인증서를 신뢰하지 않을 때 발생합니다. 이 오류를 해결하려면 시스템의 신뢰 저장소에 관련 루트 인증 기관 또는 인증서 체인을 추가한 다음 컨테이너 서비스를 재시작하십시오.
Ubuntu 또는 Alpine을 사용하는 경우 다음 명령을 실행하십시오.
cp ca.crt /usr/local/share/ca-certificates/ca.crt
update-ca-certificates
systemctl restart docker.service
Ubuntu 또는 Alpine 이외의 운영 체제를 사용하는 경우 신뢰할 수 있는 인증서를 설치하는 적절한 명령을 확인하기 위해 해당 운영 체제의 문서를 참조하십시오.
GitLab Runner 버전 및 Docker 호스트 환경에 따라 FF_RESOLVE_FULL_TLS_CHAIN 기능 플래그를 비활성화해야 할 수도 있습니다.
작업 중 apt-get: not found 오류
pre_build_script 명령은 러너가 실행하는 모든 작업의 앞에서 실행됩니다. 사용자 스크립트에 인증서를 설치할 때 특정 배포(distribution)에 특화된 apk 또는 apt-get과 같은 명령을 추가하면, 다른 배포를 기반으로 하는 이미지를 사용하는 CI 작업이 실패할 수 있습니다.
예를 들어, 일부 CI 작업이 우분투 기반 이미지를 실행하고 일부가 알파인 기반 이미지를 실행하고 우분투 명령을 추가하는 경우 알파인 기반 이미지의 작업에서 apt-get: not found 오류가 발생합니다. 이를 해결하기 위해 다음 중 하나를 수행하세요:
- 배포에 구애받지 않도록
pre_build_script를 작성하세요. - tags를 사용하여 러너가 호환되는 이미지를 사용하는 작업만 선택하도록 하세요.
도움말