보조 사이트를 구성하는 기본 단계는 다음과 같습니다:

1. 기본 사이트와 보조 사이트 사이에 필요한 구성을 복제합니다.
2. 각 보조 사이트에 추적 데이터베이스를 구성합니다.
3. 각 보조 사이트에서 GitLab을 시작합니다.

이 문서는 첫 번째 항목을 다룹니다. 테스트나 프로덕션 환경에서 실행하기 전에 모든 단계를 먼저 끝까지 읽어 보기를 권장합니다.

기본 사이트와 보조 사이트 양쪽의 사전 요구 사항:

• 데이터베이스 복제 설정
• 인가된 SSH 키의 빠른 조회 구성

1단계. GitLab 시크릿 값 수동 복제#

GitLab은 여러 시크릿 값을 /etc/gitlab/gitlab-secrets.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
   

2단계. 기본 사이트의 SSH 호스트 키 수동 복제#

GitLab은 시스템에 설치된 SSH 데몬과 통합되며, 모든 접근 요청을 처리하는 사용자(일반적으로 git)를 지정합니다.

재해 복구 상황에서는 GitLab 시스템 관리자가 보조 사이트를 기본 사이트로 승격합니다. 기본 도메인의 DNS 레코드도 새 기본 사이트 (이전의 보조 사이트)를 가리키도록 업데이트해야 합니다. 이렇게 하면 Git 원격과 API URL을 변경하지 않아도 됩니다.

이 과정에서 SSH 호스트 키가 일치하지 않아 새로 승격된 기본 사이트로 향하는 모든 SSH 요청이 실패합니다. 이를 방지하려면 기본 사이트의 SSH 호스트 키를 보조 사이트에 수동으로 복제해야 합니다.

SSH 호스트 키 경로는 사용하는 소프트웨어에 따라 다릅니다:

• OpenSSH를 사용한다면 경로는 /etc/ssh입니다.
• gitlab-sshd를 사용한다면 경로는 /var/opt/gitlab/gitlab-sshd입니다.

다음 단계에서 <ssh_host_key_path>를 사용 중인 경로로 바꿉니다:

1. 보조 사이트의 각 Rails 노드에 SSH로 접속해 root 사용자로 로그인합니다:

   sudo -i
   

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

   find <ssh_host_key_path> -iname 'ssh_host_*' -exec cp {} {}.backup.`date +%F` \;
   

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

   root 사용자로 기본 사이트에서 SSH 트래픽을 처리하는 노드(보통 주 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>:<ssh_host_key_path>/ssh_host_*_key* <ssh_host_key_path>
   

   sudo 권한이 있는 사용자로만 접근할 수 있다면:

   # Run this from the node on your primary site:
   sudo tar --transform 's/.*\///g' -zcvf ~/geo-host-key.tar.gz <ssh_host_key_path>/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 <ssh_host_key_path>
   

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

   chown root:root <ssh_host_key_path>/ssh_host_*_key*
   chmod 0600 <ssh_host_key_path>/ssh_host_*_key
   

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

   for file in <ssh_host_key_path>/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 <ssh_host_key_path>/ssh_host_*_key; do ssh-keygen -lf $file; done
   
   # This will print the fingerprint for public keys:
   for file in <ssh_host_key_path>/ssh_host_*_key.pub; do ssh-keygen -lf $file; done
   

   [!note] 개인 키 명령과 공개 키 명령의 출력은 같은 지문을 생성해야 합니다.

7. 보조 사이트의 각 Rails 노드에서 OpenSSH의 sshd 또는 gitlab-sshd 서비스를 재시작합니다:

   • OpenSSH의 경우:

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

   • gitlab-sshd의 경우:

     sudo gitlab-ctl restart gitlab-sshd
     

8. SSH가 여전히 정상 동작하는지 확인합니다.

   새 터미널에서 GitLab 보조 서버에 SSH로 접속합니다. 접속할 수 없다면 앞 단계에 따라 권한이 올바른지 확인합니다.

3단계. 보조 사이트 추가#

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'] = '<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로 접속해 서비스를 재시작합니다:

   gitlab-ctl restart
   

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

   gitlab-rake gitlab:geo:check
   

   검사 중 하나라도 실패하면 문제 해결 문서를 확인합니다.

6. 기본 사이트의 Rails 또는 Sidekiq 서버에 SSH로 접속해 root로 로그인한 뒤, 보조 사이트에 연결할 수 있는지와 Geo 설정에 일반적인 문제가 있는지 확인합니다:

   gitlab-rake gitlab:geo:check
   

   검사 중 하나라도 실패하면 문제 해결 문서를 확인합니다.

보조 사이트를 Geo 관리 페이지에 추가하고 재시작하면, 해당 사이트는 기본 사이트에서 누락된 데이터를 자동으로 복제하기 시작합니다. 이 과정을 백필이라고 합니다. 한편 기본 사이트는 변경이 발생할 때마다 각 보조 사이트에 알리기 시작하며, 보조 사이트는 그 알림에 즉시 대응할 수 있습니다.

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

기본 및 보조 URL을 허용된 ActionCable 원본으로 추가#

이 단계를 수행하면 기본 사이트와 보조 사이트에서 웹소켓이 문제없이 동작합니다.

1. 사이트(기본과 보조)의 외부 URL을 수집합니다. 앞 절에서 설명한 대로 Admin 영역의 Site 페이지에서 확인할 수 있습니다.

2. 기본 사이트의 각 Rails 및 Sidekiq 노드에 SSH로 접속해 root로 로그인합니다:

   sudo -i
   

3. /etc/gitlab/gitlab.rb를 편집해 1단계에서 수집한 URL을 action_cable_allowed_origins 설정에 추가합니다:

   gitlab_rails['action_cable_allowed_origins'] = ['https://secondary.example.com', 'https://primary.example.com']
   

4. 변경 사항을 적용하려면 각 Rails 및 Sidekiq 노드를 재구성하고 서비스를 재시작합니다:

   gitlab-ctl reconfigure
   gitlab-ctl restart
   

4단계. (선택 사항) 사용자 지정 인증서 사용#

다음에 해당한다면 이 단계를 건너뛰어도 됩니다:

• 기본 사이트가 공용 CA가 발급한 HTTPS 인증서를 사용합니다.
• 기본 사이트가 CA 발급(자체 서명이 아닌) HTTPS 인증서를 사용하는 외부 서비스에만 연결합니다.

인바운드 연결용 사용자 지정 또는 자체 서명 인증서#

GitLab Geo 기본 사이트가 인바운드 HTTPS 연결을 보호하는 사용자 지정 또는 자체 서명 인증서를 사용한다면, 이 인증서는 단일 도메인 인증서일 수도 있고 다중 도메인 인증서일 수도 있습니다.

인증서 유형에 맞는 인증서를 설치합니다:

• 기본 사이트와 보조 사이트 도메인을 모두 포함하는 다중 도메인 인증서: 보조 사이트의 모든 Rails, Sidekiq, Gitaly 노드에서 /etc/gitlab/ssl에 인증서를 설치합니다.
• Geo 사이트 도메인마다 인증서가 다른 단일 도메인 인증서: 보조 사이트 도메인에 유효한 인증서를 생성하고, 이 지침에 따라 보조 사이트의 모든 Rails, Sidekiq, Gitaly 노드에서 /etc/gitlab/ssl에 설치합니다.

사용자 지정 인증서를 사용하는 외부 서비스 연결#

외부 서비스의 자체 서명 인증서 사본을, 해당 서비스에 접근해야 하는 기본 사이트의 모든 노드 트러스트 스토어에 추가해야 합니다.

보조 사이트도 같은 외부 서비스에 접근할 수 있으려면 이 인증서를 보조 사이트의 트러스트 스토어에도 추가해야 합니다.

기본 사이트가 인바운드 HTTPS 연결용 사용자 지정 또는 자체 서명 인증서를 사용한다면, 기본 사이트의 인증서를 보조 사이트의 트러스트 스토어에 추가해야 합니다:

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

   sudo -i
   

2. 기본 사이트에서 신뢰할 수 있는 인증서를 복사합니다:

   root 사용자로 기본 사이트에서 SSH 트래픽을 처리하는 노드 중 하나에 접근할 수 있다면:

   scp root@<primary_site_node_fqdn>:/etc/gitlab/trusted-certs/* /etc/gitlab/trusted-certs
   

   sudo 권한이 있는 사용자로만 접근할 수 있다면:

   # Run this from the node on your primary site:
   sudo tar --transform 's/.*\///g' -zcvf ~/geo-trusted-certs.tar.gz /etc/gitlab/trusted-certs/*
   
   # Run this on each node on your secondary site:
   scp <user_with_sudo>@<primary_site_node_fqdn>:geo-trusted-certs.tar.gz .
   tar zxvf ~/geo-trusted-certs.tar.gz -C /etc/gitlab/trusted-certs
   

3. 보조 사이트에서 업데이트한 각 Rails, Sidekiq, Gitaly 노드를 재구성합니다:

   sudo gitlab-ctl reconfigure
   

5단계. 보조 사이트의 정상 동작 확인#

기본 사이트에서 사용한 자격 증명과 동일한 자격 증명으로 보조 사이트에 로그인할 수 있습니다. 로그인한 뒤에는 다음을 수행합니다:

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

초기 복제에는 시간이 걸릴 수 있습니다. 사이트 상태나 '백필'이 아직 진행 중일 수 있습니다. 각 Geo 사이트의 동기화 진행 상황은 브라우저에서 기본 사이트의 Geo Sites 대시보드로 모니터링할 수 있습니다.

설치가 정상적으로 동작하지 않으면 문제 해결 문서를 확인합니다.

대시보드에서 드러날 수 있는 가장 뚜렷한 문제 두 가지는 다음과 같습니다:

1. 데이터베이스 복제가 원활하지 않습니다.
2. 인스턴스 간 알림이 동작하지 않습니다. 이 경우 원인은 다음 중 하나일 수 있습니다:
   • 사용자 지정 인증서나 사용자 지정 CA를 사용하고 있습니다(문제 해결 문서 참고).
   • 인스턴스가 방화벽에 막혀 있습니다(방화벽 규칙을 확인합니다).

보조 사이트를 비활성화하면 동기화 프로세스가 중지됩니다.

기본 사이트에서 여러 리포지터리 샤드에 대해 리포지터리 스토리지를 사용자 지정했다면 각 보조 사이트에도 동일한 구성을 그대로 적용해야 합니다.

사용자에게는 Geo 사이트 사용 가이드를 안내합니다.

현재 동기화되는 항목은 다음과 같습니다:

• Git 리포지터리.
• 위키.
• LFS 객체.
• 이슈, 머지 리퀘스트, 스니펫, 댓글 첨부 파일.
• 사용자, 그룹, 프로젝트 아바타.

문제 해결#

문제 해결 문서를 참고합니다.