오퍼레이터 문제 해결

이 문서는 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 인증서를 가져오는 문제는 Namespace의 이벤트 로그에서 확인할 수 있습니다. 

$ 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
...

다음 단계는 TLS 인증서를 생성하는 중에 문제가 있는지 나타내는 문제를 찾기 위해 Cert Manager 로그를 검사하는 것입니다.

OpenShift 특정 문제

OpenShift는 보다 제한적인 보안 모델을 가지고 있고, 그 결과로 GitLab 오퍼레이터는 클러스터 관리자 계정으로 설치되어야 합니다. 개발자 계정은 오퍼레이터가 올바르게 작동하도록 하는 데 필요한 권한을 가지고 있지 않습니다.

Ingress NGINX Controller Pods가 이 이슈에 설명된대로 유효하지 않은 SCC 매개변수로 인해 프로비저닝을 할 수 없는 경우, 올바른 해결책은 리포지토리에서 SCC를 업데이트하여 Ingress NGINX가 OpenShift 클러스터에서 시작할 수 있도록 하는 것입니다:

  1. 최신 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 Operator 리포지토리의 릴리스 페이지에서 릴리스 매니페스트를 사용하면 이 문제가 발생하지 않습니다. SCC가 포함되어 있기 때문입니다. OperatorHubs에서 지원되지 않는 객체에 대한 관련 이슈:

GitLab 인스턴스 배포 문제

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

Core 서비스가 준비되지 않음

GitLab 오퍼레이터는 Redis, PostgreSQL 및 Gitaly의 인스턴스를 설치하는 데에 의존합니다. 이러한 서비스는 코어 서비스로 알려져 있습니다. GitLab 사용자 리소스를 배포한 후에 코어 서비스가 준비되지 않았다는 너무 많은 오퍼레이터 로그 메시지가 있다면, 이는 이러한 서비스 중 한 가지에서 작동하는 문제가 발생하고 있다는 것입니다.

특히 각 서비스의 엔드포인트를 확인하여 해당 서비스 Pod에 연결되는지 확인하십시오. 또한, 클러스터에 충분한 리소스가 없어 GitLab 인스턴스를 지원할 수 없다는 가능성도 있습니다. 그 경우에는 클러스터에 추가 노드를 추가해야 할 수 있습니다.

GitLab 인스턴스의 배포를 중단하는 코어 서비스가 어느 것인지 보고하는 것을 추적하기 위해 이슈 #305가 생성되었습니다.

GitLab UI 접근 불가능 (Ingress에 주소가 없고/또는 CertManager 도전 실패)

GitLab 오퍼레이터의 설치 매니페스트 및 Helm 차트는 기본적으로 모든 리소스 이름에 대해 gitlab을 접두어로 사용합니다. 단 Helm 값에서 nameOverride가 지정된 경우 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 Pods 누락

OpenShift 환경에서 NGINX Ingress Controller는 OpenShift Routes 대신에 GitLab 인스턴스로의 트래픽을 방향 지정하는 데 사용됩니다 (HTTPS 및 SSH 모두). GitLab 인스턴스에 연결 문제가 있다면, 먼저 NGINX Ingress Controller가 배포되었는지 확인하십시오.

배포가 있으면, kubectl get deploy 출력의 READY 상태를 확인하십시오. READY 상태가 0/0로 보고되면, kubectl get events -n <namespace> | grep -i nginx의 출력을 조사하여 Security Context Constraint (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 컨트롤러가 Pod를 올바르게 생성할 수 있도록 Ingress 컨트롤러 Deployment를 삭제해야 할 수도 있습니다.

Horizontal pod autoscalers are not scaling

만약 수평 파드 오토스케일러(HPA)가 트래픽 부하에 따라 파드 수를 적절히 확장하지 않는다면, Metrics Server가 설치되었는지 확인하세요. Kubernetes 클러스터에서 Metrics Server는 설치가 필요한 추가 구성 요소입니다. 설치 프로세스는 설치 문서에서 확인할 수 있습니다.

OpenShift 클러스터에는 내장된 Metrics Server가 있어서 HPAs가 올바르게 작동해야 합니다.

PersistentVolumeClaim 구성 변경 시 데이터 복원

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

예를 들어, !419에서는 GitLab Helm 차트의 MinIO 구성요소로 Operator로 정의된 MinIO 구성요소를 대체했습니다. 이 변경으로 인해 PersistentVolumeClaim를 포함한 객체 이름이 변경되었고, 이전 MinIO 인스턴스를 사용하는 사용자는 지속된 데이터를 포함한 이전 PersistentVolume에 다시 연결하기 위해 추가 작업이 필요했습니다.

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

  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을 언바인드하고 삭제할 수 있습니다. 이 작업은 .spec 필드가 변경할 수 없기 때문에 필요합니다.
  10. 이전 MinIO PersistentVolume가 새 MinIO PersistentVolumeClaim에 바인드되었는지 확인합니다.
  11. GitLab UI에서 이슈, artifacts 등으로 이동하여 데이터가 복원되었는지 확인합니다.

이전 PersistentVolume에 다시 연결하는 자세한 내용은 지속적인 볼륨 문서를 참조하세요.

참고로, 번들된 MinIO 인스턴스는 운영 환경에서 권장되지 않습니다.

여러 데이터베이스 연결 구성하기

GitLab 16.0부터 GitLab은 동일한 PostgreSQL 데이터베이스를 가리키는 두 데이터베이스 연결을 사용하도록 기본값으로 설정됩니다.

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

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

nameOverride의 변경 및 여러 *.enable: false 값을 조합하여 리소스 이름 변경 및 비활성화가 가능하지만, GitLab Operator는 더 이상 필요하지 않은 Kubernetes 리소스를 자동으로 제거하지 않습니다. 따라서 위와 같은 작업 중 어떤 것이라도 나머지 리소스를 수동으로 관리해야 합니다.

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

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