지리 정보 (Geo)

Tier: Premium, Ultimate Offering: Self-managed

Geo는 광범위하게 분산된 개발 팀을 위한 솔루션이며, 재해 복구 전략의 일환으로 대기 상태를 제공합니다.

caution
Geo는 릴리즈마다 상당한 변화를 겪습니다. 업그레이드는 지원되며 문서화되어 있지만, 설치에 적합한 문서 버전을 사용하고 있는지 확인해야 합니다.

문서의 적절한 버전을 사용하고 있는지 확인하려면 GitLab.com의 Geo 페이지로 가서 Switch branch/tag 드롭다운 목록에서 적절한 릴리스를 선택하세요. 예를 들어, v15.7.6-ee.

대규모 리포지토리를 가져오는 것은 단일 GitLab 인스턴스에서 멀리 있는 팀과 러너에게 오랜 시간이 걸릴 수 있습니다.

Geo는 원격 팀과 지리적으로 가까운 곳에 배치할 수 있는 로컬 캐시를 제공하여 읽기 요청을 처리할 수 있습니다. 이를 통해 대규모 리포지토리를 클론하고 가져오는 시간을 줄여 개발 속도를 높이고 원격 팀의 생산성을 향상시킬 수 있습니다.

Geo 보조 사이트는 쓰기 요청을 기본 사이트에 투명하게 프록시합니다. 모든 Geo 사이트는 사용자가 방문한 사이트에 관계없이 일관되고 원활하며 포괄적인 경험을 제공하도록 단일 GitLab URL에 응답하도록 구성할 수 있습니다.

Geo는 Geo 용어집에서 설명된 일련의 정의된 용어를 사용합니다. 해당 용어를 숙지하는 것이 좋습니다.

사용 사례

Geo를 구현하면 다음과 같은 이점을 제공합니다:

  • 분산된 개발자가 대규모 리포지토리와 프로젝트를 클론하고 가져오는 시간이 몇 분에서 몇 초로 줄어듭니다.
  • 모든 개발자가 어디에 있든지 아이디어를 기여하고 병렬로 작업할 수 있게 합니다.
  • 기본 사이트와 보조 사이트 간의 읽기 로드를 균형 있게 분배합니다.

또한, Geo는 다음과 같은 기능을 제공합니다:

  • 프로젝트를 클론하고 가져오는 데 사용될 수 있으며, GitLab 웹 인터페이스에서 사용할 수 있는 모든 데이터를 읽을 수 있습니다(자세한 내용은 제한 사항을 참조하세요).
  • 먼 사무실 간의 느린 연결을 극복하여 분산 팀의 속도를 향상시켜 시간을 절약합니다.
  • 자동화된 작업, 사용자 지정 통합 및 내부 워크플로의 로딩 시간을 줄이는 데 도움을 줍니다.
  • 재해 복구 시나리오에서 보조 사이트로 빠르게 실패 전환할 수 있습니다.
  • 보조 사이트로 계획된 실패 전환이 가능합니다.

Geo는 다음과 같은 기능을 제공합니다:

  • 보조 사이트에서 완전한 GitLab 경험: 하나의 기본 GitLab 사이트를 유지하면서 각 분산 팀을 위한 완전한 읽기 및 쓰기 및 UI 경험을 제공하는 보조 사이트를 활성화합니다.
  • 인증 시스템 훅: 보조 사이트는 기본 인스턴스에서 사용자 계정 및 로그인과 같은 모든 인증 데이터를 수신합니다.

Gitaly 클러스터

Geo는 Gitaly Cluster와 혼동해서는 안 됩니다. Geo와 Gitaly Cluster의 차이에 대한 자세한 내용은 Geo와의 비교를 참조하세요.

작동 방식

이 섹션에서는 GitLab 환경에서 Geo가 작동하는 방식에 대한 간단한 요약을 제공합니다. 보다 자세한 정보는 Geo 개발 페이지를 참조하세요.

당신의 Geo 인스턴스는 프로젝트를 클론하고 가져오는 데 사용될 수 있으며, 모든 데이터를 읽는 데에도 사용될 수 있습니다. 이를 통해 대규모 리포지토리를 먼 거리에서 작업할 때 훨씬 더 빠릅니다.

Geo 개요

Geo가 활성화되면:

  • 원래 인스턴스는 기본 사이트로 알려져 있습니다.
  • 복제 사이트는 보조 사이트로 알려져 있습니다.

기억해야 할 점:

  • 보조 사이트는 기본 사이트에 다음을 요청합니다:
    • 로그인용 사용자 데이터 가져오기(API).
    • 리포지토리, LFS 개체 및 첨부 파일 복제(HTTPS + JWT).
  • 기본 사이트는 복제 세부 정보를 보기 위해 보조 사이트에 요청합니다. 기본 사이트는 동기화 및 검증 데이터(API)를 위해 보조 사이트에 대한 GraphQL 쿼리를 수행합니다.
  • 당신은 보조 사이트에 직접 푸시할 수 있으며(HTTP 및 SSH 모두에 대해, Git LFS 포함), 이는 요청을 기본 사이트로 프록시합니다.
  • Geo를 사용할 때 제한 사항이 있습니다.

아키텍처

다음 다이어그램은 Geo의 기본 아키텍처를 보여줍니다.

Geo 아키텍처

이 다이어그램에서:

  • Primary 사이트와 하나의 Secondary 사이트의 세부 정보가 있습니다.

  • 데이터베이스에 대한 쓰기는 Primary 사이트에서만 수행할 수 있습니다. Secondary 사이트는 PostgreSQL 스트리밍 복제를 사용하여 데이터베이스 업데이트를 수신합니다.

  • 존재하는 경우, LDAP 서버는 재해 복구 시나리오에 대해 복제를 수행하도록 구성해야 합니다.

  • Secondary 사이트는 JWT로 보호된 특별한 인증을 사용하여 Primary 사이트에 대해 서로 다른 유형의 동기화를 수행합니다.

    • 리포지토리는 HTTPS를 통한 Git으로 복제/업데이트됩니다.
    • 첨부파일, LFS 객체 및 기타 파일은 비공식 API 엔드포인트를 사용하여 HTTPS를 통해 다운로드됩니다.

Git 작업을 수행하는 사용자의 관점에서:

  • Primary 사이트는 전체 읽기-쓰기 GitLab 인스턴스처럼 동작합니다.

  • Secondary 사이트는 전체 읽기-쓰기 GitLab 인스턴스처럼 동작합니다. Secondary 사이트는 모든 작업을 Primary 사이트로 투명하게 프록시합니다. 몇 가지 주목할 만한 예외가 있습니다. 특히, Git fetch는 최신 상태일 때 Secondary 사이트에서 제공됩니다.

GitLab UI를 탐색하거나 API를 사용하는 사용자의 관점에서:

  • Primary 사이트는 전체 읽기-쓰기 GitLab 인스턴스처럼 동작합니다.

  • Secondary 사이트는 전체 읽기-쓰기 GitLab 인스턴스처럼 동작합니다. Secondary 사이트는 모든 작업을 Primary 사이트로 투명하게 프록시합니다. 몇 가지 주목할 만한 예외가 있습니다. 특히, 웹 UI 자산은 Secondary 사이트에서 제공됩니다.

다이어그램을 단순화하기 위해 몇 가지 필요한 구성 요소가 생략되었습니다.

Secondary 사이트는 두 개의 서로 다른 PostgreSQL 데이터베이스가 필요합니다:

Secondary 사이트는 또한 추가 데몬인 Geo Log Cursor를 실행합니다.

Geo 실행 요건

Geo를 실행하기 위해서는 다음이 필요합니다:

또한 GitLab 최소 요구 사항을 확인하고 더 나은 경험을 위해 GitLab의 최신 버전을 사용하는 것이 좋습니다.

방화벽 규칙

다음 표는 Geo를 위해 기본 및 보조 사이트 간에 열어야 하는 기본 포트를 나열합니다. 장애 조치를 간소화하기 위해 두 방향 모두에서 포트를 열어야 합니다.

소스 사이트 소스 포트 대상 사이트 대상 포트 프로토콜
Primary Any Secondary 80 TCP (HTTP)
Primary Any Secondary 443 TCP (HTTPS)
Secondary Any Primary 80 TCP (HTTP)
Secondary Any Primary 443 TCP (HTTPS)
Secondary Any Primary 5432 TCP

GitLab에서 사용되는 포트의 전체 목록은 패키지 기본값에서 확인하세요.

노트: 웹 터미널 지원은 로드 밸런서가 웹소켓 연결을 올바르게 처리해야 합니다.

HTTP 또는 HTTPS 프록시를 사용할 때, 로드 밸런서는 Connection 및 Upgrade hop-by-hop 헤더를 통과하도록 설정해야 합니다. 자세한 내용은 웹 터미널 통합 가이드를 참조하세요.

노트: 포트 443에 대한 HTTPS 프로토콜을 사용할 경우, 로드 밸런서에 SSL 인증서를 추가해야 합니다.

대신 GitLab 애플리케이션 서버에서 SSL을 종료하려는 경우 TCP 프로토콜을 사용하세요.

노트: 외부/내부 URL에 대해 HTTPS만 사용하는 경우, 방화벽에서 포트 80을 열 필요는 없습니다.

내부 URL

어떤 Geo 보조 사이트에서 기본 Geo 사이트로의 HTTP 요청은 기본 Geo 사이트의 내부 URL을 사용합니다. 이 URL이 관리자 영역의 기본 Geo 사이트 설정에 명시적으로 정의되지 않으면, 기본 사이트의 공개 URL이 사용됩니다.

기본 Geo 사이트의 내부 URL을 업데이트하려면:

  1. 왼쪽 사이드바에서 맨 아래의 Admin을 선택합니다.
  2. Geo > Sites를 선택합니다.
  3. 기본 사이트에서 Edit을 선택합니다.
  4. Internal URL을 변경한 후 Save changes를 선택합니다.

Geo 추적 데이터베이스

추적 데이터베이스 인스턴스는 로컬 인스턴스에서 업데이트해야 할 내용을 제어하기 위해 메타데이터로 사용됩니다. 예를 들어:

  • 새 자산 다운로드.
  • 새로운 LFS 객체 가져오기.
  • 최근에 업데이트된 리포지토리에서 변경 사항 가져오기.

복제된 데이터베이스 인스턴스는 읽기 전용이므로 각 보조 사이트에 대해 이 추가 데이터베이스 인스턴스가 필요합니다.

Geo 로그 커서

이 데몬은:

  • 기본 사이트에서 보조 데이터베이스 인스턴스로 복제된 이벤트의 로그를 읽습니다.
  • 수행해야 할 변경 사항으로 Geo 추적 데이터베이스 인스턴스를 업데이트합니다.

추적 데이터베이스 인스턴스에서 업데이트 할 것으로 표시된 경우, 보조 사이트에서 실행되는 비동기 작업이 필수 작업을 수행하고 상태를 업데이트합니다.

이 새로운 아키텍처는 GitLab이 사이트 간 연결 문제에 대한 복원력을 제공할 수 있게 합니다. 보조 사이트가 기본 사이트에서 얼마나 오랫동안 분리되어 있든 관계없이 모든 이벤트를 올바른 순서로 재생할 수 있으며 다시 기본 사이트와 동기화될 수 있습니다.

제한 사항

경고: 이 제한 사항 목록은 GitLab의 최신 버전만 반영합니다. 이전 버전을 사용하는 경우 추가 제한 사항이 있을 수 있습니다.

  • 보조 사이트에 직접 푸시하면 요청이 직접 처리하는 대신 기본 사이트로 리디렉션(HTTP의 경우)되거나 프록시됩니다. 이 제한 사항은 URI에 자격 증명이 포함된 Git을 HTTP를 통해 사용할 수 없다는 것입니다. 자세한 내용은 Geo 사이트 사용 방법 을 참조하세요.
  • OAuth 로그인이 발생하려면 기본 사이트가 온라인 상태여야 합니다. 기존 세션과 Git은 영향을 받지 않습니다. 보조 사이트가 기본과 독립적인 OAuth 공급자를 사용할 수 있도록 지원하는 것은 계획 중입니다.
  • 설치는 여러 수동 단계를 거쳐야 하며, 상황에 따라 약 1시간 정도 소요될 수 있습니다. GitLab 환경 툴킷Terraform 및 Ansible 스크립트를 사용하여 프로덕션 GitLab 인스턴스를 배포하고 운영하는 것을 고려하세요. 참조 아키텍처 를 기반으로 하며, 일반적인 일상 작업 자동화도 포함됩니다. Epic 1465에서는 Geo 설치를 한층 더 개선할 것을 제안합니다.
  • 이슈/병합 요청의 실시간 업데이트(예: 긴 폴링을 통해)는 HTTP 프록시가 비활성화된 보조 사이트에서 작동하지 않습니다.
  • 선택적 동기화는 복제된 리포지토리와 파일을 제한하는 것만 가능합니다. 전체 PostgreSQL 데이터는 여전히 복제됩니다. 선택적 동기화는 컴플라이언스 / 수출 관리 사용 사례를 수용하기 위해 설계되지 않았습니다.
  • 페이지 액세스 제어는 보조 사이트에서 작동하지 않습니다. 자세한 내용은 GitLab 이슈 #9336를 참조하세요.
  • 여러 보조 사이트가 있는 배포의 재해 복구에서는 PostgreSQL 스트리밍 복제를 모든 비승격된 보조 사이트에서 새 기본 사이트를 따르기 위해 재초기화해야 하므로 다운타임이 발생합니다.
  • Git over SSH의 경우 프로젝트 클론 URL이 브라우징하는 사이트에 관계없이 올바르게 표시되도록 하려면, 보조 사이트가 기본 사이트와 동일한 포트를 사용해야 합니다. GitLab 이슈 #339262에서 이 제한 사항을 제거할 것을 제안합니다.
  • 보조 사이트에서 SSH를 통한 Git 푸시는 1.86 GB를 초과하는 푸시를 처리하지 않습니다. 이 버그는 GitLab 이슈 #413109에서 추적됩니다.
  • 백업은 Geo 보조 사이트에서 실행할 수 없습니다.
  • 보조 사이트에서 SSH를 통해 옵션이 있는 Git 푸시는 작동하지 않으며 연결이 종료됩니다. 자세한 내용은 이슈 417186를 참조하세요.
  • Geo 보조 사이트는 대부분의 경우 파이프라인의 첫 번째 단계에 대한 클론 요청을 가속하지 않습니다. Git 변경이 크거나 대역폭이 적거나 파이프라인 단계가 짧은 경우 나중 단계도 보조 사이트에서 제공되지 않을 수 있습니다. 일반적으로는 후속 단계의 클론 요청을 제공하며, 이슈 446176에서는 이와 관련된 이유를 논의하며 보조 사이트에서 Runner 클론 요청이 제공될 가능성을 높이기 위한 향상안을 제안합니다.
  • 단일 Git 리포지토리가 높은 비율로 푸시를 받을 경우, 보조 사이트의 로컬 복사본이 지속적으로 오래되지 않을 수 있습니다. 이로 인해 해당 리포지토리의 모든 Git 가져오기 요청이 기본 사이트로 전달됩니다. GitLab 이슈 #455870에서 참조하세요.
  • 프록시는 GitLab 응용 프로그램의 Puma 서비스 또는 웹 서비스에서만 구현되므로 다른 서비스는 이 동작으로부터 이점을 얻지 못합니다. 항상 요청이 기본으로 전송되도록 별도의 URL을 사용해야 합니다. 이러한 서비스에는 다음이 포함됩니다:
    • GitLab 컨테이너 레지스트리 - 별도의 도메인을 사용하도록 구성할 수 있습니다, 예를 들어 registry.example.com. 보조 사이트 컨테이너 레지스트리는 재해 복구를 위해 의도된 것입니다. 사용자는 푸시를 위해 이들로 라우팅되어서는 안 되며, 왜냐하면 데이터가 기본 사이트에 전파되지 않기 때문입니다.
    • GitLab 페이지 - GitLab 페이지를 실행하기 위한 전제 조건의 일부로 항상 별도의 도메인을 사용해야 합니다.
  • 통합 URL와 함께 Let’s Encrypt는 동일한 도메인을 통해 두 IP에 도달할 수 없으면 인증서를 생성할 수 없습니다. Let’s Encrypt와 함께 TLS 인증서를 사용하려면, 도메인을 Geo 사이트 중 하나에 수동으로 지시하고 인증서를 생성한 후, 모든 다른 사이트에 복사할 수 있습니다.
  • 보조 사이트가 기본 사이트와 별도의 URL을 사용하는 경우, SAML을 사용하여 보조 사이트에 로그인하는 것은 SAML ID 공급자(IdP)가 여러 콜백 URL로 구성된 응용 프로그램을 허용하는 경우에만 지원됩니다.
  • SSH를 통한 보조 사이트에 대한 Git 클론 및 가져오기 요청이 --depth 옵션과 함께 작동하지 않으며, 요청이 시작될 때 보조 사이트가 최신 상태가 아닐 경우 무한정 중지됩니다. 이는 프록시를 사용 중 Git SSH를 Git HTTPS로 변환하는 것과 관련된 문제 때문에 발생합니다. 자세한 내용은 이슈 391980를 참조하세요. 현재는 이러한 변환 단계를 포함하지 않는 새로운 워크플로가 Linux 패키지 GitLab Geo 보조 사이트에서 사용할 수 있으며, 기능 플래그로 활성화할 수 있습니다. 자세한 내용은 이슈 454707의 댓글에서 참조하세요. Cloud Native GitLab Geo 보조 사이트에 대한 수정 사항은 이슈 5641에서 추적됩니다.
  • 일부 고객은 보조 사이트가 최신 상태가 아닐 때 SSH를 통해 git fetch가 중지되거나 시간 초과되어 실패한다고 보고했습니다. SSH를 통한 git clone 요청은 영향을 받지 않습니다. 자세한 내용은 이슈 454707을 참조하세요. Linux 패키지 GitLab Geo 보조 사이트에 사용할 수 있는 수정 사항이 있으며, 기능 플래그로 활성화할 수 있습니다. 자세한 내용은 이슈 454707의 댓글에서 참조하세요. Cloud Native GitLab Geo 보조 사이트에 대한 수정 사항은 이슈 5641에서 추적됩니다.

복제 데이터 유형

모든 GitLab 데이터 유형 및
복제 데이터 유형에 대한 완전한 목록이 있습니다.

설치 후 문서

GitLab을 2차 사이트에 설치하고 초기 구성을 수행한 후, 설치 후 정보를 위한 다음 문서를 참조하세요.

Geo 설정

Geo 구성에 대한 정보는 Geo 설정을 참조하세요.

객체 저장소로 Geo 구성

객체 저장소와 함께 Geo를 구성하는 방법에 대한 정보는 객체 저장소와 함께하는 Geo를 참조하세요.

컨테이너 레지스트리 복제

컨테이너 레지스트리를 복제하는 방법에 대한 자세한 내용은 2차 사이트에 대한 컨테이너 레지스트리를 참조하세요.

Geo 사이트에 대한 통합 URL 설정

AWS Route53 또는 Google Cloud DNS를 사용하여 단일 위치 인식 URL을 설정하는 방법에 대한 예시는 Geo 사이트에 대한 통합 URL 설정을 참조하세요.

싱글 사인온 (SSO)

싱글 사인온 (SSO)을 구성하는 방법에 대한 자세한 내용은 SSO와 함께하는 Geo를 참조하세요.

LDAP

LDAP 구성에 대한 자세한 내용은 SSO와 함께하는 Geo > LDAP를 참조하세요.

Geo 튜닝

Geo 튜닝에 대한 자세한 내용은 Geo 튜닝을 참조하세요.

복제 일시 중지 및 재개

자세한 내용은 복제 일시 중지 및 재개를 참조하세요.

백필

2차 사이트가 설정되면, 주 사이트에서 누락된 데이터를 복제하기 시작하며, 이 과정은 백필로 알려져 있습니다. 브라우저에서 주 사이트의 Geo 노드 대시보드에서 각 Geo 사이트의 동기화 프로세스를 모니터링할 수 있습니다.

백필 중에 발생하는 실패는 백필 종료 후 재시도되도록 예약됩니다.

러너

Geo 업그레이드

Geo 사이트를 최신 GitLab 버전으로 업데이트하는 방법에 대한 정보는 Geo 사이트 업그레이드를 참조하세요.

보안 검토

Geo 보안에 대한 자세한 내용은 Geo 보안 검토를 참조하세요.

Geo 사이트 제거

Geo 사이트 제거에 대한 정보는 2차 Geo 사이트 제거를 참조하세요.

Geo 비활성화

Geo 비활성화 방법에 대한 내용은 Geo 비활성화를 참조하세요.

로그 파일

Geo는 geo.log 파일에 구조화된 로그 메시지를 저장합니다.

Geo 로그에 접근하고 소비하는 방법에 대한 자세한 내용은 로그 시스템 문서의 Geo 섹션을 참조하세요.

재해 복구

재해 복구 상황에서 데이터 손실을 완화하고 서비스를 복원하기 위해 Geo를 사용하는 방법에 대한 정보는 재해 복구를 참조하세요.

자주 하는 질문

자주 묻는 질문에 대한 답변은 Geo FAQ를 참조하세요.

문제 해결