• Linux 패키지(Omnibus)에 대한 Geo 설정
  • 기본 사이트 구성
  • 외부 데이터베이스를 복제하도록 구성
    • 클라우드 제공업체의 도구를 이용하여 기본 데이터베이스 복제
  • 외부 읽기 복제본을 사용하도록 보조 사이트 구성
    • GitLab 비밀 값을 수동으로 복제
    • 기본 사이트 SSH 호스트 키 수동 복제
    • 승인된 SSH 키의 빠른 조회
    • 보조 사이트 추가
    • HTTP/HTTPS 및 SSH를 통한 Git 접근 활성화
    • 보조 사이트의 정상 작동 확인
• 추적 데이터베이스 구성
  • 클라우드 관리 데이터베이스 서비스
  • 추적 데이터베이스 생성
  • GitLab 구성
    • 데이터베이스 스키마 수동 설정 (선택 사항)
• 문제 해결

두 개의 단일 노드 사이트(외부 PostgreSQL 서비스 포함)에 대한 Geo 설정

Offering: Self-managed

다음 가이드는 두 개의 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 설정

사전 요구 사항:

• PostgreSQL 12 이상을 사용해야 하며,
  pg_basebackup 도구가 포함되어 있어야 합니다.

기본 사이트 구성

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

   sudo -i
   

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

   ##
   ## Geo 사이트의 고유 식별자. 
   ## https://docs.gitlab.com/ee/administration/geo_sites.html#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을 사용합니다.

외부 데이터베이스를 복제하도록 구성

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

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

클라우드 제공업체의 도구를 이용하여 기본 데이터베이스 복제

AWS EC2에 설정된 기본 사이트가 RDS를 사용하는 경우를 가정합니다.
이제 다른 지역에 읽기 전용 복제본을 생성하면 됩니다.
복제 프로세스는 AWS에 의해 관리되므로, 보조 Rails 노드가 데이터베이스에 접근할 수 있도록 네트워크 ACL(Access Control List), 서브넷 및 보안 그룹을 필요에 맞게 설정했는지 확인하세요.

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

• Amazon RDS - 읽기 복제본 생성
• Azure Database for PostgreSQL - Azure Database for PostgreSQL에서 읽기 복제본 만들고 관리하기
• Google Cloud SQL - 읽기 복제본 만들기

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

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

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

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

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

1. SSH를 통해 각 Rails, Sidekiq, Geo Log Cursor 노드에 접속하여 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, since we are
   # using an external PostgreSQL
   postgresql['enable'] = false
   

3. 파일을 저장하고 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
   
   # 기본에서 실행한 `cat` 명령의 출력을 붙여넣기
   # 저장하고 종료
   

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 애플리케이션의 주요 노드):

     # 보조 사이트에서 실행, `<primary_site_fqdn>`을 서버의 IP 또는 FQDN으로 변경
     scp root@<primary_node_fqdn>:/etc/ssh/ssh_host_*_key* /etc/ssh
     

   • sudo 권한이 있는 사용자로만 접근할 수 있는 경우:

     # 기본 사이트의 노드에서 실행:
     sudo tar --transform 's/.*\///g' -zcvf ~/geo-host-key.tar.gz /etc/ssh/ssh_host_*_key*
     
     # 보조 사이트의 각 노드에서 실행:
     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. 기존 개인 키에 대한 올바른 공개 키가 있는지 확인합니다:

   # 개인 키에 대한 지문을 인쇄합니다:
   for file in /etc/ssh/ssh_host_*_key; do ssh-keygen -lf $file; done
   
   # 공개 키에 대한 지문을 인쇄합니다:
   for file in /etc/ssh/ssh_host_*_key.pub; do ssh-keygen -lf $file; done
   

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

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

   # Debian 또는 Ubuntu 설치
   sudo service ssh reload
   
   # CentOS 설치
   sudo service sshd reload
   

8. SSH가 여전히 기능하는지 확인하려면 새로운 터미널에서 GitLab 보조 서버에 SSH로 접속합니다.

   연결할 수 없는 경우, 올바른 권한이 있는지 확인하세요.

승인된 SSH 키의 빠른 조회

초기 복제 프로세스가 완료되면, 승인된 SSH 키의 빠른 조회를 구성하는 방법을 따르십시오.

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

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

보조 사이트 추가

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

   sudo -i
   

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

   ##
   ## Geo 사이트에 대한 고유 식별자. 자세한 내용은
   ## https://docs.gitlab.com/ee/administration/geo_sites.html#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. SSH를 통해 보조 사이트의 각 Rails 및 Sidekiq 노드에 접속하고 서비스를 재시작합니다:

   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>      # 올바른 포트로 변경
   geo_postgresql['enable'] = false     # 내부 관리 인스턴스 사용 안 함
   

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

   gitlab-ctl reconfigure
   

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

위 구성 GitLab 단계에서 재구성이 이 단계를 자동으로 처리합니다. 문제가 발생한 경우를 대비해 이 단계를 제공합니다.

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

   sudo gitlab-rake db:create:geo
   

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

   sudo gitlab-rake db:migrate:geo
   

문제 해결

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