InfoGrab DocsInfoGrab Docs

Geo에 강등된 사이트 재도입

요약

- Offering: GitLab Self-Managed 페일오버 이후, 강등된 기본 사이트(primary site)를 새로운 보조 사이트(secondary site)로 다시 가져오거나 원래의 기본 사이트를 복원할 수 있습니다.

강등된 사이트를 Geo에 다시 도입하기#

  - 
  Tier: Premium, Ultimate

- Offering: GitLab Self-Managed

페일오버 이후, 강등된 기본 사이트(primary site)를 새로운 보조 사이트(secondary site)로 다시 가져오거나 원래의 기본 사이트를 복원할 수 있습니다. 이 과정은 두 단계로 구성됩니다:

  • 이전 기본 사이트를 보조 사이트로 전환하기.

  • 보조 사이트를 기본 사이트로 승격하기.

이 사이트의 데이터 일관성에 대한 의문이 있다면, 처음부터 다시 설정하는 것이 좋습니다.

강등된 기본 사이트는 더 이상 Geo와 동기화되지 않는 독립형 GitLab 서버로 간주됩니다.

이전 기본 사이트로서의 잔여 설정을 모두 제거한 후 새로운 보조 사이트로 다시 추가해야 합니다.

이전 기본 사이트를 보조 사이트로 구성하기#

이전 기본 사이트는 현재 기본 사이트와 동기화가 맞지 않으므로, 첫 번째 단계는 이전 기본 사이트를 최신 상태로 만드는 것입니다. 리포지터리 및 업로드와 같이 디스크에 저장된 데이터의 삭제는 이전 기본 사이트를 다시 동기화할 때 재현되지 않으므로, 디스크 사용량이 증가할 수 있습니다. 이를 방지하려면 새 보조 GitLab 인스턴스를 설정하는 방법을 사용할 수 있습니다.

이전 기본 사이트를 최신 상태로 만들려면:

뒤처진 이전 기본 사이트에 SSH로 접속합니다.

/etc/gitlab/gitlab-cluster.json 파일이 존재한다면 삭제합니다. (gitlab-cluster.json 파일이란?)

보조 사이트로 다시 추가될 사이트가 gitlab-ctl geo promote 명령으로 승격된 경우, /etc/gitlab/gitlab-cluster.json 파일이 존재할 수 있습니다. 예를 들어 gitlab-ctl reconfigure 실행 시 다음과 같은 출력이 나타날 수 있습니다:

The 'geo_primary_role' is defined in /etc/gitlab/gitlab-cluster.json as 'true' and overrides the setting in the /etc/gitlab/gitlab.rb

이 경우, /etc/gitlab/gitlab.rb가 다시 단일 진실 공급원(Single Source Of Truth, SSOT)이 되도록, 사이트 내 모든 Sidekiq, PostgreSQL, Gitaly, Rails 노드에서 /etc/gitlab/gitlab-cluster.json을 삭제해야 합니다(멀티 노드 설정 사용 시).

모든 서비스가 실행 중인지 확인합니다:

sudo gitlab-ctl start

기본 사이트를 영구적으로 비활성화한 경우, 지금 해당 단계를 되돌려야 합니다. Debian/Ubuntu/CentOS7+ 등 systemd를 사용하는 배포판에서는 sudo systemctl enable gitlab-runsvdir을 실행해야 합니다. CentOS 6처럼 systemd가 없는 배포판에서는 GitLab 인스턴스를 처음부터 설치하고 설정 지침을 따라 보조 사이트로 설정해야 합니다. 이 경우에는 다음 단계를 따를 필요가 없습니다.

Geo를 설정합니다. 이 경우 보조 사이트는 이전 기본 사이트를 의미합니다.

현재 보조 사이트(기본 사이트였을 당시)에서 PgBouncer가 활성화되어 있었다면, /etc/gitlab/gitlab.rb를 편집하고 sudo gitlab-ctl reconfigure를 실행하여 비활성화합니다.

이후 보조 사이트에서 데이터베이스 복제를 설정할 수 있습니다.

다시 도입된 보조 사이트에서 Geo 추적 데이터베이스 스키마를 초기화합니다.

gitlab-ctl replicate-geo-database는 메인 gitlabhq_production 데이터베이스만 복제합니다. Geo 추적 데이터베이스(gitlabhq_geo_production)는 보조 사이트 로컬에 있으며, 일반적으로 geo_secondary['auto_migrate']를 통해 sudo gitlab-ctl reconfigure로 마이그레이션됩니다. auto_migrate가 비활성화되어 있거나, 추적 데이터베이스가 외부에 있거나, 마지막으로 reconfigure를 실행했을 때 비어 있었던 경우, Geo Log Cursor가 멈추고 모든 동기화 유형이 0%에 머무르게 됩니다.

이런 경우, 보조 사이트의 Rails 또는 Sidekiq 노드에서:

추적 데이터베이스 마이그레이션을 수동으로 실행합니다.

새로운 스키마를 인식할 수 있도록 Geo Log Cursor를 재시작합니다:

sudo gitlab-ctl restart geo-logcursor

계속 진행하기 전에 추적 데이터베이스가 올바르게 설정되었는지 확인합니다:

# Confirm the tracking database has tables
sudo gitlab-geo-psql -d gitlabhq_geo_production -c "\dt"

# Confirm all tracking database migrations are applied
sudo gitlab-rake db:migrate:status:geo | grep -w down

# Run the full Geo check
sudo gitlab-rake gitlab:geo:check

db:migrate:status:geo 명령은 down 상태의 마이그레이션이 없어야 하며, gitlab:geo:check는 출력 결과에 GitLab Geo tracking database is correctly configured ... yes가 표시되어야 합니다.

OpenBao에 대한 JWT audience를 구성합니다. GitLab Secrets Manager를 활성화했고, 기본 사이트와 보조 사이트가 동일한 JWT audience를 공유하지 않는 경우, 다시 추가된 보조 사이트의 Helm values에서 jwt_audience를 새 기본 사이트의 OpenBao URL로 설정합니다:

global:
  openbao:
    enabled: true
    url: https://openbao.old-primary.example.com:8200
    jwt_audience: https://openbao.promoted.example.com:8200

원래 기본 사이트를 분실한 경우, 설정 지침을 따라 새 보조 사이트를 설정하세요.

보조 사이트를 기본 사이트로 승격하기#

초기 복제가 완료되고 기본 사이트와 보조 사이트가 거의 동기화된 상태가 되면, 계획된 페일오버(planned failover)를 진행할 수 있습니다.

보조 사이트 복원#

두 사이트를 다시 운영하는 것이 목표라면, 첫 번째 단계 (이전 기본 사이트를 보조 사이트로 구성하기)를 보조 사이트에 대해 반복하여 보조 사이트를 다시 온라인 상태로 만들어야 합니다.

추가 보조 사이트 복원#

보조 사이트가 두 개 이상인 경우, 나머지 사이트들을 지금 온라인으로 전환할 수 있습니다. 각 나머지 사이트에 대해, 기본 사이트와 복제 프로세스를 시작합니다.

보조 사이트에서 데이터 재전송 건너뛰기#

보조 사이트가 추가될 때, 기본 사이트에서 동기화될 데이터가 이미 존재하는 경우, Geo는 해당 데이터의 재전송을 피합니다.

  • Git 리포지터리는 git fetch로 전송되며, 누락된 refs만 전송합니다.

  • Geo의 컨테이너 레지스트리 동기화 코드는 태그와 다이제스트(digest)의 쌍을 비교하여 누락된 항목만 가져옵니다.

  • Blob은 첫 번째 동기화 시 이미 존재하는 경우 건너뜁니다.

사용 사례:

  • 계획된 페일오버를 수행하고, 이전 기본 사이트를 재구축 없이 보조 사이트로 연결하여 강등하는 경우.

  • 여러 개의 보조 Geo 사이트를 운영 중에 계획된 페일오버를 수행하고, 나머지 보조 Geo 사이트들을 재구축 없이 다시 연결하는 경우.

  • 보조 사이트를 승격하고 강등하는 방식으로 페일오버 테스트를 수행한 후, 재구축 없이 다시 연결하는 경우.

  • 백업을 복원하고 해당 사이트를 보조 사이트로 연결하는 경우.

  • 동기화 문제를 해결하기 위해 보조 사이트에 수동으로 데이터를 복사하는 경우.

  • 문제를 해결하기 위해 Geo 추적 데이터베이스의 레지스트리 테이블 행을 삭제하거나 초기화하는 경우.

  • 문제를 해결하기 위해 Geo 추적 데이터베이스를 초기화하는 경우.

Blob 재전송 건너뛰기#

History

기존 blob 데이터가 있는 보조 사이트를 추가하면, 보조 Geo 사이트는 해당 데이터의 재전송을 피합니다. 이는 다음 항목에 적용됩니다:

  • CI job 아티팩트

  • CI 파이프라인 아티팩트

  • CI 보안 파일

  • LFS 객체

  • 머지 리퀘스트 diff

  • 패키지 파일

  • Pages 배포

  • Terraform 상태 버전

  • 업로드

  • Dependency proxy 매니페스트

  • Dependency proxy blob

보조 사이트의 복사본이 실제로 손상된 경우, 백그라운드 검증이 결국 실패하고 해당 blob은 재동기화됩니다.

Blob은 Geo 추적 데이터베이스에 해당하는 레지스트리 레코드가 없는 경우에만 이 방식으로 건너뜁니다. 재동기화는 거의 항상 의도적인 작업이며, 전송을 실수로 건너뛰는 위험을 방지하기 위해 조건이 엄격하게 적용됩니다.

Geo에 강등된 사이트 재도입

GitLab v19.2
원문 보기
요약

- Offering: GitLab Self-Managed 페일오버 이후, 강등된 기본 사이트(primary site)를 새로운 보조 사이트(secondary site)로 다시 가져오거나 원래의 기본 사이트를 복원할 수 있습니다.

강등된 사이트를 Geo에 다시 도입하기#

  - 
  Tier: Premium, Ultimate

- Offering: GitLab Self-Managed

페일오버 이후, 강등된 기본 사이트(primary site)를 새로운 보조 사이트(secondary site)로 다시 가져오거나 원래의 기본 사이트를 복원할 수 있습니다. 이 과정은 두 단계로 구성됩니다:

  • 이전 기본 사이트를 보조 사이트로 전환하기.

  • 보조 사이트를 기본 사이트로 승격하기.

이 사이트의 데이터 일관성에 대한 의문이 있다면, 처음부터 다시 설정하는 것이 좋습니다.

강등된 기본 사이트는 더 이상 Geo와 동기화되지 않는 독립형 GitLab 서버로 간주됩니다.

이전 기본 사이트로서의 잔여 설정을 모두 제거한 후 새로운 보조 사이트로 다시 추가해야 합니다.

이전 기본 사이트를 보조 사이트로 구성하기#

이전 기본 사이트는 현재 기본 사이트와 동기화가 맞지 않으므로, 첫 번째 단계는 이전 기본 사이트를 최신 상태로 만드는 것입니다. 리포지터리 및 업로드와 같이 디스크에 저장된 데이터의 삭제는 이전 기본 사이트를 다시 동기화할 때 재현되지 않으므로, 디스크 사용량이 증가할 수 있습니다. 이를 방지하려면 새 보조 GitLab 인스턴스를 설정하는 방법을 사용할 수 있습니다.

이전 기본 사이트를 최신 상태로 만들려면:

뒤처진 이전 기본 사이트에 SSH로 접속합니다.

/etc/gitlab/gitlab-cluster.json 파일이 존재한다면 삭제합니다. (gitlab-cluster.json 파일이란?)

보조 사이트로 다시 추가될 사이트가 gitlab-ctl geo promote 명령으로 승격된 경우, /etc/gitlab/gitlab-cluster.json 파일이 존재할 수 있습니다. 예를 들어 gitlab-ctl reconfigure 실행 시 다음과 같은 출력이 나타날 수 있습니다:

The 'geo_primary_role' is defined in /etc/gitlab/gitlab-cluster.json as 'true' and overrides the setting in the /etc/gitlab/gitlab.rb

이 경우, /etc/gitlab/gitlab.rb가 다시 단일 진실 공급원(Single Source Of Truth, SSOT)이 되도록, 사이트 내 모든 Sidekiq, PostgreSQL, Gitaly, Rails 노드에서 /etc/gitlab/gitlab-cluster.json을 삭제해야 합니다(멀티 노드 설정 사용 시).

모든 서비스가 실행 중인지 확인합니다:

sudo gitlab-ctl start

기본 사이트를 영구적으로 비활성화한 경우, 지금 해당 단계를 되돌려야 합니다. Debian/Ubuntu/CentOS7+ 등 systemd를 사용하는 배포판에서는 sudo systemctl enable gitlab-runsvdir을 실행해야 합니다. CentOS 6처럼 systemd가 없는 배포판에서는 GitLab 인스턴스를 처음부터 설치하고 설정 지침을 따라 보조 사이트로 설정해야 합니다. 이 경우에는 다음 단계를 따를 필요가 없습니다.

Geo를 설정합니다. 이 경우 보조 사이트는 이전 기본 사이트를 의미합니다.

현재 보조 사이트(기본 사이트였을 당시)에서 PgBouncer가 활성화되어 있었다면, /etc/gitlab/gitlab.rb를 편집하고 sudo gitlab-ctl reconfigure를 실행하여 비활성화합니다.

이후 보조 사이트에서 데이터베이스 복제를 설정할 수 있습니다.

다시 도입된 보조 사이트에서 Geo 추적 데이터베이스 스키마를 초기화합니다.

gitlab-ctl replicate-geo-database는 메인 gitlabhq_production 데이터베이스만 복제합니다. Geo 추적 데이터베이스(gitlabhq_geo_production)는 보조 사이트 로컬에 있으며, 일반적으로 geo_secondary['auto_migrate']를 통해 sudo gitlab-ctl reconfigure로 마이그레이션됩니다. auto_migrate가 비활성화되어 있거나, 추적 데이터베이스가 외부에 있거나, 마지막으로 reconfigure를 실행했을 때 비어 있었던 경우, Geo Log Cursor가 멈추고 모든 동기화 유형이 0%에 머무르게 됩니다.

이런 경우, 보조 사이트의 Rails 또는 Sidekiq 노드에서:

추적 데이터베이스 마이그레이션을 수동으로 실행합니다.

새로운 스키마를 인식할 수 있도록 Geo Log Cursor를 재시작합니다:

sudo gitlab-ctl restart geo-logcursor

계속 진행하기 전에 추적 데이터베이스가 올바르게 설정되었는지 확인합니다:

# Confirm the tracking database has tables
sudo gitlab-geo-psql -d gitlabhq_geo_production -c "\dt"

# Confirm all tracking database migrations are applied
sudo gitlab-rake db:migrate:status:geo | grep -w down

# Run the full Geo check
sudo gitlab-rake gitlab:geo:check

db:migrate:status:geo 명령은 down 상태의 마이그레이션이 없어야 하며, gitlab:geo:check는 출력 결과에 GitLab Geo tracking database is correctly configured ... yes가 표시되어야 합니다.

OpenBao에 대한 JWT audience를 구성합니다. GitLab Secrets Manager를 활성화했고, 기본 사이트와 보조 사이트가 동일한 JWT audience를 공유하지 않는 경우, 다시 추가된 보조 사이트의 Helm values에서 jwt_audience를 새 기본 사이트의 OpenBao URL로 설정합니다:

global:
  openbao:
    enabled: true
    url: https://openbao.old-primary.example.com:8200
    jwt_audience: https://openbao.promoted.example.com:8200

원래 기본 사이트를 분실한 경우, 설정 지침을 따라 새 보조 사이트를 설정하세요.

보조 사이트를 기본 사이트로 승격하기#

초기 복제가 완료되고 기본 사이트와 보조 사이트가 거의 동기화된 상태가 되면, 계획된 페일오버(planned failover)를 진행할 수 있습니다.

보조 사이트 복원#

두 사이트를 다시 운영하는 것이 목표라면, 첫 번째 단계 (이전 기본 사이트를 보조 사이트로 구성하기)를 보조 사이트에 대해 반복하여 보조 사이트를 다시 온라인 상태로 만들어야 합니다.

추가 보조 사이트 복원#

보조 사이트가 두 개 이상인 경우, 나머지 사이트들을 지금 온라인으로 전환할 수 있습니다. 각 나머지 사이트에 대해, 기본 사이트와 복제 프로세스를 시작합니다.

보조 사이트에서 데이터 재전송 건너뛰기#

보조 사이트가 추가될 때, 기본 사이트에서 동기화될 데이터가 이미 존재하는 경우, Geo는 해당 데이터의 재전송을 피합니다.

  • Git 리포지터리는 git fetch로 전송되며, 누락된 refs만 전송합니다.

  • Geo의 컨테이너 레지스트리 동기화 코드는 태그와 다이제스트(digest)의 쌍을 비교하여 누락된 항목만 가져옵니다.

  • Blob은 첫 번째 동기화 시 이미 존재하는 경우 건너뜁니다.

사용 사례:

  • 계획된 페일오버를 수행하고, 이전 기본 사이트를 재구축 없이 보조 사이트로 연결하여 강등하는 경우.

  • 여러 개의 보조 Geo 사이트를 운영 중에 계획된 페일오버를 수행하고, 나머지 보조 Geo 사이트들을 재구축 없이 다시 연결하는 경우.

  • 보조 사이트를 승격하고 강등하는 방식으로 페일오버 테스트를 수행한 후, 재구축 없이 다시 연결하는 경우.

  • 백업을 복원하고 해당 사이트를 보조 사이트로 연결하는 경우.

  • 동기화 문제를 해결하기 위해 보조 사이트에 수동으로 데이터를 복사하는 경우.

  • 문제를 해결하기 위해 Geo 추적 데이터베이스의 레지스트리 테이블 행을 삭제하거나 초기화하는 경우.

  • 문제를 해결하기 위해 Geo 추적 데이터베이스를 초기화하는 경우.

Blob 재전송 건너뛰기#

History

기존 blob 데이터가 있는 보조 사이트를 추가하면, 보조 Geo 사이트는 해당 데이터의 재전송을 피합니다. 이는 다음 항목에 적용됩니다:

  • CI job 아티팩트

  • CI 파이프라인 아티팩트

  • CI 보안 파일

  • LFS 객체

  • 머지 리퀘스트 diff

  • 패키지 파일

  • Pages 배포

  • Terraform 상태 버전

  • 업로드

  • Dependency proxy 매니페스트

  • Dependency proxy blob

보조 사이트의 복사본이 실제로 손상된 경우, 백그라운드 검증이 결국 실패하고 해당 blob은 재동기화됩니다.

Blob은 Geo 추적 데이터베이스에 해당하는 레지스트리 레코드가 없는 경우에만 이 방식으로 건너뜁니다. 재동기화는 거의 항상 의도적인 작업이며, 전송을 실수로 건너뛰는 위험을 방지하기 위해 조건이 엄격하게 적용됩니다.