두 단일 노드 사이트를 위한 Geo 설정 (외부 PostgreSQL 서비스 포함)

요약

- Offering: GitLab Self-Managed 다음 가이드는 두 개의 Linux 패키지 인스턴스와 RDS, Azure Database, Google Cloud SQL 같은 외부 PostgreSQL 데이터베이스를 사용하는 두 단일 노드 사이트 설치 환경에서 GitLab Geo를 배포하는 방법을 간결하게 설명합니다.

두 개의 단일 노드 사이트에 Geo 설정하기 (외부 PostgreSQL 서비스 사용)#

  - 
  Tier: Premium, Ultimate

- Offering: GitLab Self-Managed

다음 가이드는 두 개의 Linux 패키지 인스턴스와 RDS, Azure Database, Google Cloud SQL 같은 외부 PostgreSQL 데이터베이스를 사용하는 두 단일 노드 사이트 설치 환경에서 GitLab Geo를 배포하는 방법을 간결하게 설명합니다.

사전 요구 사항:

독립적으로 작동하는 GitLab 사이트가 최소 두 개 있어야 합니다. 사이트 생성 방법은 GitLab 참조 아키텍처 문서를 참조하세요.

하나의 GitLab 사이트가 **Geo 기본 사이트(primary site)**로 사용됩니다. 각 Geo 사이트에 서로 다른 참조 아키텍처 크기를 사용할 수 있습니다. 이미 작동 중인 GitLab 인스턴스가 있다면 이를 기본 사이트로 사용할 수 있습니다.

두 번째 GitLab 사이트는 **Geo 보조 사이트(secondary site)**로 사용됩니다. Geo는 여러 보조 사이트를 지원합니다.
Geo 기본 사이트에는 최소 GitLab Premium 라이선스가 필요합니다. 모든 사이트에 하나의 라이선스만 있으면 됩니다.
모든 사이트가 Geo 실행 요구 사항을 충족하는지 확인하세요.

Linux 패키지(Omnibus)에서 Geo 설정하기#

사전 요구 사항:

pg_basebackup 도구가 포함된 PostgreSQL 12 이상을 사용해야 합니다.

기본 사이트 구성하기#

GitLab 기본 사이트에 SSH로 접속하여 root로 로그인합니다:

sudo -i

/etc/gitlab/gitlab.rb에 고유한 Geo 사이트 이름을 추가합니다:

##
## The unique identifier for the Geo site. See
## https://docs.gitlab.com/administration/geo_sites/#common-settings
##
gitlab_rails['geo_node_name'] = '<site_name_here>'

변경 사항을 적용하려면 기본 사이트를 재구성합니다:

gitlab-ctl reconfigure

사이트를 Geo 기본 사이트로 정의합니다:

gitlab-ctl set-geo-primary-node

이 명령은 /etc/gitlab/gitlab.rb에 정의된 external_url을 사용합니다.

구성 예시는 외부 PostgreSQL을 사용하는 기본 사이트 완성 예시를 참조하세요.

복제할 외부 데이터베이스 구성하기#

외부 데이터베이스를 설정하려면 다음 중 하나를 선택하세요:

직접 스트리밍 복제를 설정합니다(예: Amazon RDS 또는 Linux 패키지로 관리되지 않는 베어 메탈 서버).
다음과 같이 Linux 패키지 설치의 구성을 수동으로 수행합니다.

클라우드 공급자의 도구를 활용하여 기본 데이터베이스 복제하기#

RDS를 사용하는 AWS EC2에 기본 사이트가 설정되어 있다고 가정합니다. 이 경우 다른 리전에 읽기 전용 복제본을 생성하기만 하면 되며, 복제 프로세스는 AWS가 관리합니다. 보조 Rails 노드가 데이터베이스에 접근할 수 있도록 Network ACL(액세스 제어 목록), 서브넷 및 보안 그룹을 필요에 맞게 설정했는지 확인하세요.

다음 지침에서는 주요 클라우드 공급자에서 읽기 전용 복제본을 생성하는 방법을 설명합니다:

Amazon RDS - 읽기 복제본 생성(Creating a Read Replica)
Azure Database for PostgreSQL - Azure Database for PostgreSQL에서 읽기 복제본 생성 및 관리(Create and manage read replicas in Azure Database for PostgreSQL)
Google Cloud SQL - 읽기 복제본 생성(Creating read replicas)

읽기 전용 복제본 설정이 완료되면 보조 사이트 구성하기로 건너뛸 수 있습니다.

외부 읽기 복제본을 사용하도록 보조 사이트 구성하기#

Linux 패키지 설치에서 geo_secondary_role은 세 가지 주요 기능을 수행합니다:

복제본 데이터베이스를 구성합니다.
추적 데이터베이스를 구성합니다.
Geo 로그 커서(Geo Log Cursor)를 활성화합니다.

외부 읽기 복제본 데이터베이스에 대한 연결을 구성하려면:

보조 사이트의 각 Rails, Sidekiq 및 Geo 로그 커서 노드에 SSH로 접속하여 root로 로그인합니다:

sudo -i

/etc/gitlab/gitlab.rb를 편집하고 다음 내용을 추가합니다

##
## Geo Secondary role
## - configure dependent flags automatically to enable Geo
##
roles ['geo_secondary_role']

# note this is shared between both databases,
# make sure you define the same password in both
gitlab_rails['db_password'] = '<your_db_password_here>'

gitlab_rails['db_username'] = 'gitlab'
gitlab_rails['db_host'] = '<database_read_replica_host>'

# Disable the bundled Omnibus PostgreSQL because we are
# using an external PostgreSQL
postgresql['enable'] = false

외부 PostgreSQL을 사용하는 보조 사이트 완성 예시에서 구성 예시를 복사합니다. 변경 사항을 적용하려면 파일을 저장하고 GitLab을 재구성합니다:

gitlab-ctl reconfigure

복제본 데이터베이스에 연결 문제가 발생하는 경우, 다음 명령으로 서버에서 TCP 연결을 확인하세요:

gitlab-rake gitlab:tcp_check[<replica FQDN>,5432]

이 단계가 실패하면 잘못된 IP 주소를 사용하고 있거나 방화벽이 사이트 접근을 차단하고 있을 수 있습니다. IP 주소를 확인하고, 특히 공인 주소와 사설 주소의 차이에 주의하세요. 방화벽이 있는 경우 보조 사이트가 포트 5432를 통해 기본 사이트에 연결할 수 있도록 허용되어 있는지 확인하세요.

GitLab 비밀값 수동 복제하기#

GitLab은 여러 비밀값을 /etc/gitlab/gitlab-secrets.json에 저장합니다. 이 JSON 파일은 각 사이트 노드에서 동일해야 합니다. 이슈 3789에서 이 동작 변경을 제안하고 있지만, 현재는 모든 보조 사이트에 비밀 파일을 수동으로 복제해야 합니다.

기본 사이트의 Rails 노드에 SSH로 접속하여 다음 명령을 실행합니다:

sudo cat /etc/gitlab/gitlab-secrets.json

이 명령을 실행하면 복제해야 하는 비밀값이 JSON 형식으로 출력됩니다.

보조 Geo 사이트의 각 노드에 SSH로 접속하여 root로 로그인합니다:

sudo -i

기존 비밀값을 백업합니다:

mv /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.`date +%F`

기본 사이트 Rails 노드에서 각 보조 사이트 노드로 /etc/gitlab/gitlab-secrets.json을 복사합니다. 노드 간에 파일 내용을 복사하여 붙여넣기 할 수도 있습니다:

sudo editor /etc/gitlab/gitlab-secrets.json

# paste the output of the `cat` command you ran on the primary
# save and exit

파일 권한이 올바른지 확인합니다:

chown root:root /etc/gitlab/gitlab-secrets.json
chmod 0600 /etc/gitlab/gitlab-secrets.json

변경 사항을 적용하려면 모든 Rails, Sidekiq 및 Gitaly 보조 사이트 노드를 재구성합니다:

gitlab-ctl reconfigure
gitlab-ctl restart

기본 사이트 SSH 호스트 키 수동 복제하기#

보조 사이트의 각 노드에 SSH로 접속하여 root로 로그인합니다:

sudo -i

기존 SSH 호스트 키를 백업합니다:

find /etc/ssh -iname 'ssh_host_*' -exec cp {} {}.backup.`date +%F` \;

기본 사이트에서 OpenSSH 호스트 키를 복사합니다.

SSH 트래픽을 처리하는 기본 사이트 노드 중 하나에 root로 접근할 수 있는 경우(일반적으로 주 GitLab Rails 애플리케이션 노드):

# Run this from the secondary site, change `<primary_site_fqdn>` for the IP or FQDN of the server
scp root@<primary_node_fqdn>:/etc/ssh/ssh_host_*_key* /etc/ssh

sudo 권한이 있는 사용자를 통해서만 접근할 수 있는 경우:

# Run this from the node on your primary site:
sudo tar --transform 's/.*\///g' -zcvf ~/geo-host-key.tar.gz /etc/ssh/ssh_host_*_key*

# Run this on each node on your secondary site:
scp <user_with_sudo>@<primary_site_fqdn>:geo-host-key.tar.gz .
tar zxvf ~/geo-host-key.tar.gz -C /etc/ssh

각 보조 사이트 노드에서 파일 권한이 올바른지 확인합니다:

chown root:root /etc/ssh/ssh_host_*_key*
chmod 0600 /etc/ssh/ssh_host_*_key

키 지문이 일치하는지 확인하려면 각 사이트의 기본 노드와 보조 노드 모두에서 다음 명령을 실행합니다:

for file in /etc/ssh/ssh_host_*_key; do ssh-keygen -lf $file; done

다음과 유사한 출력이 표시됩니다:

1024 SHA256:FEZX2jQa2bcsd/fn/uxBzxhKdx4Imc4raXrHwsbtP0M root@serverhostname (DSA)
256 SHA256:uw98R35Uf+fYEQ/UnJD9Br4NXUFPv7JAUln5uHlgSeY root@serverhostname (ECDSA)
256 SHA256:sqOUWcraZQKd89y/QQv/iynPTOGQxcOTIXU/LsoPmnM root@serverhostname (ED25519)
2048 SHA256:qwa+rgir2Oy86QI+PZi/QVR+MSmrdrpsuH7YyKknC+s root@serverhostname (RSA)

출력 결과는 두 노드에서 동일해야 합니다.

기존 개인 키에 대한 올바른 공개 키가 있는지 확인합니다:

# This will print the fingerprint for private keys:
for file in /etc/ssh/ssh_host_*_key; do ssh-keygen -lf $file; done

# This will print the fingerprint for public keys:
for file in /etc/ssh/ssh_host_*_key.pub; do ssh-keygen -lf $file; done

공개 키와 개인 키 명령어의 출력 결과는 동일한 지문(fingerprint)을 생성해야 합니다.

각 보조 사이트 노드에서 sshd를 재시작합니다:

# Debian or Ubuntu installations
sudo service ssh reload

# CentOS installations
sudo service sshd reload

SSH가 정상적으로 작동하는지 확인하려면, 새 터미널에서 GitLab 보조 서버로 SSH 접속합니다. 연결할 수 없는 경우 올바른 권한이 있는지 확인하세요.

인증된 SSH 키 빠른 조회#

초기 복제 프로세스가 완료되면 다음 단계에 따라 인증된 SSH 키 빠른 조회를 구성합니다.

빠른 조회는 Geo에 필요합니다.

인증은 기본 사이트에서 처리합니다. 보조 사이트에 대한 사용자 정의 인증을 설정하지 마세요.

Admin 영역에 대한 액세스가 필요한 변경 사항은 기본 사이트에서 수행해야 합니다. 보조 사이트는 읽기 전용 복사본이기 때문입니다.

보조 사이트 추가#

보조 사이트의 각 Rails 및 Sidekiq 노드에 SSH로 접속하여 root로 로그인합니다:

sudo -i

/etc/gitlab/gitlab.rb를 편집하여 사이트의 고유한 이름을 추가합니다.

##
## The unique identifier for the Geo site. See
## https://docs.gitlab.com/administration/geo_sites/#common-settings
##
gitlab_rails['geo_node_name'] = '<secondary_site_name_here>'

다음 단계를 위해 고유한 이름을 저장해 두세요.

변경 사항을 적용하려면 보조 사이트의 각 Rails 및 Sidekiq 노드를 재구성합니다.

gitlab-ctl reconfigure

기본 노드 GitLab 인스턴스로 이동합니다:

오른쪽 상단에서 Admin을 선택합니다.

Geo > Sites를 선택합니다.

Add site를 선택합니다.

[

](/19.2/administration/geo/setup/img/adding_a_secondary_v15_8.png)

Name에 /etc/gitlab/gitlab.rb의 gitlab_rails['geo_node_name'] 값을 입력합니다. 값이 정확히 일치해야 합니다.

External URL에 /etc/gitlab/gitlab.rb의 external_url 값을 입력합니다. 한쪽 값이 /로 끝나고 다른 쪽이 그렇지 않아도 괜찮습니다. 그 외의 경우 값이 정확히 일치해야 합니다.

선택 사항. **Internal URL (optional)**에 기본 사이트의 내부 URL을 입력합니다.

선택 사항. 보조 사이트에서 복제할 그룹 또는 스토리지 샤드를 선택합니다. 모두 복제하려면 필드를 비워 두세요. 선택적 동기화를 참조하세요.

Save changes를 선택합니다.

보조 사이트의 각 Rails 및 Sidekiq 노드에 SSH로 접속하여 서비스를 재시작합니다:

sudo gitlab-ctl restart

다음 명령어를 실행하여 Geo 설정의 일반적인 문제를 확인합니다:

sudo gitlab-rake gitlab:geo:check

확인 항목 중 실패하는 항목이 있으면 트러블슈팅 문서를 참조하세요.

보조 사이트에 접근할 수 있는지 확인하려면, 기본 사이트의 Rails 또는 Sidekiq 서버에 SSH로 접속하여 다음 명령어를 실행합니다:

sudo gitlab-rake gitlab:geo:check

확인 항목 중 실패하는 항목이 있으면 트러블슈팅 문서를 확인하세요.

보조 사이트가 Geo 관리 페이지에 추가되고 재시작된 후, 해당 사이트는 백필(backfill)이라 불리는 프로세스를 통해 기본 사이트에서 누락된 데이터를 자동으로 복제하기 시작합니다.

한편, 기본 사이트는 각 보조 사이트에 변경 사항을 즉시 알리기 시작하므로 보조 사이트는 알림을 즉시 처리할 수 있습니다.

보조 사이트가 실행 중이며 접근 가능한지 확인하세요. 기본 사이트에서 사용한 것과 동일한 자격 증명으로 보조 사이트에 로그인할 수 있습니다.

HTTP/HTTPS 및 SSH를 통한 Git 액세스 활성화#

Geo는 HTTP/HTTPS를 통해 리포지터리를 동기화합니다(새 설치 시 기본적으로 활성화됨). 따라서 이 클론 방식이 활성화되어 있어야 합니다. 기존 사이트를 Geo로 전환하는 경우 클론 방식이 활성화되어 있는지 확인해야 합니다.

기본 사이트에서:

오른쪽 상단에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > General을 선택합니다.
Visibility and access controls를 확장합니다.
Git over SSH를 사용하는 경우:

Enabled Git access protocols를 **Both SSH and HTTP(S)**로 설정합니다.

기본 사이트와 보조 사이트 모두에서 데이터베이스의 인증된 SSH 키 빠른 조회를 활성화합니다.
Git over SSH를 사용하지 않는 경우, Enabled Git access protocols를 **Only HTTP(S)**로 설정합니다.

보조 사이트의 정상 작동 확인#

기본 사이트에서 사용한 것과 동일한 자격 증명으로 보조 사이트에 로그인할 수 있습니다.

로그인 후:

오른쪽 상단에서 Admin을 선택합니다.
왼쪽 사이드바에서 Geo > Sites를 선택합니다.
사이트가 보조 Geo 사이트로 올바르게 식별되었는지, 그리고 Geo가 활성화되어 있는지 확인합니다.

초기 복제에는 다소 시간이 걸릴 수 있습니다. 브라우저에서 기본 사이트의 Geo Sites 대시보드를 통해 각 Geo 사이트의 동기화 프로세스를 모니터링할 수 있습니다.

[

](/19.2/administration/geo/setup/img/geo_dashboard_v14_0.png)

추적 데이터베이스 구성#

이 단계는 추적 데이터베이스를 다른 서버의 외부에 설정하려는 경우에만 선택 사항입니다.

보조 사이트는 복제 상태를 추적하고 잠재적인 복제 문제에서 자동으로 복구하기 위해 별도의 PostgreSQL 설치를 추적 데이터베이스로 사용합니다. Linux 패키지는 roles ['geo_secondary_role']이 설정된 경우 추적 데이터베이스를 자동으로 구성합니다. 이 데이터베이스를 Linux 패키지 설치 외부에서 실행하려면 다음 지침을 따르세요.

클라우드 관리형 데이터베이스 서비스#

추적 데이터베이스에 클라우드 관리형 서비스를 사용하는 경우, 추적 데이터베이스 사용자(기본값: gitlab_geo)에게 추가 권한을 부여해야 할 수 있습니다:

Amazon RDS는 rds_superuser 권한이 필요합니다.
Azure Database for PostgreSQL은 azure_pg_admin 권한이 필요합니다.
Google Cloud SQL은 cloudsqlsuperuser 권한이 필요합니다.

설치 및 업그레이드 중 확장 기능 설치를 위해 추가 권한이 필요합니다. 대안으로 필요한 확장 기능을 수동으로 설치할 수 있습니다.

Amazon RDS를 추적 데이터베이스로 사용하려면 보조 데이터베이스에 액세스할 수 있는지 확인하세요. 안타깝게도 동일한 보안 그룹을 할당하는 것만으로는 충분하지 않습니다.

아웃바운드 규칙이 RDS PostgreSQL 데이터베이스에 적용되지 않기 때문입니다. 따라서 포트 5432에서 추적 데이터베이스의 모든 TCP 트래픽을 허용하는 인바운드 규칙을 읽기 복제본의 보안 그룹에 명시적으로 추가해야 합니다.

추적 데이터베이스 생성#

PostgreSQL 인스턴스에서 추적 데이터베이스를 생성하고 구성합니다:

데이터베이스 요구 사항 문서에 따라 PostgreSQL을 설정합니다.

원하는 비밀번호로 gitlab_geo 사용자를 설정하고, gitlabhq_geo_production 데이터베이스를 생성한 후 해당 사용자를 데이터베이스의 소유자로 지정합니다. 이 설정의 예시는 소스 컴파일 설치 문서에서 확인할 수 있습니다.

클라우드 관리형 PostgreSQL 데이터베이스를 사용하지 않는 경우, 추적 데이터베이스와 연결된 pg_hba.conf를 수동으로 변경하여 보조 사이트가 추적 데이터베이스와 통신할 수 있도록 합니다. 변경 사항을 적용하려면 이후 PostgreSQL을 재시작해야 합니다:

##
## Geo Tracking Database Role
## - pg_hba.conf
##
host    all         all               <trusted tracking IP>/32      md5
host    all         all               <trusted secondary IP>/32     md5

GitLab 구성#

이 데이터베이스를 사용하도록 GitLab을 구성합니다. 다음 단계는 Linux 패키지 및 Docker 배포에 해당합니다.

GitLab 보조 서버에 SSH로 접속하여 root로 로그인합니다:

sudo -i

PostgreSQL 인스턴스가 있는 머신의 연결 매개변수와 자격 증명으로 /etc/gitlab/gitlab.rb를 편집합니다:

geo_secondary['db_username'] = 'gitlab_geo'
geo_secondary['db_password'] = '<your_tracking_db_password_here>'

geo_secondary['db_host'] = '<tracking_database_host>'
geo_secondary['db_port'] = <tracking_database_port>      # change to the correct port
geo_postgresql['enable'] = false     # don't use internal managed instance

파일을 저장하고 GitLab을 재구성합니다:

gitlab-ctl reconfigure

데이터베이스 스키마 수동 설정 (선택 사항)#

이전에 나열된 단계의 reconfigure 명령어가 이 단계들을 자동으로 처리합니다. 다음 단계는 문제가 발생한 경우를 대비하여 제공됩니다.

이 태스크는 데이터베이스 스키마를 생성합니다. 데이터베이스 사용자가 슈퍼유저여야 합니다.

sudo gitlab-rake db:create:geo

Rails 데이터베이스 마이그레이션(스키마 및 데이터 업데이트) 적용도 reconfigure 시 수행됩니다. geo_secondary['auto_migrate'] = false가 설정되어 있거나 스키마가 수동으로 생성된 경우 이 단계가 필요합니다:

sudo gitlab-rake db:migrate:geo

구성 예시#

외부 PostgreSQL을 사용하는 기본 사이트 전체 구성#

다음은 외부 PostgreSQL을 사용하는 Geo 기본 사이트에 대한 gitlab.rb 구성 전체 예시입니다:

# Primary site with external PostgreSQL configuration example

## Geo Primary role
roles(['geo_primary_role'])

## The unique identifier for the Geo site
gitlab_rails['geo_node_name'] = 'headquarters'

## External URL
external_url 'https://gitlab.example.com'

## External PostgreSQL configuration
postgresql['enable'] = false
gitlab_rails['db_adapter'] = 'postgresql'
gitlab_rails['db_encoding'] = 'unicode'
gitlab_rails['db_host'] = 'primary-postgres.example.com'
gitlab_rails['db_port'] = 5432
gitlab_rails['db_database'] = 'gitlabhq_production'
gitlab_rails['db_username'] = 'gitlab'
gitlab_rails['db_password'] = 'your_database_password_here'

## SSL/TLS configuration
nginx['listen_port'] = 80
nginx['listen_https'] = false
letsencrypt['enable'] = false

## Object Storage configuration (recommended for external services)
gitlab_rails['object_store']['enabled'] = true
gitlab_rails['object_store']['connection'] = {
  'provider' => 'AWS',
  'region' => 'us-east-1',
  'aws_access_key_id' => 'your_access_key',
  'aws_secret_access_key' => 'your_secret_key'
}

## Monitoring configuration
node_exporter['listen_address'] = '0.0.0.0:9100'
gitlab_workhorse['prometheus_listen_addr'] = '0.0.0.0:9229'

외부 PostgreSQL을 사용하는 보조 사이트 전체 구성#

다음은 외부 PostgreSQL을 사용하는 Geo 보조 사이트에 대한 gitlab.rb 구성 전체 예시입니다:

# Secondary site with external PostgreSQL configuration example

## Geo Secondary role
roles(['geo_secondary_role'])

## The unique identifier for the Geo site
gitlab_rails['geo_node_name'] = 'location-2'

## External URL
external_url 'https://gitlab.example.com'

## External PostgreSQL configuration (read-only replica)
postgresql['enable'] = false
gitlab_rails['db_adapter'] = 'postgresql'
gitlab_rails['db_encoding'] = 'unicode'
gitlab_rails['db_host'] = 'secondary-postgres.example.com'
gitlab_rails['db_port'] = 5432
gitlab_rails['db_database'] = 'gitlabhq_production'
gitlab_rails['db_username'] = 'gitlab'
gitlab_rails['db_password'] = 'your_database_password_here'

## Geo tracking database configuration
geo_secondary['db_username'] = 'gitlab_geo'
geo_secondary['db_password'] = 'your_tracking_db_password_here'
geo_secondary['db_host'] = 'secondary-tracking-db.example.com'
geo_secondary['db_port'] = 5432
geo_postgresql['enable'] = false

## SSL/TLS configuration
nginx['listen_port'] = 80
nginx['listen_https'] = false
letsencrypt['enable'] = false

## Object Storage configuration (must match primary)
gitlab_rails['object_store']['enabled'] = true
gitlab_rails['object_store']['connection'] = {
  'provider' => 'AWS',
  'region' => 'us-east-1',
  'aws_access_key_id' => 'your_access_key',
  'aws_secret_access_key' => 'your_secret_key'
}

## Monitoring configuration
node_exporter['listen_address'] = '0.0.0.0:9100'
gitlab_workhorse['prometheus_listen_addr'] = '0.0.0.0:9229'

문제 해결#

Geo 문제 해결을 참조하세요.

두 단일 노드 사이트를 위한 Geo 설정 (외부 PostgreSQL 서비스 포함)

GitLab v19.2

원문 보기

번역일: 2026-06-19

요약

두 개의 단일 노드 사이트에 Geo 설정하기 (외부 PostgreSQL 서비스 사용)#

  - 
  Tier: Premium, Ultimate

- Offering: GitLab Self-Managed

사전 요구 사항:

독립적으로 작동하는 GitLab 사이트가 최소 두 개 있어야 합니다. 사이트 생성 방법은 GitLab 참조 아키텍처 문서를 참조하세요.

두 번째 GitLab 사이트는 **Geo 보조 사이트(secondary site)**로 사용됩니다. Geo는 여러 보조 사이트를 지원합니다.
Geo 기본 사이트에는 최소 GitLab Premium 라이선스가 필요합니다. 모든 사이트에 하나의 라이선스만 있으면 됩니다.
모든 사이트가 Geo 실행 요구 사항을 충족하는지 확인하세요.

Linux 패키지(Omnibus)에서 Geo 설정하기#

사전 요구 사항:

pg_basebackup 도구가 포함된 PostgreSQL 12 이상을 사용해야 합니다.

기본 사이트 구성하기#

GitLab 기본 사이트에 SSH로 접속하여 root로 로그인합니다:

sudo -i

/etc/gitlab/gitlab.rb에 고유한 Geo 사이트 이름을 추가합니다:

##
## The unique identifier for the Geo site. See
## https://docs.gitlab.com/administration/geo_sites/#common-settings
##
gitlab_rails['geo_node_name'] = '<site_name_here>'

변경 사항을 적용하려면 기본 사이트를 재구성합니다:

gitlab-ctl reconfigure

사이트를 Geo 기본 사이트로 정의합니다:

gitlab-ctl set-geo-primary-node

이 명령은 /etc/gitlab/gitlab.rb에 정의된 external_url을 사용합니다.

구성 예시는 외부 PostgreSQL을 사용하는 기본 사이트 완성 예시를 참조하세요.

복제할 외부 데이터베이스 구성하기#

외부 데이터베이스를 설정하려면 다음 중 하나를 선택하세요:

직접 스트리밍 복제를 설정합니다(예: Amazon RDS 또는 Linux 패키지로 관리되지 않는 베어 메탈 서버).
다음과 같이 Linux 패키지 설치의 구성을 수동으로 수행합니다.

클라우드 공급자의 도구를 활용하여 기본 데이터베이스 복제하기#

다음 지침에서는 주요 클라우드 공급자에서 읽기 전용 복제본을 생성하는 방법을 설명합니다:

Amazon RDS - 읽기 복제본 생성(Creating a Read Replica)
Azure Database for PostgreSQL - Azure Database for PostgreSQL에서 읽기 복제본 생성 및 관리(Create and manage read replicas in Azure Database for PostgreSQL)
Google Cloud SQL - 읽기 복제본 생성(Creating read replicas)

읽기 전용 복제본 설정이 완료되면 보조 사이트 구성하기로 건너뛸 수 있습니다.

외부 읽기 복제본을 사용하도록 보조 사이트 구성하기#

Linux 패키지 설치에서 geo_secondary_role은 세 가지 주요 기능을 수행합니다:

복제본 데이터베이스를 구성합니다.
추적 데이터베이스를 구성합니다.
Geo 로그 커서(Geo Log Cursor)를 활성화합니다.

외부 읽기 복제본 데이터베이스에 대한 연결을 구성하려면:

보조 사이트의 각 Rails, Sidekiq 및 Geo 로그 커서 노드에 SSH로 접속하여 root로 로그인합니다:

sudo -i

/etc/gitlab/gitlab.rb를 편집하고 다음 내용을 추가합니다

##
## Geo Secondary role
## - configure dependent flags automatically to enable Geo
##
roles ['geo_secondary_role']

# note this is shared between both databases,
# make sure you define the same password in both
gitlab_rails['db_password'] = '<your_db_password_here>'

gitlab_rails['db_username'] = 'gitlab'
gitlab_rails['db_host'] = '<database_read_replica_host>'

# Disable the bundled Omnibus PostgreSQL because we are
# using an external PostgreSQL
postgresql['enable'] = false

외부 PostgreSQL을 사용하는 보조 사이트 완성 예시에서 구성 예시를 복사합니다. 변경 사항을 적용하려면 파일을 저장하고 GitLab을 재구성합니다:

gitlab-ctl reconfigure

복제본 데이터베이스에 연결 문제가 발생하는 경우, 다음 명령으로 서버에서 TCP 연결을 확인하세요:

gitlab-rake gitlab:tcp_check[<replica FQDN>,5432]

GitLab 비밀값 수동 복제하기#

기본 사이트의 Rails 노드에 SSH로 접속하여 다음 명령을 실행합니다:

sudo cat /etc/gitlab/gitlab-secrets.json

이 명령을 실행하면 복제해야 하는 비밀값이 JSON 형식으로 출력됩니다.

보조 Geo 사이트의 각 노드에 SSH로 접속하여 root로 로그인합니다:

sudo -i

기존 비밀값을 백업합니다:

mv /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.`date +%F`

sudo editor /etc/gitlab/gitlab-secrets.json

# paste the output of the `cat` command you ran on the primary
# save and exit

파일 권한이 올바른지 확인합니다:

chown root:root /etc/gitlab/gitlab-secrets.json
chmod 0600 /etc/gitlab/gitlab-secrets.json

변경 사항을 적용하려면 모든 Rails, Sidekiq 및 Gitaly 보조 사이트 노드를 재구성합니다:

gitlab-ctl reconfigure
gitlab-ctl restart

기본 사이트 SSH 호스트 키 수동 복제하기#

보조 사이트의 각 노드에 SSH로 접속하여 root로 로그인합니다:

sudo -i

기존 SSH 호스트 키를 백업합니다:

find /etc/ssh -iname 'ssh_host_*' -exec cp {} {}.backup.`date +%F` \;

기본 사이트에서 OpenSSH 호스트 키를 복사합니다.

SSH 트래픽을 처리하는 기본 사이트 노드 중 하나에 root로 접근할 수 있는 경우(일반적으로 주 GitLab Rails 애플리케이션 노드):

# Run this from the secondary site, change `<primary_site_fqdn>` for the IP or FQDN of the server
scp root@<primary_node_fqdn>:/etc/ssh/ssh_host_*_key* /etc/ssh

sudo 권한이 있는 사용자를 통해서만 접근할 수 있는 경우:

# Run this from the node on your primary site:
sudo tar --transform 's/.*\///g' -zcvf ~/geo-host-key.tar.gz /etc/ssh/ssh_host_*_key*

# Run this on each node on your secondary site:
scp <user_with_sudo>@<primary_site_fqdn>:geo-host-key.tar.gz .
tar zxvf ~/geo-host-key.tar.gz -C /etc/ssh

각 보조 사이트 노드에서 파일 권한이 올바른지 확인합니다:

chown root:root /etc/ssh/ssh_host_*_key*
chmod 0600 /etc/ssh/ssh_host_*_key

키 지문이 일치하는지 확인하려면 각 사이트의 기본 노드와 보조 노드 모두에서 다음 명령을 실행합니다:

for file in /etc/ssh/ssh_host_*_key; do ssh-keygen -lf $file; done

다음과 유사한 출력이 표시됩니다:

1024 SHA256:FEZX2jQa2bcsd/fn/uxBzxhKdx4Imc4raXrHwsbtP0M root@serverhostname (DSA)
256 SHA256:uw98R35Uf+fYEQ/UnJD9Br4NXUFPv7JAUln5uHlgSeY root@serverhostname (ECDSA)
256 SHA256:sqOUWcraZQKd89y/QQv/iynPTOGQxcOTIXU/LsoPmnM root@serverhostname (ED25519)
2048 SHA256:qwa+rgir2Oy86QI+PZi/QVR+MSmrdrpsuH7YyKknC+s root@serverhostname (RSA)

출력 결과는 두 노드에서 동일해야 합니다.

기존 개인 키에 대한 올바른 공개 키가 있는지 확인합니다:

# This will print the fingerprint for private keys:
for file in /etc/ssh/ssh_host_*_key; do ssh-keygen -lf $file; done

# This will print the fingerprint for public keys:
for file in /etc/ssh/ssh_host_*_key.pub; do ssh-keygen -lf $file; done

공개 키와 개인 키 명령어의 출력 결과는 동일한 지문(fingerprint)을 생성해야 합니다.

각 보조 사이트 노드에서 sshd를 재시작합니다:

# Debian or Ubuntu installations
sudo service ssh reload

# CentOS installations
sudo service sshd reload

SSH가 정상적으로 작동하는지 확인하려면, 새 터미널에서 GitLab 보조 서버로 SSH 접속합니다. 연결할 수 없는 경우 올바른 권한이 있는지 확인하세요.

인증된 SSH 키 빠른 조회#

초기 복제 프로세스가 완료되면 다음 단계에 따라 인증된 SSH 키 빠른 조회를 구성합니다.

빠른 조회는 Geo에 필요합니다.

인증은 기본 사이트에서 처리합니다. 보조 사이트에 대한 사용자 정의 인증을 설정하지 마세요.

Admin 영역에 대한 액세스가 필요한 변경 사항은 기본 사이트에서 수행해야 합니다. 보조 사이트는 읽기 전용 복사본이기 때문입니다.

보조 사이트 추가#

보조 사이트의 각 Rails 및 Sidekiq 노드에 SSH로 접속하여 root로 로그인합니다:

sudo -i

/etc/gitlab/gitlab.rb를 편집하여 사이트의 고유한 이름을 추가합니다.

##
## The unique identifier for the Geo site. See
## https://docs.gitlab.com/administration/geo_sites/#common-settings
##
gitlab_rails['geo_node_name'] = '<secondary_site_name_here>'

다음 단계를 위해 고유한 이름을 저장해 두세요.

변경 사항을 적용하려면 보조 사이트의 각 Rails 및 Sidekiq 노드를 재구성합니다.

gitlab-ctl reconfigure

기본 노드 GitLab 인스턴스로 이동합니다:

오른쪽 상단에서 Admin을 선택합니다.

Geo > Sites를 선택합니다.

Add site를 선택합니다.

[

](/19.2/administration/geo/setup/img/adding_a_secondary_v15_8.png)

Name에 /etc/gitlab/gitlab.rb의 gitlab_rails['geo_node_name'] 값을 입력합니다. 값이 정확히 일치해야 합니다.

선택 사항. **Internal URL (optional)**에 기본 사이트의 내부 URL을 입력합니다.

선택 사항. 보조 사이트에서 복제할 그룹 또는 스토리지 샤드를 선택합니다. 모두 복제하려면 필드를 비워 두세요. 선택적 동기화를 참조하세요.

Save changes를 선택합니다.

보조 사이트의 각 Rails 및 Sidekiq 노드에 SSH로 접속하여 서비스를 재시작합니다:

sudo gitlab-ctl restart

다음 명령어를 실행하여 Geo 설정의 일반적인 문제를 확인합니다:

sudo gitlab-rake gitlab:geo:check

확인 항목 중 실패하는 항목이 있으면 트러블슈팅 문서를 참조하세요.

보조 사이트에 접근할 수 있는지 확인하려면, 기본 사이트의 Rails 또는 Sidekiq 서버에 SSH로 접속하여 다음 명령어를 실행합니다:

sudo gitlab-rake gitlab:geo:check

확인 항목 중 실패하는 항목이 있으면 트러블슈팅 문서를 확인하세요.

한편, 기본 사이트는 각 보조 사이트에 변경 사항을 즉시 알리기 시작하므로 보조 사이트는 알림을 즉시 처리할 수 있습니다.

보조 사이트가 실행 중이며 접근 가능한지 확인하세요. 기본 사이트에서 사용한 것과 동일한 자격 증명으로 보조 사이트에 로그인할 수 있습니다.

HTTP/HTTPS 및 SSH를 통한 Git 액세스 활성화#

기본 사이트에서:

오른쪽 상단에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > General을 선택합니다.
Visibility and access controls를 확장합니다.
Git over SSH를 사용하는 경우:

Enabled Git access protocols를 **Both SSH and HTTP(S)**로 설정합니다.

기본 사이트와 보조 사이트 모두에서 데이터베이스의 인증된 SSH 키 빠른 조회를 활성화합니다.
Git over SSH를 사용하지 않는 경우, Enabled Git access protocols를 **Only HTTP(S)**로 설정합니다.

보조 사이트의 정상 작동 확인#

기본 사이트에서 사용한 것과 동일한 자격 증명으로 보조 사이트에 로그인할 수 있습니다.

로그인 후:

오른쪽 상단에서 Admin을 선택합니다.
왼쪽 사이드바에서 Geo > Sites를 선택합니다.
사이트가 보조 Geo 사이트로 올바르게 식별되었는지, 그리고 Geo가 활성화되어 있는지 확인합니다.

[

](/19.2/administration/geo/setup/img/geo_dashboard_v14_0.png)

추적 데이터베이스 구성#

이 단계는 추적 데이터베이스를 다른 서버의 외부에 설정하려는 경우에만 선택 사항입니다.

클라우드 관리형 데이터베이스 서비스#

Amazon RDS는 rds_superuser 권한이 필요합니다.
Azure Database for PostgreSQL은 azure_pg_admin 권한이 필요합니다.
Google Cloud SQL은 cloudsqlsuperuser 권한이 필요합니다.

설치 및 업그레이드 중 확장 기능 설치를 위해 추가 권한이 필요합니다. 대안으로 필요한 확장 기능을 수동으로 설치할 수 있습니다.

Amazon RDS를 추적 데이터베이스로 사용하려면 보조 데이터베이스에 액세스할 수 있는지 확인하세요. 안타깝게도 동일한 보안 그룹을 할당하는 것만으로는 충분하지 않습니다.

추적 데이터베이스 생성#

PostgreSQL 인스턴스에서 추적 데이터베이스를 생성하고 구성합니다:

데이터베이스 요구 사항 문서에 따라 PostgreSQL을 설정합니다.

##
## Geo Tracking Database Role
## - pg_hba.conf
##
host    all         all               <trusted tracking IP>/32      md5
host    all         all               <trusted secondary IP>/32     md5

GitLab 구성#

이 데이터베이스를 사용하도록 GitLab을 구성합니다. 다음 단계는 Linux 패키지 및 Docker 배포에 해당합니다.

GitLab 보조 서버에 SSH로 접속하여 root로 로그인합니다:

sudo -i

PostgreSQL 인스턴스가 있는 머신의 연결 매개변수와 자격 증명으로 /etc/gitlab/gitlab.rb를 편집합니다:

geo_secondary['db_username'] = 'gitlab_geo'
geo_secondary['db_password'] = '<your_tracking_db_password_here>'

geo_secondary['db_host'] = '<tracking_database_host>'
geo_secondary['db_port'] = <tracking_database_port>      # change to the correct port
geo_postgresql['enable'] = false     # don't use internal managed instance

파일을 저장하고 GitLab을 재구성합니다:

gitlab-ctl reconfigure

데이터베이스 스키마 수동 설정 (선택 사항)#

이전에 나열된 단계의 reconfigure 명령어가 이 단계들을 자동으로 처리합니다. 다음 단계는 문제가 발생한 경우를 대비하여 제공됩니다.

이 태스크는 데이터베이스 스키마를 생성합니다. 데이터베이스 사용자가 슈퍼유저여야 합니다.

sudo gitlab-rake db:create:geo

sudo gitlab-rake db:migrate:geo

구성 예시#

외부 PostgreSQL을 사용하는 기본 사이트 전체 구성#

다음은 외부 PostgreSQL을 사용하는 Geo 기본 사이트에 대한 gitlab.rb 구성 전체 예시입니다:

# Primary site with external PostgreSQL configuration example

## Geo Primary role
roles(['geo_primary_role'])

## The unique identifier for the Geo site
gitlab_rails['geo_node_name'] = 'headquarters'

## External URL
external_url 'https://gitlab.example.com'

## External PostgreSQL configuration
postgresql['enable'] = false
gitlab_rails['db_adapter'] = 'postgresql'
gitlab_rails['db_encoding'] = 'unicode'
gitlab_rails['db_host'] = 'primary-postgres.example.com'
gitlab_rails['db_port'] = 5432
gitlab_rails['db_database'] = 'gitlabhq_production'
gitlab_rails['db_username'] = 'gitlab'
gitlab_rails['db_password'] = 'your_database_password_here'

## SSL/TLS configuration
nginx['listen_port'] = 80
nginx['listen_https'] = false
letsencrypt['enable'] = false

## Object Storage configuration (recommended for external services)
gitlab_rails['object_store']['enabled'] = true
gitlab_rails['object_store']['connection'] = {
  'provider' => 'AWS',
  'region' => 'us-east-1',
  'aws_access_key_id' => 'your_access_key',
  'aws_secret_access_key' => 'your_secret_key'
}

## Monitoring configuration
node_exporter['listen_address'] = '0.0.0.0:9100'
gitlab_workhorse['prometheus_listen_addr'] = '0.0.0.0:9229'

외부 PostgreSQL을 사용하는 보조 사이트 전체 구성#

다음은 외부 PostgreSQL을 사용하는 Geo 보조 사이트에 대한 gitlab.rb 구성 전체 예시입니다:

# Secondary site with external PostgreSQL configuration example

## Geo Secondary role
roles(['geo_secondary_role'])

## The unique identifier for the Geo site
gitlab_rails['geo_node_name'] = 'location-2'

## External URL
external_url 'https://gitlab.example.com'

## External PostgreSQL configuration (read-only replica)
postgresql['enable'] = false
gitlab_rails['db_adapter'] = 'postgresql'
gitlab_rails['db_encoding'] = 'unicode'
gitlab_rails['db_host'] = 'secondary-postgres.example.com'
gitlab_rails['db_port'] = 5432
gitlab_rails['db_database'] = 'gitlabhq_production'
gitlab_rails['db_username'] = 'gitlab'
gitlab_rails['db_password'] = 'your_database_password_here'

## Geo tracking database configuration
geo_secondary['db_username'] = 'gitlab_geo'
geo_secondary['db_password'] = 'your_tracking_db_password_here'
geo_secondary['db_host'] = 'secondary-tracking-db.example.com'
geo_secondary['db_port'] = 5432
geo_postgresql['enable'] = false

## SSL/TLS configuration
nginx['listen_port'] = 80
nginx['listen_https'] = false
letsencrypt['enable'] = false

## Object Storage configuration (must match primary)
gitlab_rails['object_store']['enabled'] = true
gitlab_rails['object_store']['connection'] = {
  'provider' => 'AWS',
  'region' => 'us-east-1',
  'aws_access_key_id' => 'your_access_key',
  'aws_secret_access_key' => 'your_secret_key'
}

## Monitoring configuration
node_exporter['listen_address'] = '0.0.0.0:9100'
gitlab_workhorse['prometheus_listen_addr'] = '0.0.0.0:9229'

문제 해결#

Geo 문제 해결을 참조하세요.