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를 사용하여 적절한 annotations를 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를 활성화하는 annotations(자세한 내용은 문서 참조)
  2. 각 서비스에 대한 TLS secret 이름 (이는 자체 서명 동작을 비활성화합니다) 
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 인증서는 다운로드할 수 없으므로 Secret를 통해 지정할 수 없습니다. 대신, 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: 서비스별 개별 인증서 사용

전체 체인 인증서를 클러스터에 Secret으로 추가하고, 그러한 Secret 이름을 각 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

참고: GitLab 인스턴스를 다른 서비스와 통신하도록 구성하는 경우, 해당 서비스의 인증서 체인을 이 차트를 통해 GitLab에 제공해야 할 수도 있습니다.

옵션 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 인증서, 와일드카드 인증서 및 인증서 체인을 생성하여 외부에서 접근 가능한 모든 서비스에서 사용할 수 있도록 합니다. 이를 포함하는 Secret은 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 요구 사항

GitLab Pages with TLS support에서는 *.<페이지 도메인="">에 해당하는 와일드카드 인증서(기본값: <페이지 도메인="">은 `pages.<베이스 도메인="">`)가 필요합니다.베이스>페이지>페이지>

와일드카드 인증서가 필요하기 때문에 cert-manager 및 Let’s Encrypt에서 자동으로 생성할 수 없습니다. 따라서 GitLab Pages의 경우 cert-manager가 기본적으로 비활성화되어 있으며(gitlab-pages.ingress.configureCertmanager를 통해) 와일드카드 인증서가 포함된 별도의 k8s Secret을 제공해야 합니다. global.ingress.annotations을 사용하여 외부 cert-manager를 구성한 경우, gitlab-pages.ingress.annotations에서 해당 주석을 재정의해야 합니다.

기본적으로 이 시크릿의 이름은 <릴리스 이름>-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=<시크릿 이름>

문제 해결

이 섹션에는 발생할 수 있는 문제에 대한 해결책이 포함되어 있습니다.

SSL 종료 오류

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

  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 <네임스페이스> delete deployment gitlab-certmanager gitlab-certmanager-cainjector gitlab-certmanager-webhook
helm upgrade --install -n <네임스페이스> gitlab gitlab/gitlab