%%{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 Cluster (Praefect) 가상 스토리지.

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

독립 실행형 Gitaly에서 Gitaly Cluster (Praefect)로 점진적으로 마이그레이션하는 경우.
일부 리포지터리에만 고가용성이 필요한 경우.
중요한 리포지터리에만 Gitaly Cluster (Praefect)를 사용해 비용을 최적화하려는 경우.

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

독립 실행형 Gitaly 스토리지는 Gitaly 노드에 직접 연결됩니다.
Gitaly Cluster (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 Cluster (Praefect)의 내부 세부 사항이며 릴리스 사이에 안정적으로 유지된다고 보장하지 않습니다.
여기에 있는 정보는 참고와 디버깅에 도움을 주기 위한 것입니다. 디스크에서 리포지터리를 직접
변경하는 것은 지원하지 않으며, 오류가 발생하거나 변경 사항이 덮어써질 수 있습니다.

Gitaly Cluster (Praefect) 가상 스토리지는 단일 스토리지처럼 보이는 추상화를 제공하지만 실제로는 여러
물리적 스토리지로 구성됩니다. Gitaly Cluster (Praefect)는 모든 작업을 각 물리적 스토리지에 복제해야 합니다.
작업은 일부 물리적 스토리지에서는 성공하고 다른 스토리지에서는 실패할 수 있습니다.
부분적으로 적용된 작업은 다른 작업에 문제를 일으키고 시스템을 복구할 수 없는 상태로 남길 수 있습니다.
이런 유형의 문제를 피하려면 각 작업이 완전히 적용되거나 전혀 적용되지 않아야 합니다. 이러한 작업의 속성을
원자성이라고 합니다.
GitLab은 리포지터리 스토리지의 스토리지 레이아웃을 제어합니다. GitLab은 리포지터리를 생성, 삭제,
이동할 위치를 리포지터리 스토리지에 지시합니다. 이러한 작업이 여러 물리적 스토리지에 적용될 때 원자성 문제가 발생합니다.
예를 들면 다음과 같습니다.

GitLab이 복제본 중 하나를 사용할 수 없는 상태에서 리포지터리를 삭제합니다.
이후 GitLab이 그 리포지터리를 다시 생성합니다.

그 결과 삭제 시점에 사용할 수 없었던 오래된 복제본이 충돌을 일으켜 리포지터리 재생성을
막을 수 있습니다.
이러한 원자성 문제는 과거에 다음 영역에서 여러 문제를 일으켰습니다.

Gitaly Cluster (Praefect)를 사용한 보조 사이트로의 Geo 동기화.
백업 복원.
리포지터리 스토리지 사이의 리포지터리 이동.

Gitaly Cluster (Praefect)는 부분적으로 적용된 작업 때문에 발생할 수 있는 충돌을 방지하는 특수한 레이아웃으로
디스크에 리포지터리를 저장해 이러한 작업의 원자성을 보장합니다.
클라이언트 생성 복제본 경로#
리포지터리는 Gitaly 클라이언트가 정한 상대 경로에 스토리지에 저장됩니다. 이러한 경로는
@cluster 접두사로 시작하지 않는다는 점으로 식별할 수 있습니다. 상대 경로는
해시 스토리지 스키마를 따릅니다.
Praefect 생성 복제본 경로#
Gitaly Cluster (Praefect)가 리포지터리를 생성할 때 고유하고 영구적인 ID인 리포지터리 ID 를 그 리포지터리에 할당합니다. 리포지터리 ID는
Gitaly Cluster (Praefect) 내부용이며 GitLab의 다른 ID와는 관련이 없습니다. 리포지터리가 Gitaly Cluster (Praefect)에서 제거된 뒤 다시
추가되면 새 리포지터리 ID가 할당되고, Gitaly Cluster (Praefect) 관점에서는 다른 리포지터리가 됩니다. 리포지터리 ID 시퀀스는
항상 증가하지만 시퀀스에 빈 구간이 생길 수 있습니다.
리포지터리 ID는 클러스터의 각 리포지터리에 대해 복제본 경로 라는 고유한 스토리지 경로를 도출하는 데 사용됩니다. 한 리포지터리의
복제본은 모두 스토리지의 같은 복제본 경로에 저장됩니다. 복제본 경로는 상대 경로 와 구별됩니다.

상대 경로는 Gitaly 클라이언트가 가상 스토리지와 함께 리포지터리를 식별하는 데 사용하는 이름이며, 그 클라이언트에게만 고유합니다.
복제본 경로는 물리적 스토리지에 있는 실제 물리 경로입니다.

Praefect는 클라이언트 요청을 처리할 때 RPC 안의 리포지터리를 가상 식별자 (virtual storage, relative path)에서 물리 리포지터리
식별자 (storage, replica_path)로 변환합니다.
복제본 경로의 형식은 다음과 같습니다.

오브젝트 풀은 @cluster/pools/<xx>/<xx>/<repository ID> 입니다. 오브젝트 풀은 다른 리포지터리와 다른 디렉터리에 저장됩니다.
하우스키핑 과정에서 정리되지 않도록 Gitaly가 오브젝트 풀을 식별할 수 있어야 합니다. 오브젝트 풀을 정리하면 연결된
리포지터리에서 데이터 손실이 발생할 수 있습니다.
그 외 리포지터리는 @cluster/repositories/<xx>/<xx>/<repository ID> 입니다

예를 들면 @cluster/repositories/6f/96/54771 입니다.
복제본 경로의 마지막 구성 요소 54771이 리포지터리 ID입니다. 이 값으로 디스크에서 리포지터리를 식별할 수 있습니다.
<xx>/<xx>는 리포지터리 ID 문자열 표현의 SHA256 해시 중 앞 네 자리 16진수입니다. 이
자릿수는 일부 파일 시스템에서 문제를 일으킬 수 있는 지나치게 큰 디렉터리를 피하기 위해 리포지터리를
하위 디렉터리에 고르게 분산하는 데 사용됩니다. 이 예시에서 54771은
6f960ab01689464e768366d3315b3d3b2c28f38761a58a70110554eb04d582f7로 해싱되므로 앞 네 자리는 6f와 96입니다.
디스크에서 리포지터리 식별#
praefect metadata 하위 명령으로 다음을 수행합니다.

메타데이터 저장소에서 리포지터리의 가상 스토리지와 상대 경로를 조회합니다. 해시 스토리지 경로를 확보한 뒤에는 Rails
콘솔로 프로젝트 경로를 조회할 수 있습니다.
다음 중 하나로 클러스터에서 리포지터리가 저장된 위치를 찾습니다.

가상 스토리지와 상대 경로.
리포지터리 ID.



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

PostgreSQL에서 리포지터리 ID를 예약합니다. 이 과정은 원자적이며 두 생성 작업이 같은 ID를 받지 않습니다.
리포지터리 ID에서 도출한 복제본 경로에 Gitaly 스토리지의 복제본을 생성합니다.
디스크에 리포지터리가 성공적으로 생성된 뒤 메타데이터 레코드를 생성합니다.

동시에 두 작업이 같은 리포지터리를 생성하더라도 스토리지의 서로 다른 디렉터리에 저장되므로 충돌하지
않습니다. 먼저 완료된 작업이 메타데이터 레코드를 생성하고, 다른 작업은 "already exists" 오류로 실패합니다.
실패한 생성 작업은 스토리지에 리포지터리를 남깁니다. 스토리지에 남은 리포지터리를 정리하는
백그라운드 크롤러 작업이 진행되고 있습니다.
리포지터리 ID는 PostgreSQL의 repositories_repository_id_seq에서 생성됩니다. 앞의 예시에서 실패한 작업은
리포지터리를 생성하지 못한 채 리포지터리 ID 하나를 가져갔습니다. 실패한 리포지터리 생성이 리포지터리 ID에 빈 구간을 남기는 것은 예상된 결과입니다.
리포지터리 삭제#
리포지터리는 메타데이터 레코드를 제거해 삭제합니다. 메타데이터 레코드가 삭제되는 즉시 리포지터리는 논리적으로 존재하지 않게 됩니다.
PostgreSQL이 제거의 원자성을 보장하며, 동시에 실행된 삭제는 "not found" 오류로 실패합니다. 메타데이터 레코드를 성공적으로
삭제한 뒤 Praefect는 스토리지에서 복제본 제거를 시도합니다. 이 작업은 실패해 스토리지에 잔여 상태를 남길 수 있습니다.
잔여 상태는 이후에 정리됩니다.
리포지터리 이동#
Gitaly와 달리 Gitaly Cluster (Praefect)는 스토리지에서 리포지터리를 이동하지 않고, 메타데이터 저장소에 있는
리포지터리의 상대 경로를 갱신해 가상으로만 이동합니다.
구성 요소#
Gitaly Cluster (Praefect)는 여러 구성 요소로 이루어집니다.

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

아키텍처#
Praefect는 Gitaly의 라우터이자 트랜잭션 관리자이며, Gitaly Cluster (Praefect)를 실행하는 데
필요한 구성 요소입니다.

자세한 내용은 Gitaly 고가용성(HA) 설계를 참고합니다.
기능#
Gitaly Cluster (Praefect)는 다음 기능을 제공합니다.

Gitaly 노드 사이의 분산 읽기.
보조 복제본의 강력한 일관성.
중복성을 높이기 위한 리포지터리 복제 인수.
기본 Gitaly 노드에서 보조 Gitaly 노드로의
자동 페일오버.
복제 큐가 비어 있지 않은 경우 발생할 수 있는 데이터 손실 보고.

제안된 개선 사항은 에픽 1489에서 확인할 수 있으며,
읽기의 수평 분산도 여기에 포함됩니다.
분산 읽기#
Gitaly Cluster (Praefect)는 가상 스토리지에 구성된 Gitaly 노드 전체에 읽기 작업을
분산할 수 있습니다.
ACCESSOR 옵션이 표시된 모든 RPC는 최신 상태이고 정상인 Gitaly 노드로 리디렉션됩니다.
예를 들어 GetBlob이 그렇습니다.
여기에서 "최신 상태"는 다음을 뜻합니다.

이 Gitaly 노드에 예약된 복제 작업이 없습니다.
마지막 복제 작업이 완료 상태입니다.

다음 경우에는 기본 노드가 요청을 처리하도록 선택됩니다.

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

멀티 기가바이트 모노레포처럼 크고 변경이 잦은 리포지터리에서는 Praefect가 보조 노드로 복제하는 속도보다 변경이 더 빨리 들어오면 기본 노드가 대부분 또는 모든 요청을 처리할 수 있습니다.
이 경우 CI/CD job과 그 외 리포지터리 트래픽이 기본 노드의 용량에 병목이 생깁니다.
Prometheus를 사용해 읽기 분산을 모니터링할 수 있습니다.
강력한 일관성#
Gitaly Cluster (Praefect)는 정상이고 최신 상태인 모든 복제본에 변경 사항을 동기적으로 기록해 강력한 일관성을 제공합니다. 트랜잭션 시점에
복제본이 오래되었거나 정상이 아니면 그 복제본에는 비동기적으로 복제됩니다.
강력한 일관성이 기본 복제 방식입니다. 일부 작업은 여전히 강력한 일관성 대신 복제 job(최종 일관성)을
사용합니다. 자세한 내용은
강력한 일관성 에픽을 참고합니다.
강력한 일관성을 사용할 수 없으면 Gitaly Cluster (Praefect)는 최종 일관성을 보장합니다. 이 경우
Gitaly Cluster (Praefect)는 기본 Gitaly 노드에 쓰기가 발생한 뒤 모든 쓰기를 보조 Gitaly 노드로 복제합니다.
강력한 일관성 모니터링에 대한 자세한 내용은
Gitaly Cluster (Praefect) 모니터링을 참고합니다.
복제 인수#
복제 인수는 Gitaly Cluster (Praefect)가 특정 리포지터리에 대해 유지하는 복사본 수입니다. 복제 인수가
높으면 다음과 같습니다.

중복성과 읽기 워크로드 분산이 더 좋아집니다.
스토리지 비용이 더 높아집니다.

기본적으로 Gitaly Cluster (Praefect)는 가상 스토리지의 모든 스토리지로 리포지터리를
복제합니다.
구성 정보는 복제 인수 구성을 참고합니다.
Gitaly Cluster (Praefect) 업그레이드#
Gitaly Cluster (Praefect)를 업그레이드하려면
무중단 업그레이드 문서를 따릅니다.
Gitaly Cluster (Praefect)를 이전 버전으로 롤백#
Gitaly Cluster (Praefect)를 이전 버전으로 롤백해야 한다면 일부 Praefect 데이터베이스 마이그레이션을 되돌려야 할 수 있습니다.
Praefect 노드가 여러 개라고 가정할 때 Gitaly Cluster (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 노드에서 되돌릴 마이그레이션을 검증하기 위해 롤백을 시험 실행합니다. 
은 롤백한 노드가 보고한 unknown 마이그레이션 수입니다.
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 Cluster (Praefect)로 마이그레이션#
Warning
Gitaly Cluster (Praefect)에는 몇 가지 알려진 문제가 있습니다. 계속하기 전에 다음 정보를 검토합니다.

Gitaly Cluster (Praefect)로 마이그레이션하기 전에 다음을 수행합니다.

Gitaly Cluster (Praefect) 배포 전을 검토합니다.
개선 사항과 버그 수정을 활용하기 위해 가능한 최신 GitLab 버전으로 업그레이드합니다.

Gitaly Cluster (Praefect)로 마이그레이션하는 방법은 다음과 같습니다.

필요한 스토리지를 생성합니다.
리포지터리 스토리지 권장 사항을 참고합니다.
Gitaly Cluster (Praefect)를 생성하고 구성합니다.
아직 그렇게 구성되지 않았다면 기존 Gitaly 인스턴스가 TCP를 사용하도록 구성합니다.
리포지터리를 이동합니다. Gitaly Cluster (Praefect)로 마이그레이션하려면 Gitaly Cluster (Praefect) 밖에
저장된 기존 리포지터리를 이동해야 합니다. 자동 마이그레이션은 없지만 GitLab API로 이동 작업을
예약할 수 있습니다.

default 리포지터리 스토리지를 사용하지 않더라도 이 스토리지는 반드시 구성해야 합니다.
이 제한 사항에 대한 자세한 내용을 참고합니다.
Kubernetes의 Gitaly 차트에서 마이그레이션하려면
전용 마이그레이션 지침을 따릅니다.
Gitaly Cluster (Praefect)에서 마이그레이션#
Gitaly Cluster (Praefect)의 제한 사항과 장단점이 환경에 맞지 않는다면, Gitaly Cluster (Praefect)에서
샤딩된 Gitaly 인스턴스로 마이그레이션할 수 있습니다.

새 Gitaly 서버를 생성하고 구성합니다.
새로 만든 스토리지로 리포지터리를 이동합니다. 샤드별 또는
그룹별로 이동할 수 있으므로 여러 Gitaly 서버에 분산할 수 있습니다.

Kubernetes의 Gitaly Cluster#
히스토리
GitLab 19.1에서 도입되었습니다. 이 기능은 베타 상태입니다.
Gitaly Cluster (Praefect)는 인스턴스 전체에 데이터를 복제해 데이터와 서비스의 고가용성 문제를 해결합니다.
다만 Kubernetes의 Gitaly Cluster는 현재 베타입니다. 일반 공개로 전환하기 전에 이 알려진 문제와 관련 항목을 해결하고 있습니다.