오퍼레이터 문제 해결

이 문서는 GitLab 오퍼레이터의 설치 및 GitLab 사용자 지정 리소스를 통한 GitLab 인스턴스 배포의 문제 해결을 돕기 위한 노트 및 팁 컬렉션입니다.

설치 문제

Kubernetes 환경에서 오퍼레이터의 설치를 문제 해결하는 것은 다른 Kubernetes 워크로드를 문제 해결하는 것과 매우 유사합니다. 오퍼레이터 매니페스트를 배포한 후 오퍼레이터 Pod의 kubectl describe 출력 또는 kubectl get events -n <namespace>를 모니터링합니다. 이를 통해 오퍼레이터 이미지를 검색하거나 오퍼레이터를 시작하기 전 필요한 다른 사전 조건에 대한 문제를 알 수 있습니다.

오퍼레이터가 시작되지만 이륙되면, 오퍼레이터 로그를 검사하여 Pod의 종료 원인에 대한 정보를 얻을 수 있습니다. 다음 명령으로 이 작업을 수행할 수 있습니다.

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

또한, 오퍼레이터는 올바른 작동을 위해 Cert Manager에 의존합니다. TLS 인증서가 Secret으로 생성되고 오퍼레이터 Pod에 볼륨으로 마운트됩니다. TLS 인증서를 가져오는 문제는 네임스페이스의 이벤트 로그에서 찾을 수 있습니다.

$ kubectl get events -n gitlab-system
...
102초        Warning   FailedMount         pod/gitlab-controller-manager-d4f65f856-b4mdj    volume "cert"을(를) 위한 MountVolume.SetUp이(가) 실패했습니다: secret "webhook-server-cert"을(를) 찾을 수 없음
107초        Warning   FailedMount         pod/gitlab-controller-manager-d4f65f856-b4mdj    볼륨을 연결하거나 마운트할 수 없음: unmounted volumes=[cert], unattached volumes=[cert gitlab-manager-token-fc4p9]: 조건을 기다리는 동안 시간이 초과됨
...

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

OpenShift에 특화된 문제

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

Ingress NGINX Controller Pods가 이 이슈에 설명된 것처럼 잘못된 SCC 매개변수로 인해 프로비저닝을 할 수 없다면, 올바른 해결책은 해당 리포지터리의 SCC를 업데이트하여 Ingress NGINX를 OpenShift 클러스터에서 시작할 수 있도록 하는 것입니다.

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

SCC를 추출합니다.

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

scc.yaml을 클러스터에 적용합니다.
```
kubectl apply -f scc.yaml
```

GitLab 오퍼레이터 리포지터리의 릴리스 페이지에서 릴리스된 매니페스트로부터 설치하면 이런 문제가 발생하지 않습니다. SCC가 포함되어 있기 때문입니다. OperatorHubs에서 지원되지 않는 객체에 대한 관련 이슈:

GitLab 인스턴스 배포 문제

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

핵심 서비스가 준비되지 않음

GitLab 오퍼레이터는 Redis, PostgreSQL 및 Gitaly의 인스턴스를 설치하는 데 의존합니다. 이러한 서비스는 핵심 서비스로 알려져 있습니다. GitLab 사용자 지정 리소스를 배포한 후 핵심 서비스가 준비되지 않았다는 워터마크 메시지가 지나치게 많이 나타나면, 이는 이러한 서비스 중 하나가 작동에 문제가 있는 것입니다.

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

GitLab 인스턴스의 배포를 중단하는 핵심 서비스가 무엇인지 보고하는 이슈 #305이 생성되었습니다.

GitLab UI에 연결할 수 없음 (Ingresses에 주소가 없거나/또는 CertManager 도전 실패)

GitLab 오퍼레이터의 설치 매니페스트 및 Helm 차트는 기본적으로 모든 리소스 이름에 대해 gitlab을 접두어로 사용합니다. nameOverride가 Helm 값에서 명시되지 않는 한, 기본 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

명시적 설정 없이 Ingresses는 존재하지 않는 demo-nginx라는 Ingress를 찾으려고 시도할 것입니다.

NGINX Ingress Controller pods MISSING

OpenShift 환경에서 NGINX Ingress Controller는 OpenShift Routes 대신 GitLab 인스턴스로의 트래픽을 안내하기 위해 사용됩니다. GitLab 인스턴스에 연결할 문제가 있으면 먼저 NGINX Ingress Controller가 배포되어 있는지 확인하십시오.

배포가 존재하는 경우, kubectl get deploy 출력의 READY 상태를 확인합니다. READY 상태가 0/0으로 보고되면, kubectl get events -n <namespace> | grep -i nginx 출력을 검사하여 OpenShift용 NGINX RBAC 리소스가 위반되었다는 메시지를 찾습니다.

이는 NGINX RBAC 리소스가 OpenShift에 배포되지 않았음을 나타냅니다. OpenShift용 오퍼레이터 매니페스트를 다음 명령으로 다시 적용해야 합니다.

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

매니페스트를 적용한 후, SCC를 올바르게 획득하고 Ingress Controller가 올바르게 Pod를 생성할 수 있도록 Ingress Controller 배포를 삭제하는 것이 필요할 수 있습니다.

Horizontal pod autoscalers가 스케일링되지 않음

Horizontal pod autoscalers (HPA)가 트래픽 부하에 따라 pod 수를 조절하지 않는다는 것을 확인하면 Metrics Server의 설치 여부를 확인합니다. Kubernetes 클러스터에서 Metrics Server는 추가 컴포넌트이므로 설치 문서에서 설치 프로세스를 찾을 수 있습니다.

OpenShift 클러스터에는 기본으로 Metrics Server가 내장되어 있으므로 HPA가 정상적으로 작동해야 합니다.

PersistentVolumeClaim 구성 변경 시 데이터 복원

데이터 지속성을 위해 MinIO와 같은 컴포넌트를 사용하는 경우, 이전 PersistentVolume에 다시 연결해야 할 수도 있습니다.

예를 들어, !419는 오퍼레이터로부터 제공되는 MinIO 컴포넌트를 GitLab Helm 차트의 MinIO 컴포넌트로 대체했습니다. 이 변경 사항의 일환으로 객체 이름이 변경되었으며, 그 중에는 PersistentVolumeClaim도 포함됩니다. 따라서 오퍼레이터 번들 MinIO 인스턴스를 사용하는 경우 이전 PersistentVolume에 다시 연결해야 할 수 있습니다.

GitLab 오퍼레이터를 0.6.4로 업그레이드한 후, 새 PersistentVolumeClaim을 이전 PersistentVolume에 연결하려면 다음 단계를 수행하십시오.

$RELEASE_NAME-minio-secret Secret을 삭제합니다. 0.6.4로 업그레이드하면 Secret의 내용이 변경되지만 Secret 이름은 변경되지 않습니다.
이전 MinIO PersistentVolume의 .spec.persistentVolumeReclaimPolicy를 Delete에서 Retain으로 변경합니다.
이전 MinIO StatefulSet인 $RELEASE_NAME-minio를 삭제합니다.
이전 MinIO PersistentVolume에서 .spec.ClaimRef를 제거하여 이전 MinIO PersistentVolumeClaim과 연결을 해제합니다.
이전 MinIO PersistentVolumeClaim인 export-gitlab-minio-0를 삭제합니다.
이전 PersistentVolume 상태가 Available로 변경되었는지 확인합니다.
GitLab 사용자 지정 리소스에서 다음 값을 설정합니다: minio.persistence.volumeName=<이전 PersistentVolume 이름>.
GitLab 사용자 지정 리소스를 적용합니다.
새 MinIO PersistentVolumeClaim (및 MinIO Pod)을 삭제하여 PersistentVolumeClaim을 언바운드 상태로 만들고 삭제할 수 있도록 합니다. .spec 필드가 변경할 수 없기 때문에 Operator가 PersistentVolumeClaim를 다시 만들 것입니다.
이전 MinIO PersistentVolume가 새 MinIO PersistentVolumeClaim에 바인딩되었는지 확인합니다.
데이터가 복원되었는지 GitLab UI에서 issues, artifacts 등을 확인합니다.

이전 PersistentVolume에 다시 연결하는 자세한 정보는 지속적인 볼륨 문서를 참조하십시오.

다시 한 번 말씀드리지만, 번들 MinIO 인스턴스는 프로덕션 환경에서 권장되지 않습니다.

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

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

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

컴포넌트의 비활성화 또는 이름 바꾸기

nameOverride의 변경 및 여러 *.enable: false 값의 조합을 통해 리소스의 이름을 바꾸거나 비활성화하는 것이 가능하지만, GitLab Operator는 더 이상 필요하지 않은 Kubernetes 리소스를 자동으로 제거하지 않습니다. 결과적으로 위의 작업 중 어떤 것이라도 남아있는 리소스를 매뉴얼으로 관리해야 합니다.

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

그러나 !889 문제가 생성되어 이를 추적하고 있습니다.