다음 가이드는 두 개의 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 노드가 데이터베이스에 접근할 수 있도록 Network 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 트래픽을 처리하는 기본 사이트 노드(보통 주 GitLab Rails 애플리케이션 노드) 중 하나에 root로 접근할 수 있는 경우:

     # 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 Sites 대시보드를 통해 각 Geo 사이트의 동기화 과정을 모니터링할 수 있습니다.

추적 데이터베이스 구성#

보조 사이트는 복제 상태를 추적하고 발생할 수 있는 복제 문제에서 자동으로 복구하기 위해 별도의 PostgreSQL 설치를 추적 데이터베이스로 사용합니다. Linux 패키지는 roles ['geo_secondary_role']이 설정되면 추적 데이터베이스를 자동으로 구성합니다. 이 데이터베이스를 Linux 패키지 설치 환경 외부에서 실행하려면 다음 안내를 따릅니다.

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

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

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

설치와 업그레이드 과정에서 확장을 설치하려면 추가 역할이 필요합니다. 대안으로 필요한 확장을 수동으로 설치할 수 있습니다.

추적 데이터베이스 생성#

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
   

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

앞에 나열된 단계의 reconfigure 명령이 이 작업을 자동으로 처리합니다. 다음 단계는 문제가 발생한 경우를 위해 제공합니다.

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

   sudo gitlab-rake db:create:geo
   

2. 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 문제 해결을 참고합니다.