GitLab Runner는 TLS 피어를 확인하는 데 사용할 인증서를 구성하기 위해 두 가지 옵션을 제공합니다:

• GitLab 서버 연결: 인증서 파일은 GitLab 서버를 대상으로 하는 자체 서명 인증서에 대한 지원 옵션 섹션에 설명된 대로 지정할 수 있습니다.

  이렇게 하면 Runner를 등록할 때 x509: certificate signed by unknown authority 문제가 해결됩니다.

  기존 Runner의 경우 잡을 확인하려고 할 때 Runner 로그에서 동일한 오류를 볼 수 있습니다:

  Couldn't execute POST against 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 실행자를 위한 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) 및 [[runners]] 섹션 아래의 config.toml에서 tls-ca-file 옵션을 노출합니다. 이를 통해 사용자 정의 인증서 파일을 지정할 수 있습니다. 이 파일은 Runner가 GitLab 서버에 접근하려고 할 때마다 읽힙니다. GitLab Runner Helm 차트를 사용하는 경우 사용자 정의 인증서로 GitLab에 접근에 설명된 대로 인증서를 구성해야 합니다.

• PEM 인증서 읽기: GitLab Runner는 미리 정의된 파일에서 PEM 인증서(DER 형식은 지원되지 않음)를 읽습니다:

  • root로 GitLab Runner가 실행될 때 *nix 시스템의 /etc/gitlab-runner/certs/gitlab.example.com.crt.

    서버 주소가 https://gitlab.example.com:8443/인 경우 /etc/gitlab-runner/certs/gitlab.example.com.crt에 인증서 파일을 생성합니다.

    openssl 클라이언트를 사용하여 GitLab 인스턴스의 인증서를 /etc/gitlab-runner/certs로 다운로드할 수 있습니다:

    openssl s_client -showcerts -connect gitlab.example.com:443 -servername gitlab.example.com < /dev/null 2>/dev/null | openssl x509 -outform PEM > /etc/gitlab-runner/certs/gitlab.example.com.crt
    

    파일이 올바르게 설치되었는지 확인하려면 openssl과 같은 도구를 사용할 수 있습니다. 예시:

    echo | openssl s_client -CAfile /etc/gitlab-runner/certs/gitlab.example.com.crt -connect gitlab.example.com:443 -servername gitlab.example.com
    

  • 비root로 GitLab Runner가 실행될 때 *nix 시스템의 ~/.gitlab-runner/certs/gitlab.example.com.crt.

  • 다른 시스템의 ./certs/gitlab.example.com.crt. GitLab Runner를 Windows 서비스로 실행하는 경우 이것은 작동하지 않습니다. 대신 사용자 정의 인증서 파일을 지정하세요.

참고:

• GitLab 서버 인증서가 CA에 의해 서명된 경우 GitLab 서버 서명 인증서 대신 CA 인증서를 사용하세요. 중간 인증서도 체인에 추가해야 할 수 있습니다. 예를 들어, 기본, 중간, 루트 인증서가 있는 경우 모두 하나의 파일에 넣을 수 있습니다:

  -----BEGIN CERTIFICATE-----
  (Your primary SSL certificate: your_domain_name.crt)
  -----END CERTIFICATE-----
  -----BEGIN CERTIFICATE-----
  (Your intermediate certificate)
  -----END CERTIFICATE-----
  -----BEGIN CERTIFICATE-----
  (Your root 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는 각각의 가능한 시나리오에서 인증서를 설치하는 방법을 알 수 없습니다.
• Git, 아티팩트 및 캐시 작업을 처리하는 데 사용되는 Runner 헬퍼 이미지. 다른 CI/CD 단계를 위한 인증서 신뢰와 관련된 시나리오의 경우, 사용자는 특정 위치(예: /etc/gitlab-runner/certs/ca.crt)에서 인증서 파일을 사용 가능하게만 하면 되며 Docker 컨테이너가 사용자를 위해 자동으로 설치합니다.

사용자 스크립트를 위한 인증서 신뢰#

빌드에서 자체 서명 인증서 또는 사용자 정의 인증서와 함께 TLS를 사용하는 경우 피어 통신을 위해 빌드 잡에 인증서를 설치합니다. 사용자 스크립트를 실행하는 Docker 컨테이너에는 기본적으로 인증서 파일이 설치되어 있지 않습니다. 이는 사용자 정의 캐시 호스트를 사용하거나 보조 git clone을 수행하거나 wget과 같은 도구를 통해 파일을 가져오는 데 필요할 수 있습니다.

인증서를 설치하려면:

1. Docker 컨테이너가 볼 수 있도록 스크립트를 실행하는 Docker 컨테이너에 필요한 파일을 Docker 볼륨으로 매핑합니다. config.toml 파일에서 [runners.docker] 내의 해당 키 안에 볼륨을 추가하여 이를 수행합니다. 예시:

   • Linux:

     [[runners]]
       name = "docker"
       url = "https://example.com/"
       token = "TOKEN"
       executor = "docker"
     
       [runners.docker]
          image = "ubuntu:latest"
     
          # Add path to your ca.crt file in the volumes list
          volumes = ["/cache", "/path/to-ca-cert-dir/ca.crt:/etc/gitlab-runner/certs/ca.crt:ro"]
     

2. Linux 전용: 다음을 수행하는 pre_build_script에서 매핑된 파일(예: ca.crt)을 사용합니다:

   1. Docker 컨테이너 내의 /usr/local/share/ca-certificates/ca.crt에 복사합니다.

   2. update-ca-certificates --fresh를 실행하여 설치합니다. 예시(명령은 사용 중인 배포에 따라 다름):

      • Ubuntu의 경우:

        [[runners]]
          name = "docker"
          url = "https://example.com/"
          token = "TOKEN"
          executor = "docker"
        
          # Copy and install CA certificate before each job
          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"
        
          # Copy and install CA certificate before each job
          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
          """
        

사용할 수 있는 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"
  
      # Add path to your ca.crt file in the volumes list
      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"
  
      # Add directory holding your ca.crt file in the volumes list
      volumes = ["c:\\cache", "c:\\path\\to-ca-cert-dir:C:\\GitLab-Runner\\certs:ro"]
  

Kubernetes#

Kubernetes에서 실행되는 잡에 인증서 파일을 제공하려면:

1. 네임스페이스에 인증서를 Kubernetes 시크릿으로 저장합니다:

   kubectl create secret generic  --namespace  --from-file=
   

2. 및 을 적절한 값으로 교체하여 Runner에 볼륨으로 시크릿을 마운트합니다:

   gitlab-runner:
     runners:
      config: |
        [[runners]]
          [runners.kubernetes]
            namespace = "{{.Release.Namespace}}"
            image = "ubuntu:latest"
          [[runners.kubernetes.volumes.secret]]
              name = ""
              mount_path = ""
   

   mount_path는 인증서가 저장된 컨테이너의 디렉터리입니다. /etc/gitlab-runner/certs/를 mount_path로, ca.crt를 인증서 파일로 사용한 경우, 컨테이너 내에서 /etc/gitlab-runner/certs/ca.crt에서 인증서를 사용할 수 있습니다.

3. 잡의 일부로 매핑된 인증서 파일을 시스템 인증서 저장소에 설치합니다. 예를 들어 Ubuntu 컨테이너에서:

   script:
     - cp /etc/gitlab-runner/certs/ca.crt /usr/local/share/ca-certificates/
     - update-ca-certificates
   

Kubernetes 실행자의 헬퍼 이미지 ENTRYPOINT 처리에는 알려진 문제가 있습니다. 인증서 파일이 매핑될 때 시스템 인증서 저장소에 자동으로 설치되지 않습니다.

문제 해결#

일반 SSL 문제 해결 문서를 참조하세요.

또한 tlsctl 도구를 사용하여 Runner 측에서 GitLab 인증서를 디버그할 수 있습니다.

오류: x509: certificate signed by unknown authority#

이 오류는 Runner가 실행자를 스케줄링하는 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 명령은 Runner가 실행하는 모든 잡 이전에 실행됩니다. apk 또는 apt-get과 같은 배포별 명령은 문제를 일으킬 수 있습니다. 사용자 스크립트용 인증서를 설치할 때 CI 잡이 다른 배포 기반의 이미지를 사용하는 경우 실패할 수 있습니다.

예를 들어 CI 잡이 Ubuntu 및 Alpine 이미지를 실행하는 경우 Ubuntu 명령은 Alpine에서 실패합니다. apt-get: not found 오류는 Alpine 기반 이미지가 있는 잡에서 발생합니다. 이 문제를 해결하려면 다음 중 하나를 수행합니다:

• pre_build_script를 배포 독립적으로 작성합니다.
• Runner가 호환되는 이미지가 있는 잡만 선택하도록 태그를 사용합니다.

오류: self-signed certificate in certificate chain#

CI/CD 잡이 다음 오류와 함께 실패합니다:

fatal: unable to access 'https://gitlab.example.com/group/project.git/': SSL certificate problem: self-signed certificate in certificate chain

그러나 OpenSSL 디버깅 명령은 오류를 감지하지 못합니다.

이 오류는 Git이 openssl s_client 문제 해결 명령이 기본적으로 사용하지 않는 프록시를 통해 연결할 때 발생할 수 있습니다. Git이 프록시를 사용하여 리포지터리를 가져오는지 확인하려면 디버깅을 활성화합니다:

variables:
  GIT_CURL_VERBOSE: 1

Git이 프록시를 사용하지 않도록 하려면 NO_PROXY 변수를 GitLab 호스트 이름을 포함하도록 설정합니다:

variables:
  NO_PROXY: gitlab.example.com