InfoGrab DocsInfoGrab Docs

두 단일 노드 사이트를 위한 Geo 설정

요약

다음 가이드는 외부 서비스를 설정하지 않은 두 개의 Linux 패키지 인스턴스를 사용하여 두 단일 노드 사이트 설치에 GitLab Geo를 배포하는 방법을 간결하게 안내합니다. 아래에 언급된 설정을 GitLab 컨테이너의 /etc/gitlab/gitlab.rb 파일에 직접 적용하거나, Docker Compose 파일의 GITLAB_OMNIBUS_CONFIG 환경 변수에 추가합니다.

다음 가이드는 외부 서비스를 설정하지 않은 두 개의 Linux 패키지 인스턴스를 사용하여 두 단일 노드 사이트 설치에 GitLab Geo를 배포하는 방법을 간결하게 안내합니다. 이 가이드는 Docker 기반 설치에도 적용됩니다.

사전 요구 사항:

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

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

사전 요구 사항:

기본 사이트 구성#

Note

Docker 기반 설치의 경우:

아래에 언급된 설정을 GitLab 컨테이너의 /etc/gitlab/gitlab.rb 파일에 직접 적용하거나, Docker Compose 파일의 GITLAB_OMNIBUS_CONFIG 환경 변수에 추가합니다.

Docker Compose를 사용할 때는 구성 변경을 적용하기 위해 gitlab-ctl reconfigure 대신 docker-compose -f <docker-compose-file-name>.yml up을 사용합니다.

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

    sudo -i

  2. GitLab을 업그레이드할 때 의도하지 않은 다운타임이 발생하지 않도록 자동 PostgreSQL 업그레이드를 거부합니다. Geo 환경에서 PostgreSQL을 업그레이드할 때 알려진 주의 사항을 숙지합니다. 특히 대규모 환경에서는 PostgreSQL 업그레이드를 의식적으로 계획하고 실행해야 합니다. 따라서 앞으로 PostgreSQL 업그레이드가 정기 유지 관리 활동에 포함되도록 합니다.

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

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

    gitlab-ctl reconfigure

  5. 해당 사이트를 기본 Geo 사이트로 정의합니다:

    gitlab-ctl set-geo-primary-node

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

  6. 완전한 기본 사이트의 구성 예시를 복사합니다.

  7. gitlab 데이터베이스 사용자의 비밀번호를 생성하고 새 비밀번호를 사용하도록 Rails를 업데이트합니다.

    [!note] gitlab_rails['db_password'] 설정과 postgresql['sql_user_password'] 설정에 구성하는 값은 일치해야 합니다. 다만 MD5로 암호화된 비밀번호여야 하는 것은 postgresql['sql_user_password'] 값뿐입니다. 이에 대한 변경은 쿡북에서 PostgreSQL 비밀번호를 처리하는 방식 재검토에서 논의 중입니다.

    1. 원하는 비밀번호의 MD5 해시를 생성합니다:

      gitlab-ctl pg-password-md5 gitlab
# Enter password: <your_db_password_here>
# Confirm password: <your_db_password_here>
# fca0b89a972d69f00eb3ec98a5838484

    2. /etc/gitlab/gitlab.rb를 편집합니다:

      # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab`
postgresql['sql_user_password'] = '<md5_hash_of_your_db_password>'

# Every node that runs Puma or Sidekiq needs to have the database
# password specified as below. If you have a high-availability setup, this
# must be present in all application nodes.
gitlab_rails['db_password'] = '<your_db_password_here>'

  8. 데이터베이스 복제 사용자의 비밀번호를 정의합니다. /etc/gitlab/gitlab.rb의 postgresql['sql_replication_user'] 설정에 정의된 사용자 이름을 사용합니다. 기본값은 gitlab_replicator입니다.

    1. 원하는 비밀번호의 MD5 해시를 생성합니다:

      gitlab-ctl pg-password-md5 gitlab_replicator

# Enter password: <your_replication_password_here>
# Confirm password: <your_replication_password_here>
# 950233c0dfc2f39c64cf30457c3b7f1e

    2. /etc/gitlab/gitlab.rb를 편집합니다:

      # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab_replicator`
postgresql['sql_replication_password'] = '<md5_hash_of_your_replication_password>'

    3. 선택 사항. Linux 패키지가 관리하지 않는 외부 데이터베이스를 사용하는 경우 gitlab_replicator 사용자를 생성하고 그 사용자의 비밀번호를 직접 정의해야 합니다:

      --- Create a new user 'replicator'
CREATE USER gitlab_replicator;

--- Set/change a password and grants replication privilege
ALTER USER gitlab_replicator WITH REPLICATION ENCRYPTED PASSWORD '<replication_password>';

  9. /etc/gitlab/gitlab.rb에서 역할을 geo_primary_role로 설정합니다:

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

  10. 네트워크 인터페이스에서 수신하도록 PostgreSQL을 구성합니다:

    1. Geo 사이트의 주소를 조회하려면 Geo 사이트에 SSH로 접속해 다음을 실행합니다:

      ##
## Private address
##
ip route get 255.255.255.255 | awk '{for (i=1; i<=NF; i++) if ($i == "src") { print "Private address:", $(i+1); exit }}'

##
## Public address
##
echo "External address: $(curl --silent "ipinfo.io/ip")"

      대부분의 경우 GitLab Geo를 구성할 때 다음 주소를 사용합니다:

      구성 주소
      postgresql['listen_address'] 기본 사이트 공용 또는 VPC 프라이빗 주소.
      postgresql['md5_auth_cidr_addresses'] 기본 및 보조 사이트 공용 또는 VPC 프라이빗 주소.

      Google Cloud Platform, SoftLayer 또는 가상 사설 클라우드(VPC)를 제공하는 다른 공급업체를 사용하는 경우 postgresql['md5_auth_cidr_addresses']와 postgresql['listen_address']에 기본 및 보조 사이트의 프라이빗 주소(Google Cloud Platform에서는 "내부 주소"에 해당)를 사용할 수 있습니다.

      [!note] listen_address로 0.0.0.0 또는 *를 사용해야 하는 경우, Rails가 127.0.0.1을 통해 연결할 수 있도록 postgresql['md5_auth_cidr_addresses'] 설정에 127.0.0.1/32도 추가해야 합니다. 자세한 내용은 이슈 5258을 참고합니다.

      네트워크 구성에 따라 제안된 주소가 올바르지 않을 수 있습니다. 기본 사이트와 보조 사이트가 로컬 영역 네트워크로 연결되거나, 가용 영역을 연결하는 가상 네트워크 (Amazon VPC 또는 Google VPC)로 연결된다면 postgresql['md5_auth_cidr_addresses']에 보조 사이트의 프라이빗 주소를 사용해야 합니다.

    2. /etc/gitlab/gitlab.rb에 다음 줄을 추가합니다. IP 주소는 네트워크 구성에 맞는 주소로 반드시 교체합니다:

      ##
## Primary address
## - replace '<primary_node_ip>' with the public or VPC address of your Geo primary node
##
postgresql['listen_address'] = '<primary_site_ip>'

##
# Allow PostgreSQL client authentication from the primary and secondary IPs. These IPs may be
# public or VPC addresses in CIDR format, for example ['198.51.100.1/32', '198.51.100.2/32']
##
postgresql['md5_auth_cidr_addresses'] = ['<primary_site_ip>/32', '<secondary_site_ip>/32']

  11. PostgreSQL이 재시작되어 프라이빗 주소에서 수신할 때까지 자동 데이터베이스 마이그레이션을 일시적으로 비활성화합니다. /etc/gitlab/gitlab.rb에서 gitlab_rails['auto_migrate']를 false로 설정합니다:

    ## Disable automatic database migrations
gitlab_rails['auto_migrate'] = false

  12. 이 변경 사항을 적용하려면 GitLab을 재구성하고 PostgreSQL을 재시작합니다:

    gitlab-ctl reconfigure
gitlab-ctl restart postgresql

  13. 마이그레이션을 다시 활성화하려면 /etc/gitlab/gitlab.rb를 편집해 gitlab_rails['auto_migrate']를 true로 변경합니다:

    gitlab_rails['auto_migrate'] = true

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

    gitlab-ctl reconfigure

    PostgreSQL 서버가 원격 연결을 수락하도록 설정되었습니다.

  14. netstat -plnt | grep 5432를 실행해 PostgreSQL이 기본 사이트 프라이빗 주소의 5432 포트에서 수신하는지 확인합니다.

  15. GitLab을 재구성할 때 인증서가 자동으로 생성되었습니다. 이 인증서는 도청자로부터 PostgreSQL 트래픽을 보호하는 데 자동으로 사용됩니다. 능동적인("중간자") 공격자를 막으려면 인증서를 보조 사이트에 복사합니다:

    1. 기본 사이트에서 server.crt의 복사본을 만듭니다:

      cat ~gitlab-psql/data/server.crt

    2. 보조 사이트를 구성할 때 사용할 수 있도록 출력을 저장합니다. 인증서는 민감한 데이터가 아닙니다.

    인증서는 일반적인 PostgreSQL 공통 이름으로 생성됩니다. 호스트 이름 불일치 오류를 방지하려면 데이터베이스를 복제할 때 verify-ca 모드를 사용해야 합니다.

보조 서버 구성#

  1. GitLab 보조 사이트에 SSH로 접속해 root로 로그인합니다:

    sudo -i

  2. GitLab을 업그레이드할 때 의도하지 않은 다운타임이 발생하지 않도록 자동 PostgreSQL 업그레이드를 거부합니다. Geo 환경에서 PostgreSQL을 업그레이드할 때 알려진 주의 사항을 숙지합니다. 특히 대규모 환경에서는 PostgreSQL 업그레이드를 의식적으로 계획하고 실행해야 합니다. 따라서 앞으로 PostgreSQL 업그레이드가 정기 유지 관리 활동에 포함되도록 합니다.

  3. 사이트를 구성하기 전에 어떤 명령도 실행되지 않도록 애플리케이션 서버와 Sidekiq을 중지합니다:

    gitlab-ctl stop puma
gitlab-ctl stop sidekiq

  4. 기본 사이트 PostgreSQL 서버에 대한 TCP 연결을 확인합니다:

    gitlab-rake gitlab:tcp_check[<primary_site_ip>,5432]

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

  5. 보조 사이트에서 server.crt라는 파일을 생성하고 기본 사이트를 구성할 때 만든 인증서 복사본을 추가합니다.

    editor server.crt

  6. 보조 사이트에서 PostgreSQL TLS 검증을 설정하려면 gitlab-psql 사용자용으로 server.crt를 설치합니다:

    install \
   -D \
   -o gitlab-psql \
   -g gitlab-psql \
   -m 0400 \
   -T server.crt ~gitlab-psql/.postgresql/root.crt

    이제 PostgreSQL은 TLS 연결을 검증할 때 이 인증서만 인식합니다. 이 인증서는 기본 사이트에만 있는 개인 키에 접근할 수 있는 사람이 복제할 수 있습니다.

    gitlab-ctl replicate-geo-database는 root로 실행되므로 root 사용자용으로도 인증서를 설치합니다. 그렇지 않으면 sslmode=verify-ca 또는 sslmode=verify-full을 사용할 때 복제 명령이 could not open certificate file 오류와 함께 실패합니다:

    install \
   -D \
   -o root \
   -g root \
   -m 0400 \
   -T server.crt /root/.postgresql/root.crt

  7. gitlab-psql 사용자가 기본 사이트 데이터베이스에 연결할 수 있는지 테스트합니다. Linux 패키지의 기본 이름은 gitlabhq_production입니다:

   sudo \
       -u gitlab-psql /opt/gitlab/embedded/bin/psql \
       --list \
       -U gitlab_replicator \
       -d "dbname=gitlabhq_production sslmode=verify-ca" \
       -W \
       -h <primary_site_ip>

   docker exec -it <container_name> su - gitlab-psql -c '/opt/gitlab/embedded/bin/psql \
       --list \
       -U gitlab_replicator \
       -d "dbname=gitlabhq_production sslmode=verify-ca" \
       -W \
       -h <primary_site_ip>'

메시지가 표시되면 gitlab_replicator 사용자에 설정한 평문 비밀번호를 입력합니다. 모두 정상적으로 동작했다면 기본 사이트 데이터베이스 목록이 표시됩니다.

  1. /etc/gitlab/gitlab.rb를 편집해 역할을 geo_secondary_role로 설정합니다:

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

    자세한 내용은 Geo 역할을 참고합니다.

  2. PostgreSQL을 구성하려면 /etc/gitlab/gitlab.rb를 편집해 다음을 추가합니다:

    ##
## Secondary address
## - replace '<secondary_site_ip>' with the public or VPC address of your Geo secondary site
##
postgresql['listen_address'] = '<secondary_site_ip>'
postgresql['md5_auth_cidr_addresses'] = ['<secondary_site_ip>/32']

##
## Database credentials password (defined previously in primary site)
## - replicate same values here as defined in primary site
##
postgresql['sql_replication_password'] = '<md5_hash_of_your_replication_password>'
postgresql['sql_user_password'] = '<md5_hash_of_your_db_password>'
gitlab_rails['db_password'] = '<your_db_password_here>'

    IP 주소는 네트워크 구성에 맞는 주소로 반드시 교체합니다.

  3. 완전한 보조 사이트의 구성 예시를 복사합니다.

  4. 변경 사항을 적용하려면 파일을 저장하고 GitLab을 재구성합니다:

    gitlab-ctl reconfigure

  5. IP 주소 변경을 적용하려면 PostgreSQL을 재시작합니다:

    gitlab-ctl restart postgresql

데이터베이스 복제#

보조 사이트의 데이터베이스를 기본 사이트의 데이터베이스에 연결합니다. 아래 스크립트를 사용하면 데이터베이스를 복제하고 스트리밍 복제에 필요한 파일을 생성할 수 있습니다.

이 스크립트는 Linux 패키지의 기본 디렉터리를 사용합니다. 기본값을 변경했다면 아래 스크립트의 디렉터리 이름과 경로 이름을 사용 중인 이름으로 교체합니다.

Warning

복제 스크립트는 보조 사이트에서만 실행합니다. 이 스크립트는 pg_basebackup을 실행하기 전에 모든 PostgreSQL 데이터를 삭제하므로 데이터 손실로 이어질 수 있습니다.

데이터베이스를 복제하려면 다음을 수행합니다:

  1. GitLab 보조 사이트에 SSH로 접속해 root로 로그인합니다:

    sudo -i

    [!note] 로그인 셸 없이 root로 전환한 경우(예: su 또는 sudo su), 계속하기 전에 sudo -i를 실행합니다. root 로그인 환경 없이 gitlab-ctl replicate-geo-database를 실행하면 PostgreSQL 데이터 디렉터리의 소유자가 gitlab-psql이 아니라 root가 되고, 그 결과 PostgreSQL이 could not access the server configuration file ".../postgresql.conf": Permission denied 오류로 실패합니다.

  2. 복제 슬롯 이름으로 사용할 데이터베이스에 적합한 이름을 보조 사이트에 대해 선택합니다. 예를 들어 도메인이 secondary.geo.example.com이면 슬롯 이름으로 secondary_example을 사용합니다.

    복제 슬롯 이름에는 소문자, 숫자, 밑줄 문자만 사용할 수 있습니다.

  3. 다음 명령을 실행해 데이터베이스를 백업하고 복원한 뒤 복제를 시작합니다.

    [!warning] 각 Geo 보조 사이트는 고유한 복제 슬롯 이름을 가져야 합니다. 두 보조 사이트가 같은 슬롯 이름을 사용하면 PostgreSQL 복제가 중단됩니다.

    gitlab-ctl replicate-geo-database \
   --slot-name=<secondary_slot_name> \
   --host=<primary_site_ip> \
   --sslmode=verify-ca

    메시지가 표시되면 gitlab_replicator에 설정한 평문 비밀번호를 입력합니다.

복제 과정이 완료되었습니다.

새 보조 사이트 구성#

초기 복제 과정이 완료되면 보조 사이트에서 다음 항목을 구성합니다.

승인된 SSH 키 빠른 조회#

승인된 SSH 키 빠른 조회 구성 문서를 따릅니다.

빠른 조회는 Geo에 필수입니다.

Note

인증은 기본 사이트에서 처리합니다. 보조 사이트에는 사용자 지정 인증을 설정하지 않습니다. 보조 사이트는 읽기 전용 복사본이므로, Admin 영역 접근이 필요한 변경은 기본 사이트에서 수행해야 합니다.

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로 접속합니다. 연결할 수 없으면 권한이 올바른지 확인합니다.

보조 사이트 추가#

  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를 선택합니다.

      Name, External URL, Internal URL (optional) 세 개의 입력 필드가 있는 새 사이트 추가 양식.

    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

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

    gitlab-rake gitlab:geo:check

    확인 항목 중 하나라도 실패하면 문제 해결 문서를 참고합니다.

  7. 보조 사이트에 연결할 수 있는지 확인하려면 기본 사이트의 Rails 또는 Sidekiq 서버에 SSH로 접속해 root로 로그인합니다:

    gitlab-rake gitlab:geo:check

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

보조 사이트가 Geo 관리 페이지에 추가되고 재시작되면, 해당 사이트는 백필이라고 하는 과정으로 기본 사이트에서 누락된 데이터를 자동으로 복제하기 시작합니다.

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

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

허용된 ActionCable 오리진으로 기본 및 보조 URL 추가#

이 단계는 기본 사이트와 보조 사이트에서 웹소켓이 매끄럽게 동작하도록 합니다.

  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

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 사이트의 동기화 과정을 모니터링할 수 있습니다.

동기화 상태를 표시하는 Geo Sites 대시보드.

구성 예시#

완전한 기본 사이트#

이 완전한 gitlab.rb 구성 예시는 Geo 기본 사이트에 사용됩니다:

# Primary site 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'

## Database configuration
gitlab_rails['db_password'] = 'your_database_password_here'
postgresql['sql_user_password'] = 'md5_hash_of_your_database_password'
postgresql['sql_replication_password'] = 'md5_hash_of_your_replication_password'

## PostgreSQL network configuration
postgresql['listen_address'] = '10.0.1.10'  # Primary site IP
postgresql['md5_auth_cidr_addresses'] = ['10.0.1.10/32', '10.0.2.10/32']  # Primary and secondary IPs

## Disable automatic migrations (handled centrally, and to avoid unplanned downtime)
gitlab_rails['auto_migrate'] = false

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

## Object Storage configuration (optional)
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 (optional)
node_exporter['listen_address'] = '0.0.0.0:9100'
gitlab_workhorse['prometheus_listen_addr'] = '0.0.0.0:9229'
gitlab_rails['monitoring_whitelist'] = ['127.0.0.0/8', '10.0.0.0/8']

## Gitaly configuration
gitaly['configuration'] = {
  prometheus_listen_addr: '0.0.0.0:9236',
}

## ActionCable allowed origins
gitlab_rails['action_cable_allowed_origins'] = ['https://secondary.example.com', 'https://primary.example.com']

완전한 보조 사이트#

이 완전한 gitlab.rb 구성 예시는 Geo 보조 사이트용입니다:

# Secondary site 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 (can be the same as primary for unified URL setup)
external_url 'https://gitlab.example.com'

## Database configuration
gitlab_rails['db_password'] = 'your_database_password_here'
postgresql['sql_user_password'] = 'md5_hash_of_your_database_password'
postgresql['sql_replication_password'] = 'md5_hash_of_your_replication_password'

## PostgreSQL network configuration
postgresql['listen_address'] = '10.0.2.10'  # Secondary site IP
postgresql['md5_auth_cidr_addresses'] = ['10.0.2.10/32']

## 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 (optional)
node_exporter['listen_address'] = '0.0.0.0:9100'
gitlab_workhorse['prometheus_listen_addr'] = '0.0.0.0:9229'
gitlab_rails['monitoring_whitelist'] = ['127.0.0.0/8', '10.0.0.0/8']

## Gitaly configuration
gitaly['configuration'] = {
  prometheus_listen_addr: '0.0.0.0:9236',
}

관련 주제#

두 단일 노드 사이트를 위한 Geo 설정

GitLab v19.4
Tier: Premium, Ultimate
Offering: GitLab Self-Managed
원문 보기

요약

다음 가이드는 외부 서비스를 설정하지 않은 두 개의 Linux 패키지 인스턴스를 사용하여 두 단일 노드 사이트 설치에 GitLab Geo를 배포하는 방법을 간결하게 안내합니다. 아래에 언급된 설정을 GitLab 컨테이너의 /etc/gitlab/gitlab.rb 파일에 직접 적용하거나, Docker Compose 파일의 GITLAB_OMNIBUS_CONFIG 환경 변수에 추가합니다.

다음 가이드는 외부 서비스를 설정하지 않은 두 개의 Linux 패키지 인스턴스를 사용하여 두 단일 노드 사이트 설치에 GitLab Geo를 배포하는 방법을 간결하게 안내합니다. 이 가이드는 Docker 기반 설치에도 적용됩니다.

사전 요구 사항:

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

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

사전 요구 사항:

기본 사이트 구성#

Note

Docker 기반 설치의 경우:

아래에 언급된 설정을 GitLab 컨테이너의 /etc/gitlab/gitlab.rb 파일에 직접 적용하거나, Docker Compose 파일의 GITLAB_OMNIBUS_CONFIG 환경 변수에 추가합니다.

Docker Compose를 사용할 때는 구성 변경을 적용하기 위해 gitlab-ctl reconfigure 대신 docker-compose -f <docker-compose-file-name>.yml up을 사용합니다.

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

    sudo -i

  2. GitLab을 업그레이드할 때 의도하지 않은 다운타임이 발생하지 않도록 자동 PostgreSQL 업그레이드를 거부합니다. Geo 환경에서 PostgreSQL을 업그레이드할 때 알려진 주의 사항을 숙지합니다. 특히 대규모 환경에서는 PostgreSQL 업그레이드를 의식적으로 계획하고 실행해야 합니다. 따라서 앞으로 PostgreSQL 업그레이드가 정기 유지 관리 활동에 포함되도록 합니다.

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

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

    gitlab-ctl reconfigure

  5. 해당 사이트를 기본 Geo 사이트로 정의합니다:

    gitlab-ctl set-geo-primary-node

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

  6. 완전한 기본 사이트의 구성 예시를 복사합니다.

  7. gitlab 데이터베이스 사용자의 비밀번호를 생성하고 새 비밀번호를 사용하도록 Rails를 업데이트합니다.

    [!note] gitlab_rails['db_password'] 설정과 postgresql['sql_user_password'] 설정에 구성하는 값은 일치해야 합니다. 다만 MD5로 암호화된 비밀번호여야 하는 것은 postgresql['sql_user_password'] 값뿐입니다. 이에 대한 변경은 쿡북에서 PostgreSQL 비밀번호를 처리하는 방식 재검토에서 논의 중입니다.

    1. 원하는 비밀번호의 MD5 해시를 생성합니다:

      gitlab-ctl pg-password-md5 gitlab
# Enter password: <your_db_password_here>
# Confirm password: <your_db_password_here>
# fca0b89a972d69f00eb3ec98a5838484

    2. /etc/gitlab/gitlab.rb를 편집합니다:

      # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab`
postgresql['sql_user_password'] = '<md5_hash_of_your_db_password>'

# Every node that runs Puma or Sidekiq needs to have the database
# password specified as below. If you have a high-availability setup, this
# must be present in all application nodes.
gitlab_rails['db_password'] = '<your_db_password_here>'

  8. 데이터베이스 복제 사용자의 비밀번호를 정의합니다. /etc/gitlab/gitlab.rb의 postgresql['sql_replication_user'] 설정에 정의된 사용자 이름을 사용합니다. 기본값은 gitlab_replicator입니다.

    1. 원하는 비밀번호의 MD5 해시를 생성합니다:

      gitlab-ctl pg-password-md5 gitlab_replicator

# Enter password: <your_replication_password_here>
# Confirm password: <your_replication_password_here>
# 950233c0dfc2f39c64cf30457c3b7f1e

    2. /etc/gitlab/gitlab.rb를 편집합니다:

      # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab_replicator`
postgresql['sql_replication_password'] = '<md5_hash_of_your_replication_password>'

    3. 선택 사항. Linux 패키지가 관리하지 않는 외부 데이터베이스를 사용하는 경우 gitlab_replicator 사용자를 생성하고 그 사용자의 비밀번호를 직접 정의해야 합니다:

      --- Create a new user 'replicator'
CREATE USER gitlab_replicator;

--- Set/change a password and grants replication privilege
ALTER USER gitlab_replicator WITH REPLICATION ENCRYPTED PASSWORD '<replication_password>';

  9. /etc/gitlab/gitlab.rb에서 역할을 geo_primary_role로 설정합니다:

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

  10. 네트워크 인터페이스에서 수신하도록 PostgreSQL을 구성합니다:

    1. Geo 사이트의 주소를 조회하려면 Geo 사이트에 SSH로 접속해 다음을 실행합니다:

      ##
## Private address
##
ip route get 255.255.255.255 | awk '{for (i=1; i<=NF; i++) if ($i == "src") { print "Private address:", $(i+1); exit }}'

##
## Public address
##
echo "External address: $(curl --silent "ipinfo.io/ip")"

      대부분의 경우 GitLab Geo를 구성할 때 다음 주소를 사용합니다:

      구성 주소
      postgresql['listen_address'] 기본 사이트 공용 또는 VPC 프라이빗 주소.
      postgresql['md5_auth_cidr_addresses'] 기본 및 보조 사이트 공용 또는 VPC 프라이빗 주소.

      Google Cloud Platform, SoftLayer 또는 가상 사설 클라우드(VPC)를 제공하는 다른 공급업체를 사용하는 경우 postgresql['md5_auth_cidr_addresses']와 postgresql['listen_address']에 기본 및 보조 사이트의 프라이빗 주소(Google Cloud Platform에서는 "내부 주소"에 해당)를 사용할 수 있습니다.

      [!note] listen_address로 0.0.0.0 또는 *를 사용해야 하는 경우, Rails가 127.0.0.1을 통해 연결할 수 있도록 postgresql['md5_auth_cidr_addresses'] 설정에 127.0.0.1/32도 추가해야 합니다. 자세한 내용은 이슈 5258을 참고합니다.

      네트워크 구성에 따라 제안된 주소가 올바르지 않을 수 있습니다. 기본 사이트와 보조 사이트가 로컬 영역 네트워크로 연결되거나, 가용 영역을 연결하는 가상 네트워크 (Amazon VPC 또는 Google VPC)로 연결된다면 postgresql['md5_auth_cidr_addresses']에 보조 사이트의 프라이빗 주소를 사용해야 합니다.

    2. /etc/gitlab/gitlab.rb에 다음 줄을 추가합니다. IP 주소는 네트워크 구성에 맞는 주소로 반드시 교체합니다:

      ##
## Primary address
## - replace '<primary_node_ip>' with the public or VPC address of your Geo primary node
##
postgresql['listen_address'] = '<primary_site_ip>'

##
# Allow PostgreSQL client authentication from the primary and secondary IPs. These IPs may be
# public or VPC addresses in CIDR format, for example ['198.51.100.1/32', '198.51.100.2/32']
##
postgresql['md5_auth_cidr_addresses'] = ['<primary_site_ip>/32', '<secondary_site_ip>/32']

  11. PostgreSQL이 재시작되어 프라이빗 주소에서 수신할 때까지 자동 데이터베이스 마이그레이션을 일시적으로 비활성화합니다. /etc/gitlab/gitlab.rb에서 gitlab_rails['auto_migrate']를 false로 설정합니다:

    ## Disable automatic database migrations
gitlab_rails['auto_migrate'] = false

  12. 이 변경 사항을 적용하려면 GitLab을 재구성하고 PostgreSQL을 재시작합니다:

    gitlab-ctl reconfigure
gitlab-ctl restart postgresql

  13. 마이그레이션을 다시 활성화하려면 /etc/gitlab/gitlab.rb를 편집해 gitlab_rails['auto_migrate']를 true로 변경합니다:

    gitlab_rails['auto_migrate'] = true

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

    gitlab-ctl reconfigure

    PostgreSQL 서버가 원격 연결을 수락하도록 설정되었습니다.

  14. netstat -plnt | grep 5432를 실행해 PostgreSQL이 기본 사이트 프라이빗 주소의 5432 포트에서 수신하는지 확인합니다.

  15. GitLab을 재구성할 때 인증서가 자동으로 생성되었습니다. 이 인증서는 도청자로부터 PostgreSQL 트래픽을 보호하는 데 자동으로 사용됩니다. 능동적인("중간자") 공격자를 막으려면 인증서를 보조 사이트에 복사합니다:

    1. 기본 사이트에서 server.crt의 복사본을 만듭니다:

      cat ~gitlab-psql/data/server.crt

    2. 보조 사이트를 구성할 때 사용할 수 있도록 출력을 저장합니다. 인증서는 민감한 데이터가 아닙니다.

    인증서는 일반적인 PostgreSQL 공통 이름으로 생성됩니다. 호스트 이름 불일치 오류를 방지하려면 데이터베이스를 복제할 때 verify-ca 모드를 사용해야 합니다.

보조 서버 구성#

  1. GitLab 보조 사이트에 SSH로 접속해 root로 로그인합니다:

    sudo -i

  2. GitLab을 업그레이드할 때 의도하지 않은 다운타임이 발생하지 않도록 자동 PostgreSQL 업그레이드를 거부합니다. Geo 환경에서 PostgreSQL을 업그레이드할 때 알려진 주의 사항을 숙지합니다. 특히 대규모 환경에서는 PostgreSQL 업그레이드를 의식적으로 계획하고 실행해야 합니다. 따라서 앞으로 PostgreSQL 업그레이드가 정기 유지 관리 활동에 포함되도록 합니다.

  3. 사이트를 구성하기 전에 어떤 명령도 실행되지 않도록 애플리케이션 서버와 Sidekiq을 중지합니다:

    gitlab-ctl stop puma
gitlab-ctl stop sidekiq

  4. 기본 사이트 PostgreSQL 서버에 대한 TCP 연결을 확인합니다:

    gitlab-rake gitlab:tcp_check[<primary_site_ip>,5432]

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

  5. 보조 사이트에서 server.crt라는 파일을 생성하고 기본 사이트를 구성할 때 만든 인증서 복사본을 추가합니다.

    editor server.crt

  6. 보조 사이트에서 PostgreSQL TLS 검증을 설정하려면 gitlab-psql 사용자용으로 server.crt를 설치합니다:

    install \
   -D \
   -o gitlab-psql \
   -g gitlab-psql \
   -m 0400 \
   -T server.crt ~gitlab-psql/.postgresql/root.crt

    이제 PostgreSQL은 TLS 연결을 검증할 때 이 인증서만 인식합니다. 이 인증서는 기본 사이트에만 있는 개인 키에 접근할 수 있는 사람이 복제할 수 있습니다.

    gitlab-ctl replicate-geo-database는 root로 실행되므로 root 사용자용으로도 인증서를 설치합니다. 그렇지 않으면 sslmode=verify-ca 또는 sslmode=verify-full을 사용할 때 복제 명령이 could not open certificate file 오류와 함께 실패합니다:

    install \
   -D \
   -o root \
   -g root \
   -m 0400 \
   -T server.crt /root/.postgresql/root.crt

  7. gitlab-psql 사용자가 기본 사이트 데이터베이스에 연결할 수 있는지 테스트합니다. Linux 패키지의 기본 이름은 gitlabhq_production입니다:

   sudo \
       -u gitlab-psql /opt/gitlab/embedded/bin/psql \
       --list \
       -U gitlab_replicator \
       -d "dbname=gitlabhq_production sslmode=verify-ca" \
       -W \
       -h <primary_site_ip>

   docker exec -it <container_name> su - gitlab-psql -c '/opt/gitlab/embedded/bin/psql \
       --list \
       -U gitlab_replicator \
       -d "dbname=gitlabhq_production sslmode=verify-ca" \
       -W \
       -h <primary_site_ip>'

메시지가 표시되면 gitlab_replicator 사용자에 설정한 평문 비밀번호를 입력합니다. 모두 정상적으로 동작했다면 기본 사이트 데이터베이스 목록이 표시됩니다.

  1. /etc/gitlab/gitlab.rb를 편집해 역할을 geo_secondary_role로 설정합니다:

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

    자세한 내용은 Geo 역할을 참고합니다.

  2. PostgreSQL을 구성하려면 /etc/gitlab/gitlab.rb를 편집해 다음을 추가합니다:

    ##
## Secondary address
## - replace '<secondary_site_ip>' with the public or VPC address of your Geo secondary site
##
postgresql['listen_address'] = '<secondary_site_ip>'
postgresql['md5_auth_cidr_addresses'] = ['<secondary_site_ip>/32']

##
## Database credentials password (defined previously in primary site)
## - replicate same values here as defined in primary site
##
postgresql['sql_replication_password'] = '<md5_hash_of_your_replication_password>'
postgresql['sql_user_password'] = '<md5_hash_of_your_db_password>'
gitlab_rails['db_password'] = '<your_db_password_here>'

    IP 주소는 네트워크 구성에 맞는 주소로 반드시 교체합니다.

  3. 완전한 보조 사이트의 구성 예시를 복사합니다.

  4. 변경 사항을 적용하려면 파일을 저장하고 GitLab을 재구성합니다:

    gitlab-ctl reconfigure

  5. IP 주소 변경을 적용하려면 PostgreSQL을 재시작합니다:

    gitlab-ctl restart postgresql

데이터베이스 복제#

보조 사이트의 데이터베이스를 기본 사이트의 데이터베이스에 연결합니다. 아래 스크립트를 사용하면 데이터베이스를 복제하고 스트리밍 복제에 필요한 파일을 생성할 수 있습니다.

이 스크립트는 Linux 패키지의 기본 디렉터리를 사용합니다. 기본값을 변경했다면 아래 스크립트의 디렉터리 이름과 경로 이름을 사용 중인 이름으로 교체합니다.

Warning

복제 스크립트는 보조 사이트에서만 실행합니다. 이 스크립트는 pg_basebackup을 실행하기 전에 모든 PostgreSQL 데이터를 삭제하므로 데이터 손실로 이어질 수 있습니다.

데이터베이스를 복제하려면 다음을 수행합니다:

  1. GitLab 보조 사이트에 SSH로 접속해 root로 로그인합니다:

    sudo -i

    [!note] 로그인 셸 없이 root로 전환한 경우(예: su 또는 sudo su), 계속하기 전에 sudo -i를 실행합니다. root 로그인 환경 없이 gitlab-ctl replicate-geo-database를 실행하면 PostgreSQL 데이터 디렉터리의 소유자가 gitlab-psql이 아니라 root가 되고, 그 결과 PostgreSQL이 could not access the server configuration file ".../postgresql.conf": Permission denied 오류로 실패합니다.

  2. 복제 슬롯 이름으로 사용할 데이터베이스에 적합한 이름을 보조 사이트에 대해 선택합니다. 예를 들어 도메인이 secondary.geo.example.com이면 슬롯 이름으로 secondary_example을 사용합니다.

    복제 슬롯 이름에는 소문자, 숫자, 밑줄 문자만 사용할 수 있습니다.

  3. 다음 명령을 실행해 데이터베이스를 백업하고 복원한 뒤 복제를 시작합니다.

    [!warning] 각 Geo 보조 사이트는 고유한 복제 슬롯 이름을 가져야 합니다. 두 보조 사이트가 같은 슬롯 이름을 사용하면 PostgreSQL 복제가 중단됩니다.

    gitlab-ctl replicate-geo-database \
   --slot-name=<secondary_slot_name> \
   --host=<primary_site_ip> \
   --sslmode=verify-ca

    메시지가 표시되면 gitlab_replicator에 설정한 평문 비밀번호를 입력합니다.

복제 과정이 완료되었습니다.

새 보조 사이트 구성#

초기 복제 과정이 완료되면 보조 사이트에서 다음 항목을 구성합니다.

승인된 SSH 키 빠른 조회#

승인된 SSH 키 빠른 조회 구성 문서를 따릅니다.

빠른 조회는 Geo에 필수입니다.

Note

인증은 기본 사이트에서 처리합니다. 보조 사이트에는 사용자 지정 인증을 설정하지 않습니다. 보조 사이트는 읽기 전용 복사본이므로, Admin 영역 접근이 필요한 변경은 기본 사이트에서 수행해야 합니다.

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로 접속합니다. 연결할 수 없으면 권한이 올바른지 확인합니다.

보조 사이트 추가#

  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를 선택합니다.

      Name, External URL, Internal URL (optional) 세 개의 입력 필드가 있는 새 사이트 추가 양식.

    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

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

    gitlab-rake gitlab:geo:check

    확인 항목 중 하나라도 실패하면 문제 해결 문서를 참고합니다.

  7. 보조 사이트에 연결할 수 있는지 확인하려면 기본 사이트의 Rails 또는 Sidekiq 서버에 SSH로 접속해 root로 로그인합니다:

    gitlab-rake gitlab:geo:check

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

보조 사이트가 Geo 관리 페이지에 추가되고 재시작되면, 해당 사이트는 백필이라고 하는 과정으로 기본 사이트에서 누락된 데이터를 자동으로 복제하기 시작합니다.

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

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

허용된 ActionCable 오리진으로 기본 및 보조 URL 추가#

이 단계는 기본 사이트와 보조 사이트에서 웹소켓이 매끄럽게 동작하도록 합니다.

  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

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 사이트의 동기화 과정을 모니터링할 수 있습니다.

동기화 상태를 표시하는 Geo Sites 대시보드.

구성 예시#

완전한 기본 사이트#

이 완전한 gitlab.rb 구성 예시는 Geo 기본 사이트에 사용됩니다:

# Primary site 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'

## Database configuration
gitlab_rails['db_password'] = 'your_database_password_here'
postgresql['sql_user_password'] = 'md5_hash_of_your_database_password'
postgresql['sql_replication_password'] = 'md5_hash_of_your_replication_password'

## PostgreSQL network configuration
postgresql['listen_address'] = '10.0.1.10'  # Primary site IP
postgresql['md5_auth_cidr_addresses'] = ['10.0.1.10/32', '10.0.2.10/32']  # Primary and secondary IPs

## Disable automatic migrations (handled centrally, and to avoid unplanned downtime)
gitlab_rails['auto_migrate'] = false

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

## Object Storage configuration (optional)
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 (optional)
node_exporter['listen_address'] = '0.0.0.0:9100'
gitlab_workhorse['prometheus_listen_addr'] = '0.0.0.0:9229'
gitlab_rails['monitoring_whitelist'] = ['127.0.0.0/8', '10.0.0.0/8']

## Gitaly configuration
gitaly['configuration'] = {
  prometheus_listen_addr: '0.0.0.0:9236',
}

## ActionCable allowed origins
gitlab_rails['action_cable_allowed_origins'] = ['https://secondary.example.com', 'https://primary.example.com']

완전한 보조 사이트#

이 완전한 gitlab.rb 구성 예시는 Geo 보조 사이트용입니다:

# Secondary site 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 (can be the same as primary for unified URL setup)
external_url 'https://gitlab.example.com'

## Database configuration
gitlab_rails['db_password'] = 'your_database_password_here'
postgresql['sql_user_password'] = 'md5_hash_of_your_database_password'
postgresql['sql_replication_password'] = 'md5_hash_of_your_replication_password'

## PostgreSQL network configuration
postgresql['listen_address'] = '10.0.2.10'  # Secondary site IP
postgresql['md5_auth_cidr_addresses'] = ['10.0.2.10/32']

## 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 (optional)
node_exporter['listen_address'] = '0.0.0.0:9100'
gitlab_workhorse['prometheus_listen_addr'] = '0.0.0.0:9229'
gitlab_rails['monitoring_whitelist'] = ['127.0.0.0/8', '10.0.0.0/8']

## Gitaly configuration
gitaly['configuration'] = {
  prometheus_listen_addr: '0.0.0.0:9236',
}

관련 주제#