• 클러스터 상태 확인
  • Praefect 마이그레이션
  • 노드 연결 및 디스크 접근
  • 데이터베이스 읽기 및 쓰기 액세스
  • 액세스할 수 없는 리포지터리
  • 클록 동기화 확인
• Praefect 로그의 오류
• Praefect 데이터베이스에서 높은 CPU 부하
• 기본 Gitaly 노드 결정
• 리포지터리 메타데이터 보기
  • 예시
  • 사용 가능한 메타데이터
  • ‘리포지터리를 찾을 수 없음’ 오류로 명령이 실패하는 경우
• 리포지터리가 동기화되었는지 확인합니다
• ‘Relation does not exist’ 오류
• ‘리포지터리에 대한 유효하지 않은 리포지터리’ 오류로 요청이 실패하는 경우
• 클라우드 플랫폼에서의 Gitaly 클러스터 성능 문제
• gitlab-ctl reconfigure 명령이 STDOUT: praefect: configuration error: error reading config file: toml: cannot store TOML string into a Go int 오류로 실패하는 경우

Gitaly 클러스터의 문제 해결

Gitaly 클러스터(프리펙트) 문제 해결 시 아래 정보를 참조하세요. Gitaly 문제 해결에 대한 자세한 내용은 Gitaly 문제 해결을 참조하세요.

클러스터 상태 확인

• GitLab 14.5에 도입됨.

check Praefect 하위 명령은 Gitaly 클러스터의 상태를 확인하는 일련의 체크를 실행합니다.

gitlab-ctl praefect check

다음 섹션에서 실행되는 체크에 대해 설명합니다.

Praefect 마이그레이션

Praefect가 올바르게 작동하려면 데이터베이스 마이그레이션이 최신 상태여야 합니다. Praefect 마이그레이션이 최신 상태인지 확인합니다.

이 체크가 실패하면:

1. 데이터베이스의 schema_migrations 테이블을 확인하여 실행된 마이그레이션을 확인합니다.
2. 마이그레이션을 최신 상태로 만들기 위해 praefect sql-migrate를 실행합니다.

노드 연결 및 디스크 접근

Praefect가 모든 Gitaly 노드에 액세스할 수 있는지, 각 Gitaly 노드가 모든 스토리지에 대해 읽기 및 쓰기 액세스 권한을 가지고 있는지 확인합니다.

이 체크가 실패하면:

1. 네트워크 주소 및 토큰이 올바르게 설정되어 있는지 확인합니다:
   • Praefect 구성.
   • 각 Gitaly 노드의 구성.
2. Gitaly 노드에서 실행 중인 gitaly 프로세스가 git으로 실행되는지 확인합니다. Gitaly가 스토리지 디렉터리에 액세스하는 데 제한이 있는 문제가 있을 수 있습니다.
3. Praefect를 Gitaly 노드에 연결하는 네트워크에 문제가 있는지 확인합니다.

데이터베이스 읽기 및 쓰기 액세스

Praefect가 데이터베이스에서 읽기 및 쓰기를 할 수 있는지 확인합니다.

이 체크가 실패하면:

1. Praefect 데이터베이스가 복구 모드인지 확인합니다. 복구 모드에서는 테이블을 읽기 전용으로 설정할 수 있습니다. 확인하려면 다음을 실행합니다.

   select pg_is_in_recovery()
   

2. Praefect가 PostgreSQL에 연결하는 데 사용하는 사용자가 데이터베이스에 읽기 및 쓰기 액세스 권한을 가지고 있는지 확인합니다.

3. 데이터베이스가 읽기 전용 모드로 설정되었는지 확인합니다. 확인하려면 다음을 실행합니다.

   show default_transaction_read_only
   

액세스할 수 없는 리포지터리

기본 할당이 없거나 기본 할당이 사용할 수 없어서 액세스할 수 없는 리포지터리가 몇 개 있는지 확인합니다.

이 체크가 실패하면:

1. Gitaly 노드 중 어떤 것이 다운되었는지 확인합니다. 확인하려면 praefect ping-nodes를 실행합니다.
2. Praefect 데이터베이스에 부하가 많은지 확인합니다. Praefect 데이터베이스가 응답이 느리면 건강 체크가 데이터베이스에 지속적으로 실패하여 Praefect가 노드가 건강하지 않다고 판단할 수 있습니다.

클록 동기화 확인

• GitLab 14.8에 도입됨.

Praefect와 Gitaly 서버 간의 인증에는 서버 시간이 동기화되어 있어야 토큰 확인이 성공할 수 있습니다.

이 체크는 permission denied 오류의 근본 원인을 파악하는 데 도움을 줍니다.

공용 pool.ntp.org 서버에 액세스할 수 없는 오프라인 환경에서는 Praefect check 하위 명령이 다음과 유사한 오류 메시지와 함께 이 체크를 실패합니다.

checking with NTP service at  and allowed clock drift 60000ms [correlation_id: <XXX>]
Failed (fatal) error: gitaly node at tcp://[gitlab.example-instance.com]:8075: rpc error: code = DeadlineExceeded desc = context deadline exceeded

이 문제를 해결하려면 모든 Praefect 서버에서 다음과 같이 환경 변수를 설정하여 액세스할 수 있는 내부 NTP 서버를 가리키도록 합니다.

export NTP_HOST=ntp.example.com

Praefect 로그의 오류

오류가 발생하면 /var/log/gitlab/gitlab-rails/production.log를 확인합니다.

일반적인 오류 및 가능한 원인은 다음과 같습니다:

• 500 응답 코드
  • ActionView::Template::Error (7:permission denied)
    • GitLab 서버에서 praefect['configuration'][:auth][:token] 및 gitlab_rails['gitaly_token']이 일치하지 않습니다.
  • Unable to save project. Error: 7:permission denied
    • GitLab 서버에서 praefect['configuration'][:virtual_storage]의 시크릿 토큰이 하나 이상의 Gitaly 서버의 gitaly['auth_token'] 값과 일치하지 않습니다.
• 503 응답 코드
  • GRPC::Unavailable (14:failed to connect to all addresses)
    • GitLab이 Praefect에 연결할 수 없었습니다.
  • GRPC::Unavailable (14:all SubCons are in TransientFailure...)
    • Praefect가 자식 Gitaly 노드 중 하나 이상에 연결할 수 없습니다. 진단을 위해 Praefect 연결 확인기를 실행해 보세요.

Praefect 데이터베이스에서 높은 CPU 부하

Praefect 데이터베이스가 높은 CPU 사용률을 경험하는 일반적인 이유는 다음과 같습니다:

• Prometheus 메트릭 스크랩이 비용이 많이 드는 쿼리를 실행합니다. GitLab 14.2 이상인 경우, gitlab.rb에서 praefect['configuration'][:prometheus_exclude_database_from_default_metrics] = true를 설정합니다.
• 읽기 분배 캐싱이 비활성화되어 있어 사용자 트래픽이 많을 때 데이터베이스로 실행되는 쿼리 수가 증가합니다. 읽기 분배 캐싱이 활성화되었는지 확인합니다.

기본 Gitaly 노드 결정

리포지터리의 기본 노드를 확인하려면:

• GitLab 14.6 이상에서는 praefect metadata 하위 명령을 사용합니다.
• GitLab 13.12에서 GitLab 14.5에는 리포지터리별 기본 노드를 사용하면, gitlab:praefect:replicas Rake 작업을 사용합니다.

• GitLab 13.12 및 이전의 레거시 선택 전략에서 기본 노드는 가상 리포지터리의 모든 리포지터리에 대해 동일했습니다. 특정 가상 리포지터리의 현재 기본 Gitaly 노드를 확인하려면:

  • (권장) Gitlab Omnibus - Praefect 대시보드의 Shard Primary Election Grafana 차트를 사용합니다.

  • Grafana를 설정하지 않았다면 각 Praefect 노드의 각 호스트에서 다음 명령을 사용합니다.

    curl localhost:9652/metrics | grep gitaly_praefect_primaries
    

리포지터리 메타데이터 보기

• GitLab 14.6에서 소개됨.

Gitaly 클러스터는 클러스터에 저장된 리포지터리에 대한 메타데이터 데이터베이스를 유지합니다. 문제 해결을 위해 메타데이터를 검사하려면 praefect metadata 하위 명령을 사용하세요.

Praefect에서 할당한 리포지터리 ID를 사용하여 리포지터리의 메타데이터를 검색할 수 있습니다:

sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml metadata -repository-id <repository-id>

물리적 리포지터리 상의 물리적 경로가 @cluster로 시작하는 경우, 물리적 경로에서 리포지터리 ID를 찾을 수 있습니다.

가상 리포지터리와 상대 경로를 사용하여 리포지터리의 메타데이터를 검색할 수도 있습니다:

sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml metadata -virtual-storage <virtual-storage> -relative-path <relative-path>

예시

Praefect에서 할당한 리포지터리 ID가 1인 리포지터리의 메타데이터를 검색하려면 다음과 같이 합니다:

sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml metadata -repository-id 1

가상 리포지터리가 default이고 상대 경로가 @hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9.git인 리포지터리의 메타데이터를 검색하려면 다음과 같이 합니다:

sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml metadata -virtual-storage default -relative-path @hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9.git

이 중 하나의 예시를 사용하여 예시 리포지터리의 다음 메타데이터를 검색합니다:

리포지터리 ID: 54771
가상 리포지터리: "default"
상대 경로: "@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9.git"
레플리카 경로: "@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9.git"
프라이머리: "gitaly-1"
생성: 1
레플리카:
- 리포지터리: "gitaly-1"
  할당됨: true
  생성: 1, 완전히 최신 상태
  건강함: true
  유효한 프라이머리: true
  확인됨: 2021-04-01 10:04:20 +0000 UTC
- 리포지터리: "gitaly-2"
  할당됨: true
  생성: 0, 1개의 변경 뒤쳐짐
  건강함: true
  유효한 프라이머리: false
  확인됨: 확인되지 않음
- 리포지터리: "gitaly-3"
  할당됨: true
  생성: 레플리카가 아직 생성되지 않음
  건강하지 않음: false
  유효한 프라이머리: false
  확인됨: 확인되지 않음

사용 가능한 메타데이터

praefect metadata에 의해 검색된 메타데이터에는 다음 표에 나열된 필드가 포함됩니다.

각 레플리카에 대해 다음 메타데이터를 사용할 수 있습니다:

‘리포지터리를 찾을 수 없음’ 오류로 명령이 실패하는 경우

-virtual-storage에 제공된 값이 잘못된 경우, 다음 오류가 발생합니다:

get metadata: rpc error: code = NotFound desc = repository not found

문서화된 예제는 -virtual-storage default를 지정합니다. Praefect 서버 설정인 /etc/gitlab/gitlab.rb의 praefect['configuration'][:virtual_storage]를 확인하십시오.

리포지터리가 동기화되었는지 확인합니다

어떤 경우에는 Praefect 데이터베이스가 기본 Gitaly 노드와 동기화되지 않을 수 있습니다. 주어진 리포지터리가 모든 노드에서 완전히 동기화되었는지 확인하려면 Rails 노드에서 gitlab:praefect:replicas Rake 작업을 실행하십시오. 이 Rake 작업은 모든 Gitaly 노드에서 리포지터리를 체크섬합니다.

Praefect dataloss 명령은 Praefect 데이터베이스의 리포지터리 상태만 확인하며 이러한 시나리오에서 동기화 문제를 감지하는 데 사용할 수 없습니다.

‘Relation does not exist’ 오류

기본적으로 Praefect 데이터베이스 테이블은 gitlab-ctl reconfigure 작업에 의해 자동으로 생성됩니다.

그러나 Praefect 데이터베이스 테이블은 초기 재구성 시 자동으로 생성되지 않을 수 있으며 다음 중 하나의 경우에 관계가 존재하지 않는 오류를 발생시킬 수 있습니다:

• gitlab-ctl reconfigure 명령을 실행하지 않은 경우.
• 실행 중에 오류가 발생한 경우.

예를 들면:

• ERROR: relation "node_status" does not exist at character 13
• ERROR: relation "replication_queue_lock" does not exist at character 40

• 다음과 같은 오류:

  {"level":"error","msg":"Error updating node: pq: relation \"node_status\" does not exist","pid":210882,"praefectName":"gitlab1x4m:0.0.0.0:2305","time":"2021-04-01T19:26:19.473Z","virtual_storage":"praefect-cluster-1"}
  

이를 해결하기 위해 praefect 명령의 sql-migrate 하위 명령을 사용하여 데이터베이스 스키마 마이그레이션을 수행할 수 있습니다:

$ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml sql-migrate
praefect sql-migrate: OK (applied 21 migrations)

‘리포지터리에 대한 유효하지 않은 리포지터리’ 오류로 요청이 실패하는 경우

이는 Praefect 구성에서 사용된 가상 리포지터리 이름이 GitLab의 gitaly['configuration'][:storage][<index>][:name] 설정에 사용된 리포지터리 이름과 일치하지 않음을 나타냅니다.

Praefect와 GitLab 구성에서 사용된 가상 리포지터리 이름을 일치시켜 이 문제를 해결하십시오.

클라우드 플랫폼에서의 Gitaly 클러스터 성능 문제

Praefect는 많은 CPU나 메모리를 필요로 하지 않으며, 소규모 가상 머신에서 실행할 수 있습니다. 클라우드 서비스는 디스크 IO 및 네트워크 트래픽과 같은 소규모 VM이 사용할 수 있는 리소스에 대한 제한을 가할 수 있습니다.

Praefect 노드는 많은 네트워크 트래픽을 생성합니다. 클라우드 서비스에서 네트워크 대역폭이 제한된 경우 다음 증상이 관측될 수 있습니다:

• Git 작업의 성능 저하.
• 높은 네트워크 latency.
• Praefect에 의한 높은 메모리 사용량.

가능한 해결책:

• 더 큰 VM을 프로비저닝하여 더 큰 네트워크 트래픽 할당량에 액세스하십시오.
• Praefect 노드가 교통 할당량을 고갈시키지 않았는지 확인하기 위해 클라우드 서비스의 모니터링 및 로깅을 사용하십시오.

gitlab-ctl reconfigure 명령이 STDOUT: praefect: configuration error: error reading config file: toml: cannot store TOML string into a Go int 오류로 실패하는 경우

이 오류는 praefect['database_port'] 또는 praefect['database_direct_port']가 정수가 아닌 문자열로 구성된 경우 발생합니다.