GitLab 차트를 위한 TLS 구성

Tier: Free, Premium, Ultimate Offering: 자체 관리

이 차트는 NGINX Ingress 컨트롤러를 사용하여 TLS 종료를 수행할 수 있습니다. 배포에 대한 TLS 인증서를 어떻게 획득할지 선택할 수 있습니다. 자세한 내용은 글로벌 Ingress 설정에서 찾을 수 있습니다.

옵션 1: cert-manager 및 Let’s Encrypt

Let’s Encrypt는 무료이며 자동화된 공개 CA(Certificate Authority)입니다. 인증서는 다양한 도구를 사용하여 자동으로 요청할 수 있습니다. 이 차트는 인기 있는 선택인 cert-manager와 쉽게 통합할 수 있도록 준비되어 있습니다.

이미 cert-manager를 사용 중이라면, global.ingress.annotations를 사용하여 cert-manager 배포에 대한 적절한 주석을 구성할 수 있습니다.

클러스터에 cert-manager가 설치되어 있지 않은 경우, 이 차트의 종속성으로 설치하고 구성할 수 있습니다.

내부 cert-manager 및 Issuer 

helm repo update
helm dep update
helm install gitlab gitlab/gitlab \
  --set certmanager-issuer.email=you@example.com

cert-manager를 설치하는 것은 certmanager.install 설정으로 제어되며, 차트에서 사용하는 것은 global.ingress.configureCertmanager 설정으로 제어됩니다. 기본적으로 둘 다 true이므로 기본 설정으로는 이메일만 제공하면 됩니다.

외부 cert-manager 및 내부 Issuer

외부 cert-manager를 활용하면서 이 차트의 일부로 Issuer를 제공할 수 있습니다. 

helm install gitlab gitlab/gitlab \
  --set certmanager.install=false \
  --set certmanager-issuer.email=you@example.com \
  --set global.ingress.annotations."kubernetes\.io/tls-acme"=true

외부 cert-manager 및 Issuer (외부)

외부 cert-manager 및 Issuer 리소스를 활용하려면, 자체 서명 인증서가 활성화되지 않도록 여러 항목을 제공해야 합니다.

  1. 외부 cert-manager를 활성화하는 주석(자세한 내용은 문서 참조)
  2. 각 서비스의 TLS 시크릿 이름 (자체 서명 동작 비활성화) 
helm install gitlab gitlab/gitlab \
  --set certmanager.install=false \
  --set global.ingress.configureCertmanager=false \
  --set global.ingress.annotations."kubernetes\.io/tls-acme"=true \
  --set gitlab.webservice.ingress.tls.secretName=RELEASE-gitlab-tls \
  --set registry.ingress.tls.secretName=RELEASE-registry-tls \
  --set minio.ingress.tls.secretName=RELEASE-minio-tls \
  --set gitlab.kas.ingress.tls.secretName=RELEASE-kas-tls

옵션 2: 자체 와일드카드 인증서 사용

완전한 체인 인증서와 키를 Secret로 클러스터에 추가합니다. 

kubectl create secret tls <tls-secret-name> --cert=<path/to-full-chain.crt> --key=<path/to.key>

다음 옵션을 포함합니다. 

helm install gitlab gitlab/gitlab \
  --set certmanager.install=false \
  --set global.ingress.configureCertmanager=false \
  --set global.ingress.tls.secretName=<tls-secret-name>

AWS ACM을 사용하여 인증서 관리

AWS ACM을 사용하여 와일드카드 인증서를 생성하는 경우, ACM 인증서는 다운로드할 수 없기 때문에 시크릿을 통해 지정할 수 없습니다. 대신 nginx-ingress.controller.service.annotations를 통해 지정합니다. 

nginx-ingress:
  controller:
    service:
      annotations:
        ...
        service.beta.kubernetes.io/aws-load-balancer-ssl-cert: arn:aws:acm:{region}:{user id}:certificate/{id}

옵션 3: 서비스당 개별 인증서 사용

클러스터에 완전한 체인 인증서를 시크릿으로 추가한 다음, 각 인그레스에 해당 시크릿 이름을 전달합니다. 

helm install gitlab gitlab/gitlab \
  --set certmanager.install=false \
  --set global.ingress.configureCertmanager=false \
  --set global.ingress.tls.enabled=true \
  --set gitlab.webservice.ingress.tls.secretName=RELEASE-gitlab-tls \
  --set registry.ingress.tls.secretName=RELEASE-registry-tls \
  --set minio.ingress.tls.secretName=RELEASE-minio-tls \
  --set gitlab.kas.ingress.tls.secretName=RELEASE-kas-tls

참고: GitLab 인스턴스를 다른 서비스와 통신할 수 있도록 구성하는 경우, 해당 서비스의 인증서 체인을 이 차트를 통해 GitLab에 제공해야 할 수도 있습니다. (자세한 내용은 글로벌 Ingress 설정 참조)

옵션 4: 자동 생성된 자체 서명 와일드카드 인증서 사용

이 차트는 자동 생성된 자체 서명 와일드카드 인증서를 제공하는 기능도 제공합니다. 이 기능은 Let’s Encrypt를 사용할 수 없지만 SSL을 통한 보안이 여전히 필요한 환경에서 유용할 수 있습니다. 이 기능은 shared-secrets 작업에 의해 제공됩니다.

참고: gitlab-runner 차트는 자체 서명된 인증서와 제대로 작동하지 않습니다. 아래와 같이 비활성화하는 것을 권장합니다. 

helm install gitlab gitlab/gitlab \
  --set certmanager.install=false \
  --set global.ingress.configureCertmanager=false \
  --set gitlab-runner.install=false

그런 다음 shared-secrets 작업은 모든 외부 접근 가능한 서비스에서 사용할 CA 인증서, 와일드카드 인증서, 그리고 인증서 체인을 생성합니다. 이에 대한 보안 요소는 RELEASE-wildcard-tls, RELEASE-wildcard-tls-ca, RELEASE-wildcard-tls-chain입니다. RELEASE-wildcard-tls-ca에는 배포되는 GitLab 인스턴스에 액세스하는 사용자 및 시스템에게 배포할 수 있는 공개 CA 인증서가 포함되어 있습니다. RELEASE-wildcard-tls-chain에는 CA 인증서와 와일드카드 인증서가 모두 포함되어 있으며, 이를 gitlab-runner.certsSecretName=RELEASE-wildcard-tls-chain을 통해 GitLab Runner에 직접 사용할 수 있습니다.

GitLab Pages의 TLS 요구사항

TLS 지원을 통한 GitLab Pages를 위한 와일드카드 인증서가 *.<pages domain> (기본값은 <pages domain>이 pages.<base domain>)에 적용되어야 합니다.

와일드카드 인증서가 필요하기 때문에 cert-manager 및 Let’s Encrypt에서는 자동으로 생성되지 않습니다. 따라서 GitLab Pages에 대해 기본적으로 cert-manager가 비활성화되어 있으며(gitlab-pages.ingress.configureCertmanager를 통해), 와일드카드 인증서를 포함하는 자체 k8s Secret를 제공해야 합니다. global.ingress.annotations를 사용하여 구성된 외부 cert-manager가 있는 경우, 이러한 주석을 gitlab-pages.ingress.annotations에서 덮어쓰기하고 싶을 것입니다.

기본적으로 이 시크릿의 이름은 <RELEASE>-pages-tls입니다. 다른 이름을 지정하려면 gitlab.gitlab-pages.ingress.tls.secretName 설정을 사용하세요: 

helm install gitlab gitlab/gitlab \
  --set global.pages.enabled=true \
  --set gitlab.gitlab-pages.ingress.tls.secretName=<secret name>

문제 해결

이 섹션에는 문제 해결을 위한 가능한 해결책이 포함되어 있습니다.

SSL 종료 오류

Let’s Encrypt를 TLS 공급자로 사용하고 인증서 관련 오류가 발생하는 경우 다음 옵션을 사용하여 디버깅할 수 있습니다:

  1. 가능한 오류를 찾기 위해 letsdebug에서 도메인을 확인하세요.

  2. letsdebug에서 오류가 없는 경우 cert-manager와 관련된 문제가 있는지 확인하세요: 

    kubectl describe certificate,order,challenge --all-namespaces

    오류가 있으면 인증서 오브젝트를 제거하여 새 인증서를 요청하도록 시도해보세요.

  3. 위의 방법이 모두 작동하지 않으면 cert-manager를 다시 설치하는 것을 고려해보세요.