GitLab 차트를 위한 TLS 구성

Tier: Free, Premium, Ultimate Offering: Self-Managed

이 차트는 NGINX Ingress Controller를 사용하여 TLS 종료를 수행할 수 있습니다. 배포에 대한 TLS 인증서 획득 방법을 선택할 수 있습니다. 자세한 내용은 전역 Ingress 설정에서 찾을 수 있습니다.

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

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

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

클러스터에 cert-manager를 이미 설치하지 않았다면, 이 차트의 의존성으로 cert-manager를 설치하고 구성할 수 있습니다.

내부 cert-manager 및 발급자 

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 및 내부 발급자

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

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 및 발급자 (외부)

외부 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: 서비스별 개별 인증서 사용

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

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
note
GitLab 인스턴스를 다른 서비스와 통신하도록 구성하는 경우, 해당 서비스에 대한 인증서 체인을 이 차트를 통해 제공해야 할 수 있습니다.

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

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

note
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 종료 오류

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

  1. 가능한 오류를 확인하려면 도메인을 letsdebug에서 확인합니다.

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

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

    오류가 표시된다면 새로운 인증서를 요청하도록 인증서 개체를 제거해 보세요.

  3. 위의 모든 방법이 동작하지 않는 경우 기존 cert-manager 리소스를 제거하고 cert-manager를 다시 설치하는 것을 고려합니다. 내부 cert-manager를 사용 중인 경우, 이름에 certmanager가 포함된 배포를 삭제하고 Helm 차트를 다시 설치합니다. 이때, 기본적으로 gitlab이라는 이름의 릴리스를 가정합니다: 

    kubectl -n <namespace> delete deployment gitlab-certmanager gitlab-certmanager-cainjector gitlab-certmanager-webhook
helm upgrade --install -n <namespace> gitlab gitlab/gitlab