오퍼레이터 문제 해결

이 문서는 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초        경고   FailedMount         pod/gitlab-controller-manager-d4f65f856-b4mdj    볼륨 "cert"를 위한 MountVolume.SetUp이 실패함: secret "webhook-server-cert"를 찾을 수 없음
107초        경고   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를 올바르게 시작할 수 있도록 하는 것입니다:

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 접근 불가 (Ingress가 주소를 가지지 않거나/또는 CertManager 도전 작업이 실패함)

GitLab 오퍼레이터의 설치 매니페스트 및 Helm 차트는 기본값으로 모든 리소스 이름에 대해 gitlab을 접두어로 사용합니다. Helm 값에서 nameOverride가 지정되지 않는 한, 결과적으로 NGINX IngressClass는 기본적으로 gitlab-nginx로 이름이 지정됩니다. 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를 찾으려고 하지만 해당 이름의 Ingress는 존재하지 않기 때문에 문제가 발생합니다.

NGINX Ingress Controller pods missing

오픈시프트 환경에서는 OpenShift Routes 대신 NGINX Ingress Controller를 사용하여 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)가 위반되었다는 메시지가 있는지 확인하세요.

이는 NGINX RBAC 리소스가 OpenShift에 배포되지 않았음을 나타냅니다. OpenShift를 위한 operator manifest는 다음 명령으로 다시 적용해야 합니다:

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

manifest를 적용한 후에는 Ingress 컨트롤러 배포를 삭제하여 SCC를 올바르게 획득하고 Ingress 컨트롤러가 Pod를 올바르게 생성할 수 있도록 해야 할지도 모릅니다.

Horizontal pod autoscalers are not scaling

수평 Pod 오토스케일러 (HPA)가 트래픽 부하에 따라 Pod 수를 확장하지 않는 것을 발견한다면, 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로 업그레이드한 후, 다음 단계를 완료하여 새 PersistentVolumeClaim을 이전 PersistentVolume에 연결하세요:

$RELEASE_NAME-minio-secret Secret을 삭제합니다. Secret의 내용은 0.6.4 업그레이드로 변경되지만 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 CustomResource에서 다음 값을 설정합니다: minio.persistence.volumeName=<이전 PersistentVolume 이름>.
GitLab CustomResource를 적용합니다.
새 MinIO PersistentVolumeClaim을 삭제합니다(new MinIO pod도 함께 삭제하여 PersistentVolumeClaim이 언바운드 상태가 되고 삭제할 수 있도록 합니다). 이는 .spec 필드가 변경할 수 없기 때문에 필요합니다.
이전 MinIO PersistentVolume가 새 MinIO PersistentVolumeClaim에 바인딩되었는지 확인합니다.
데이터가 복원되었는지 확인합니다. GitLab UI에서 이슈, 아티팩트 등으로 이동하여 확인합니다.

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

마지막으로 번들 MinIO 인스턴스는 운영상 용도에 권장되지 않습니다.

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

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

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

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

nameOverride 및 다양한 *.enable: false 값 조합을 통해 리소스 이름을 변경하거나 비활성화하는 것은 가능하지만, GitLab Operator는 더 이상 필요하지 않은 Kubernetes 리소스를 자동으로 제거하지 않습니다. 결과적으로 위의 작업 중 어느 것이든 남은 리소스를 수동으로 관리해야 합니다.

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

해당 인스턴스의 GitLab 사용자 지정 리소스를 삭제하면 위의 모든 리소스가 예상대로 제거됩니다.

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