%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD
    accTitle: Multiple virtual storages
    accDescr: Example of multiple virtual storages, one with a replication factor of three and one with a replication factor of two.
GitLab[[GitLab server]]
Storage1[(storage-1<br/>Praefect cluster)]
Storage2[(storage-2<br/>Praefect cluster)]

GitLab --> Storage1
GitLab --> Storage2

Storage1 --> G1[Gitaly node 1]
Storage1 --> G2[Gitaly node 2]
Storage1 --> G3[Gitaly node 3]

Storage2 --> G4[Gitaly node 4]
Storage2 --&gt; G5[Gitaly node 5]</code></pre></details></div>

구성 지침은 여러 가상 스토리지 구성을 참조하십시오.
혼합 구성#
GitLab을 다음의 조합으로 사용하도록 구성할 수 있습니다:

독립형 Gitaly 인스턴스(직접 Gitaly 스토리지).
Gitaly 클러스터(Praefect) 가상 스토리지.

다음과 같은 경우 혼합 구성을 사용할 수 있습니다:

독립형 Gitaly에서 Gitaly 클러스터(Praefect)로 점진적으로 마이그레이션하는 경우.
일부 저장소는 고가용성이 필요하고 다른 저장소는 그렇지 않은 경우.
중요한 저장소에만 Gitaly 클러스터(Praefect)를 사용하여 비용을 최적화하려는 경우.

혼합 구성에서 각 스토리지는 GitLab에서 독립적으로 구성됩니다:

독립형 Gitaly 스토리지는 Gitaly 노드에 직접 연결됩니다.
Gitaly 클러스터(Praefect) 스토리지는 Praefect 로드 밸런서에 연결됩니다.

GitLab은 독립형인지 클러스터된인지에 관계없이 모든 구성된 스토리지를 동등하게 취급합니다. 새 저장소를 만들 때 GitLab은 구성된 스토리지 가중치와 사용 가능한 용량을 기반으로 스토리지를 선택합니다.
Mermaid 다이어그램 (15줄)
소스 코드 보기
%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD
    accTitle: Mixed configuration
    accDescr: Example result of mixed configuration, with a Gitaly Cluster (Praefect) and standalone Gitaly configured together.
GitLab[[GitLab server]]
Praefect[(Praefect cluster)]
Standalone1[(Standalone gitaly)]

GitLab --&gt;|cluster storage| Praefect
GitLab --&gt;|default storage| Standalone1

Praefect --&gt; G1[Gitaly node 1]
Praefect --&gt; G2[Gitaly node 2]
Praefect --&gt; G3[Gitaly node 3]</code></pre></details></div>

자세한 내용은 다음을 참조하십시오:

구성 예시는 혼합 구성.
마이그레이션 지침은 기존 GitLab 인스턴스에 TCP 사용.

스토리지 레이아웃#
Warning
스토리지 레이아웃은 Gitaly 클러스터(Praefect)의 내부 세부 사항이며 릴리스 간에 안정적으로 유지되는 것이 보장되지 않습니다.
여기의 정보는 참고 목적으로만 제공되며 디버깅에 도움을 주기 위한 것입니다. 디스크에서 직접 저장소를 변경하는 것은 지원되지 않으며 장애를 일으키거나 변경 사항이 덮어쓰여질 수 있습니다.

Gitaly 클러스터(Praefect) 가상 스토리지는 단일 스토리지처럼 보이는 추상화를 제공하지만 실제로는 여러 물리적 스토리지로 구성됩니다. Gitaly 클러스터(Praefect)는 각 물리적 스토리지에 각 작업을 복제해야 합니다. 작업은 일부 물리적 스토리지에서는 성공하고 다른 곳에서는 실패할 수 있습니다.
부분적으로 적용된 작업은 다른 작업에 문제를 일으키고 시스템이 복구할 수 없는 상태로 만들 수 있습니다.
이러한 문제를 방지하기 위해 각 작업은 완전히 적용되거나 전혀 적용되지 않아야 합니다. 작업의 이 속성을
원자성이라고 합니다.
GitLab은 저장소 스토리지의 스토리지 레이아웃을 제어합니다. GitLab은 저장소 스토리지에 저장소를 생성, 삭제, 이동할 위치를 지시합니다. 이러한 작업은 여러 물리적 스토리지에 적용될 때 원자성 문제를 일으킵니다.
예를 들어:

GitLab이 레플리카 중 하나를 사용할 수 없는 동안 저장소를 삭제합니다.
GitLab이 나중에 저장소를 다시 생성합니다.

그 결과 삭제 시 사용할 수 없었던 오래된 레플리카가 충돌을 일으키고 저장소 재생성을 방해할 수 있습니다.
이러한 원자성 문제는 다음과 관련하여 과거에 여러 문제를 일으켰습니다:

Gitaly 클러스터(Praefect)가 있는 보조 사이트로의 Geo 동기화.
백업 복원.
저장소 스토리지 간 저장소 이동.

Gitaly 클러스터(Praefect)는 부분적으로 적용된 작업으로 인해 발생할 수 있는 충돌을 방지하는 특수 레이아웃에 디스크에 저장소를 저장하여 이러한 작업에 원자성을 제공합니다.
클라이언트 생성 레플리카 경로#
저장소는 Gitaly 클라이언트에 의해 결정된 상대 경로에 스토리지에 저장됩니다. 이러한 경로는 @cluster 접두사로 시작하지 않는 것으로 식별할 수 있습니다. 상대 경로는 해시 스토리지 스키마를 따릅니다.
Praefect 생성 레플리카 경로#
Gitaly 클러스터(Praefect)가 저장소를 만들 때 저장소에 _저장소 ID_라고 하는 고유하고 영구적인 ID를 할당합니다. 저장소 ID는 Gitaly 클러스터(Praefect)에 내부적이며 GitLab의 다른 곳에 있는 ID와 관련이 없습니다. 저장소가 Gitaly 클러스터(Praefect)에서 제거되고 나중에 다시 이동되면 저장소에 새 저장소 ID가 할당되며 Gitaly 클러스터(Praefect)의 관점에서 다른 저장소가 됩니다. 저장소 ID의 시퀀스는 항상 증가하지만 시퀀스에 간격이 있을 수 있습니다.
저장소 ID는 클러스터의 각 저장소에 대한 _레플리카 경로_라는 고유한 스토리지 경로를 도출하는 데 사용됩니다. 저장소의 레플리카는 모두 스토리지의 동일한 레플리카 경로에 저장됩니다. 레플리카 경로는 _상대 경로_와 구별됩니다:

상대 경로는 Gitaly 클라이언트가 가상 스토리지와 함께 저장소를 식별하는 데 사용하는 이름으로, 그것들에게 고유합니다.
레플리카 경로는 물리적 스토리지의 실제 물리적 경로입니다.

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

오브젝트 풀은 @cluster/pools/<xx>/<xx>/<저장소 ID>입니다. 오브젝트 풀은 다른 저장소와 다른 디렉토리에 저장됩니다.
하우스키핑의 일부로 가지치기되는 것을 방지하기 위해 Gitaly에서 식별 가능해야 합니다. 오브젝트 풀을 가지치기하면 연결된 저장소에서 데이터가 손실될 수 있습니다.
다른 저장소는 @cluster/repositories/<xx>/<xx>/<저장소 ID>입니다.

예를 들어 @cluster/repositories/6f/96/54771.
레플리카 경로의 마지막 구성 요소인 54771이 저장소 ID입니다. 이를 사용하여 디스크에서 저장소를 식별할 수 있습니다.
<xx>/<xx>는 저장소 ID의 문자열 표현의 SHA256 해시의 처음 네 개 16진수입니다. 이 숫자는 일부 파일 시스템에서 문제를 일으킬 수 있는 지나치게 큰 디렉토리를 피하기 위해 저장소를 하위 디렉토리에 고르게 분산하는 데 사용됩니다. 이 경우 54771은 6f960ab01689464e768366d3315b3d3b2c28f38761a58a70110554eb04d582f7로 해시되므로 처음 네 자리는 6f와 96입니다.
디스크에서 저장소 식별#
praefect metadata 하위 명령을 사용하여 다음을 수행합니다:

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

가상 스토리지와 상대 경로.
저장소 ID.



디스크의 저장소에는 Git 구성 파일에 프로젝트 경로도 포함되어 있습니다. 저장소의 메타데이터가 삭제된 경우에도 이 구성 파일을 사용하여 프로젝트 경로를 확인할 수 있습니다.
해시 스토리지 문서의 지침을 따릅니다.
작업의 원자성#
Gitaly 클러스터(Praefect)는 PostgreSQL 메타데이터 저장소와 스토리지 레이아웃을 사용하여 저장소 생성, 삭제, 이동 작업의 원자성을 보장합니다. 디스크 작업은 여러 스토리지에 걸쳐 원자적으로 적용할 수 없습니다. 그러나 PostgreSQL은 메타데이터 작업의 원자성을 보장합니다. Gitaly 클러스터(Praefect)는 실패한 작업이 항상 메타데이터를 일관된 상태로 유지하는 방식으로 작업을 모델링합니다. 성공적인 작업 후에도 디스크에 오래된 상태가 남아 있을 수 있습니다. 이 상황은 예상된 것이며 남은 상태는 향후 작업을 방해하지 않지만 정리가 수행될 때까지 불필요하게 디스크 공간을 사용할 수 있습니다.
스토리지에서 남은 저장소를 정리하는 백그라운드 크롤러에 대한 작업이 진행 중입니다.
저장소 생성#
저장소를 만들 때 Praefect는:

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

두 개의 동시 작업이 동일한 저장소를 만들더라도 스토리지의 다른 디렉토리에 저장되므로 충돌하지 않습니다. 먼저 완료되는 것이 메타데이터 레코드를 만들고 다른 작업은 "이미 존재함" 오류와 함께 실패합니다.
실패한 생성은 스토리지에 남은 저장소를 남깁니다. 스토리지에서 남은 저장소를 정리하는 백그라운드 크롤러에 대한 작업이 진행 중입니다.
저장소 ID는 PostgreSQL의 repositories_repository_id_seq에서 생성됩니다. 이전 예시에서 실패한 작업은 성공적으로 저장소를 만들지 않고 하나의 저장소 ID를 차지했습니다. 실패한 저장소 생성으로 인해 저장소 ID에 간격이 생기는 것은 예상된 일입니다.
저장소 삭제#
저장소는 메타데이터 레코드를 제거하여 삭제됩니다. 메타데이터 레코드가 삭제되는 즉시 저장소는 논리적으로 존재하지 않게 됩니다.
PostgreSQL은 제거의 원자성을 보장하며 동시 삭제는 "찾을 수 없음" 오류와 함께 실패합니다. 메타데이터 레코드를 성공적으로 삭제한 후 Praefect는 스토리지에서 레플리카를 제거하려고 시도합니다. 이는 실패하여 스토리지에 남은 상태를 남길 수 있습니다.
남은 상태는 결국 정리됩니다.
저장소 이동#
Gitaly와 달리 Gitaly 클러스터(Praefect)는 스토리지에서 저장소를 이동하지 않고 메타데이터 저장소에서 저장소의 상대 경로를 업데이트하여 저장소를 가상으로만 이동합니다.
구성 요소#
Gitaly 클러스터(Praefect)는 여러 구성 요소로 구성됩니다:

요청을 분산하고 Praefect 노드에 내결함성 액세스를 제공하는 로드 밸런서.
클러스터를 관리하고 Gitaly 노드로 요청을 라우팅하는 Praefect 노드.
클러스터 메타데이터를 유지하기 위한 PostgreSQL 데이터베이스 및 Praefect의 데이터베이스 연결 풀링에 권장되는 PgBouncer.
저장소 스토리지 및 Git 액세스를 제공하는 Gitaly 노드.

아키텍처#
Praefect는 Gitaly용 라우터 및 트랜잭션 관리자이며 Gitaly 클러스터(Praefect) 실행에 필요한 구성 요소입니다.

자세한 내용은 Gitaly 고가용성(HA) 설계를 참조하십시오.
기능#
Gitaly 클러스터(Praefect)는 다음 기능을 제공합니다:

Gitaly 노드 간 분산 읽기.
보조 레플리카의 강한 일관성.
향상된 중복성을 위한 저장소의 복제 계수.
프라이머리 Gitaly 노드에서 보조 Gitaly 노드로 자동 페일오버.
복제 큐가 비어 있지 않은 경우 가능한 데이터 손실 보고.

읽기의 수평적 분산을 포함한 제안된 개선 사항은 에픽 1489를 따르십시오.
분산 읽기#
Gitaly 클러스터(Praefect)는 가상 스토리지에 구성된 Gitaly 노드 간에 읽기 작업 분산을 지원합니다.
ACCESSOR 옵션으로 표시된 모든 RPC는 최신 상태이며 정상적인 Gitaly 노드로 리디렉션됩니다.
예를 들어 GetBlob.
여기서 "최신 상태"는 다음을 의미합니다:

이 Gitaly 노드에 대한 복제 작업이 예약되어 있지 않습니다.
마지막 복제 작업이 완료된 상태입니다.

다음과 같은 경우 프라이머리 노드가 요청을 처리하기 위해 선택됩니다:

최신 상태의 노드가 없습니다.
노드 선택 중 다른 오류가 발생합니다.

변경 사항이 Praefect가 보조 노드에 복제할 수 있는 것보다 더 빠르게 들어오는 경우(예: 매우 크고 빈번하게 수정되는 저장소) 프라이머리 노드가 대부분 또는 모든 요청을 처리할 수 있습니다. 이 경우 CI/CD 잡 및 기타 저장소 트래픽이 프라이머리 노드의 용량으로 병목 현상이 발생합니다.
Prometheus를 사용하여 읽기 분산을 모니터링할 수 있습니다.
강한 일관성#
Gitaly 클러스터(Praefect)는 모든 정상적인 최신 레플리카에 동기적으로 변경 사항을 기록하여 강한 일관성을 제공합니다. 레플리카가 트랜잭션 시점에 오래되었거나 비정상적인 경우 쓰기는 비동기적으로 복제됩니다.
강한 일관성은 기본 복제 방법입니다. 일부 작업은 강한 일관성 대신 복제 잡(결과적 일관성)을 사용합니다. 자세한 내용은 강한 일관성 에픽을 참조하십시오.
강한 일관성을 사용할 수 없는 경우 Gitaly 클러스터(Praefect)는 결과적 일관성을 보장합니다. 이 경우 Gitaly 클러스터(Praefect)는 프라이머리 Gitaly 노드에 쓰기가 발생한 후 보조 Gitaly 노드에 모든 쓰기를 복제합니다.
강한 일관성 모니터링에 대한 자세한 내용은 Gitaly 클러스터(Praefect) 모니터링을 참조하십시오.
복제 계수#
복제 계수는 Gitaly 클러스터(Praefect)가 주어진 저장소의 복사본을 유지하는 수입니다. 더 높은 복제 계수는:

더 나은 중복성과 읽기 워크로드 분산을 제공합니다.
더 높은 스토리지 비용을 초래합니다.

기본적으로 Gitaly 클러스터(Praefect)는 가상 스토리지의 모든 스토리지에 저장소를 복제합니다.
구성 정보는 복제 계수 구성을 참조하십시오.
Gitaly 클러스터(Praefect) 업그레이드#
Gitaly 클러스터(Praefect)를 업그레이드하려면 제로 다운타임 업그레이드 문서를 따르십시오.
Gitaly 클러스터(Praefect)를 이전 버전으로 롤백#
Gitaly 클러스터(Praefect)를 이전 버전으로 롤백해야 하는 경우 일부 Praefect 데이터베이스 마이그레이션을 되돌려야 할 수 있습니다.
여러 Praefect 노드가 있는 경우 Gitaly 클러스터(Praefect)를 롤백하려면:


모든 Praefect 노드에서 Praefect 서비스를 중지합니다:
gitlab-ctl stop praefect



Praefect 노드 중 하나에서 GitLab 패키지를 이전 버전으로 롤백합니다.


롤백된 노드에서 Praefect 마이그레이션 상태를 확인합니다:
sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml sql-migrate-status



APPLIED 열에 unknown migration이 있는 마이그레이션 수를 세어봅니다.


롤백되지 않은 Praefect 노드에서 롤백의 드라이 런을 수행하여 되돌릴 마이그레이션을 검증합니다. 은 롤백된 노드에서 보고한 알 수 없는 마이그레이션 수입니다.
sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml sql-migrate 



결과가 올바르면 -f 옵션을 사용하여 동일한 명령을 실행하여 마이그레이션을 되돌립니다:
sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml sql-migrate -f 



나머지 Praefect 노드에서 GitLab 패키지를 롤백하고 Praefect 서비스를 다시 시작합니다:
gitlab-ctl start praefect



Gitaly 클러스터(Praefect)로 마이그레이션#
Warning
Gitaly 클러스터(Praefect)에는 일부 알려진 문제가 있습니다. 계속하기 전에 다음 정보를 검토하십시오.

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

Gitaly 클러스터(Praefect) 배포 전에를 검토합니다.
GitLab의 최신 가능한 버전으로 업그레이드하여 개선 사항과 버그 수정을 활용합니다.

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

필요한 스토리지를 만듭니다. 저장소 스토리지 권장 사항을 참조합니다.
Gitaly 클러스터(Praefect)를 만들고 구성합니다.
아직 그렇게 구성되지 않은 경우 기존 Gitaly 인스턴스를 TCP 사용으로 구성합니다.
저장소를 이동합니다. Gitaly 클러스터(Praefect)로 마이그레이션하려면 Gitaly 클러스터(Praefect) 외부에 저장된 기존 저장소를 이동해야 합니다. 자동 마이그레이션은 없지만 GitLab API로 이동을 예약할 수 있습니다.

default 저장소 스토리지를 사용하지 않더라도 구성해야 합니다.
이 제한 사항에 대한 자세한 내용.
Kubernetes의 Gitaly 차트에서 마이그레이션하려면 특정 마이그레이션 지침을 따릅니다.
Gitaly 클러스터(Praefect)에서 마이그레이션#
Gitaly 클러스터(Praefect)의 제한 사항과 트레이드오프가 환경에 적합하지 않은 경우 Gitaly 클러스터(Praefect)에서 샤드된 Gitaly 인스턴스로 마이그레이션할 수 있습니다:

새 Gitaly 서버를 만들고 구성합니다.
새로 생성된 스토리지로 저장소를 이동합니다. 샤드 또는 그룹별로 이동할 수 있으며 여러 Gitaly 서버에 분산할 수 있습니다.