• 사용 사례
  • Gitaly 클러스터
• 작동 방식
  • 아키텍처
• Geo 실행에 필요한 요구 사항
  • 방화벽 규칙
    • 내부 URL
  • Geo 추적 데이터베이스
  • Geo 로그 커서
• 제한 사항
  • 복제된 데이터 유형
• 설치 후 문서
  • Geo 설정
  • 객체 스토리지로 Geo 구성
  • 컨테이너 레지스트리 복제
  • Geo 사이트를 위한 통합 URL 설정
  • 단일 로그인 (SSO)
    • LDAP
  • Geo 조정
  • 복제 일시 중지 및 재개
  • 백필
  • 러너
  • Geo 업그레이드
  • 보안 검토
• Geo 사이트 제거
• Geo 비활성화
• 로그 파일
• 재해 복구
• 자주 묻는 질문
• 문제 해결

Geo

Geo는 널리 분산된 개발 팀 및 재해 복구 전략의 일환으로 웜 스탠바이를 제공하는 솔루션입니다.

경고: Geo는 릴리스마다 중요한 변경 사항이 발생합니다. 업그레이드는 지원되며 문서화되어 있지만 설치된 버전에 맞는 문서를 사용하는지 확인해야 합니다.

적절한 문서 버전을 사용 중인지 확인하려면 GitLab.com의 Geo 페이지로 이동하여 스위치 브랜치/태그 드롭다운 목록에서 적절한 릴리스를 선택하세요. 예를 들어, v15.7.6-ee.

팀 및 실행기가 단일 GitLab 인스턴스에서 멀리 떨어진 곳에 위치한 경우 대규모 저장소를 가져오는 데 시간이 오래 걸릴 수 있습니다.

Geo는 원격 팀에 지리적으로 가깝게 배치될 수 있는 로컬 캐시를 제공하여 읽기 요청을 처리할 수 있습니다. 이를 통해 대규모 저장소를 복제하고 가져오는 데 걸리는 시간을 줄일 수 있어 개발 속도를 높이고 원격 팀의 생산성을 향상시킬 수 있습니다.

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

Geo는 Geo 용어집에 설명된 일련의 정의된 용어를 사용합니다. 해당 용어에 익숙해지시기 바랍니다.

사용 사례

Geo를 구현하면 다음과 같은 이점을 얻을 수 있습니다:

• 분산된 개발자가 대규모 저장소 및 프로젝트를 복제하고 가져오는 데 걸리는 시간을 분에서 초 단위로 줄입니다.
• 어디에서나 모든 개발자가 아이디어를 기여하고 병렬로 작업할 수 있도록 합니다.
• 기본 및 보조 사이트 간의 읽기 부하를 균형 있게 분산시킵니다.

또한 다음을 수행합니다:

• 제한 사항을 참조하여 GitLab 웹 인터페이스에서 사용 가능한 데이터를 읽는 것 외에도 프로젝트를 복제하고 가져오는 데 사용할 수 있습니다.
• 먼 사무실 간의 느린 연결을 극복하여 분산된 팀의 속도를 개선하여 시간을 절약합니다.
• 자동화된 작업, 사용자 지정 통합 및 내부 워크플로우의 로딩 시간을 줄이는 데 도움이 됩니다.
• 재해 복구 시나리오에서 보조 사이트로 빠르게 장애 조치를 수행할 수 있습니다.
• 보조 사이트로의 계획된 장애 조치를 허용합니다.

Geo는 다음을 제공합니다:

• 보조 사이트에서 완전한 GitLab 경험: 기본 프라이머리 GitLab 사이트를 유지하면서 각각의 분산된 팀에 대해 보조 사이트에 대한 완전한 읽기 및 쓰기 및 UI 경험을 제공합니다.
• 인증 시스템 후크: 보조 사이트는 모든 인증 데이터(사용자 계정 및 로그인과 같은)를 프라이머리 인스턴스로부터 수신합니다.

Gitaly 클러스터

Geo는 Gitaly 클러스터와 혼동되어서는 안 됩니다. Geo와 Gitaly 클러스터의 차이에 대한 자세한 내용은 Geo와 비교를 참조하십시오.

작동 방식

이것은 GitLab 환경에서 Geo가 작동하는 간략한 요약입니다. 자세한 정보는 Geo 개발 페이지를 참조하십시오.

Geo 인스턴스는 대규모 저장소를 사용하는 데 필요한 프로젝트 복제 및 가져오기 외에도 모든 데이터를 읽는 데 사용할 수 있습니다. 이를 통해 멀리 떨어진 거리에 있는 대규모 저장소 작업을 빠르게 처리할 수 있습니다.

Geo 활성화 시:

• 원본 인스턴스는 기본 사이트로 알려집니다.
• 복제하는 사이트는 보조 사이트로 알려집니다.

기억해야 할 중요한 사항:

• 보조 사이트는 기본 사이트에게 다음 작업을 수행합니다:
  • 로그인을 위한 사용자 데이터(API)
  • 저장소, LFS 오브젝트 및 첨부 파일을 복제(HTTPS + JWT)
• 기본 사이트는 동기화 세부 정보를 보기 위해 보조 사이트와 통신합니다. 형상 및 확인 데이터에 대해 기본이 보조 사이트에 대해 GraphQL 쿼리를 수행합니다(API).
• 보조 사이트로 직접 푸시할 수 있습니다(HTTP 및 SSH 모두에 대해, Git LFS포함) 및 이는 기본 사이트로 요청을 프록시화합니다.
• Geo 사용시 제한 사항이 있습니다.

아키텍처

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

이 다이어그램에서:

• 기본 사이트와 보조 사이트 중 하나의 세부 정보가 표시됩니다.
• 데이터베이스에 대한 기록은 기본 사이트에서만 수행할 수 있습니다. 보조 사이트는 PostgreSQL 스트리밍 복제를 사용하여 데이터베이스 업데이트를 받습니다.
• LDAP 서버가 존재하는 경우 재해 복구 시나리오에 대비하도록 구성되어 있어야합니다.
• 보조 사이트는 JWT로 보호된 특수 인증을 사용하여 기본 사이트에 대해 다른 유형의 동기화를 수행합니다:
  • 저장소는 HTTPS를 통해 복제/업데이트됩니다.
  • 첨부 파일, LFS 오브젝트 및 기타 파일은 비공개 API 엔드포인트를 사용하여 HTTPS를 통해 다운로드됩니다.

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

• 기본 사이트는 완전한 읽기-쓰기 GitLab 인스턴스처럼 작동합니다.
• 보조 사이트는 완전한 읽기-쓰기 GitLab 인스턴스처럼 작동합니다. 보조 사이트는 일부 주목할만한 예외 사항으로 전체 작업을 기본 사이트로 프록시화합니다. 특히, Git 가져오기는 보조 사이트가 최신 상태일 때 제공됩니다.

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

• 기본 사이트는 완전한 읽기-쓰기 GitLab 인스턴스처럼 작동합니다.
• 보조 사이트는 완전한 읽기-쓰기 GitLab 인스턴스처럼 작동합니다. 보조 사이트는 일부 주목할만한 예외 사항으로 전체 작업을 기본 사이트로 프록시화합니다. 특히, 웹 UI 자산은 보조 사이트로부터 제공됩니다.

다이어그램을 간소화하기 위해 일부 필요한 컴포넌트가 생략되었습니다.

• SSH를 통한 Git은 gitlab-shell이 필요합니다.
• HTTPS를 통한 Git은 gitlab-workhorse가 필요합니다.

보조 사이트는 다음 두 가지 PostgreSQL 데이터베이스가 필요합니다:

• 주된 GitLab 데이터베이스에서 데이터를 스트리밍하는 읽기 전용 데이터베이스 인스턴스.
• 보조 사이트 내부에서 사용하는 읽기/쓰기 데이터베이스(트래킹 데이터베이스).

보조 사이트는 별도의 데몬도 실행합니다: Geo Log Cursor.

Geo 실행에 필요한 요구 사항

다음은 Geo를 실행하는 데 필요한 사항입니다.

• 매우 빠른 SSH 키 데이터베이스 조회 기능을 위한 OpenSSH 6.9 이상을 지원하는 운영 체제(필요함) 현재 OpenSSH의 최신 버전을 탑재한 알려진 운영 체제는 다음과 같습니다.
  • CentOS 7.4 이상
  • Ubuntu 16.04 이상
• 가능한 경우 모든 Geo 사이트에서 동일한 운영 체제 버전을 사용해야 합니다. Geo 사이트 간에 다른 운영 체제 버전을 사용하는 경우 데이터베이스 인덱스의 무음 수정을 피하기 위해 Geo 사이트 간의 OS 지역 데이터 호환성을 확인해야 합니다.
• 지원되는 PostgreSQL 버전은 GitLab 릴리스에 대해 스트리밍 복제를 할 수 있어야 합니다.
  • PostgreSQL 논리 복제는 지원되지 않습니다.
• 모든 사이트는 동일한 PostgreSQL 버전을 실행해야 합니다.
• Git 2.9 이상
• LFS를 사용하는 경우 사용자 측에서는 Git-lfs 2.4.2 이상이어야 합니다.
• 모든 사이트는 정확히 동일한 GitLab 버전을 실행해야 합니다. 주 버전, 부 버전, 패치 버전이 모두 일치해야 합니다.
• 모든 사이트는 동일한 저장소 저장소를 정의해야 합니다.

또한, 더 나은 경험을 위해 GitLab의 최소 요구 사항을 확인하고 최신 버전을 사용하세요.

방화벽 규칙

다음 표는 Geo를 위해 기본 포트를 열어야 하는 주 사이트와 보조 사이트 사이의 포트를 나열합니다. 장애 조치 과정을 단순화하기 위해 양쪽 방향으로 포트를 열어야 합니다.

출발지 사이트	출발지 포트	목적지 사이트	목적지 포트	프로토콜
주 사이트	아무거나	보조 사이트	80	TCP (HTTP)
주 사이트	아무거나	보조 사이트	443	TCP (HTTPS)
보조 사이트	아무거나	주 사이트	80	TCP (HTTP)
보조 사이트	아무거나	주 사이트	443	TCP (HTTPS)
보조 사이트	아무거나	주 사이트	5432	TCP

GitLab에서 사용하는 포트 전체 목록은 패키지 기본값을 참고하세요.

참고: 웹 터미널 지원을 위해서는 로드 밸런서가 WebSocket 연결을 올바르게 처리해야 합니다. HTTP 또는 HTTPS 프록시를 사용하는 경우 로드 밸런서는 Connection 및 Upgrade hop-by-hop 헤더를 통과시키도록 구성되어야 합니다. 자세한 내용은 웹 터미널 통합 가이드를 참고하세요.

참고: 포트 443에 HTTPS 프로토콜을 사용하는 경우 로드 밸런서에 SSL 인증서를 추가해야 합니다. 외부/내부 URL에 대해 HTTPS만 사용하는 경우 방화벽에서 포트 80을 열 필요가 없습니다.

내부 URL

보조 Geo 사이트에서 주 Geo 사이트로의 HTTP 요청은 주 Geo 사이트의 내부 URL을 사용합니다. 주 Geo 사이트 설정에 명시적으로 정의되지 않은 경우 주 사이트의 공개 URL이 사용됩니다.

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

1. 왼쪽 사이드 바에서 관리자를 선택합니다.
2. Geo > 사이트를 선택합니다.
3. 주 사이트에서 편집을 선택합니다.
4. 내부 URL을 변경한 다음 변경사항 저장을 선택합니다.

Geo 추적 데이터베이스

추적 데이터베이스 인스턴스는 로컬 인스턴스에서 업데이트해야 할 메타데이터로 사용됩니다. 예를 들어 다음과 같은 작업을 수행합니다.

• 새 자산 다운로드
• 새 LFS 오브젝트 검색
• 최근에 업데이트된 저장소에서 변경 사항 검색

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

Geo 로그 커서

이 데몬은 다음을 수행합니다.

• 주 사이트에서 보조 데이터베이스 인스턴스로 복제된 이벤트 로그를 읽습니다.
• 변경을 해당 예비 공간 데이터베이스 인스턴스에 업데이트합니다.

추적 데이터베이스 인스턴스에서 업데이트할 항목이 표시되면 보조 사이트에서 비동기 작업이 실행되어 필요한 작업을 수행하고 상태를 업데이트합니다.

이러한 새 아키텍처를 사용하면 사이트 간 연결 문제에 강하게 대처할 수 있습니다. 보조 사이트가 주 사이트에서 얼마 동안 끊겨 있더라도 모든 이벤트를 올바른 순서대로 다시 재생하고 다시 주 사이트와 동기화할 수 있습니다.

제한 사항

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

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

복제된 데이터 유형

모든 GitLab 데이터 유형 및 복제된 데이터 유형의 완전한 목록을 참조하세요.

설치 후 문서

보조 사이트에 GitLab을 설치한 후 초기 구성을 수행한 경우, 설치 후 정보를 확인하려면 다음 문서를 참조하세요.

Geo 설정

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

객체 스토리지로 Geo 구성

객체 스토리지로 Geo를 구성하는 방법에 대한 정보는 객체 스토리지로 Geo를 참조하세요.

컨테이너 레지스트리 복제

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

Geo 사이트를 위한 통합 URL 설정

AWS Route53 또는 Google Cloud DNS로 단일한 위치 인식 URL을 설정하는 예제는 Geo 사이트를 위한 통합 URL 설정을 참조하세요.

단일 로그인 (SSO)

단일 로그인 (SSO)을 구성하는 자세한 내용은 단일 로그인 (SSO)로 Geo를 참조하세요.

LDAP

LDAP를 구성하는 자세한 내용은 단일 로그인 (SSO)로 Geo > LDAP를 참조하세요.

Geo 조정

Geo 조정에 대한 자세한 정보는 Geo 조정을 참조하세요.

복제 일시 중지 및 재개

자세한 정보는 복제 일시 중지 및 재개를 참조하세요.

백필

보조 사이트가 설정되면 기본 사이트에서 알려진 백필 프로세스를 통해 기본 사이트의 누락된 데이터를 복제하기 시작합니다. 브라우저에서 기본 사이트의 Geo 노드 대시보드에서 각 Geo 사이트의 동기화 프로세스를 모니터링할 수 있습니다.

백필 중 발생하는 실패는 백필 종료 시 재시도 예정입니다.

러너

• 런너 플리트를 배포하는 기본적인 모범 사례 외에, 러너는 작업 부하를 분산하기 위해 Geo 보조에 연결하도록 구성할 수 있습니다. 보조에 러너 등록하는 방법을 확인하세요.
• 러너 재해 복구 처리 방법도 참조하세요.

Geo 업그레이드

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

보안 검토

Geo 보안에 대한 자세한 정보는 Geo 보안 검토를 참조하세요.

Geo 사이트 제거

Geo 사이트를 제거하는 방법에 대한 자세한 정보는 보조 Geo 사이트 제거를 참조하세요.

Geo 비활성화

Geo를 비활성화하는 방법은 Geo 비활성화를 참조하세요.

로그 파일

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

Geo 로그에 액세스하고 소비하는 방법에 대한 자세한 정보는 로그 시스템 문서의 Geo 섹션을 참조하세요.

재해 복구

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

자주 묻는 질문

일반적인 질문에 대한 답변은 Geo FAQ를 참조하세요.

문제 해결

• Geo 문제 해결 단계에 대한 자세한 내용은 Geo 문제 해결을 참조하세요.
• 재해 복구 문제 해결 단계에 대한 자세한 내용은 재해 복구 문제 해결을 참조하세요.