Geo 데이터베이스 복제

Tier: 프리미엄, 얼티메이트 Offering: Self-managed

이 문서는 기본 GitLab 데이터베이스를 보조 사이트의 데이터베이스로 복제하는 데 필요한 최소한의 단계를 설명합니다. 데이터베이스의 설정 및 크기 등의 특성에 따라 일부 값을 수정해야 할 수 있습니다.

note

GitLab 설치에서 외부 PostgreSQL 인스턴스(리눅스 패키지 설치가 관리하지 않음)를 사용하는 경우 roles은 제대로 된 모든 구성 단계를 수행할 수 없습니다. 이 경우 외부 PostgreSQL 인스턴스를 사용하는 Geo 프로세스를 대신 사용하십시오.
note

설치 프로세스의 각 단계는 문서화된 순서대로 완료해야 합니다. 그렇지 않은 경우, 진행하기 전에 이전 모든 단계를 완료해야 합니다.

secondary 사이트가 primary 사이트와 동일한 GitLab Enterprise Edition 버전을 실행 중인지 확인하세요. primary 사이트에 프리미엄 또는 얼티메이트 가입을 완료했는지 확인하세요.

실험 또는 프로덕션 환경에서 이러한 단계를 실행하기 전에 모든 단계를 꼼꼼히 읽고 검토하세요.

단일 인스턴스 데이터베이스 복제

단일 인스턴스 데이터베이스 복제는 설정이 쉽고 클러스터화된 대안과 동등한 Geo 기능을 제공합니다. 단일 기계에서 실행하거나 미래의 클러스터 설치를 위해 Geo를 평가하는 설정에 유용합니다.

단일 인스턴스는 Patroni를 사용하여 고가용성 아키텍처를 위해 권장되는 클러스터 버전으로 확장할 수 있습니다.

아래 지침에 따라 PostgreSQL 복제를 단일 인스턴스 데이터베이스로 설정하는 방법을 따르세요. 또는 Patroni 클러스터를 사용하여 멀티 노드 데이터베이스 복제를 설정하는 지침을 참조하세요.

PostgreSQL 복제

쓰기 작업이 발생하는 GitLab primary 사이트는 primary 데이터베이스 서버에 연결됩니다. secondary 사이트는 자체 데이터베이스 서버(읽기 전용)에 연결합니다.

PostgreSQL 복제 슬롯을 사용하여 secondary 사이트가 복구에 필요한 모든 데이터를 primary 사이트에서 유지하도록 해야 합니다. 자세한 내용은 아래를 참조하세요.

다음 가이드에서는:

  • 리눅스 패키지를 사용 중이며 (pg_basebackup 도구를 포함한) PostgreSQL 12 이상을 사용 중입니다.
  • primary 사이트가 이미 설정되어 있으며, 리눅스 패키지 설치에 의해 관리되는 PostgreSQL(또는 해당 버전)이 실행 중이며, 동일 PostgreSQL 버전, OS 및 GitLab이 있는 새 secondary 사이트가 설정되어 있습니다.

경고:
Geo는 스트리밍 복제로 작동합니다. 논리적 복제는 현재 지원되지 않습니다. 지원이 논의 중인 이슈가 있습니다.

단계 1. primary 사이트 구성

  1. GitLab primary 사이트에 SSH로 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'] = '<site_name_here>'

  3. 변경 사항이 적용되려면 primary 사이트를 다시 구성하세요: 

    gitlab-ctl reconfigure

  4. 아래 명령을 실행하여 사이트를 primary 사이트로 정의하세요: 

    gitlab-ctl set-geo-primary-node

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

  5. gitlab 데이터베이스 사용자의 암호를 정의하세요:

    원하는 암호의 MD5 해시를 생성하세요: 

    gitlab-ctl pg-password-md5 gitlab
# 암호 입력: <your_db_password_here>
# 암호 확인: <your_db_password_here>
# fca0b89a972d69f00eb3ec98a5838484

    /etc/gitlab/gitlab.rb을 편집하세요: 

    # `gitlab-ctl pg-password-md5 gitlab`로 생성된 해시로 채웁니다
postgresql['sql_user_password'] = '<md5_hash_of_your_db_password>'

# Puma 또는 Sidekiq를 실행하는 모든 노드마다 다음과 같이 데이터베이스 암호를 지정해야 합니다. 고가용성 설정을 사용하는 경우 모든 애플리케이션 노드에 이 값이 있어야 합니다.
gitlab_rails['db_password'] = '<your_db_password_here>'

  6. 데이터베이스 복제 사용자의 암호를 정의하세요.

    /etc/gitlab/gitlab.rb에서 postgresql['sql_replication_user'] 하위에 정의된 사용자 이름을 사용하세요. 기본값은 gitlab_replicator입니다. 사용자 이름을 다른 값으로 변경했다면 아래 지침을 적용하세요.

    원하는 암호의 MD5 해시를 생성하세요: 

    gitlab-ctl pg-password-md5 gitlab_replicator
# 암호 입력: <your_replication_password_here>
# 암호 확인: <your_replication_password_here>
# 950233c0dfc2f39c64cf30457c3b7f1e

    /etc/gitlab/gitlab.rb을 편집하세요: 

    # `gitlab-ctl pg-password-md5 gitlab_replicator`로 생성된 해시로 채웁니다
postgresql['sql_replication_password'] = '<md5_hash_of_your_replication_password>'

    리눅스 패키지 설치에서 관리하지 않는 외부 데이터베이스를 사용하는 경우 gitlab_replicator 사용자를 생성하고 해당 사용자에 대해 암호를 수동으로 정의해야 합니다: 

    --- 'replicator' 사용자 생성
CREATE USER gitlab_replicator;

--- 암호 설정 및 복제 권한 부여
ALTER USER gitlab_replicator WITH REPLICATION ENCRYPTED PASSWORD '<replication_password>';

  7. /etc/gitlab/gitlab.rb을 편집하고 geo_primary_role을 설정하세요(자세한 내용은 Geo roles 참조): 

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

  8. PostgreSQL이 네트워크 인터페이스에서 수신 대기하도록 구성하세요:

    보안상의 이유로 PostgreSQL은 기본적으로 어떤 네트워크 인터페이스에서도 수신 대기하지 않습니다. 그러나 Geo에서는 secondary 사이트가 primary 사이트의 데이터베이스에 연결할 수 있어야 합니다. 이를 위해 각 사이트의 IP 주소가 필요합니다.

    note

    외부 PostgreSQL 인스턴스의 경우 추가 지침을 참조하세요.

    클라우드 제공 업체를 사용하는 경우 클라우드 제공자의 관리 콘솔을 통해 각 Geo 사이트의 주소를 확인할 수 있습니다.

    Geo 사이트의 주소를 확인하려면 Geo 사이트에 SSH로 연결하여 다음 명령을 실행하세요: 

    ##
## 개인 주소
##
ip route get 255.255.255.255 | awk '{print "Private address:", $NF; exit}'

##
## 공용 주소
##
echo "External address: $(curl --silent "ipinfo.io/ip")"

    대부분의 경우, GitLab Geo를 구성하는 데 다음과 같은 주소가 사용됩니다:

    구성 주소
    postgresql['listen_address'] primary 사이트의 공용 또는 VPC 개인 주소
    postgresql['md5_auth_cidr_addresses'] primary 및 secondary 사이트의 공용 또는 VPC 개인 주소

    Google Cloud Platform, SoftLayer 등의 가상 프라이빗 클라우드(VPC)를 사용하는 경우 postgresql['md5_auth_cidr_addresses'] 및 postgresql['listen_address']에 primary 및 secondary 사이트의 “개인” 또는 “내부” 주소를 사용하는 것이 좋습니다.

    listen_address 옵션은 지정된 주소에 해당하는 인터페이스로부터 네트워크 연결을 엽니다. 자세한 내용은 PostgreSQL 설명서를 참조하세요.

    note

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

    네트워크 구성에 따라 제안된 주소가 잘못될 수 있습니다. primary 사이트와 secondary 사이트가 로컬 영역 네트워크나 Amazon의 VPC, Google의 VPC 같은 가용성 영역을 연결하는 가상 네트워크를 통해 연결되는 경우 postgresql['md5_auth_cidr_addresses']를 위한 secondary 사이트의 개인 주소를 사용해야 합니다.

    /etc/gitlab/gitlab.rb을 편집하고 아래 내용을 해당 네트워크 구성에 맞는 주소로 대체하여 추가하세요: 

    ##
## Primary address
## - '<primary_node_ip>'를 Geo primary 노드의 공용 또는 VPC 주소로 대체합니다
##
postgresql['listen_address'] = '<primary_site_ip>'

##
# PostgreSQL 클라이언트 인증을 primary 및 secondary IP에서 허용합니다. 이 IP는 예를 들어 CIDR 형식의 공용 또는 VPC 주소가 될 수 있습니다. 예: ['198.51.100.1/32', '198.51.100.2/32']
##
postgresql['md5_auth_cidr_addresses'] = ['<primary_site_ip>/32', '<secondary_site_ip>/32']

##
## 복제 설정
##
# postgresql['max_replication_slots'] = 1 # 여러 개의 Geo secondary 노드가 있다면 해당 노드 수로 설정합니다.
# postgresql['max_wal_senders'] = 10
# postgresql['wal_keep_segments'] = 10

  9. PostgreSQL이 개인 주소에서 수신 대기 및 재부팅되고 복제 슬롯 변경이 적용되도록 하기 위해 자동 데이터베이스 마이그레이션을 일시적으로 비활성화합니다. /etc/gitlab/gitlab.rb을 편집하고 구성을 false로 변경하세요: 

    ## 자동 데이터베이스 마이그레이션 비활성화
gitlab_rails['auto_migrate'] = false

  10. 선택 사항: 다른 secondary 사이트를 추가하려면 해당 설정은 다음과 같을 것입니다: 

    postgresql['md5_auth_cidr_addresses'] = ['<primary_site_ip>/32', '<secondary_site_ip>/32', '<another_secondary_site_ip>/32']

    또한 wal_keep_segments 및 max_wal_senders를 귀사의 데이터베이스 복제 요구 사항에 맞추도록 변경할 수 있습니다. 자세한 내용은 PostgreSQL - 복제 문서를 참조하세요.

  11. 파일을 저장하고 데이터베이스 수신 주소 변경 및 복제 슬롯 변경이 적용되도록 GitLab을 다시 구성하세요: 

    gitlab-ctl reconfigure

    효과를 발휘하도록 PostgreSQL을 재시작하세요: 

    gitlab-ctl restart postgresql

  12. PostgreSQL 서버가 원격 연결을 수락할 수 있도록 설정되었으므로 netstat -plnt | grep 5432를 실행하여 PostgreSQL이 primary 사이트의 개인 주소에서 포트 5432에서 수신 대기 중인지 확인하세요.

  13. PostgreSQL 트래픽을 도청으로부터 보호하기 위해 자동으로 인증하는 인증서가 자동으로 생성되었습니다. secondary 사이트에서도 해당 인증서의 서명자(CA)의 복사본이 필요합니다. 이 경우 self-signed 인증서의 PostgreSQL server.crt 파일을 primary 사이트에서 복사합니다. 다음 명령을 실행해 복사하세요: 

    cat ~gitlab-psql/data/server.crt

    출력을 클립보드에 복사하거나 로컬 파일에 넣으세요. 복제하는 동안 인증서가 필요합니다! 이 인증서는 민감한 데이터가 아닙니다.

    그러나 이 인증서는 일반적인 PostgreSQL 공통 이름으로 생성됩니다. 따라서 secondary 사이트에서 데이터베이스를 복제할 때 verify-ca 모드를 사용해야 합니다. 그렇지 않으면 호스트 이름 불일치로 오류가 발생합니다.

  14. 선택 사항: SSL 인증서를 직접 생성하고 PostgreSQL을 위해 SSL 구성을 수동으로 구성할 수 있습니다. 최소한 SSL 인증서와 키가 필요합니다. 전체 경로에 대해 postgresql['ssl_cert_file'] 및 postgresql['ssl_key_file'] 값을 설정하세요.

단계 2. 보조 서버 구성

  1. GitLab 보조 사이트에 SSH로 로그인하고 root로 서명하세요: 

    sudo -i

  2. 애플리케이션 서버 및 Sidekiq을 정지하세요: 

    gitlab-ctl stop puma
gitlab-ctl stop sidekiq
    note
    사이트가 완전히 구성되기 전에 아무 것도 실행하지 않도록 이 단계가 중요합니다.

  3. 주요 사이트의 PostgreSQL 서버로의 TCP 연결을 확인하세요: 

    gitlab-rake gitlab:tcp_check[<primary_site_ip>,5432]
    note
    이 단계가 실패하면 잘못된 IP 주소를 사용하고 있을 수 있거나 방화벽이 사이트 접근을 막고 있을 수 있습니다. 공용 및 사설 주소 사이의 차이를 주의 깊게 확인하고, 방화벽이 있는 경우, 보조 사이트에서 주요 사이트로의 5432 포트 연결을 허용하는지 확인하세요.

  4. 보조 사이트에 server.crt 파일을 생성하고, 주요 사이트 설정의 마지막 단계에서 얻은 내용으로 해당 파일을 작성하세요: 

    editor server.crt

  5. 보조 사이트에서 PostgreSQL TLS 인증을 설정하세요:

    server.crt 파일을 설치하세요: 

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

    이제 PostgreSQL은 TLS 연결을 확인할 때 해당 정확한 인증서만 인식합니다. 이 인증서는 주요 사이트에서만 있는 개인 키에 액세스 권한이 있는 사람만 복제할 수 있습니다.

  6. gitlab-psql 사용자가 주요 사이트의 데이터베이스에 연결할 수 있는지 테스트하세요 (리눅스 패키지 설치의 기본 데이터베이스 이름은 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>
    note
    수동으로 생성된 인증서를 사용하고 전체 호스트 이름 확인을 위해 sslmode=verify-full을 사용하려면 위의 명령을 실행할 때 verify-ca를 verify-full로 바꿔주세요.

    물어 본 경우, 첫 단계에서 gitlab_replicator 사용자를 위해 설정한 평문 암호를 입력하세요. 모두 올바르게 처리되었다면, 주요 사이트의 데이터베이스 목록이 표시됩니다.

    여기서 연결에 실패하면 TLS 구성이 잘못되었음을 나타냅니다. 주요 사이트의 ~gitlab-psql/data/server.crt의 내용이 보조 사이트의 ~gitlab-psql/.postgresql/root.crt의 내용과 일치하는지 확인하세요.

  7. /etc/gitlab/gitlab.rb 파일을 편집하고 역할을 geo_secondary_role로 설정하세요 (자세한 내용은 Geo 역할을 참조하세요): 

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

  8. PostgreSQL을 구성하세요:

    이 단계는 주요 인스턴스를 구성하는 방법과 유사합니다. 단일 노드를 사용하더라도 반드시 이를 활성화해야 합니다.

    /etc/gitlab/gitlab.rb 파일을 편집하고 다음을 추가하세요. IP 주소를 해당 네트워크 구성에 맞게 변경하세요: 

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

    외부 PostgreSQL 인스턴스의 경우, 추가 지침을 참조하세요. 주요 사이트를 보조 사이트로 다시 온라인 상태로 복구하는 경우, roles(['geo_primary_role']) 또는 geo_primary_role['enable'] = true을 제거해야 합니다.

  9. 변경 사항이 적용되도록 GitLab을 다시 구성하세요: 

    gitlab-ctl reconfigure

  10. IP 변경을 적용하기 위해 PostgreSQL을 다시 시작하세요: 

    gitlab-ctl restart postgresql

단계 3. 복제 프로세스 시작

아래는 보조 사이트의 데이터베이스를 주요 사이트의 데이터베이스에 연결하는 스크립트입니다. 이 스크립트는 데이터베이스를 복제하고 스트리밍 복제에 필요한 파일을 생성합니다.

기본적으로 리눅스 패키지 설치 시 설정된 기본 디렉토리를 사용합니다. 기본값을 수정했다면 해당 스크립트를 설정하세요(디렉토리 및 경로를 대체).

경고: pg_basebackup을 실행하기 전에 보조 사이트에서 실행해야 하므로 PostgreSQL의 모든 데이터를 제거합니다.

  1. GitLab 보조 사이트에 SSH로 로그인하고 root로 서명하세요: 

    sudo -i

  2. 데이터베이스 친화적인 이름을 선택하여 보조 사이트에서 사용할 복제 슬롯 이름으로 사용하세요. 예를 들어, 도메인이 secondary.geo.example.com인 경우, 아래 명령에서 secondary_example를 슬롯 이름으로 사용하세요.

  3. 아래 명령을 실행하여 백업/복원을 시작하고 복제를 시작하세요

    경고: 각 Geo 보조 사이트는 고유한 복제 슬롯 이름을 가져야 합니다. 두 개 이상의 보조가 동일한 슬롯 이름을 사용하면 PostgreSQL 복제가 중단됩니다.

    note
    복제 슬롯 이름은 소문자 문자, 숫자 및 밑줄 문자만 포함해야 합니다.

    물어 본 경우, 첫 단계에서 gitlab_replicator 사용자를 위해 설정한 평문 암호를 입력하세요. 

    gitlab-ctl replicate-geo-database \
   --slot-name=<secondary_site_name> \
   --host=<primary_site_ip> \
   --sslmode=verify-ca
    note
    사용자 지정 PostgreSQL 인증서를 생성한 경우 추가적인 보안을 위해 --sslmode=verify-full을 사용하거나 (또는 sslmode 행을 제거)해야 합니다. 그렇지 않으면 verify-full을 사용하도록 자동으로 생성된 인증서를 사용하면 이 명령에서 --host 값과 일치하지 않는 일반적인 PostgreSQL CN이 있어 실패합니다.

    이 명령은 추가 옵션을 몇 가지 사용합니다. 모두 나열하려면 --help을 사용할 수 있지만 이런 팁이 있습니다:

    • 주요 사이트가 단일 노드인 경우 --host 매개변수로 주요 노드 호스트를 사용하세요.
    • 주요 사이트가 외부 PostgreSQL 데이터베이스를 사용하는 경우 --host 매개변수를 조정해야 합니다.
      • PgBouncer 설정의 경우 실제 PostgreSQL 데이터베이스 호스트를 대상으로 설정하세요, PgBouncer 주소가 아닙니다.
      • Patroni 구성의 경우 현재 Patroni 리더 호스트를 대상으로 설정하세요.
      • 부하 분산기(예: HAProxy)를 사용하는 경우, 부하 분산기가 항상 Patroni 리더로 라우팅하도록 구성된 경우 주소 대신 부하 분산기를 대상으로 설정할 수 있습니다. 그렇지 않으면 실제 데이터베이스 호스트를 대상으로 설정해야 합니다.
      • 전용 PostgreSQL 노드가 있는 경우, 전용 데이터베이스 호스트를 대상으로 설정하세요.
    • --slot-name을 주요 데이터베이스에서 사용할 복제 슬롯 이름으로 변경하세요. 스크립트는 복제 슬롯을 자동으로 생성하려고 시도합니다.
    • PostgreSQL이 비표준 포트에서 청취 중인 경우, --port=를 추가하세요.
    • 데이터베이스가 30분 이내에 전송될 수 없을 만큼 매우 크다면 제한 시간을 늘려야 합니다. 초기 복제에 1시간 이하가 소요될 것으로 예상한다면 --backup-timeout=3600을 사용하세요.
    • PostgreSQL TLS 인증을 완전히 건너뛰려면 --sslmode=disable을 전달하세요(예: 네트워크 경로가 안전하다고 확신하는 경우 또는 site-to-site VPN을 사용 중인 경우). 이것은 공용 인터넷에서는 안전하지 않습니다!
    • 각 sslmode에 대한 자세한 정보는 PostgreSQL 문서를 참조하세요. 위의 명령은 수동 도청자 및 적극적인 “중간자 공격”으로부터 보호를 보장하기 위해 주의 깊게 작성되었습니다.
    • Geo 보조 사이트에서 이전 사이트를 다시 사용하는 경우 명령줄에 --force를 추가해야 합니다.
    • 제품 머신이 아닌 경우 (정말 그렇게 하고 싶은 경우) 백업 단계를 건너뛰도록 --skip-backup을 추가할 수 있습니다.

복제 프로세스가 이제 완료되었습니다.

PgBouncer 지원 (옵션)

PgBouncer 은 GitLab Geo와 함께 사용하여 PostgreSQL 연결을 풀링할 수 있으며, 단일 인스턴스 설치를 사용할 때에도 성능을 향상시킬 수 있습니다.

GitLab을 고가용성 구성으로 사용하는 경우 PgBouncer를 사용해야 합니다. 이는 Geo primary 사이트를 지원하는 노드 클러스터와 Geo secondary 사이트를 지원하는 노드 클러스터 두 개를 사용할 때 성립됩니다. main 데이터베이스와 추적 데이터베이스 각각을 위한 두 개의 PgBouncer 노드가 필요합니다. 자세한 내용은 관련 문서를 참조하세요.

복제 비밀번호 변경

리눅스 패키지 설치로 관리되는 PostgreSQL 인스턴스를 사용할 때 복제 사용자의 비밀번호를 변경하려면:

GitLab Geo primary 사이트에서:

  1. 복제 사용자의 기본값은 gitlab_replicator이지만, /etc/gitlab/gitlab.rb에서 postgresql['sql_replication_user'] 설정 하에 사용자 지정 복제 사용자를 설정한 경우에는 해당 사용자에 맞게 다음 지침을 적용하세요.

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

    sudo gitlab-ctl pg-password-md5 gitlab_replicator
# 비밀번호 입력: <여기에_귀하의_복제_비밀번호_입력>
# 비밀번호 확인: <여기에_귀하의_복제_비밀번호_입력>
# 950233c0dfc2f39c64cf30457c3b7f1e

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

    # `gitlab-ctl pg-password-md5 gitlab_replicator`에 의해 생성된 해시로 채웁니다
postgresql['sql_replication_password'] = '<귀하의_복제_비밀번호의_md5_해시>'

  2. 파일을 저장하고 PostgreSQL에서 복제 사용자의 비밀번호를 변경하려면 GitLab을 다시 구성합니다: 

    sudo gitlab-ctl reconfigure

  3. 복제 비밀번호를 변경하려면 PostgreSQL을 다시 시작합니다: 

    sudo gitlab-ctl restart postgresql

secondary 사이트의 모든 데이터베이스가 비밀번호를 업데이트할 때까지 PostgreSQL 로그에는 다음과 같은 오류 메시지가 표시됩니다: 

FATAL:  could not connect to the primary server: FATAL:  password authentication failed for user "gitlab_replicator"

모든 GitLab Geo secondary 사이트에서:

  1. 구성 관점에서는 첫 번째 단계가 필요하지 않습니다. 왜냐하면 해시된 'sql_replication_password'는 secondary 사이트에서 사용되지 않기 때문입니다. 그러나 secondary 사이트를 GitLab Geo primary으로 승격해야 하는 경우를 대비하여 secondary 사이트 구성에서 'sql_replication_password'를 일치시키도록 주의하세요.

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

    # `gitlab-ctl pg-password-md5 gitlab_replicator`로 생성된 해시로 채웁니다
postgresql['sql_replication_password'] = '<귀하의_복제_비밀번호의_md5_해시>'

  2. 초기 복제 설정 중에 gitlab-ctl replicate-geo-database 명령은 복제 사용자 계정의 평문 비밀번호를 두 위치에 작성합니다:

    • gitlab-geo.conf: 기본적으로 /var/opt/gitlab/postgresql/data/gitlab-geo.conf에 PostgreSQL 데이터 디렉토리에 작성되는 PostgreSQL 복제 프로세스에서 사용됩니다.
    • .pgpass: 기본적으로 /var/opt/gitlab/postgresql/.pgpass에 위치한 gitlab-psql 사용자에서 사용됩니다.

    이 두 파일의 평문 비밀번호를 업데이트하고 PostgreSQL을 다시 시작합니다: 

    sudo gitlab-ctl restart postgresql

Multi-node database replication

단일 PostgreSQL 노드를 Patroni로 마이그레이션

Patroni 도입 이전에 Geo는 secondary 사이트에서의 HA(High Availability) 설정에 대한 리눅스 패키지 설치를 지원하지 않았습니다.

Patroni를 사용하면 이제 이 지원이 가능합니다. 기존 PostgreSQL을 Patroni로 마이그레이션하려면:

  1. secondary 사이트에서 primary 사이트에서 설정한 것과 유사한 방식으로 Consul 클러스터를 설정하세요.
  2. 영구 복제 슬롯 구성.
  3. 내부 로드 밸런서 구성.
  4. PgBouncer 노드 구성.
  5. Standby Cluster 구성 단일 노드 머신에서.

이것으로 단일 노드 _Standby Cluster_가 생성됩니다. 이를 통해 동일한 지침을 따라 추가적인 Patroni 노드를 추가할 수 있습니다.

Patroni 지원

Patroni는 Geo를 위한 공식 복제 관리 솔루션입니다. Patroni는 primary 및 secondary Geo 사이트에 고가용성 클러스터를 빌드하는 데 사용될 수 있습니다. secondary 사이트에서 Patroni를 사용하는 것은 선택 사항이며 두 Geo 사이트에 동일한 수의 노드를 사용할 필요는 없습니다.

primary 사이트에 Patroni를 설정하는 방법은 관련 문서를 참조하세요.

Geo secondary 사이트를 위한 Patroni 클러스터 구성

Geo secondary 사이트에서, 주 PostgreSQL 데이터베이스는 primary 사이트의 PostgreSQL 데이터베이스의 읽기 전용 복제본입니다.

제품화에 적합하고 안전한 구성을 위해서는 적어도 다음이 필요합니다:

  • 3개의 Consul 노드 (primary 및 secondary 사이트)
  • 2개의 Patroni 노드 (primary 및 secondary 사이트)
  • 1개의 PgBouncer 노드 (primary 및 secondary 사이트)
  • 1개의 내부 로드 밸런서 (primary 사이트만)

내부 로드 밸런서는 새 리더가 선출될 때마다 Patroni 클러스터 리더에 연결하기 위한 단일 엔드포인트를 제공합니다. 이 로드 밸런서는 secondary 사이트에서의 계층화 복제를 가능하게 하는 데 필요합니다.

암호 자격 증명 및 기타 데이터베이스 베스트 프랙티스를 반드시 사용하세요.

단계 1. Primary 사이트에서 Patroni 영구 복제 슬롯 구성

Primary 데이터베이스에 영구 복제 슬롯을 설정하여 복제를 계속적으로 Primary 데이터베이스에서 Secondary 노드에 대한 Patroni 클러스터로 실행되도록 합니다.

Patroni 클러스터가 있는 Primary

secondary 사이트에서 Patroni를 사용하여 데이터베이스 복제를 설정하려면 Primary 사이트의 Patroni 클러스터에 영구 복제 슬롯을 구성하고, 암호 인증을 사용해야 합니다.

Primary 사이트의 각 Patroni 인스턴스를 실행하는 노드에서 시작하여:

  1. Patroni 인스턴스에 SSH하고 루트로 로그인합니다: 

    sudo -i

  2. /etc/gitlab/gitlab.rb를 수정하고 다음을 추가합니다: 

    roles(['patroni_role'])

consul['services'] = %w(postgresql)
consul['configuration'] = {
  retry_join: %w[CONSUL_PRIMARY1_IP CONSUL_PRIMARY2_IP CONSUL_PRIMARY3_IP]
}

# PostgreSQL slot_name 규칙에 따라 고유한 이름을 가진 각 **secondary**에 대해 하나의 항목이 필요합니다:
#
# 구성 구문: 'unique_slotname' => { 'type' => 'physical' },
# logical 복제 유형에 대한 영구 복제 슬롯 설정은 지원하지 않습니다.
patroni['replication_slots'] = {
  'geo_secondary' => { 'type' => 'physical' }
}

patroni['use_pg_rewind'] = true
patroni['postgresql']['max_wal_senders'] = 8 # patroni/예약 슬롯 수의 두 배를 사용하세요 (3 patroni + Geo **secondary**를 위한 1개의 예약 슬롯).
patroni['postgresql']['max_replication_slots'] = 8 # patroni/예약 슬롯 수의 두 배를 사용하세요 (3 patroni + Geo **secondary**를 위한 1개의 예약 슬롯).
patroni['username'] = 'PATRONI_API_USERNAME'
patroni['password'] = 'PATRONI_API_PASSWORD'
patroni['replication_password'] = '평문_POSTGRESQL_복제_비밀번호'

# allowlist에 모든 patroni 노드를 추가합니다
patroni['allowlist'] = %w[
  127.0.0.1/32
  PATRONI_PRIMARY1_IP/32 PATRONI_PRIMARY2_IP/32 PATRONI_PRIMARY3_IP/32
  PATRONI_SECONDARY1_IP/32 PATRONI_SECONDARY2_IP/32 PATRONI_SECONDARY3_IP/32
]

# 모든 secondary 인스턴스를 나열합니다. 이들은 모두 Standby Leader가 될 수 있습니다.
postgresql['md5_auth_cidr_addresses'] = %w[
  PATRONI_PRIMARY1_IP/32 PATRONI_PRIMARY2_IP/32 PATRONI_PRIMARY3_IP/32 PATRONI_PRIMARY_PGBOUNCER/32
  PATRONI_SECONDARY1_IP/32 PATRONI_SECONDARY2_IP/32 PATRONI_SECONDARY3_IP/32 PATRONI_SECONDARY_PGBOUNCER/32
]

postgresql['pgbouncer_user_password'] = 'PGBOUNCER_PASSWORD_HASH'
postgresql['sql_replication_password'] = 'POSTGRESQL_REPLICATION_PASSWORD_HASH'
postgresql['sql_user_password'] = 'POSTGRESQL_PASSWORD_HASH'
postgresql['listen_address'] = '0.0.0.0' # 여기에 공용 또는 VPC 주소를 사용할 수 있습니다

  3. 변경 사항이 적용되도록 GitLab을 다시 구성합니다: 

    gitlab-ctl reconfigure
단일 PostgreSQL 인스턴스가 있는 Primary

단일 노드 인스턴스에 SSH하고 루트로 로그인합니다: 

   sudo -i

  1. /etc/gitlab/gitlab.rb를 수정하고 다음을 추가합니다: 

    postgresql['max_wal_senders'] = 2 # 2개씩 secondary 사이트에 사용 (초기 Patroni 복제를 위한 임시 슬롯 1개 + Geo **secondary**를 위한 예약 슬롯 1개)
postgresql['max_replication_slots'] = 2 # 2개씩 secondary 사이트에 사용 (초기 Patroni 복제를 위한 임시 슬롯 1개 + Geo **secondary**를 위한 예약 슬롯 1개)

  2. GitLab을 다시 구성합니다: 

    gitlab-ctl reconfigure

  3. PostgreSQL 서비스를 다시 시작하여 새로운 변경 사항이 적용되도록 합니다: 

    gitlab-ctl restart postgresql

  4. 데이터베이스 콘솔을 시작합니다: 

    gitlab-psql

  5. Primary 사이트에서 영구 복제 슬롯을 설정합니다: 

    select pg_create_physical_replication_slot('geo_secondary')

  6. 옵션: primary가 PgBouncer를 가지고 있지 않으나 secondary가 있다면:

    pgbouncer 사용자를 primary 사이트에 구성하고 리눅스 패키지에 포함된 PgBouncer를 위한 필요한 pg_shadow_lookup 함수를 추가합니다. 두 서버의 PgBouncer가 여전히 secondary 사이트의 PostgreSQL 노드에 연결할 수 있어야 합니다. 

    --- 새 사용자 'pgbouncer' 생성
CREATE USER pgbouncer;

--- 비밀번호 설정/변경하고 복제 권한 부여
ALTER USER pgbouncer WITH REPLICATION ENCRYPTED PASSWORD '<secondary로부터_얻은_pgbouncer_비밀번호>';

CREATE OR REPLACE FUNCTION public.pg_shadow_lookup(in i_username text, out username text, out password text) RETURNS record AS $$
BEGIN
    SELECT usename, passwd FROM pg_catalog.pg_shadow
    WHERE usename = i_username INTO username, password;
    RETURN;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

REVOKE ALL ON FUNCTION public.pg_shadow_lookup(text) FROM public, pgbouncer;
GRANT EXECUTE ON FUNCTION public.pg_shadow_lookup(text) TO pgbouncer;
단계 2. 기본 사이트에서 내부 로드 밸런서 구성

기본 사이트에서 새로운 리더가 선출될 때마다 보조 리더를 다시 구성하지 않으려면 TCP 내부 로드 밸런서를 설정해야 합니다. 이 로드 밸런서는 Patroni 클러스터의 리더에 연결하기 위한 단일 엔드포인트를 제공합니다.

Linux 패키지에는 로드 밸런서가 포함되어 있지 않습니다. HAProxy를 사용하여 수행할 수 있습니다.

다음 IP와 이름은 예시로 사용됩니다: - 10.6.0.21: Patroni 1 (patroni1.internal) - 10.6.0.22: Patroni 2 (patroni2.internal) - 10.6.0.23: Patroni 3 (patroni3.internal) 

global
    log /dev/log local0
    log localhost local1 notice
    log stdout format raw local0

defaults
    log global
    default-server inter 3s fall 3 rise 2 on-marked-down shutdown-sessions

frontend internal-postgresql-tcp-in
    bind *:5432
    mode tcp
    option tcplog

    default_backend postgresql

backend postgresql
    mode tcp
    option httpchk
    http-check expect status 200

    server patroni1.internal 10.6.0.21:5432 maxconn 100 check port 8008
    server patroni2.internal 10.6.0.22:5432 maxconn 100 check port 8008
    server patroni3.internal 10.6.0.23:5432 maxconn 100 check port 8008

자세한 안내는 선호하는 로드 밸런서에 대한 설명서를 참조하세요.

단계 3. 보조 사이트에서 PgBouncer 노드 구성

운영준비 상태이고 고가용성이 확보된 구성에는 최소한 세 개의 Consul 노드와 최소한 하나의 PgBouncer 노드가 필요합니다. 그러나 데이터베이스 노드 당 하나의 PgBouncer 노드를 갖는 것이 권장됩니다. 둘 이상의 PgBouncer 서비스 노드가 있는 경우 내부 로드 밸런서 (TCP)가 필요합니다. 내부 로드 밸런서는 PgBouncer 클러스터에 연결하기 위한 단일 엔드포인트를 제공합니다. 자세한 정보는 관련 문서를 참조하세요.

보조 사이트의 각 PgBouncer 인스턴스를 실행하는 노드에서:

  1. PgBouncer 노드로 SSH 연결하고 루트로 로그인합니다: 

    sudo -i

  2. /etc/gitlab/gitlab.rb를 편집하고 다음을 추가합니다: 

    # Pgbouncer 및 Consul 에이전트 이외의 모든 구성 요소를 비활성화합니다
roles(['pgbouncer_role'])

# PgBouncer 구성
pgbouncer['admin_users'] = %w(pgbouncer gitlab-consul)
pgbouncer['users'] = {
'gitlab-consul': {
   # 다음으로 생성: `gitlab-ctl pg-password-md5 gitlab-consul`
   password: 'GITLAB_CONSUL_PASSWORD_HASH'
 },
  'pgbouncer': {
    # 다음으로 생성: `gitlab-ctl pg-password-md5 pgbouncer`
    password: 'PGBOUNCER_PASSWORD_HASH'
  }
}

# Consul 구성
consul['watchers'] = %w(postgresql)
consul['configuration'] = {
  retry_join: %w[CONSUL_SECONDARY1_IP CONSUL_SECONDARY2_IP CONSUL_SECONDARY3_IP]
}
consul['monitoring_service_discovery'] =  true

  3. 변경 사항이 적용되도록 GitLab을 다시 구성합니다: 

    gitlab-ctl reconfigure

  4. .pgpass 파일을 생성하여 Consul이 PgBouncer를 다시로드할 수 있도록 합니다. 질문 받을 때 PLAIN_TEXT_PGBOUNCER_PASSWORD를 두 번 입력합니다: 

    gitlab-ctl write-pgpass --host 127.0.0.1 --database pgbouncer --user pgbouncer --hostuser gitlab-consul

  5. PgBouncer 서비스를 다시로드합니다: 

    gitlab-ctl hup pgbouncer
단계 4. 보조 사이트에서 Standby 클러스터 구성

참고: 단일 PostgreSQL 인스턴스가 있는 보조 사이트를 Patroni 클러스터로 변환하는 경우, 먼저 PostgreSQL 인스턴스에서 시작해야 합니다. 이 인스턴스는 Patroni Standby 리더 인스턴스가 되며 필요한 경우 다른 복제본으로 전환할 수 있습니다.

보조 사이트에서 Patroni 인스턴스를 실행하는 각 노드에서:

  1. Patroni 노드로 SSH 연결하고 루트로 로그인합니다: 

    sudo -i

  2. /etc/gitlab/gitlab.rb를 편집하고 다음을 추가합니다: 

    roles(['consul_role', 'patroni_role'])

consul['enable'] = true
consul['configuration'] = {
  retry_join: %w[CONSUL_SECONDARY1_IP CONSUL_SECONDARY2_IP CONSUL_SECONDARY3_IP]
}
consul['services'] = %w(postgresql)

postgresql['md5_auth_cidr_addresses'] = [
  'PATRONI_SECONDARY1_IP/32', 'PATRONI_SECONDARY2_IP/32', 'PATRONI_SECONDARY3_IP/32', 'PATRONI_SECONDARY_PGBOUNCER/32',
  # 설명서대로 데이터베이스에 액세스해야 하는 다른 인스턴스
]


# allowlist에 patroni 노드 추가
patroni['allowlist'] = %w[
  127.0.0.1/32
  PATRONI_SECONDARY1_IP/32 PATRONI_SECONDARY2_IP/32 PATRONI_SECONDARY3_IP/32
]

patroni['standby_cluster']['enable'] = true
patroni['standby_cluster']['host'] = 'INTERNAL_LOAD_BALANCER_PRIMARY_IP'
patroni['standby_cluster']['port'] = INTERNAL_LOAD_BALANCER_PRIMARY_PORT
patroni['standby_cluster']['primary_slot_name'] = 'geo_secondary' # 또는 이전에 설정한 고유한 복제 슬롯 이름
patroni['username'] = 'PATRONI_API_USERNAME'
patroni['password'] = 'PATRONI_API_PASSWORD'
patroni['replication_password'] = 'PLAIN_TEXT_POSTGRESQL_REPLICATION_PASSWORD'
patroni['use_pg_rewind'] = true
patroni['postgresql']['max_wal_senders'] = 5 # 복제본 당 최소 세 개, 추가 복제본 당 두 개
patroni['postgresql']['max_replication_slots'] = 5 # 복제본 당 최소 세 개, 추가 복제본 당 두 개

postgresql['pgbouncer_user_password'] = 'PGBOUNCER_PASSWORD_HASH'
postgresql['sql_replication_password'] = 'POSTGRESQL_REPLICATION_PASSWORD_HASH'
postgresql['sql_user_password'] = 'POSTGRESQL_PASSWORD_HASH'
postgresql['listen_address'] = '0.0.0.0' # 여기에는 공용 또는 VPC 주소를 사용할 수 있습니다.

gitlab_rails['db_password'] = 'POSTGRESQL_PASSWORD'
gitlab_rails['enable'] = true
gitlab_rails['auto_migrate'] = false

    patroni['standby_cluster']['host'] 및 patroni['standby_cluster']['port']를 구성할 때: - INTERNAL_LOAD_BALANCER_PRIMARY_IP은 기본 내부 로드 밸런서 IP를 가리켜야 합니다. - INTERNAL_LOAD_BALANCER_PRIMARY_PORT는 기본 Patroni 클러스터 리더에 대해 구성된 프론트엔드 포트를 가리켜야 합니다. PgBouncer 프론트엔드 포트를 사용하면 안 됩니다.

  3. 변경 사항이 적용되도록 GitLab을 다시 구성합니다. 이 단계는 PostgreSQL 사용자와 설정을 시작하는 데 필요합니다.

    • Patroni를 처음 설치하는 경우: 

      gitlab-ctl reconfigure

    • 이전에 작동하던 Patroni 클러스터가 있는 사이트에 보조 클러스터를 구성하는 경우:

      1. Patroni가 관리하는 모든 노드에서 Patroni를 중지합니다(포함하여 cascade 복제본): 

        gitlab-ctl stop patroni

      2. 새로운 보조 클러스터를 재생성하기 위해 리더 Patroni 노드에서 다음을 실행합니다: 

        rm -rf /var/opt/gitlab/postgresql/data
/opt/gitlab/embedded/bin/patronictl -c /var/opt/gitlab/patroni/patroni.yaml remove postgresql-ha
gitlab-ctl reconfigure

      3. 복제 과정을 시작하기 위해 리더 Patroni 노드에서 Patroni를 시작합니다: 

        gitlab-ctl start patroni

      4. 클러스터 상태를 확인합니다: 

        gitlab-ctl patroni members

        다음을 확인하세요: - 현재 Patroni 노드가 출력에 표시됩니다. - 역할이 Standby Leader로 표시됩니다. 초기에는 Replica로 표시될 수 있습니다. - 상태가 Running으로 표시됩니다. 초기에는 Creating replica로 표시될 수 있습니다.

        노드 역할이 Standby Leader로 안정화되고 상태가 Running으로 표시될 때까지 기다립니다. 이 과정에는 몇 분이 걸릴 수 있습니다.

      5. 리더 Patroni 노드에서 Standby Leader이 되고 Running 상태인 경우, 보조 클러스터 내의 다른 Patroni 노드에서 Patroni를 시작합니다: 

        gitlab-ctl start patroni

        다른 Patroni 노드는 자동으로 새로운 보조 클러스터에 복제본으로 가입하고 리더 Patroni 노드부터 복제를 시작해야 합니다.

  4. 클러스터 상태를 확인합니다: 

    gitlab-ctl patroni members

    모든 Patroni 노드가 Running 상태로 나열되는지 확인하세요. Standby Leader 노드와 여러 Replica 노드가 있어야 합니다.

단일 추적 데이터베이스 노드를 Patroni로 이관

Patroni가 도입되기 전에 Geo는 HA 설정에서의 Linux 패키지 설치를 지원하지 않았습니다.

Patroni를 사용하면 이제 HA 설정을 지원할 수 있습니다. 그러나 Patroni의 일부 제한 사항으로 인해 동일한 머신에서 두 개의 다른 클러스터를 관리할 수 없습니다. 새로운 추적 데이터베이스를 위해 동일한 지침에 따라 새 Patroni 클러스터를 설정해야 합니다.

보조 노드는 새 추적 데이터베이스를 백필하며 데이터 동기화가 필요하지 않습니다.

추적 PostgreSQL 데이터베이스를 위한 Patroni 클러스터 구성

보조 Geo 사이트는 별도의 PostgreSQL 설치를 사용하여 복제 상태를 추적하고 잠재적인 복제 문제에서 자동으로 복구합니다.

Geo 추적 데이터베이스를 단일 노드에서 실행하려면 Geo 보조 사이트에서 Geo 추적 데이터베이스 구성를 참조하세요.

Linux 패키지는 Geo 추적 데이터베이스를 고가용성 구성에서 실행하는 것을 지원하지 않습니다. 특히 장애 조치가 제대로 작동하지 않습니다. 기능 요청 이슈를 확인하세요.

Geo 추적 데이터베이스를 고가용성 구성에서 실행하려면 보조 사이트를 외부 PostgreSQL 데이터베이스(예: 클라우드 관리형 데이터베이스) 또는 GitLab Linux 패키지로 관리되지 않는 수동으로 구성한 Patroni 클러스터에 연결할 수 있습니다. 외부 PostgreSQL 인스턴스와 함께 Geo 사용를 참조하세요.

문제 해결

문제 해결 문서를 참조하세요.