Geo 데이터 재동기화 및 재검증
GitLab v19.5Offering: GitLab Self-Managed
요약
재동기화와 재검증은 표준 운영 작업입니다. 보조 Geo 사이트의 Rails 콘솔에서 다음 작업을 수행할 수 있습니다. 보조 사이트에서 Admin > Geo > Replication으로 이동하면 개별 항목의 재동기화 또는 재검증을 강제할 수 있습니다.
재동기화와 재검증은 표준 운영 작업입니다. 자동 재시도 간격을 기다리지 않고 복제나 검증을 다시 시도하거나, 복제 또는 검증 실패 후 복구할 때 사용할 수 있습니다.
보조 Geo 사이트의 Rails 콘솔에서 다음 작업을 수행할 수 있습니다.
개별 구성 요소 재동기화 및 재검증#
보조 사이트에서 Admin > Geo > Replication으로 이동하면 개별 항목의 재동기화 또는 재검증을 강제할 수 있습니다.
이 방법이 동작하지 않으면 Rails 콘솔에서 같은 작업을 수행할 수 있습니다. 다음 절에서는 Rails 콘솔에서 내부 애플리케이션 명령을 사용해 개별 레코드의 복제 또는 검증을 동기 또는 비동기로 실행하는 방법을 설명합니다.
Replicator 인스턴스 가져오기#
데이터를 변경하는 명령은 올바르지 않게 또는 적절한 조건이 아닌 상태에서 실행하면 피해를 줄 수 있습니다. 항상 테스트 환경에서 먼저 명령을 실행하고, 복원할 수 있는 백업 인스턴스를 준비합니다.
동기화나 검증 작업을 수행하려면 먼저 Replicator 인스턴스를 가져와야 합니다.
먼저 수행하려는 작업에 따라 기본 사이트 또는 보조 사이트에서 Rails 콘솔 세션을 시작합니다.
기본 사이트:
- 리소스의 체크섬을 계산할 수 있습니다.
보조 사이트:
- 리소스를 동기화할 수 있습니다.
- 리소스의 체크섬을 계산하고 그 체크섬을 기본 사이트의 체크섬과 대조하여 검증할 수 있습니다.
다음으로 아래 스니펫 중 하나를 실행해 Replicator 인스턴스를 가져옵니다.
모델 레코드의 ID가 주어진 경우#
123을 실제 ID로 바꿉니다.Packages::PackageFile을 Geo 데이터 유형 모델 클래스 중 하나로 바꿉니다.
model_record = Packages::PackageFile.find_by(id: 123)
replicator = model_record.replicator
레지스트리 레코드의 ID가 주어진 경우#
432를 실제 ID로 바꿉니다. 레지스트리 레코드의 ID 값은 추적하는 모델 레코드의 ID 값과 같을 수도 있고 다를 수도 있습니다.Geo::PackageFileRegistry를 Geo 레지스트리 클래스 중 하나로 바꿉니다.
보조 Geo 사이트에서:
registry_record = Geo::PackageFileRegistry.find_by(id: 432)
replicator = registry_record.replicator
레지스트리 레코드의 last_sync_failure에 오류 메시지가 있는 경우#
Geo::PackageFileRegistry를 Geo 레지스트리 클래스 중 하나로 바꿉니다.error message here를 실제 오류 메시지로 바꿉니다.
registry = Geo::PackageFileRegistry.find_by("last_sync_failure LIKE '%error message here%'")
replicator = registry.replicator
레지스트리 레코드의 verification_failure에 오류 메시지가 있는 경우#
Geo::PackageFileRegistry를 Geo 레지스트리 클래스 중 하나로 바꿉니다.error message here를 실제 오류 메시지로 바꿉니다.
registry = Geo::PackageFileRegistry.find_by("verification_failure LIKE '%error message here%'")
replicator = registry.replicator
Replicator 인스턴스로 작업 수행#
replicator 변수에 Replicator 인스턴스를 저장한 후에는 다양한 작업을 수행할 수 있습니다.
콘솔에서 동기화#
이 스니펫은 보조 사이트에서만 동작합니다.
콘솔에서 동기화 코드를 동기식으로 실행하므로, 리소스를 동기화하는 데 걸리는 시간을 확인하거나 전체 오류 백트레이스를 볼 수 있습니다.
replicator.sync
필요하면 콘솔의 로그 수준을 설정된 로그 수준보다 더 상세하게 지정한 다음 동기화를 수행합니다.
Rails.logger.level = :debug
콘솔에서 체크섬 계산 또는 검증#
이 스니펫은 모든 기본 사이트와 보조 사이트에서 동작합니다.
기본 사이트에서는 리소스의 체크섬을 계산하고 그 결과를 기본 GitLab 데이터베이스에 저장합니다. 보조 사이트에서는 리소스의 체크섬을 계산하고, 기본 사이트가 생성해 기본 GitLab 데이터베이스에 저장된 체크섬과 비교한 다음 그 결과를 Geo 추적 데이터베이스에 저장합니다.
콘솔에서 체크섬 계산 및 검증 코드를 동기식으로 실행하므로, 걸리는 시간을 확인하거나 전체 오류 백트레이스를 볼 수 있습니다.
replicator.verify
Sidekiq 작업으로 동기화#
이 스니펫은 보조 사이트에서만 동작합니다.
Sidekiq이 리소스의 동기화를 수행하도록 작업을 대기열에 추가합니다.
replicator.enqueue_sync
Sidekiq 작업으로 검증#
이 스니펫은 모든 기본 사이트와 보조 사이트에서 동작합니다.
Sidekiq이 리소스의 체크섬 계산 또는 검증을 수행하도록 작업을 대기열에 추가합니다.
replicator.verify_async
모델 레코드 가져오기#
이 스니펫은 모든 기본 사이트와 보조 사이트에서 동작합니다.
replicator.model_record
레지스트리 레코드 가져오기#
레지스트리 테이블은 Geo 추적 데이터베이스(DB)에 저장되므로 이 스니펫은 보조 사이트에서만 동작합니다.
replicator.registry
Geo 데이터 유형 모델 클래스#
Geo 데이터 유형은 하나 이상의 GitLab 기능이 관련 데이터를 저장하기 위해 필요로 하며 Geo가 보조 사이트로 복제하는 특정 데이터 클래스입니다.
- Blob 유형:
Ci::JobArtifactCi::PipelineArtifactCi::SecureFileLfsObjectMergeRequestDiffPackages::PackageFilePagesDeploymentTerraform::StateVersionUploadDependencyProxy::ManifestDependencyProxy::Blob
- Git 리포지터리 유형:
DesignManagement::RepositoryProjectRepositoryProjectWikiRepositorySnippetRepositoryGroupWikiRepository
- 기타 유형:
ContainerRepository
주요 클래스 종류는 Registry, Model, Replicator입니다. 이 클래스 중 하나의 인스턴스가 있으면 나머지도 가져올 수 있습니다. Registry와 Model은 주로 PostgreSQL 데이터베이스(DB) 상태를 관리합니다. Replicator는 PostgreSQL이 아닌 데이터(파일, Git 리포지터리, 컨테이너 리포지터리)를 복제하거나 검증하는 방법을 알고 있습니다.
Geo 레지스트리 클래스#
GitLab Geo에서 레지스트리 레코드는 Geo 추적 데이터베이스의 레지스트리 테이블을 가리킵니다. 각 레코드는 LFS 파일이나 프로젝트 Git 리포지터리처럼 기본 GitLab 데이터베이스에 있는 복제 대상 하나를 추적합니다. 조회할 수 있는 Geo 레지스트리 테이블에 대응하는 Rails 모델은 다음과 같습니다.
- Blob 유형:
Geo::CiSecureFileRegistryGeo::DependencyProxyBlobRegistryGeo::DependencyProxyManifestRegistryGeo::JobArtifactRegistryGeo::LfsObjectRegistryGeo::MergeRequestDiffRegistryGeo::PackageFileRegistryGeo::PagesDeploymentRegistryGeo::PipelineArtifactRegistryGeo::ProjectWikiRepositoryRegistryGeo::SnippetRepositoryRegistryGeo::TerraformStateVersionRegistryGeo::UploadRegistry
- Git 리포지터리 유형:
Geo::DesignManagementRepositoryRegistryGeo::ProjectRepositoryRegistryGeo::ProjectWikiRepositoryRegistryGeo::SnippetRepositoryRegistryGeo::GroupWikiRepositoryRegistry
- 기타 유형:
Geo::ContainerRepositoryRegistry
여러 구성 요소 재동기화 및 재검증#
구성 요소 리소스의 동기화 또는 검증이 실패하면 일괄 작업을 실행해 복제 대기열을 다시 시작할 수 있습니다. 이 작업은 재시도 횟수와 예약 시간을 0으로 초기화하므로, 시스템이 최대 1시간을 기다리지 않고 실패한 리소스를 더 빨리 처리합니다.
이 작업은 리소스를 즉시 처리하지 않습니다. 대신 동기화와 검증을 담당하는 백그라운드 작업을 다시 대기열에 추가합니다. 실제 복제 작업은 표준 Geo 복제 프로세스를 통해 비동기로 수행됩니다.
재동기화 및 재검증 동작 방식#
재동기화 또는 재검증 작업을 실행하면 시스템이 일치하는 레코드를 pending으로 표시합니다. Geo 재동기화 및
재검증 백그라운드 워커가 이 레코드를 가져와 일반 대기열 우선순위에 따라 처리합니다.
이 방식으로 작업이 끝날 때까지 기다리지 않고도 실패한 리소스의 처리를 앞당길 수 있습니다.
동기화에 성공하지 못한 레코드는 재검증할 수 없습니다. 동기화된 레코드만 검증할 수 있습니다.
일괄 작업은 UI 또는 Rails 콘솔에서 실행할 수 있습니다.
UI에서#
UI에서 한 구성 요소의 모든 리소스에 대한 전체 재동기화를 예약할 수 있습니다.
- 오른쪽 상단에서 Admin을 선택합니다.
- 왼쪽 사이드바에서 Geo > Sites를 선택합니다.
- Replication details에서 원하는 구성 요소를 선택합니다.
선택한 구성 요소의 리소스 재동기화#
- Resync all을 선택합니다. 선택한 리소스의 모든 레코드가 이미 동기화되었는지 여부와 관계없이 상태를 초기화합니다.
- Resync all failed를 선택합니다. 동기화에 실패한 모든 레코드를 초기화합니다.
선택한 구성 요소의 리소스 재검증#
- Reverify all을 선택합니다. 선택한 리소스의 모든 레코드가 이미 검증되었는지 여부와 관계없이 상태를 초기화합니다.
- Reverify all failed를 선택합니다. 검증에 실패했지만 동기화에는 성공한 모든 레코드를 초기화합니다.
모든 사이트에서 한 구성 요소 재검증#
기본 사이트의 체크섬이 의심스러운 경우 기본 사이트가 체크섬을 다시 계산하도록 해야 합니다.
기본 사이트에서 각 체크섬이 다시 계산되면 이벤트가 생성되어 모든 보조 사이트로 전파되고,
보조 사이트가 자체 체크섬을 다시 계산해 값을 비교하므로 "전체 재검증"이 이루어집니다.
값이 하나라도 일치하지 않으면 레지스트리가 sync failed로 표시되고 동기화 재시도가 예약됩니다.
UI에서 기본 사이트의 체크섬을 다시 계산할 수 있습니다.
- 오른쪽 상단에서 Admin을 선택합니다.
- 왼쪽 사이드바에서 Monitoring > Data management를 선택합니다.
- 드롭다운 목록에서 원하는 구성 요소를 선택합니다.
- Checksum all을 선택합니다.
Resync all, Reverify all, Checksum all은 이미 동기화되었거나 검증되었는지 여부와 관계없이 모든 리소스의 업데이트를 실행합니다. 인스턴스에 한 객체 유형이 수천 개 있는 경우(예: CI 작업 아티팩트)에는 실행하지 않아야 합니다.
Rails 콘솔에서#
데이터를 변경하는 명령은 올바르지 않게 또는 적절한 조건이 아닌 상태에서 실행하면 피해를 줄 수 있습니다. 항상 테스트 환경에서 먼저 명령을 실행하고, 복원할 수 있는 백업 인스턴스를 준비합니다.
다음 절에서는 Rails 콘솔에서 내부 애플리케이션 명령을 사용해 일괄 복제 또는 검증을 실행하는 방법을 설명합니다.
동기화에 실패한 한 구성 요소의 모든 리소스 동기화#
다음 스크립트는 다음을 수행합니다.
- 실패한 모든 리포지터리를 반복합니다.
- 마지막 실패 원인을 포함한 Geo 동기화 및 검증 메타데이터를 표시합니다.
- 리포지터리 재동기화를 시도합니다.
- 실패가 발생하면 그 사실과 원인을 보고합니다.
- 완료까지 시간이 걸릴 수 있습니다. 각 리포지터리 확인이 끝나야
결과를 보고하기 때문입니다. 세션이 타임아웃되면
screen세션을 시작하거나 Rails runner와nohup으로 실행하는 등 프로세스가 계속 실행되도록 조치합니다.
이 스크립트는 보조 Geo 사이트에서 실행합니다.
Geo::ProjectRepositoryRegistry.failed.find_each do |registry|
begin
puts "ID: #{registry.id}, Project ID: #{registry.project_id}, Last Sync Failure: '#{registry.last_sync_failure}'"
registry.replicator.sync
puts "Sync initiated for registry ID: #{registry.id}"
rescue => e
puts "ID: #{registry.id}, Project ID: #{registry.project_id}, Failed: '#{e}'", e.backtrace.join("\n")
end
end; nil
기본 사이트에서 체크섬 계산에 실패한 모든 리소스 재검증#
기본 사이트에서 체크섬 계산에 실패한 모든 리소스는 시스템이 자동으로 재검증하지만, 과도한 실패가 발생하지 않도록 점진적 백오프 방식을 사용합니다.
조치를 시도한 뒤처럼 필요한 경우에는 재검증을 더 일찍 수동으로 실행할 수 있습니다.
-
기본 사이트의 GitLab Rails 노드에 SSH로 접속합니다.
-
Rails 콘솔을 엽니다.
-
LfsObject를 Geo 데이터 유형 모델 클래스 중 하나로 바꾸고, 모든 리소스를pending verification으로 표시합니다.LfsObject.verification_state_table_class.where(verification_state: 3).each_batch do |relation| relation.update_all(verification_state: 0) end