Geo 셀프 서비스 프레임워크

note
이 문서는 프레임워크를 구현하고 개선하는 과정에서 변경될 수 있습니다.
에픽에서 진행 상황을 확인하세요.
새로운 데이터 유형을 복제해야 하는 경우, Geo 팀에 연락하여 옵션을 논의하세요.
Slack의 #g_geo에서 그들과 연락할 수 있으며, 이슈나 병합 요청에서 @geo-team을 언급할 수 있습니다.

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

Geo는 완료 정의의 필수 요건입니다

Geo는 재난 복구를 위한 GitLab 솔루션입니다.
강력한 재난 복구 솔루션은 모든 GitLab 데이터를 복제해야 하며,
재난 발생 시 모든 GitLab 서비스가 최소한의 데이터 손실로 성공적으로 복원될 수 있습니다.

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

셀프 서비스 프레임워크(SSF)를 통한 Geo 지원 추가는 간단하며,
이 페이지에서는 다양한 유형의 데이터에 대한 자세한 설명이 나와 있습니다.
새로운 GitLab 기능에 Geo 지원을 추가해야 하는지 여부를 결정하는 데 도움이 되는
보다 일반적인 지침을 원하신다면, 여기에서 시작할 수 있습니다.

명명법

API를 깊이 있게 살펴보기 전에 개발자는 몇 가지 Geo 전용
명명 규칙을 알아야 합니다:

  • 모델:
    모델은 Active Model이며, Rails 코드베이스 전체에서 이렇게 알려져 있습니다.
    보통 데이터베이스 테이블에 연결되어 있습니다. Geo 관점에서,
    모델은 하나 이상의 리소스를 가질 수 있습니다.

  • 리소스:
    리소스는 모델에 속하며, GitLab 기능에 의해 생성된 데이터 조각입니다.
    저장 메커니즘을 사용하여 지속됩니다. 기본적으로,
    리소스는 Geo 복제 가능하지 않습니다.

  • 데이터 유형:
    데이터 유형은 리소스가 저장되는 방법입니다. 각 리소스는
    Geo가 지원하는 데이터 유형 중 하나에 맞아야 합니다:
    • Git 저장소
    • Blob
    • 데이터베이스

    자세한 내용은 데이터 유형을 참조하세요.

  • Geo 복제 가능:
    복제 가능성은 Geo가 Geo 사이트 간에 동기화하려는 리소스입니다.
    복제 가능한 데이터 유형의 지원 목록은 제한되어 있습니다.
    알려진 데이터 유형 중 하나에 속하는 리소스의 복제를 구현하는 데 필요한 노력은 최소화됩니다.

  • Geo 복제기:
    Geo 복제기는 복제 가능성을 복제하는 방법을 아는 객체입니다.
    다음의 책임이 있습니다:
    • 이벤트 발생 (생산자)
    • 이벤트 소비 (소비자)

    Geo 복제 가능 데이터 유형에 연결되어 있습니다. 모든 복제기는
    이벤트를 처리하기 위해 사용될 수 있는 공통 인터페이스를 가지고 있습니다.
    이는 이벤트가 발생하는 기본 사이트와 이벤트가 소비되는 보조 사이트 간의
    통신을 처리합니다. Geo를 자신의 기능에 통합하고자 하는 엔지니어는
    복제기의 API를 사용하여 이를 실현합니다.

  • Geo 도메인 특화 언어:
    리소스를 복제할지 여부와 방법을 쉽게 지정할 수 있도록 해주는 문법적 설탕입니다.

Geo 도메인 특정 언어

복제기

먼저 복제기를 작성해야 합니다. 복제기는 ee/app/replicators/geo 에 존재합니다.

복제가 필요한 각 리소스에 대해 별도의 복제기를 지정해야 하며, 여러 리소스가 동일한 모델과 연결되어 있더라도 마찬가지입니다.

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

module Geo
  class PackageFileReplicator < Gitlab::Geo::Replicator
    # 리소스에 필요한 전략 중 하나를 포함합니다
    include ::Geo::BlobReplicatorStrategy

    # 사용된 전략에 필요한 CarrierWave 업로더를 지정합니다
    def carrierwave_uploader
      model_record.file
    end

    # 이 복제기가 속한 모델을 지정합니다
    def self.model
      ::Packages::PackageFile
    end
  end
end

클래스 이름은 고유해야 합니다. 또한 레지stry의 테이블 이름과 밀접하게 연관되어 있으므로 이 예에서 레지스트리 테이블은 package_file_registry입니다.

Geo에서 지원하는 다양한 데이터 유형에 따라 포함해야 할 다양한 전략이 있습니다. 필요에 맞는 전략을 선택하세요.

모델과 연결하기

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

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

  with_replicator Geo::PackageFileReplicator
end

API

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

package_file = Packages::PackageFile.find(4) # 예시를 위한 임의의 ID
replicator = package_file.replicator

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

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

복제기는 ActiveRecord 후크에서 이벤트를 생성하는 데 사용될 수 있습니다:

  after_create_commit -> { replicator.publish_created_event }

라이브러리

이 모든 것 뒤에 있는 프레임워크는 ee/lib/gitlab/geo/에 위치해 있습니다.

기존 복제기 전략

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

Blob 복제기 전략

CarrierWave’s Uploader::Base를 사용하는 모델은 Geo::BlobReplicatorStrategy 모듈로 Geo에서 지원됩니다. 예를 들어, 파이프라인 아티팩트에 대한 Geo 복제가 어떻게 구현되었는지를 참고하세요.

각 파일은 고유한 기본 ID와 모델을 가져야 합니다. Geo는 모든 단일 파일을 1급 시민으로 취급할 것을 강력히 권장합니다. 왜냐하면 우리의 경험으로 볼 때, 이는 복제 및 검증 상태 추적을 크게 단순화하기 때문입니다.

새로운 blob 유형 모델의 Geo 복제를 구현하려면, 제공된 이슈 템플릿으로 문제를 열어주세요.

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

저장소 복제기 전략

디스크의 모든 Git 저장소를 참조하는 모델은 Geo::RepositoryReplicatorStrategy 모듈로 Geo에서 지원됩니다. 예를 들어, 그룹 수준 위키에 대한 Geo 복제가 어떻게 구현되었는지를 확인하세요. 이 문제에서는 Git 저장소의 검증이 아직 Geo 셀프 서비스 프레임워크에 추가되지 않았기 때문에 검증을 구현하지 않았습니다. 검증을 구현한 예는 Snippet 저장소 검증 추가에 대한 merge request에서 확인할 수 있습니다.

각 Git 저장소는 고유한 기본 ID 및 모델을 가질 것으로 예상됩니다.

새로운 Git 저장소 유형 모델의 Geo 복제를 구현하려면, 제공된 문제 템플릿으로 문제를 열어주세요.

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