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

사전 요구사항:

• 독립적으로 작동하는 GitLab 사이트가 최소 두 개 있어야 합니다. 사이트를 생성하려면 GitLab 참조 아키텍처 문서를 참조하세요.
  • 하나의 GitLab 사이트는 Geo 기본 사이트로 사용됩니다. 각 Geo 사이트에 다른 참조 아키텍처 크기를 사용할 수 있습니다. 이미 작동하는 GitLab 인스턴스가 있다면 기본 사이트로 사용할 수 있습니다.
  • 두 번째 GitLab 사이트는 Geo 보조 사이트로 사용됩니다. Geo는 여러 보조 사이트를 지원합니다.
• Geo 기본 사이트에는 최소한 GitLab Premium 라이선스가 있어야 합니다. 모든 사이트에 라이선스 하나만 필요합니다.
• 모든 사이트가 Geo 실행 요구사항을 충족하는지 확인합니다.

Linux 패키지(Omnibus)용 Geo 설정#

사전 요구사항:

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

기본 사이트 구성#

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

   sudo -i
   

2. /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>'
   

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

   gitlab-ctl reconfigure
   

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

   gitlab-ctl set-geo-primary-node
   

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

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

복제될 외부 데이터베이스 구성#

외부 데이터베이스를 설정하려면 다음 중 하나를 수행합니다:

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

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

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

다음 지침은 일반 클라우드 공급자의 읽기 전용 복제본을 생성하는 방법을 자세히 설명합니다:

• Amazon RDS - 읽기 전용 복제본 생성
• Azure Database for PostgreSQL - Azure Database for PostgreSQL에서 읽기 전용 복제본 생성 및 관리
• Google Cloud SQL - 읽기 전용 복제본 생성

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

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

Linux 패키지 설치의 경우 geo_secondary_role에는 세 가지 주요 기능이 있습니다:

1. 복제본 데이터베이스를 구성합니다.
2. 추적 데이터베이스를 구성합니다.
3. Geo Log Cursor를 활성화합니다.

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

1. 보조 사이트의 각 Rails, Sidekiq 및 Geo Log Cursor 노드에 SSH로 접속하고 root로 로그인합니다:

   sudo -i
   

2. /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
   

3. 외부 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에서 이 동작을 변경하도록 제안되어 있지만 현재는 모든 보조 사이트에서 비밀 파일을 수동으로 복제해야 합니다.

1. 기본 사이트의 Rails 노드에 SSH로 접속하고 아래 명령을 실행합니다:

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

   JSON 형식으로 복제해야 하는 비밀이 표시됩니다.

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

   sudo -i
   

3. 기존 비밀을 백업합니다:

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

4. 기본 사이트 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
   

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

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

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

   gitlab-ctl reconfigure
   gitlab-ctl restart
   

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

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

   sudo -i
   

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

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

3. 기본 사이트에서 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
     

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

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

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

   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)
   

   두 노드에서 출력이 동일해야 합니다.

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

   # 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
   

   공개 키와 개인 키 명령의 출력은 동일한 지문을 생성해야 합니다.

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

   # Debian or Ubuntu installations
   sudo service ssh reload
   
   # CentOS installations
   sudo service sshd reload
   

8. SSH가 여전히 작동하는지 확인하려면 새 터미널에서 GitLab 보조 서버에 SSH로 접속합니다. 연결할 수 없는 경우 올바른 권한이 있는지 확인합니다.

승인된 SSH 키의 빠른 조회#

초기 복제 프로세스가 완료된 후 승인된 SSH 키의 빠른 조회 구성 단계를 따르세요.

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

보조 사이트 추가#

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

   sudo -i
   

2. /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>'
   

   다음 단계를 위해 고유한 이름을 저장합니다.

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

   gitlab-ctl reconfigure
   

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

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

   2. Geo > Sites를 선택합니다.

   3. Add site를 선택합니다.

      

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

   5. External URL에서 /etc/gitlab/gitlab.rb의 external_url 값을 입력합니다. 하나의 값이 /로 끝나고 다른 값이 그렇지 않아도 됩니다. 그렇지 않으면 값이 정확히 일치해야 합니다.

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

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

   8. Save changes를 선택합니다.

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

   sudo gitlab-ctl restart
   

6. 다음을 실행하여 Geo 설정에 일반적인 문제가 있는지 확인합니다:

   sudo gitlab-rake gitlab:geo:check
   

   점검이 실패하면 문제 해결 문서를 참조하세요.

7. 보조 사이트에 도달할 수 있는지 확인하려면 기본 사이트의 Rails 또는 Sidekiq 서버에 SSH로 접속하고 실행합니다:

   sudo gitlab-rake gitlab:geo:check
   

   점검이 실패하면 문제 해결 문서를 확인합니다.

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

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

보조 사이트가 실행 중이고 액세스 가능한지 확인합니다. 기본 사이트에 사용된 것과 동일한 자격 증명으로 보조 사이트에 로그인할 수 있습니다.

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

Geo는 HTTP/HTTPS(새 설치의 경우 기본적으로 활성화됨)를 통해 리포지토리를 동기화하므로 이 클론 방법이 활성화되어 있어야 합니다. 기존 사이트를 Geo로 변환하는 경우 클론 방법이 활성화되어 있는지 확인해야 합니다.

기본 사이트에서:

1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Visibility and access controls를 확장합니다.
4. SSH를 통해 Git을 사용하는 경우:
   1. Enabled Git access protocols이 **Both SSH and HTTP(S)**로 설정되어 있는지 확인합니다.
   2. 기본 및 보조 사이트 모두에서 데이터베이스에서 승인된 SSH 키의 빠른 조회를 활성화합니다.
5. SSH를 통해 Git을 사용하지 않는 경우 Enabled Git access protocols를 **Only HTTP(S)**로 설정합니다.

보조 사이트의 올바른 기능 확인#

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

로그인 후:

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

초기 복제에는 시간이 걸릴 수 있습니다. 기본 사이트에서 각 Geo 사이트의 동기화 프로세스를 모니터링할 수 있습니다.

브라우저에서 기본 사이트의 Geo Sites 대시보드를 통해 확인합니다.

추적 데이터베이스 구성#

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

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

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

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

설치 및 업그레이드 중 확장 설치를 위해 추가 역할이 필요합니다. 대안으로 확장이 수동으로 설치되어 있는지 확인하고 향후 GitLab 업그레이드 중에 발생할 수 있는 문제에 대해 읽으세요.

추적 데이터베이스 생성#

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

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

2. 원하는 비밀번호로 gitlab_geo 사용자를 설정하고 gitlabhq_geo_production 데이터베이스를 생성하고 사용자를 데이터베이스의 소유자로 만듭니다. 이 설정의 예시는 소스에서 설치 문서에서 확인할 수 있습니다.

3. 클라우드 관리 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 배포용입니다.

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

   sudo -i
   

2. 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
   

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

   gitlab-ctl reconfigure
   

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

이전에 나열된 단계의 재구성 명령이 이러한 단계를 자동으로 처리합니다. 이러한 단계는 무언가 잘못된 경우를 위해 제공됩니다.

1. 이 작업은 데이터베이스 스키마를 생성합니다. 데이터베이스 사용자가 슈퍼유저여야 합니다.

   sudo gitlab-rake db:create:geo
   

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

   sudo gitlab-rake db:migrate:geo
   

구성 예시#

외부 PostgreSQL이 있는 완전한 기본 사이트#

이 완전한 gitlab.rb 구성 예시는 외부 PostgreSQL을 사용하는 Geo 기본 사이트를 위한 것입니다:

# 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이 있는 완전한 보조 사이트#

이 완전한 gitlab.rb 구성 예시는 외부 PostgreSQL을 사용하는 Geo 보조 사이트를 위한 것입니다:

# 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 문제 해결을 참조하세요.