이 문서는 프레임워크를 계속 구현하고 개선함에 따라 변경될 수 있습니다. 진행 상황은 에픽에서 확인할 수 있습니다. 새로운 데이터 타입을 복제해야 하는 경우 Geo 팀에 연락하여 옵션을 논의하세요. Slack의 #g_geo 채널에서 팀에 연락하거나, 이슈 또는 머지 리퀘스트에서 @geo-team을 멘션하세요.

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): 모델은 Active Model로, 전체 Rails 코드베이스에서 이와 같이 알려져 있습니다. 일반적으로 데이터베이스 테이블과 연결됩니다. Geo 관점에서 모델은 하나 이상의 리소스를 가질 수 있습니다.

• 리소스(Resource): 리소스는 모델에 속하며 GitLab 기능에 의해 생성되는 데이터 조각입니다. 저장소 메커니즘을 사용하여 지속됩니다. 기본적으로 리소스는 Geo 복제 가능 대상이 아닙니다.

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

  Git 리포지터리

  • Blob

  • 데이터베이스

  자세한 내용은 데이터 타입을 참조하세요.

• Geo 복제 가능(Geo Replicable): 복제 가능(Replicable)은 Geo가 Geo 사이트 간에 동기화하려는 리소스입니다. 지원되는 복제 가능 데이터 타입의 집합은 제한적입니다. 알려진 데이터 타입 중 하나에 속하는 리소스의 복제를 구현하는 데 필요한 노력은 최소화됩니다.

• Geo 복제자(Geo Replicator): Geo 복제자는 복제 가능 대상을 복제하는 방법을 아는 객체입니다. 다음을 담당합니다:

  이벤트 발생(생산자)

  • 이벤트 소비(소비자)

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

• Geo 도메인 특정 언어(Geo Domain-Specific Language): 엔지니어가 어떤 리소스를 복제해야 하는지, 어떻게 복제해야 하는지를 지정할 수 있게 해주는 문법적 편의 기능입니다.

Geo 도메인 특정 언어#

복제자#

우선 복제자를 작성해야 합니다. 복제자는 ee/app/replicators/geo에 위치합니다. 복제해야 하는 각 리소스에 대해 여러 리소스가 동일한 모델에 연결되어 있더라도 별도의 복제자를 지정해야 합니다.

예를 들어, 다음 복제자는 패키지 파일을 복제합니다:

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가 지원하는 다양한 데이터 타입에 따라 포함할 수 있는 다양한 전략이 있습니다. 필요에 맞는 전략을 선택하세요.

모델과 연결하기#

이 복제자를 모델에 연결하려면 모델 코드에 다음을 추가해야 합니다:

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

  with_replicator Geo::PackageFileReplicator
end

API#

이 설정이 완료되면 모델을 통해 복제자에 쉽게 접근할 수 있습니다:

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

또는 복제자에서 모델을 다시 가져올 수 있습니다:

replicator.model_record
=> 

복제자는 예를 들어 ActiveRecord 훅에서 이벤트를 생성하는 데 사용할 수 있습니다:

  after_create_commit -> { replicator.publish_created_event }

라이브러리#

이 모든 것을 뒷받침하는 프레임워크는 ee/lib/gitlab/geo/에 위치합니다.

기존 복제자 전략#

새로운 종류의 복제자 전략을 작성하기 전에 아래를 확인하여 기존 전략 중 하나로 리소스를 처리할 수 있는지 확인하세요. 확실하지 않은 경우 Geo 팀에 문의하세요.

Blob 복제자 전략#

CarrierWave의 Uploader::Base를 사용하는 모델은 Geo::BlobReplicatorStrategy 모듈을 통해 Geo에서 지원됩니다. 예를 들어, 파이프라인 아티팩트에 대한 Geo 복제가 구현된 방법을 참조하세요.

각 파일은 자체적인 기본 ID와 모델을 가질 것으로 예상됩니다. Geo는 모든 단일 파일을 1급 시민(first-class citizen)으로 취급할 것을 강력히 권장합니다. 경험상 이렇게 하면 복제 및 검증 상태 추적이 크게 단순화되기 때문입니다.

새로운 blob 타입 모델의 Geo 복제를 구현하려면 제공된 이슈 템플릿으로 이슈를 열어보세요.

이슈를 열지 않고 구현 단계를 보려면 이슈 템플릿 파일을 확인하세요.

리포지터리 복제자 전략#

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

각 Git 리포지터리는 자체적인 기본 ID와 모델을 가질 것으로 예상됩니다.

리포지터리 동기화 흐름, 배타적 임대(exclusive lease) 메커니즘, 고아 임대 키 문제 해결에 대한 자세한 설명은 리포지터리 동기화 문서를 참조하세요.

새로운 Git 리포지터리 타입 모델의 Geo 복제를 구현하려면 제공된 이슈 템플릿으로 이슈를 열어보세요.

이슈를 열지 않고 구현 단계를 보려면 이슈 템플릿 파일을 확인하세요.