Geo는 Geo 사이트 간에 데이터 유형을 복제할 수 있도록 API를 제공합니다. 이 API는 Ruby 도메인 특정 언어(Domain-Specific Language, DSL)로 제공되며, 데이터 유형을 만든 엔지니어가 최소한의 노력으로 데이터를 복제할 수 있도록 하는 것을 목표로 합니다.

Geo는 완료 정의의 요구 사항입니다#

Geo는 재해 복구를 위한 GitLab 솔루션입니다. 견고한 재해 복구 솔루션은 모든 GitLab 데이터를 복제해, 재해가 발생했을 때 모든 GitLab 서비스를 최소한의 데이터 손실로 온전히 복원할 수 있어야 합니다.

이러한 이유로 GitLab 이 생성한 데이터에 대한 Geo 복제 및 검증 지원은 완료 정의의 일부입니다. 이를 통해 새로운 기능이 Geo 지원과 함께 출시되고 고객이 데이터 손실에 노출되지 않도록 보장합니다.

셀프 서비스 프레임워크(Self Service Framework, SSF)로 Geo 지원을 추가하는 일은 어렵지 않으며, 이 페이지에서 여러 데이터 유형별로 자세히 설명합니다. 다만 새 GitLab 기능에 Geo 지원을 추가해야 하는지, 추가한다면 어떻게 해야 하는지 판단하는 데 도움이 되는 더 일반적인 안내는 여기에서 시작합니다.

명명 규칙#

API를 살펴보기 전에 개발자는 Geo 고유의 명명 규칙을 몇 가지 알아야 합니다.

• Model: 모델은 Rails 코드베이스 전반에서 알려진 그대로의 Active Model 입니다. 대개 데이터베이스 테이블과 연결됩니다. Geo 관점에서 하나의 모델은 하나 이상의 리소스를 가질 수 있습니다.

• Resource: 리소스는 모델에 속하며 GitLab 기능이 만들어 내는 데이터 조각입니다. 스토리지 메커니즘을 사용해 영속화됩니다. 기본적으로 리소스는 Geo replicable 이 아닙니다.

• Data type: 데이터 유형은 리소스가 저장되는 방식입니다. 각 리소스는 Geo가 지원하는 데이터 유형 중 하나에 속해야 합니다.

  • Git 리포지터리
  • Blob
  • 데이터베이스

  자세한 내용은 데이터 유형을 참고합니다.

• Geo Replicable: Replicable은 Geo가 Geo 사이트 간에 동기화하려는 리소스입니다. replicable로 지원되는 데이터 유형은 제한적입니다. 알려진 데이터 유형에 속하는 리소스의 복제를 구현하는 데 필요한 노력은 최소한입니다.

• Geo Replicator: Geo Replicator는 replicable을 복제하는 방법을 아는 객체입니다. 다음을 담당합니다.

  • 이벤트 발행(producer)
  • 이벤트 소비(consumer)

  Geo Replicable 데이터 유형과 연결됩니다. 모든 replicator는 이벤트를 처리(즉, 생산하고 소비)하는 데 사용할 수 있는 공통 인터페이스를 가집니다. 기본 사이트(이벤트가 생산되는 곳)와 보조 사이트(이벤트가 소비되는 곳) 사이의 통신을 처리합니다. 자신의 기능에 Geo를 포함하려는 엔지니어는 replicator의 API를 사용해 이를 구현합니다.

• Geo Domain-Specific Language: 어떤 리소스를 어떻게 복제할지 엔지니어가 지정할 수 있게 해 주는 문법적 설탕입니다.

Geo 도메인 특정 언어#

복제자#

먼저 replicator를 작성해야 합니다. replicator는 ee/app/replicators/geo에 있습니다. 복제해야 하는 리소스마다 별도의 replicator를 지정해야 하며, 여러 리소스가 같은 모델에 연결되어 있더라도 마찬가지입니다.

예를 들어 다음 replicator는 패키지 파일을 복제합니다.

module Geo
  class PackageFileReplicator < Gitlab::Geo::Replicator
    # Include one of the strategies your resource needs
    include ::Geo::BlobReplicatorStrategy

    # Specify the CarrierWave uploader needed by the used strategy
    def carrierwave_uploader
      model_record.file
    end

    # Specify the model this replicator belongs to
    def self.model
      ::Packages::PackageFile
    end
  end
end

클래스 이름은 고유해야 합니다. 또한 레지스트리의 테이블 이름과 긴밀하게 결합되어 있어, 이 예시에서 레지스트리 테이블은 package_file_registry 입니다.

Geo가 지원하는 데이터 유형마다 포함할 수 있는 전략이 다릅니다. 필요에 맞는 것을 선택합니다.

모델과 연결하기#

이 replicator를 모델과 연결하려면 모델 코드에 다음을 추가해야 합니다.

class Packages::PackageFile < ApplicationRecord
  include ::Geo::ReplicableModel

  with_replicator Geo::PackageFileReplicator
end

API#

이 설정이 끝나면 모델을 통해 replicator에 손쉽게 접근할 수 있습니다.

package_file = Packages::PackageFile.find(4) # just a random ID as example
replicator = package_file.replicator

또는 replicator에서 모델을 다시 가져올 수 있습니다.

replicator.model_record
=> <Packages::PackageFile id:4>

replicator는 이벤트를 생성하는 데 사용할 수 있으며, 예를 들면 ActiveRecord 훅에서 사용합니다.

  after_create_commit -> { replicator.publish_created_event }

라이브러리#

이 모든 것의 기반이 되는 프레임워크는 ee/lib/gitlab/geo/에 있습니다.

기존 복제자 전략#

새로운 종류의 Replicator Strategy를 작성하기 전에, 해당 리소스를 이미 기존 전략으로 처리할 수 있는지 아래에서 확인합니다. 확실하지 않다면 Geo 팀에 문의합니다.

Blob 복제자 전략#

CarrierWave의 Uploader::Base를 사용하는 모델은 Geo::BlobReplicatorStrategy 모듈을 통해 Geo에서 지원됩니다. 예시로 파이프라인 아티팩트에 Geo 복제를 구현한 방식을 참고합니다.

각 파일은 자체 기본 ID와 모델을 가져야 합니다. Geo는 모든 파일을 일급 객체로 다루기를 강력히 권장합니다. 경험상 이렇게 하면 복제 및 검증 상태를 추적하기가 훨씬 단순해지기 때문입니다.

새로운 blob 유형 모델의 Geo 복제를 구현하려면 제공된 이슈 템플릿으로 이슈를 생성합니다.

이슈를 생성하지 않고 구현 단계를 보려면 이슈 템플릿 파일을 확인합니다.

리포지터리 복제자 전략#

디스크상의 Git 리포지터리를 참조하는 모델은 Geo::RepositoryReplicatorStrategy 모듈을 통해 Geo에서 지원됩니다. 예시로 그룹 수준 위키에 Geo 복제를 구현한 방식을 참고합니다. 이 이슈는 검증을 구현하지 않는데, Git 리포지터리 검증이 아직 Geo 셀프 서비스 프레임워크에 추가되지 않았기 때문입니다. 검증을 구현한 예시는 스니펫 리포지터리 검증 추가 머지 리퀘스트에서 확인할 수 있습니다.

각 Git 리포지터리는 자체 기본 ID와 모델을 가져야 합니다.

리포지터리 동기화 흐름, 배타적 리스 메커니즘, 고아 리스 키 문제 해결에 대한 자세한 설명은 리포지터리 동기화 문서를 참고합니다.

새로운 Git 리포지터리 유형 모델의 Geo 복제를 구현하려면 제공된 이슈 템플릿으로 이슈를 생성합니다.

이슈를 생성하지 않고 구현 단계를 보려면 이슈 템플릿 파일을 확인합니다.