오퍼레이터 문제 해결

이 문서는 GitLab 오퍼레이터의 설치 및 GitLab 인스턴스의 배포를 문제 해결하는 데 도움이 되는 노트와 팁 모음입니다.

설치 문제

Kubernetes 환경에서 오퍼레이터 설치를 문제 해결하는 것은 다른 Kubernetes 워크로드의 문제 해결과 유사합니다. 오퍼레이터 매니페스트를 배포한 후, 오퍼레이터 Pod에 대한 kubectl describe의 출력을 모니터링하거나 kubectl get events -n <namespace>를 실행합니다. 이는 오퍼레이터 이미지를 가져오거나 오퍼레이터를 시작하기 위한 기타 사전 조건과 관련된 문제를 나타냅니다.

오퍼레이터가 시작되지만 조기에 종료되는 경우, 오퍼레이터 로그를 검사하면 Pod의 종료 원인에 대한 정보를 제공할 수 있습니다. 다음 명령어로 확인할 수 있습니다:

kubectl logs deployment/gitlab-controller-manager -c manager -f -n <namespace>

추가로, 오퍼레이터는 올바른 작동을 위해 TLS 인증서를 생성하기 위해 Cert Manager에 의존합니다. TLS 인증서는 Secret으로 생성되어 오퍼레이터 Pod에 볼륨으로 마운트됩니다. TLS 인증서 획득과 관련된 문제는 네임스페이스의 이벤트 로그에서 확인할 수 있습니다.

$ kubectl get events -n gitlab-system
...
102s        Warning   FailedMount         pod/gitlab-controller-manager-d4f65f856-b4mdj    MountVolume.SetUp failed for volume "cert" : secret "webhook-server-cert" not found
107s        Warning   FailedMount         pod/gitlab-controller-manager-d4f65f856-b4mdj    Unable to attach or mount volumes: unmounted volumes=[cert], unattached volumes=[cert gitlab-manager-token-fc4p9]: timed out waiting for the condition
...

다음 단계는 Cert Manager 로그를 검사하여 TLS 인증서 생성 실패를 나타내는 문제를 찾는 것입니다.

OpenShift 특정 문제

OpenShift는 더 제한적인 보안 모델을 가지고 있으며, 결과적으로 GitLab 오퍼레이터는 클러스터 관리 계정으로 설치해야 합니다. 개발자 계정은 오퍼레이터가 제대로 작동하는 데 필요한 권한이 없습니다.

Ingress NGINX Controller Pods가 이 문제에서 설명된 바와 같이 잘못된 SCC 매개변수로 인해 프로비저닝할 수 없는 경우, 적절한 해결 방법은 레포지토리에서 SCC를 업데이트하여 OpenShift 클러스터에서 Ingress NGINX를 시작할 수 있도록 하는 것입니다:

  1. GitLab 오퍼레이터의 최신 OpenShift 매니페스트를 가져옵니다. gitlab-operator-openshift-VERSION.yaml이 필요합니다.

  2. SCC를 추출합니다.

    yq eval '. | select(.metadata.name | test(".*scc.*"))' gitlab-operator-openshift-VERSION.yaml > scc.yaml

  3. 클러스터에 scc.yaml을 적용합니다:

    kubectl apply -f scc.yaml

GitLab 오퍼레이터 레포지토리의 릴리즈 페이지에서 배포된 매니페스트로 설치하면 SCC가 포함되어 있기 때문에 이 문제가 발생하지 않습니다.

OperatorHub에서 지원되지 않는 객체에 대한 관련 문제:

GitLab 인스턴스 배포 문제

여기에 제시된 정보 외에도, GitLab Helm 차트 문제 해결 문서를 참고해야 합니다.

코어 서비스 준비되지 않음

GitLab Operator는 Redis, PostgreSQL 및 Gitaly의 인스턴스를 설치하는 데 의존합니다. 이들은 코어 서비스로 알려져 있습니다. GitLab 고객 리소스를 배포한 후 코어 서비스가 준비되지 않았다는 운영자 로그 메시지가 과도하게 발생하면, 문제를 일으키고 있는 서비스 중 하나입니다.

각 서비스의 엔드포인트를 구체적으로 확인하여 서비스의 Pod에 연결되고 있는지 확인해야 합니다. 이것은 클러스터가 GitLab 인스턴스를 지원하기에 충분한 자원이 없다는 가능한 표시일 수도 있으며, 클러스터에 추가 노드를 추가해야 할 수도 있습니다.

문제 #305가 생성되어 GitLab 인스턴스의 배포를 중단시키는 코어 서비스를 추적하고 있습니다.

GitLab UI에 접근할 수 없음 (Ingress에 주소가 없거나 CertManager Challenges 실패)

GitLab Operator의 설치 매니페스트 및 Helm 차트는 기본적으로 모든 리소스 이름에 gitlab을 접두사로 사용합니다. 단, Helm 값에서 nameOverride가 지정된 경우는 제외입니다.

따라서 NGINX IngressClass는 gitlab-nginx로 명명됩니다. GitLab 사용자 정의 리소스에서 metadata.name 아래에 gitlab이 아닌 다른 릴리즈 이름이 지정된 경우, 기본 IngressClass 이름은 global.ingress.class 아래에서 명시적으로 설정해야 합니다.

예를 들어: metadata.name이 demo로 설정된 경우, global.ingress.class=gitlab-nginx로 설정하세요:

apiVersion: apps.gitlab.com/v1beta1
kind: GitLab
metadata:
  name: demo
spec:
  chart:
    version: "X.Y.Z"
    values:
      global:
        ingress:
          # 올바른 IngressClass 이름을 사용하세요.
          class: gitlab-nginx

이 명시적 설정이 없으면 Ingress는 demo-nginx라는 이름의 Ingress를 찾으려 시도하게 되지만, 이는 존재하지 않습니다.

NGINX Ingress Controller Pod 없음

OpenShift 환경에서는 NGINX Ingress Controller가 GitLab 인스턴스(HTTPS 및 SSH)에 트래픽을 유도하기 위해 OpenShift Routes 대신 사용됩니다. GitLab 인스턴스에 연결하는 데 문제가 발생하는 경우, 우선 NGINX Ingress Controller 배포가 존재하는지 확인해야 합니다.

배포가 존재하는 경우 kubectl get deploy 출력의 READY 열을 확인하세요. READY 상태가 0/0으로 보고되면, kubectl get events -n <namespace> | grep -i nginx의 출력을 검사하여 보안 컨텍스트 제약 조건(SCC)이 위반되었다고 보고하는 메시지를 찾으세요.

이는 OpenShift에 대한 NGINX RBAC 리소스가 배포되지 않았음을 나타냅니다. OpenShift용 운영자 매니페스트를 다음 명령으로 재적용해야 합니다:

kubectl apply -f https://gitlab.com/api/v4/projects/18899486/packages/generic/gitlab-operator/<VERSION>/gitlab-operator-openshift.yaml

매니페스트를 적용한 후, SCC를 제대로 확보하고 Ingress 컨트롤러가 Pods를 올바르게 생성할 수 있도록 Ingress 컨트롤러 배포를 삭제해야 할 수도 있습니다.

수평 팟 오토스케일러가 스케일링되지 않음

수평 팟 오토스케일러(HPA)가 트래픽 부하에 따라 팟 수를 스케일링하지 않는 경우, Metrics Server의 설치 여부를 확인하세요. Kubernetes 클러스터에서 Metrics Server는 설치해야 하는 추가 구성 요소입니다. 설치 과정은 설치 문서에서 확인할 수 있습니다.

OpenShift 클러스터에는 Metrics Server가 내장되어 있으므로 HPA는 제대로 작동해야 합니다.

PersistentVolumeClaim 구성 변경 시 데이터 복원

데이터 지속성을 위해 MinIO와 같은 구성 요소를 사용할 때, 이전 PersistentVolume에 다시 연결해야 할 수 있습니다.

예를 들어, !419는 Operator에서 정의한 MinIO 구성 요소를 GitLab Helm Charts의 MinIO 구성 요소로 교체했습니다. 이 변경의 일환으로, 객체 이름이 변경되었으며, PersistentVolumeClaim도 포함됩니다. 따라서 Operator와 패키지된 MinIO 인스턴스를 사용하는 사람은 지속된 데이터를 포함한 이전 PersistentVolume에 다시 연결하기 위해 추가 단계를 수행해야 했습니다.

GitLab Operator 0.6.4로 업그레이드한 후, 이전 PersistentVolume에 새로운 PersistentVolumeClaim을 연결하려면 다음 단계를 완료하세요:

  1. $RELEASE_NAME-minio-secret Secret을 삭제합니다. Secret의 내용은 0.6.4 업그레이드와 함께 변경되지만, Secret 이름은 변경되지 않습니다.

  2. 이전 MinIO PersistentVolume을 편집하여 .spec.persistentVolumeReclaimPolicy를 Delete에서 Retain으로 변경합니다.

  3. 이전 MinIO StatefulSet, $RELEASE_NAME-minio를 삭제합니다.

  4. 이전 MinIO PersistentVolume에서 .spec.ClaimRef를 제거하여 이전 MinIO PersistentVolumeClaim과의 관계를 끊습니다.

  5. 이전 MinIO PersistentVolumeClaim, export-gitlab-minio-0을 삭제합니다.

  6. 이전 PersistentVolume 상태가 이제 Available인지 확인합니다.

  7. GitLab 사용자 지정 리소스에 다음 값을 설정합니다: minio.persistence.volumeName=<이전 PersistentVolume 이름>.

  8. GitLab 사용자 지정 리소스를 적용합니다.

  9. 새로운 MinIO PersistentVolumeClaim(및 MinIO 팟)을 삭제하여 PersistentVolumeClaim이 연결 해제되고 삭제될 수 있도록 합니다. Operator는 PersistentVolumeClaim을 다시 생성합니다. 이는 .spec 필드가 불변성이기 때문에 필요합니다.

  10. 이전 MinIO PersistentVolume이 이제 새로운 MinIO PersistentVolumeClaim에 연결되었는지 확인합니다.

  11. GitLab UI에서 이슈, 아티팩트 등을 탐색하여 데이터가 복원되었는지 확인합니다.

이전 PersistentVolume에 다시 연결하는 방법에 대한 자세한 내용은 영구 볼륨 문서를 참조하세요.

다시 말씀드리면, 패키지된 MinIO 인스턴스는 운영 환경 사용을 권장하지 않습니다.

다중 데이터베이스 연결 구성

GitLab 16.0에서 GitLab은 같은 PostgreSQL 데이터베이스를 가리키는 두 개의 데이터베이스 연결을 기본으로 사용합니다.

단일 데이터베이스 연결로 다시 전환하려면 다중 데이터베이스 연결 구성을 참조하세요.

구성 요소 비활성화 또는 이름 변경

리소스의 이름을 변경하고 비활성화하는 것은 nameOverride 변경 및 다양한 *.enable: false 값을 조합하여 가능하지만, GitLab Operator는 더 이상 필요하지 않은 Kubernetes 리소스를 자동으로 제거하지 않습니다. 따라서 위에서 언급한 모든 작업은 남은 리소스에 대한 수동 관리를 요구합니다.

그러나 GitLab 사용자 지정 리소스의 인스턴스를 삭제하면 해당 인스턴스와 연결된 모든 리소스가 예상대로 제거됩니다.

문제 !889가 이를 추적하기 위해 생성되었습니다.