• Gitaly Cluster를 배포하기 전에
  • 알려진 문제
  • 스냅샷 백업 및 복구 제한 사항
  • 문제 또는 제한 사항이 발생한 Gitaly Cluster의 조치
• 디스크 요구 사항
• 리포지토리 직접 액세스
• Gitaly
  • Gitaly 아키텍처
  • Gitaly 구성
  • Gitaly CLI
  • 리포지토리 백업
• Gitaly 클러스터
  • Geo와의 비교
  • 가상 스토리지
  • 저장소 레이아웃
    • 클라이언트 생성 레플리카 경로
    • Praefect에서 생성된 레플리카 경로 (GitLab 15.0 이상)
    • 디스크 상의 저장소 식별
    • 작업의 원자성
      • 저장소 생성
      • 저장소 삭제
      • 저장소 이동
  • 구성 요소
  • 아키텍처
  • 기능
    • 분산 읽기
    • 강력한 일관성
    • 복제 요소
  • Gitaly 클러스터 구성
  • Gitaly 클러스터 업그레이드
  • 이전 버전으로 Gitaly 클러스터 다운그레이드
  • Gitaly 클러스터로 마이그레이션
  • Gitaly 클러스터에서 마이그레이션
  • Gitaly 클러스터로 전환

Gitaly 및 Gitaly Cluster

Gitaly은 Git 저장소에 대한 고수준 RPC 액세스를 제공합니다. GitLab에서 Git 데이터를 읽고 쓰는 데 사용됩니다.

Gitaly는 모든 GitLab 설치에 있으며 Git 저장소 저장 및 검색을 조정합니다. Gitaly는 다음과 같이 구성할 수 있습니다.

• 단일 인스턴스 Linux 패키지 설치(모든 GitLab이 한 기기에 있는)에서 작동하는 백그라운드 서비스.
• 스케일링 및 가용성 요구에 따라 전체 클러스터 구성에서 자체 인스턴스로 분리 및 구성됨.

Gitaly는 클라이언트-서버 아키텍처를 구현합니다.

• Gitaly 서버는 Gitaly 자체를 실행하는 모든 노드입니다.
• Gitaly 클라이언트는 Gitaly 서버에 요청을 하는 프로세스를 실행하는 모든 노드입니다. Gitaly 클라이언트는 _Gitaly consumers_로도 알려져 있으며 다음을 포함합니다:
  • GitLab Rails application
  • GitLab Shell
  • GitLab Workhorse
  • GitLab Elasticsearch Indexer
  • GitLab Zoekt Indexer

Gitaly는 GitLab에서 Git 저장소 액세스만 관리합니다. 다른 유형의 GitLab 데이터는 Gitaly를 통해 액세스되지 않습니다.

GitLab은 구성된 저장소 저장소를 통해 저장소에 액세스합니다. 각 새 저장소는 구성된 가중치를 기반으로 한 저장소 저장소 중 하나에 저장됩니다. 각 저장소 저장소는 다음 중 하나입니다.

• 저장 경로를 사용하여 저장소에 직접 액세스하는 Gitaly 저장소, 모든 요청은 이 노드로 라우팅됩니다.
• Gitaly Cluster에서 제공되는 가상 저장소, 여기서 각 저장소는 고장 허용성을 위해 여러 Gitaly 노드에 저장될 수 있습니다. Gitaly Cluster에서:
  • 읽기 요청은 여러 Gitaly 노드에 분산되어 성능을 향상시킬 수 있습니다.
  • 쓰기 요청은 저장소 복제본으로 브로드캐스트됩니다.

Gitaly Cluster를 배포하기 전에

Gitaly Cluster는 고장 허용성의 이점을 제공하지만 추가적인 설정 및 관리 복잡성을 가지고 있습니다. Gitaly Cluster를 배포하기 전에 다음을 검토하세요.

• 기존 알려진 문제.
• 스냅샷 제한 사항.
• 구성 가이드 및 저장소 저장 옵션을 검토하여 Gitaly Cluster가 최선의 설정인지 확인하세요.

아직 Gitaly Cluster로 마이그레이션하지 않은 경우 두 가지 옵션이 있습니다.

• 분할된 Gitaly 인스턴스.
• Gitaly Cluster.

질문이 있다면 고객 성공 관리자나 고객 지원팀에 문의하세요.

알려진 문제

다음 표는 Gitaly Cluster 사용에 영향을 미치는 현재 알려진 문제를 개요로 보여줍니다. 이러한 문제의 현재 상태에 대한 자세한 내용은 참조된 이슈 및 에픽을 확인하세요.

스냅샷 백업 및 복구 제한 사항

Gitaly 클러스터는 스냅샷 백업을 지원하지 않습니다. 스냅샷 백업을 사용하면 Praefect 데이터베이스가 디스크 저장소와 동기화가 안 맞는 문제가 발생할 수 있습니다. 복원 중 Praefect가 Gitaly 디스크 정보의 복제 메타데이터를 다시 만드는 방식 때문에 공식 백업 및 복원 Rake 작업을 사용해야 합니다.

점진적 백업 방법을 사용하여 Gitaly 클러스터 백업을 가속화할 수 있습니다.

두 방법을 사용할 수 없는 경우, 복구 지원을 위해 고객 지원팀에 문의하십시오.

문제 또는 제한 사항이 발생한 Gitaly Cluster의 조치

즉시 복원 또는 복구를 위해 고객 지원팀에 문의하십시오.

디스크 요구 사항

Gitaly 및 Gitaly 클러스터는 무거운 I/O 기반 프로세스이기 때문에 효과적으로 작동하기 위해 빠른 로컬 저장소가 필요합니다. 따라서, 모든 Gitaly 노드가 고체 상태 드라이브(SSD)를 사용하는 것을 강력히 권장합니다.

이러한 SSD는 적어도 다음과 같은 처리량을 가져야 합니다:

• 읽기 작업에 대해 초당 8,000개의 입출력 작업(IOPS).
• 쓰기 작업에 대해 2,000개의 IOPS.

이 IOPS 값은 초기 권장 사항이며, 환경의 작업량 규모에 따라 더 크거나 작은 값으로 조정될 수 있습니다. 환경을 클라우드 제공업체에서 실행하는 경우 IOPS를 올바르게 구성하는 방법에 대해서는 해당 문서를 참조하십시오.

성능과 일관성을 이유로 Gitaly 및 Gitaly 클러스터에는 리포지토리 데이터에 대해 로컬 저장소만 지원합니다. NFS나 클라우드 기반 파일 시스템과 같은 대체 방법은 지원되지 않습니다.

리포지토리 직접 액세스

GitLab은 Gitaly 리포지토리에 직접적으로 액세스하는 것을 권장하지 않습니다. 왜냐하면 Gitaly는 지속적으로 개선되고 변경되기 때문에 여러분의 가정을 무효화시킬 수 있고, 결과적으로 성능 저하, 불안정성, 심지어 데이터 손실을 초래할 수 있기 때문입니다. 예를 들어 다음과 같은 개선 사항 때문입니다:

• Gitaly에는 info/refs 광고 캐시와 같은 최적화가 있으며, 이를 위해서는 Gitaly가 공식 gRPC 인터페이스를 통해 리포지토리 액세스를 제어하고 모니터링해야 합니다.
• Gitaly 클러스터는 장애 허용 및 분산 읽기와 같은 최적화를 위해 gRPC 인터페이스와 데이터베이스에 의존하여 리포지토리 상태를 결정해야 합니다.

경고: Git 리포지토리에 직접 액세스하는 것은 고객의 책임 하에 이루어져야 하며, 지원되지 않습니다.

Gitaly

다음은 Gitaly를 사용하도록 설정한 GitLab을 보여줍니다:

이 예에서: - 각 리포지토리는 storage-1, storage-2, 또는 storage-3 중 하나의 Gitaly 저장소에 저장됩니다. - 각 저장소는 Gitaly 노드로 서비스됩니다. - 세 개의 Gitaly 노드는 각각의 파일 시스템에 데이터를 저장합니다.

Gitaly 아키텍처

다음은 Gitaly 클라이언트-서버 아키텍처를 보여줍니다:

Gitaly 구성

Gitaly는 Linux 패키지 설치 시 미리 구성되어 있으며, 이는 최대 1000 사용자까지의 구성에 적합한 구성입니다. 다음을 위해:

• 최대 2000 사용자까지의 Linux 패키지 설치에 대해서는 특정한 Gitaly 구성 지침을 참조하십시오.
• 자체 컴파일된 설치 또는 사용자 정의 Gitaly 설치에 대해서는 Gitaly 구성을 참조하십시오.

일일 Git 쓰기 작업을 수행하는 2000명 이상의 활성 사용자를 위한 GitLab 설치는 Gitaly 클러스터를 사용하는 것이 가장 적합할 수 있습니다.

Gitaly CLI

gitaly 명령어는 Gitaly 관리자를 위한 추가 하위 명령을 제공하는 명령줄 인터페이스입니다. 예를 들어, Gitaly CLI는 다음을 수행하는 데 사용됩니다:

• 리포지토리에 대한 사용자 정의 Git 후크 구성.
• Gitaly 구성 파일 유효성 검사.
• 내부 Gitaly API의 접근 가능 여부 확인.

다른 하위 명령어에 대한 자세한 정보는 gitaly --help를 실행하십시오.

리포지토리 백업

GitLab 외의 도구를 사용하여 리포지토리를 백업하거나 동기화할 때는 리포지토리 데이터를 복사하는 동안 쓰기 방지해야 합니다.

Gitaly 클러스터

Git 저장소는 GitLab의 Gitaly 서비스를 통해 제공되며, GitLab의 작동에 필수적입니다. 사용자, 저장소 및 활동 수가 증가함에 따라 Gitaly를 적절하게 확장하는 것이 중요합니다. 이를 위해 다음을 수행합니다.

• Git, Gitaly 및 GitLab 애플리케이션 성능 저하를 방지하기 위해 리소스 고갈이 발생하기 전에 Git에 사용 가능한 CPU 및 메모리 리소스를 증가시킵니다.
• 쓰기 작업이 실패하는 저장소 한계에 도달하기 전에 사용 가능한 저장소를 증가시킵니다.
• 단일 장애 지점을 제거하여 오류 허용성을 향상시킵니다. 서비스 저하로 인해 프로덕션에 변경 사항을 배포할 수 없게 된다면 Git은 미션 중요성이 있어야 합니다.

Gitaly는 클러스터 구성으로 실행할 수 있어 다음과 같은 이점이 있습니다.

• Gitaly 서비스 확장
• 오류 허용성 향상

이 구성에서 모든 Git 저장소는 클러스터의 여러 Gitaly 노드에 저장됩니다.

Gitaly 클러스터를 사용하면 다음과 같은 방법으로 오류 허용성이 향상됩니다.

• 웜 스탠바이 Gitaly 노드로 쓰기 작업 복제
• Gitaly 노드 장애 감지
• 사용 가능한 Gitaly 노드로 Git 요청 자동 라우팅

참고: Gitaly 클러스터의 기술 지원은 GitLab 프리미엄 및 얼티밋 고객에게 한정됩니다.

다음은 storage-1에 액세스하도록 구성된 GitLab를 보여주는 그림입니다. storage-1은 Gitaly 클러스터에서 제공된 가상 스토리지입니다.

이 예시에서:

• 저장소는 storage-1이라는 가상 스토리지에 저장됩니다.
• 세 개의 Gitaly 노드인 gitaly-1, gitaly-2, gitaly-3가 storage-1 액세스를 제공합니다.
• 세 개의 Gitaly 노드가 각각의 별도의 해시 스토리지 위치에 있는 데이터를 공유합니다.
• 복제 요소는 3입니다. 각 저장소의 복사본이 세 개 유지됩니다.

Gitaly 클러스터의 가용성 목표는 단일 노드 장애를 가정하고 다음과 같습니다.

• 복구 지점 목표 (RPO): 1분 미만

  쓰기 작업은 비동기적으로 복제됩니다. 새롭게 승격된 기본 상태에 복제되지 않은 모든 쓰기 작업은 손실됩니다.

  강력한 일관성은 특정 상황에서 손실을 방지합니다.

• 복구 시간 목표 (RTO): 10초 미만

  각 Praefect 노드에서 매 초 실행되는 헬스 체크에 의해 장애가 감지됩니다. 장애 조치에는 각 Praefect 노드에서 10회 연속 실패한 헬스 체크가 필요합니다.

RPO 및 RTO의 개선사항은 epic 8903에서 제안됩니다.

경고: 완전한 클러스터 장애가 발생하면 재해 복구 계획을 실행해야 합니다. 이로 인해 위에서 논의한 RPO 및 RTO에 영향을 줄 수 있습니다.

Geo와의 비교

Gitaly 클러스터와 Geo는 모두 중복성을 제공합니다. 그러나

• Gitaly 클러스터는 데이터 저장을 위한 오류 허용성을 제공하며 사용자에게는 보이지 않습니다. 사용자가 Gitaly 클러스터를 사용하는지 알 수 없습니다.
• Geo는 GitLab의 전체 인스턴스에 대한 복제 및 재해 복구를 제공합니다. 사용자는 복제를 위해 Geo를 사용하고 있는지 알 수 있습니다. Geo는 Git 데이터를 포함한 여러 데이터 유형을 복제합니다.

다음 표는 Gitaly 클러스터와 Geo 간의 주요 차이점을 보여줍니다.

더 많은 정보는 다음을 참조하십시오.

• Geo 사용 사례.
• Geo 아키텍처.

가상 스토리지

가상 스토리지를 사용하면 GitLab에서 하나의 저장소 스토리지만 사용하여 저장소 관리를 간소화할 수 있습니다.

Gitaly 클러스터와 함께 가상 스토리지를 사용하면 직접적인 Gitaly 스토리지 구성을 대체할 수 있습니다. 단, 이는 각 저장소를 여러 Gitaly 노드에 저장해야 하므로 추가 저장소 공간을 필요로 합니다. Gitaly 클러스터 가상 스토리지를 사용하는 이점은 다음과 같습니다.

• 모든 Gitaly 노드가 각 저장소의 복사본을 가지고 있기 때문에 오류 허용성이 향상됩니다.
• 읽기 부하가 Gitaly 노드에 분산되므로, 샤드별 피크 부하를 위해 과다한 공급이 필요하지 않아 리소스 이용률이 향상됩니다.
• 읽기 부하가 Gitaly 노드에 분산되므로 성능을 위해 수동 리밸런싱이 필요하지 않습니다.
• 모든 Gitaly 노드가 동일하기 때문에 관리가 더 간단합니다.

저장소 복제본 수는 복제 요소를 사용하여 구성할 수 있습니다.

모든 저장소에 대해 동일한 복제 요소를 가지는 것은 경제적으로 부적합할 수 있습니다. 극히 큰 GitLab 인스턴스에 대해 더 큰 유연성을 제공하기 위해 가변 복제 요소가 이 이슈에서 추적됩니다.

표준 Gitaly 저장소와 마찬가지로 가상 저장소도 샤드될 수 있습니다.

저장소 레이아웃

경고: 저장소 레이아웃은 Gitaly 클러스터의 내부 세부 사항으로, 릴리스 간에 안정적으로 유지되리라고 보장되지 않습니다. 이곳의 정보는 정보 제공 목적으로만 제공되며 디버깅을 돕기 위한 것입니다. 디스크에서 저장소에 직접 변경을 수행하는 것은 지원되지 않으며 일부 변경 사항이 지워지거나 변경되는 것을 유발할 수 있습니다.

Gitaly 클러스터의 가상 저장소는 단일 저장소처럼 보이지만 실제로 여러 물리적 저장소로 구성됩니다. Gitaly 클러스터는 각 작업을 각 물리적 저장소에 복제해야 합니다. 작업은 일부 물리적 저장소에서 성공할 수 있지만 다른 곳에서 실패할 수 있습니다.

일부 적용된 작업은 다른 작업에 문제를 일으킬 수 있으며 시스템을 회복할 수 없는 상태로 남길 수 있습니다. 이러한 유형의 문제를 피하기 위해 각 작업은 완전히 적용되거나 전혀 적용되지 않아야 합니다. 이러한 작업의 속성을 원자성이라고 합니다.

GitLab은 저장소 저장소의 저장소 레이아웃을 제어합니다. GitLab은 저장소 저장소에게 저장소를 생성, 삭제, 이동할 위치를 지시합니다. 이러한 작업은 여러 물리적 저장소에 적용될 때 원자성 문제를 발생시킵니다. 예를 들어:

• GitLab이 복제본 중 하나가 사용할 수 없는 상태에서 저장소를 삭제합니다.
• GitLab이 나중에 저장소를 다시 생성합니다.

결과적으로 삭제 시에 사용할 수 없던 구식 복제본이 충돌을 일으켜 저장소의 재생성을 방해할 수 있습니다.

이러한 원자성 문제로 인해 과거에 다음과 같은 여러 문제가 발생했습니다.

• Gitaly 클러스터의 둘째 사이트에 대한 지오 동기화.
• 백업 복원.
• 저장소 저장소 간의 이동.

Gitaly 클러스터는 이러한 작업에 대해 저장소에서 충돌을 방지하는 특별한 레이아웃으로 디스크에 저장함으로써 원자성을 제공합니다.

클라이언트 생성 레플리카 경로

저장소는 Gitaly 클라이언트가 결정한 상대 경로에 저장됩니다. 이러한 경로는 @cluster 접두사로 시작하지 않아서 식별할 수 있습니다. 상대적인 경로는 해시된 저장소 스키마를 따릅니다.

Praefect에서 생성된 레플리카 경로 (GitLab 15.0 이상)

• GitLab 15.0에서 소개됨 (기본값으로 비활성화된) gitaly_praefect_generated_replica_paths 플래그를 사용.
• GitLab 15.2에서 GitLab.com에 활성화됨.
• GitLab 15.3에서 self-managed에 활성화됨.
• GitLab 15.6에서 다양한 기능이 제공됨. gitaly_praefect_generated_replica_paths 플래그가 제거됨.

Gitaly 클러스터가 저장소를 생성할 때, 저장소에는 _repository ID_라고 하는 고유하고 영구적인 ID가 할당됩니다. 저장소 ID는 Gitaly 클러스터 내부에 있으며 GitLab의 다른 곳의 ID와 관련이 없습니다. 저장소가 Gitaly 클러스터에서 제거되고 나중에 다시 이동되면 저장소에는 새 저장소 ID가 할당되고 Gitaly 클러스터의 관점에서는 전혀 다른 저장소가 됩니다. 저장소 ID의 순서는 항상 증가하지만 순서에는 공백이 있을 수 있습니다.

저장소 ID는 클러스터의 각 저장소에 대한 고유한 저장소 경로인 _replica path_를 파생하는 데 사용됩니다. 저장소의 레플리카는 모두 저장소에서 동일한 레플리카 경로에 저장됩니다. 레플리카 경로는 _상대 경로_와 구별됩니다.

• 상대 경로는 Gitaly 클라이언트가 사용하는 저장소와 가상 저장소를 식별하는 데 사용하는 이름입니다.
• 레플리카 경로는 물리적 저장소의 실제 경로입니다.

Praefect는 클라이언트 요청을 처리할 때 RPC에서 저장소별 레플리카의 가상 (가상 저장소, 상대 경로) 식별자를 물리적 저장소의 (저장소, 레플리카 경로) 식별자로 변환합니다.

다음에 대한 레플리카 경로의 형식:

• 오브젝트 풀: @cluster/pools/<xx>/<xx>/<repository ID>입니다. 오브젝트 풀은 다른 저장소들과 다른 디렉터리에 저장됩니다. Gitaly에서 식별되어야 하며, 이들은 정리 과정의 일부로 제거되지 않도록 해야 합니다. 오브젝트 풀을 정리하면 연결된 저장소에서 데이터 손실이 발생할 수 있습니다.
• 다른 저장소: @cluster/repositories/<xx>/<xx>/<repository ID>입니다.

예를 들어, @cluster/repositories/6f/96/54771입니다.

레플리카 경로의 마지막 구성 요소인 54771은 저장소 ID입니다. 이를 사용하여 디스크에서 저장소를 식별할 수 있습니다.

<xx>/<xx>은 저장소 ID의 문자열 표현의 SHA256 해시의 처음 네 자릿수입니다. 이러한 숫자들은 너무 큰 디렉터리를 피하기 위해 저장소들을 균등하게 나누기 위해 사용됩니다. 이 경우 54771을 해시하면 6f960ab01689464e768366d3315b3d3b2c28f38761a58a70110554eb04d582f7이 되므로 처음 네 자릿수는 6f 및 96입니다.

디스크 상의 저장소 식별

praefect metadata 하위 명령어를 사용하여 다음을 수행하세요:

• 메타데이터 저장소에서 저장소의 가상 저장소와 상대 경로를 검색합니다. 해시된 저장소 경로를 얻은 후에 Rails 콘솔을 사용하여 프로젝트 경로를 검색할 수 있습니다.
• 저장소가 클러스터에서 어디에 저장되어 있는지 다음 중 하나로 찾습니다:
  • 가상 저장소와 상대 경로.
  • 저장소 ID.

디스크 상의 저장소에는 Git 구성 파일에 프로젝트 경로도 포함되어 있습니다. 메타데이터가 삭제된 경우에도 구성 파일을 사용하여 프로젝트 경로를 결정할 수 있습니다. 해시된 저장소의 문서에서 지시 사항을 확인하세요.

작업의 원자성

Gitaly 클러스터는 저장소 생성, 삭제 및 이동 작업의 원자성을 보장하기 위해 PostgreSQL 메타데이터 저장소와 함께 저장소 레이아웃을 사용합니다. 디스크 작업은 여러 저장소 간에 원자적으로 적용될 수 없습니다. 그러나 PostgreSQL은 메타데이터 작업의 원자성을 보장합니다. Gitaly 클러스터는 작업을 모델링하여 실패한 작업이 메타데이터를 항상 일관되게 유지하도록 합니다. 성공한 작업 이후에도 디스크에는 구식 상태가 남을 수 있습니다. 이 상황은 예상된 것이며 남아있는 상태는 미래 작업에 방해가 되지 않지만 정리가 이루어질 때까지 디스크 공간을 불필요하게 사용할 수 있습니다.

남아있는 저장소를 정리하는 백그라운드 크롤러에 대한 계속되는 작업이 있습니다.

저장소 생성

저장소를 생성할 때 Praefect은 다음을 수행합니다:

1. PostgreSQL에서 저장소 ID를 예약하며, 이는 원자적이므로 두 개의 생성이 동일한 ID를 받지 않습니다.
2. 생성된 저장소에 대해 Gitaly 저장소에 레플리카를 생성하며, 이는 저장소 ID에서 파생된 레플리카 경로에 저장됩니다.
3. 저장소가 디스크에 성공적으로 생성된 후 메타데이터 레코드를 만듭니다.

두 개의 동시 작업이 동일한 저장소를 만들더라도 그들은 저장소의 다른 디렉토리에 저장되어 충돌하지 않습니다. 먼저 완료하는 쪽이 메타데이터 레코드를 만들고 다른 작업은 “이미 존재함” 오류로 실패합니다. 실패한 생성은 저장소에 남아있게 됩니다. 남아있는 저장소를 정리하는 백그라운드 크롤러에 대한 계속되는 작업이 있습니다.

저장소 ID는 PostgreSQL의 repositories_repository_id_seq에서 생성됩니다. 위의 예에서 실패한 작업이 한 개의 저장소 ID를 가져가고 이를 성공적으로 저장소를 만들지 못했습니다. 실패한 저장소 생성은 저장소 ID에서 간격(gap)을 생기게 할 것으로 예상됩니다.

저장소 삭제

저장소는 해당 메타데이터 레코드를 제거함으로써 삭제됩니다. 메타데이터 레코드가 삭제되는 즉시 저장소는 논리적으로 더는 존재하지 않습니다. PostgreSQL은 제거 작업의 원자성을 보장하며 동시 삭제는 “찾을 수 없음” 오류로 실패합니다. 메타데이터 레코드를 성공적으로 삭제한 후 Praefect는 저장소로부터 레플리카를 제거하려고 시도합니다. 이 작업은 실패할 수 있으며 저장소에 남아있는 상태가 생길 수 있습니다. 남아있는 상태는 최종적으로 정리됩니다.

저장소 이동

Gitaly와 달리, Gitaly 클러스터는 저장소를 외부에서 이동시키지 않고 메타데이터 저장소에서 저장소의 상대 경로를 업데이트하여 가상적으로만 저장소를 이동시킵니다.

구성 요소

Gitaly 클러스터는 다음과 같은 여러 구성 요소로 구성됩니다:

• 로드 밸런서는 요청 배포 및 안정적인 Praefect 노드 접근을 제공합니다.
• Praefect 노드는 클러스터를 관리하고 Gitaly 노드로의 요청을 라우팅합니다.
• PostgreSQL 데이터베이스는 클러스터 메타데이터를 지속하며 PgBouncer는 Praefect의 데이터베이스 연결을 풀링하는 데 권장됩니다.
• 저장소 저장 및 Git 액세스를 제공하기 위한 Gitaly 노드.

아키텍처

Praefect는 Gitaly의 라우터 및 트랜잭션 관리자이자 Gitaly 클러스터를 실행하는 데 필요한 필수 구성 요소입니다.

자세한 내용은 Gitaly 고가용성(HA) 디자인을 참조하십시오.

기능

Gitaly 클러스터는 다음 기능을 제공합니다:

• Gitaly 노드 간의 분산 판독.
• 보조 레플리카의 강력한 일관성.
• 저장소의 복제 요소로 증가된 부정합성을 위한 복제 요소.
• 프라이머리 Gitaly 노드에서 보조 Gitaly 노드로의 자동 장애 조치.
• 복제 큐가 비어있지 않은 경우 데이터 손실의 가능성에 대한 보고.

가로로 판독을 분산을 포함한 개선을 위해 Gitaly 클러스터 에픽을 따르세요.

분산 읽기

Gitaly 클러스터는 가상 저장소에 구성된 Gitaly 노드 간에 읽기 작업을 분산 지원합니다.

ACCESSOR 옵션으로 표시된 모든 RPC는 최신 및 건강한 Gitaly 노드로 리디렉션됩니다. 예를 들어, GetBlob.

이 문맥에서 ‘최신’은 다음을 의미합니다:

• 이 Gitaly 노드에 대한 복제 작업이 예정되어 있지 않습니다.
• 마지막 복제 작업이 ‘완료’ 상태에 있습니다.

만약:

• 최신 노드가 존재하지 않는다면 기본 노드가 요청을 처리하도록 선택됩니다.
• 노드 선택 중에 다른 오류가 발생한다면 기본 노드가 선택됩니다.

크고 많이 수정된 리포지토리(다중 기가바이트 단일 리포지토리와 같은)를 보유하고 있다면 변경 사항이 Praefect가 이를 보조 노드로 복제하는 속도보다 빠르게 발생한다면 기본 노드가 대부분 또는 모든 요청을 서비스할 수 있습니다. 이런 경우에는 CI/CD 작업 및 기타 리포지토리 트래픽이 기본 노드의 용량에 의해 병목 현상이 발생합니다.

Prometheus를 사용하여 읽기 분산 모니터링하기.

강력한 일관성

• GitLab 14.0에서 강력한 일관성은 주 복제 방법입니다.

Gitaly 클러스터는 변경 사항을 모든 건강하고 최신 복제본에 동기적으로 작성하여 강력한 일관성을 제공합니다. 트랜잭션 시간에 복제본이 오래되었거나 건강하지 않다면, 쓰기는 비동기적으로 복제됩니다.

강력한 일관성은 주 복제 방법입니다. 일부 작업은 여전히 강력한 일관성을 사용하는 대신 복제 작업(최종 일관성)을 사용합니다. 자세한 내용은 강력한 일관성 이픽을 참조하세요.

강력한 일관성을 사용할 수 없는 경우, Gitaly 클러스터는 최종적 일관성을 보장합니다. 이 경우, Gitaly 클러스터는 모든 쓰기 작업을 기본 Gitaly 노드에 작성한 후 보조 Gitaly 노드로 복제합니다.

강력한 일관성 모니터링에 대한 자세한 내용은 Gitaly 클러스터 Prometheus 메트릭 문서를 참조하세요.

복제 요소

복제 요소는 Gitaly 클러스터가 특정 리포지토리의 복사본을 유지하는 수입니다. 더 높은 복제 요소는:

• 보다 높은 신뢰성과 읽기 작업의 분산을 제공합니다.
• 더 높은 저장 비용을 초래합니다.

기본적으로 Gitaly 클러스터는 가상 저장소의 모든 저장소에 복제합니다.

구성 정보는 복제 요소 구성을 참조하세요.

Gitaly 클러스터 구성

Gitaly 클러스터 구성에 대한 자세한 내용은 Gitaly 클러스터 구성을 참조하세요.

Gitaly 클러스터 업그레이드

Gitaly 클러스터를 업그레이드하려면 제로 다운타임 업그레이드 문서를 참조하세요.

이전 버전으로 Gitaly 클러스터 다운그레이드

Gitaly 클러스터를 이전 버전으로 롤백해야 하는 경우, 일부 Praefect 데이터베이스 마이그레이션이 되돌아가야 할 수 있습니다.

Gitaly 클러스터를 다운그레이드하려면 (여러 Praefect 노드가 있는 것으로 가정):

1. 모든 Praefect 노드에서 Praefect 서비스를 중지하세요:

   gitlab-ctl stop praefect
   

2. Praefect 노드 중 하나에서 GitLab 패키지를 이전 버전으로 다운그레이드하세요.

3. 이전 버전으로 다운그레이드한 노드에서 Praefect 마이그레이션 상태를 확인하세요:

   /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml sql-migrate-status
   

4. APPLIED 열에 unknown migration가 포함된 마이그레이션 수를 세어보세요.

5. 이전 버전으로 다운그레이드한 노드에서 되돌려야 할 마이그레이션을 유효성 검사하기 위해 롤백의 시연을 실행하세요. <CT_UNKNOWN>은 이전 노드가 보고한 알 수 없는 마이그레이션 수입니다.

   /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml sql-migrate <CT_UNKNOWN>
   

6. 결과가 올바르게 보인다면, 동일한 명령을 -f 옵션을 사용하여 마이그레이션을 되돌립니다.

   /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml sql-migrate -f <CT_UNKNOWN>
   

7. 남은 Praefect 노드에서 GitLab 패키지를 이전 버전으로 다운그레이드하고 Praefect 서비스를 다시 시작하세요:

   gitlab-ctl start praefect
   

Gitaly 클러스터로 마이그레이션

경고: Gitaly 클러스터에는 알려진 문제가 존재합니다. 계속하기 전에 다음 정보를 검토하세요.

Gitaly 클러스터로 마이그레이션하기 전에:

• Gitaly 클러스터 배포 전을 검토하세요.
• 개선 사항 및 버그 수정을 활용하기 위해 가능한 최신 버전의 GitLab으로 업그레이드하세요.

Gitaly 클러스터로 마이그레이션하려면:

1. 필요한 저장소를 생성하세요. 리포지토리 저장소 권장사항을 참조하세요.
2. Gitaly 클러스터를 생성 및 구성하세요.
3. 기존 Gitaly 인스턴스가 아직 해당 방법으로 구성되지 않았다면, 기존 Gitaly 인스턴스를 TCP를 사용하도록 구성하세요.
4. 리포지토리를 이동하세요. Gitaly 클러스터로 마이그레이션하기 위해, Gitaly 클러스터 외부에 저장된 기존 리포지토리를 이동해야 합니다. 자동으로 마이그레이션되지 않지만 GitLab API를 사용하여 이동을 예약할 수 있습니다.

기본 리포지토리 저장소를 사용하지 않더라도 구성되어 있는지 확인해야 합니다. 이 제한에 대해 자세히 알아보세요.

Gitaly 클러스터에서 마이그레이션

Gitaly 클러스터의 제한 사항과 절충안이 환경에 적합하지 않은 경우, 샤드로 분할된 Gitaly 인스턴스로 마이그레이션할 수 있습니다:

1. 새로운 Gitaly 서버를 생성하고 구성합니다.
2. 저장소를 이동하여 새로 생성된 저장소로 이동합니다. 샤드별 또는 그룹별로 이동할 수 있어 여러 Gitaly 서버에 분산시킬 수 있습니다.

Gitaly 클러스터로 전환

복잡성을 제거하기 위해 GitLab에서 직접적인 Git 액세스를 제거해야 합니다. 그러나 일부 GitLab 설치에서 NFS 상의 Git 저장소가 필요한 경우에는 삭제할 수 없습니다.

GitLab에서 직접적인 Git 액세스를 제거하기 위한 두 가지 노력은 다음과 같습니다:

• GitLab에서 수행되는 비효율적인 Gitaly 쿼리의 수를 줄입니다.
• 고장 허용이나 수평 확장된 GitLab 인스턴스의 관리자들에게 NFS에서 마이그레이션할 것을 설득합니다.

두 번째 노력이 유일한 실질적인 해결책을 제시합니다. 이를 위해 Gitaly 클러스터를 개발했습니다.