Gitaly 클러스터(Praefect)는 프라이머리 노드 장애 및 사용할 수 없는 저장소에서 복구할 수 있습니다. Gitaly 클러스터(Praefect)는 데이터 복구를 수행할 수 있으며 Praefect 추적 데이터베이스 도구를 갖추고 있습니다.

Gitaly 클러스터(Praefect)의 Gitaly 노드 관리#

Gitaly 클러스터(Praefect)에서 Gitaly 노드를 추가하고 교체할 수 있습니다.

새 Gitaly 노드 추가#

새 Gitaly 노드를 추가하려면:

1. 문서에 따라 새 Gitaly 노드를 설치합니다.

2. praefect['virtual_storages'] 아래의 Praefect 구성에 새 노드를 추가합니다.

3. 다음 명령을 실행하여 Praefect를 재구성하고 다시 시작합니다:

   gitlab-ctl reconfigure
   gitlab-ctl restart praefect
   

복제 동작은 복제 계수 설정에 따라 다릅니다.

사용자 정의 복제 계수#

사용자 정의 복제 계수가 설정된 경우 Praefect는 기존 저장소를 새 Gitaly 노드에 자동으로 복제하지 않습니다. set-replication-factor Praefect 명령을 사용하여 각 저장소에 대해 복제 계수를 설정해야 합니다. 새 저장소는 복제 계수를 기반으로 복제됩니다.

기본 복제 계수#

기본 복제 계수를 사용하는 경우 Praefect는 복제 계수를 유지하기 위해 구성에 추가된 모든 새 Gitaly 노드에 모든 데이터를 자동으로 복제합니다.

기존 Gitaly 노드 교체#

기존 Gitaly 노드를 동일한 이름 또는 다른 이름의 새 노드로 교체할 수 있습니다. 이전 노드를 제거하기 전에:

• 복제 계수가 설정된 경우 데이터 손실을 방지하기 위해 1보다 커야 합니다.
• 복제 계수가 설정되지 않은 경우 저장소는 가상 스토리지 아래의 모든 노드에 복제됩니다.

프라이머리 Gitaly 노드가 제거되면 해당 노드에서 관리하는 저장소는 다음 중 하나가 될 때까지 사용할 수 없게 됩니다:

• 노드가 교체되고 복제됩니다.
• 교체된 프라이머리 노드의 데이터가 포함된 새 교체 노드가 사용 가능해집니다.

노드를 사용할 수 없는 동안 영향받은 저장소에 대한 읽기 요청은 404 오류와 함께 실패합니다. Gitaly는 영향받은 저장소에 다음 번 쓰기 시도 시 새 프라이머리 노드를 설정하기 위한 페일오버를 트리거하여 이 상황을 자동으로 해결합니다.

동일한 이름의 노드로 교체#

교체 노드에 동일한 이름을 사용하려면 저장소 검증기를 사용하여 스토리지를 검사하고 연결이 끊어진 메타데이터 레코드를 제거합니다. 프로세스를 가속화하기 위해 교체된 스토리지의 수동 우선순위 검증을 수행합니다.

다른 이름의 노드로 교체#

Gitaly 클러스터(Praefect)에서 노드를 다른 이름의 노드로 교체하는 단계는 복제 계수가 설정되어 있는지에 따라 다릅니다.

사용자 정의 복제 계수가 설정된 경우 praefect set-replication-factor를 사용하여 새 스토리지가 할당되도록 저장소별 복제 계수를 다시 설정합니다.

예를 들어 가상 스토리지의 두 노드가 복제 계수 2이고 새 노드(gitaly-3)가 추가된 경우 복제 계수를 3으로 늘려야 합니다:

$ sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml set-replication-factor -virtual-storage default -relative-path @hashed/3f/db/3fdba35f04dc8c462986c992bcf875546257113072a909c162f7e470e581e278.git -replication-factor 3

current assignments: gitaly-1, gitaly-2, gitaly-3

이렇게 하면 저장소가 새 노드에 복제되고 repository_assignments 테이블이 새 Gitaly 노드의 이름으로 업데이트됩니다.

기본 복제 계수가 설정된 경우 새 노드는 자동으로 복제에 포함되지 않습니다. 앞서 설명한 단계를 따라야 합니다.

저장소가 새 노드에 성공적으로 복제되었는지 확인한 후:

1. praefect['virtual_storages'] 아래의 Praefect 구성에서 gitaly-1 노드를 제거합니다.

2. Praefect를 재구성하고 다시 시작합니다:

   gitlab-ctl reconfigure
   gitlab-ctl restart praefect
   

이전 Gitaly 노드를 참조하는 데이터베이스 상태는 무시할 수 있습니다.

대안으로 새 Gitaly 노드를 구성한 후 이전 스토리지에서 새 스토리지로 모든 저장소를 재할당할 수 있습니다:

1. Praefect 데이터베이스에 연결합니다:

   /opt/gitlab/embedded/bin/psql -h <psql host> -U <user> -d <database name>
   

2. repository_assignments 테이블을 업데이트하여 이전 Gitaly 노드 이름(예: old-gitaly)을 새 Gitaly 노드 이름(예: new-gitaly)으로 교체합니다:

   UPDATE repository_assignments SET storage='new-gitaly' WHERE storage='old-gitaly';
   

이렇게 하면 시스템을 원하는 상태로 되돌리기 위한 적절한 복제 잡이 트리거됩니다.

프라이머리 노드 장애#

Gitaly 클러스터(Praefect)는 정상적인 보조 노드를 새 프라이머리로 승격하여 프라이머리 Gitaly 노드 장애로부터 복구합니다. Gitaly 클러스터(Praefect)는:

• 저장소의 완전히 최신 복사본을 가진 정상적인 보조를 새 프라이머리로 선출합니다.
• 완전히 최신 보조가 없는 경우 프라이머리에서 가장 적은 미복제 쓰기가 있는 보조를 새 프라이머리로 선출합니다.
• 정상적인 보조에 완전히 최신 복사본이 없는 경우 저장소를 사용할 수 없게 됩니다. Praefect dataloss 하위 명령을 사용하여 감지합니다.

사용 불가능한 저장소#

최신 레플리카가 모두 사용 불가능한 경우 저장소를 사용할 수 없습니다. 사용 불가능한 저장소는 자동화된 도구를 손상시킬 수 있는 오래된 데이터를 제공하는 것을 방지하기 위해 Praefect를 통해 액세스할 수 없습니다.

데이터 손실 확인#

Praefect dataloss 하위 명령은 사용 불가능한 저장소를 식별합니다. 이는 잠재적인 데이터 손실과 최신 레플리카 복사본이 모두 사용 불가능하여 더 이상 액세스할 수 없는 저장소를 식별하는 데 도움이 됩니다.

다음 파라미터를 사용할 수 있습니다:

• 확인할 가상 스토리지를 지정하는 -virtual-storage. 관리자 개입이 필요할 수 있으므로 기본 동작은 사용 불가능한 저장소를 표시하는 것입니다.
• -partially-unavailable는 사용 가능하지만 일부 할당된 복사본이 사용 불가능한 저장소를 출력에 포함할지 여부를 지정합니다.

오래된 프라이머리 또는 사용 불가능한 저장소를 확인하려면 다음을 실행합니다:

sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml dataloss [-virtual-storage <virtual-storage>]

지정하지 않으면 구성된 모든 가상 스토리지가 확인됩니다:

sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml dataloss

정상적이고 완전히 최신 복사본이 없는 저장소가 출력에 나열됩니다. 각 저장소에 대해 다음 정보가 출력됩니다:

• 저장소의 스토리지 디렉토리에 대한 상대 경로는 각 저장소를 식별하고 관련 정보를 그룹화합니다.
• 저장소를 사용할 수 없는 경우 디스크 경로 옆에 (unavailable)이 출력됩니다.
• 프라이머리 필드는 저장소의 현재 프라이머리를 나열합니다. 저장소에 프라이머리가 없는 경우 필드에 No Primary가 표시됩니다.
• 동기화된 스토리지는 최신 성공적인 쓰기와 그 이전의 모든 쓰기를 복제한 레플리카를 나열합니다.
• 오래된 스토리지는 오래된 저장소 복사본을 포함하는 레플리카를 나열합니다. 저장소의 복사본이 없지만 포함해야 하는 레플리카도 여기에 나열됩니다. 레플리카가 누락한 최대 변경 수가 레플리카 옆에 나열됩니다. 오래된 레플리카가 완전히 최신 상태이거나 나중 변경 사항을 포함할 수 있지만 Praefect가 이를 보장할 수 없다는 점을 유의하는 것이 중요합니다.

추가 정보 포함:

• 노드가 저장소를 호스팅하도록 할당되었는지 여부는 각 노드의 상태와 함께 나열됩니다. assigned host는 저장소를 저장하도록 할당된 노드 옆에 출력됩니다. 노드에 저장소 복사본이 있지만 저장소를 저장하도록 할당되지 않은 경우 텍스트가 생략됩니다. 이러한 복사본은 Praefect에 의해 동기화되지 않지만 할당된 복사본을 최신 상태로 만들기 위한 복제 소스 역할을 할 수 있습니다.
• 비정상적인 Gitaly 노드에 위치한 복사본 옆에 unhealthy가 출력됩니다.

출력 예시:

Virtual storage: default
  Outdated repositories:
    @hashed/3f/db/3fdba35f04dc8c462986c992bcf875546257113072a909c162f7e470e581e278.git (unavailable):
      Primary: gitaly-1
      In-Sync Storages:
        gitaly-2, assigned host, unhealthy
      Outdated Storages:
        gitaly-1 is behind by 3 changes or less, assigned host
        gitaly-3 is behind by 3 changes or less

모든 저장소를 사용할 수 있으면 확인이 출력됩니다. 예를 들어:

Virtual storage: default
  All repositories are available!

사용 가능한 저장소의 사용 불가능한 레플리카#

사용 가능하지만 일부 할당된 노드에서 사용 불가능한 저장소의 정보도 나열하려면 -partially-unavailable 플래그를 사용합니다.

사용 가능한 정상적인 최신 레플리카가 있으면 저장소를 사용할 수 있습니다. 할당된 일부 보조 레플리카는 최신 변경 사항을 복제하기를 기다리는 동안 일시적으로 사용할 수 없을 수 있습니다.

sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml dataloss [-virtual-storage <virtual-storage>] [-partially-unavailable]

출력 예시:

Virtual storage: default
  Outdated repositories:
    @hashed/3f/db/3fdba35f04dc8c462986c992bcf875546257113072a909c162f7e470e581e278.git:
      Primary: gitaly-1
      In-Sync Storages:
        gitaly-1, assigned host
      Outdated Storages:
        gitaly-2 is behind by 3 changes or less, assigned host
        gitaly-3 is behind by 3 changes or less

-partially-unavailable 플래그가 설정된 경우 모든 할당된 레플리카가 완전히 최신 상태이고 정상적이면 확인이 출력됩니다.

예를 들어:

Virtual storage: default
  All repositories are fully available on all assigned storages!

저장소 체크섬 확인#

모든 Gitaly 노드에서 프로젝트 저장소 체크섬을 확인하려면 메인 GitLab 노드에서 레플리카 Rake 작업을 실행합니다.

데이터 손실 수락#

최신 레플리카 중 하나를 다시 온라인 상태로 만드는 것이 불가능한 경우 데이터 손실을 수락해야 할 수 있습니다. 데이터 손실을 수락할 때 Praefect는 선택된 저장소 레플리카를 최신 버전으로 표시하고 다른 할당된 Gitaly 노드에 복제합니다. 이 프로세스는 저장소의 다른 버전을 덮어쓰므로 주의해야 합니다.

sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml accept-dataloss
-virtual-storage <virtual-storage> -relative-path <relative-path> -authoritative-storage <storage-name>

쓰기 활성화 또는 데이터 손실 수락#

Praefect는 쓰기를 다시 활성화하거나 데이터 손실을 수락하기 위한 다음 하위 명령을 제공합니다. 최신 노드 중 하나를 다시 온라인 상태로 만드는 것이 불가능한 경우 데이터 손실을 수락해야 할 수 있습니다:

sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml accept-dataloss -virtual-storage <virtual-storage> -relative-path <relative-path> -authoritative-storage <storage-name>

데이터 손실을 수락할 때 Praefect는:

1. 선택된 저장소 복사본을 최신 버전으로 표시합니다.

2. 복사본을 다른 할당된 Gitaly 노드에 복제합니다.

   이 프로세스는 저장소의 다른 복사본을 덮어쓰므로 주의해야 합니다.

데이터 복구#

Gitaly 노드가 어떤 이유로 복제 잡에 실패하면 영향받은 저장소의 오래된 버전을 호스팅하게 됩니다. Praefect는 자동 조정을 위한 도구를 제공합니다. 이러한 도구는 오래된 저장소를 조정하여 완전히 최신 상태로 만듭니다.

Praefect는 최신 상태가 아닌 저장소를 자동으로 조정합니다. 기본적으로 이 작업은 5분마다 수행됩니다. 정상적인 Gitaly 노드의 각 오래된 저장소에 대해 Praefect는 다른 정상적인 Gitaly 노드에서 저장소의 무작위 완전 최신 레플리카를 선택하여 복제합니다. 대상 저장소에 대한 다른 복제 잡이 보류 중이 없는 경우에만 복제 잡이 예약됩니다.

조정 빈도는 구성을 통해 변경할 수 있습니다. 값은 유효한 Go 지속 시간 값이 될 수 있습니다. 0 미만의 값은 기능을 비활성화합니다.

예시:

praefect['configuration'] = {
   # ...
   reconciliation: {
      # ...
      scheduling_interval: '5m', # the default value
   },
}

praefect['configuration'] = {
   # ...
   reconciliation: {
      # ...
      scheduling_interval: '30s', # reconcile every 30 seconds
   },
}

praefect['configuration'] = {
   # ...
   reconciliation: {
      # ...
      scheduling_interval: '0', # disable the feature
   },
}

수동으로 저장소 제거#

remove-repository Praefect 하위 명령은 Gitaly 클러스터(Praefect)에서 저장소를 제거하며 다음을 포함한 주어진 저장소와 관련된 모든 상태를 제거합니다:

• 관련 모든 Gitaly 노드의 디스크 저장소.
• Praefect에서 추적하는 모든 데이터베이스 상태.

기본적으로 명령은 드라이 런 모드로 작동합니다. 예를 들어:

sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml remove-repository -virtual-storage <virtual-storage> -relative-path <repository>

• <virtual-storage>를 저장소가 포함된 가상 스토리지 이름으로 교체합니다.

• <repository>를 제거할 저장소의 상대 경로로 교체합니다.

• -db-only를 추가하면 디스크 저장소를 제거하지 않고 Praefect 추적 데이터베이스 항목만 제거합니다. 고아 데이터베이스 항목을 제거하고 유효한 저장소가 실수로 지정된 경우 디스크 저장소 데이터가 삭제되는 것을 방지하려면 이 옵션을 사용합니다. 데이터베이스 항목이 실수로 삭제된 경우 track-repository 명령으로 저장소를 다시 추적합니다.

• -apply를 추가하면 드라이 런 모드 외부에서 명령을 실행하고 저장소를 제거합니다. 예를 들어:

  sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml remove-repository -virtual-storage <virtual-storage> -relative-path <repository> -apply
  

• -virtual-storage는 저장소가 위치한 가상 스토리지입니다. 가상 스토리지는 /etc/gitlab/gitlab.rb에서 praefect['configuration']['virtual_storage] 아래에 구성됩니다:

  praefect['configuration'] = {
    # ...
    virtual_storage: [
      {
        # ...
        name: 'default',
      },
      {
        # ...
        name: 'storage-1',
      },
    ],
  }
  

  이 예시에서 지정할 가상 스토리지는 default 또는 storage-1입니다.

• -repository는 @hashed로 시작하는 스토리지의 저장소 상대 경로입니다. 예를 들어:

  @hashed/f5/ca/f5ca38f748a1d6eaf726b8a42fb575c3c71f1864a8143301782de13da2d9202b.git
  

remove-repository를 실행한 후 저장소의 일부가 계속 존재할 수 있습니다. 이는 다음 때문일 수 있습니다:

• 삭제 오류.
• 저장소를 대상으로 하는 진행 중인 RPC 호출.

이 경우 remove-repository를 다시 실행합니다.

Praefect 추적 데이터베이스 유지 관리#

Praefect 추적 데이터베이스의 일반적인 유지 관리 작업이 이 섹션에 설명되어 있습니다.

추적되지 않은 저장소 나열#

list-untracked-repositories Praefect 하위 명령은 다음과 같은 Gitaly 클러스터(Praefect) 저장소를 나열합니다:

• 하나 이상의 Gitaly 스토리지에 존재합니다.
• Praefect 추적 데이터베이스에서 추적되지 않습니다.

다음과 같은 저장소를 표시하지 않으려면 -older-than 옵션을 추가합니다:

• 생성 중인 저장소.
• Praefect 추적 데이터베이스에 아직 레코드가 없는 저장소.

<duration>을 시간 지속 시간으로 교체합니다(예: 5s, 10m, 1h). 기본값은 6h입니다.

sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml list-untracked-repositories -older-than <duration>

지정된 지속 시간 이전에 생성 시간이 있는 저장소만 고려됩니다.

명령 출력:

• 결과를 STDOUT 및 명령 로그에 출력합니다.
• 오류를 STDERR에 출력합니다.

각 항목은 끝에 줄 바꿈이 있는 완전한 JSON 문자열입니다(-delimiter 플래그를 사용하여 구성 가능). 예를 들어:

sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml list-untracked-repositories
{"virtual_storage":"default","storage":"gitaly-1","relative_path":"@hashed/ab/cd/abcd123456789012345678901234567890123456789012345678901234567890.git"}
{"virtual_storage":"default","storage":"gitaly-1","relative_path":"@hashed/ab/cd/abcd123456789012345678901234567890123456789012345678901234567891.git"}

단일 저장소를 추적 데이터베이스에 수동으로 추가#

track-repository Praefect 하위 명령은 디스크의 저장소를 Praefect 추적 데이터베이스에 추가하여 추적합니다.

sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml track-repository -virtual-storage <virtual-storage> -authoritative-storage <storage-name> -relative-path <repository> -replica-path <disk_path> -replicate-immediately

• -virtual-storage는 저장소가 위치한 가상 스토리지입니다. 가상 스토리지는 /etc/gitlab/gitlab.rb에서 praefect['configuration'][:virtual_storage] 아래에 구성됩니다:

  praefect['configuration'] = {
    # ...
    virtual_storage: [
      {
        # ...
        name: 'default',
      },
      {
        # ...
        name: 'storage-1',
      },
    ],
  }
  

  이 예시에서 지정할 가상 스토리지는 default 또는 storage-1입니다.

• -relative-path는 가상 스토리지의 상대 경로입니다. 일반적으로 @hashed로 시작합니다. 예를 들어:

  @hashed/f5/ca/f5ca38f748a1d6eaf726b8a42fb575c3c71f1864a8143301782de13da2d9202b.git
  

• -replica-path는 물리적 스토리지의 상대 경로입니다. @cluster로 시작하거나 relative_path와 일치할 수 있습니다.

• -authoritative-storage는 Praefect가 프라이머리로 취급할 스토리지입니다. 복제 전략으로 저장소별 복제가 설정된 경우 필요합니다.

• -replicate-immediately는 명령이 저장소를 즉시 보조 노드에 복제하게 합니다. 그렇지 않으면 복제 잡이 데이터베이스에서 실행 예약되고 Praefect 백그라운드 프로세스에 의해 처리됩니다.

명령 출력:

• 결과를 STDOUT 및 명령 로그에 출력합니다.
• 오류를 STDERR에 출력합니다.

다음과 같은 경우 이 명령이 실패합니다:

• 저장소가 이미 Praefect 추적 데이터베이스에 의해 추적되고 있습니다.
• 저장소가 디스크에 존재하지 않습니다.

많은 저장소를 추적 데이터베이스에 수동으로 추가#

API를 사용한 마이그레이션은 저장소를 Praefect 추적 데이터베이스에 자동으로 추가합니다.

대신 기존 인프라에서 저장소를 수동으로 복사하는 경우 track-repositories Praefect 하위 명령을 사용할 수 있습니다. 이 하위 명령은 디스크 저장소의 대규모 배치를 Praefect 추적 데이터베이스에 추가합니다.

# Omnibus GitLab install
sudo gitlab-ctl praefect track-repositories --input-path /path/to/input.json

# Source install
sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml track-repositories -input-path /path/to/input.json

명령은 모든 항목이 다음을 확인합니다:

• 올바르게 형식이 지정되어 있고 필수 필드를 포함합니다.
• 디스크의 유효한 Git 저장소에 해당합니다.
• Praefect 추적 데이터베이스에서 추적되지 않습니다.

항목이 이 확인에 실패하면 저장소 추적을 시도하기 전에 명령이 중단됩니다.

• input-path는 줄 바꿈으로 구분된 JSON 객체로 형식화된 저장소 목록을 포함하는 파일 경로입니다. 객체는 다음 키를 포함해야 합니다:

  • relative_path: track-repository의 repository에 해당합니다.

  • authoritative-storage: Praefect가 프라이머리로 취급할 스토리지.

  • virtual-storage: 저장소가 위치한 가상 스토리지.

    예를 들어:

    {"relative_path":"@hashed/f5/ca/f5ca38f748a1d6eaf726b8a42fb575c3c71f1864a8143301782de13da2d9202b.git","replica_path":"@cluster/fe/d3/1","authoritative_storage":"gitaly-1","virtual_storage":"default"}
    {"relative_path":"@hashed/f8/9f/f89f8d0e735a91c5269ab08d72fa27670d000e7561698d6e664e7b603f5c4e40.git","replica_path":"@cluster/7b/28/2","authoritative_storage":"gitaly-2","virtual_storage":"default"}
    

• -replicate-immediately는 명령이 저장소를 즉시 보조 노드에 복제하게 합니다. 그렇지 않으면 복제 잡이 데이터베이스에서 실행 예약되고 Praefect 백그라운드 프로세스에 의해 처리됩니다.

가상 스토리지 세부 정보 나열#

list-storages Praefect 하위 명령은 가상 스토리지와 관련 스토리지 노드를 나열합니다. 가상 스토리지가:

• -virtual-storage를 사용하여 지정된 경우 지정된 가상 스토리지의 스토리지 노드만 나열합니다.
• 지정되지 않은 경우 모든 가상 스토리지와 관련 스토리지 노드가 표 형식으로 나열됩니다.

sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml list-storages -virtual-storage <virtual_storage_name>

명령 출력:

• 결과를 STDOUT 및 명령 로그에 출력합니다.
• 오류를 STDERR에 출력합니다.