데이터베이스 설정

Tier: Free, Premium, Ultimate Offering: Self-Managed

GitLab은 PostgreSQL 데이터베이스 관리 시스템만을 지원합니다.

따라서 Linux 패키지 설치와 함께 사용할 데이터베이스 서버 옵션은 두 가지가 있습니다:

  • Linux 패키지 설치에 포함된 패키지형 PostgreSQL 서버 사용(구성 필요 없음, 권장).
  • 외부 PostgreSQL 서버 사용.

Linux 패키지와 함께 제공되는 PostgreSQL 데이터베이스 서비스 사용

다시 구성 및 PostgreSQL 재시작

Linux 패키지 설치는 일반적으로 gitlab.rb 파일에서 해당 서비스의 구성 설정이 변경된 경우, 다시 구성시 해당 서비스를 자동으로 재시작합니다. PostgreSQL은 일부 설정이 재로딩(HUP)을 통해 적용되고, 일부는 PostgreSQL을 재시작해야만 합니다. 따라서 PostgreSQL을 원하는 시점에 직접 재시작할 수 있도록 Linux 패키지 설치는 재구성시 PostgreSQL을 재시작하는 대신 재로딩합니다. 이는 PostgreSQL을 다시 시작해야 하는 설정을 변경한다면, PostgreSQL을 재구성 후 매뉴얼으로 재시작해야 한다는 것을 의미합니다.

GitLab 구성 템플릿에서 어떤 PostgreSQL 설정이 재시작을 필요로 하는지, 그리고 재로딩만 필요로 하는지 확인할 수 있습니다. 또한 다음 쿼리를 실행하여 변경하려는 개별 설정이 재시작이 필요한지 확인할 수 있습니다. sudo gitlab-psql을 사용하여 데이터베이스 콘솔을 시작한 후, 다음 쿼리에서 <setting name>을 변경하는 설정 이름으로 바꿉니다. 

SELECT name,setting FROM pg_settings WHERE context = 'postmaster' AND name = '<setting name>';

설정을 변경할 경우, 쿼리는 실행 중인 PostgreSQL 인스턴스에서 해당 설정의 이름과 현재 값으로 결과를 반환합니다.

PostgreSQL 버전 변경시 자동 재시작

기본적으로 Linux 패키지 설치는 PostgreSQL의 기초 버전 변경이 감지되면 PostgreSQL을 자동으로 재시작합니다. 이 동작은 postgresql 및 geo-postgresql에서 제공되는 auto_restart_on_version_change 설정을 통해 제어할 수 있습니다.

PostgreSQL 버전 변경시 자동 재시작을 비활성화하려면:

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

    # For PostgreSQL/Patroni
postgresql['auto_restart_on_version_change'] = false
   
# For Geo PostgreSQL
geo_postgresql['auto_restart_on_version_change'] = false

  2. GitLab을 재구성합니다: 

    sudo gitlab-ctl reconfigure
note
기초 버전 변경시 PostgreSQL을 재시작하는 것을 권장하며, 그렇지 않을 경우 필요한 라이브러리를 로드하는 문제와 같은 오류가 발생할 수 있습니다.

SSL 구성

Linux 패키지 설치는 기본적으로 PostgreSQL 서버에서 SSL을 자동으로 활성화하지만, 기본적으로 암호화된 및 암호화되지 않은 연결을 모두 허용합니다. SSL을 강제하려면 pg_hba.conf에서 hostssl 구성을 사용해야 합니다. 자세한 내용은 pg_hba.conf 문서를 참조하세요.

SSL 지원은 다음 파일에 의존합니다:

  • 데이터베이스의 공개 SSL 인증서(server.crt).
  • SSL 인증서에 대한 해당 개인 키(server.key).
  • 서버의 인증서를 검증하는 루트 인증서 번들 (root.crt). Linux 패키지 설치는 기본적으로 /opt/gitlab/embedded/ssl/certs/cacert.pem에 포함된 내장된 인증서 번들을 사용합니다. 이는 자체 서명된 인증서에는 필요하지 않습니다.

Linux 패키지 설치에서는 사용되도록 10년 유효 기간의 자체 서명된 인증서와 개인 키가 생성됩니다. CA로 서명된 인증서를 사용하거나 자체 서명된 인증서로 교체하려면 다음 단계를 따르세요.

이 파일들의 위치는 구성 가능하지만, 개인 키는 반드시 gitlab-psql 사용자가 읽을 수 있어야 합니다. Linux 패키지 설치는 파일의 권한을 관리하지만, 경로가 사용자 정의된 경우 반드시 gitlab-psql이 액세스할 수 있는지 확인해야 합니다.

자세한 내용은 PostgreSQL 문서를 참조하세요.

server.crt 및 server.key는 GitLab에 액세스하는데 사용되는 기본 SSL 인증서와 다를 수 있습니다. 예를 들어, 데이터베이스의 외부 호스트 이름이 database.example.com이고 외부 GitLab 호스트 이름이 gitlab.example.com이라면 *.example.com에 대한 와일드카드 인증서나 두 개의 다른 SSL 인증서가 필요합니다.

ssl_cert_file, ssl_key_file, ssl_ca_file 파일은 PostgreSQL에 인증서, 키, 번들을 어디서 찾을지 지시합니다. 이러한 변경은 postgresql.conf에 적용됩니다. internal_certificate와 internal_key 지시문은 이러한 파일의 내용을 채우는 데 사용됩니다. 내용은 직접 추가하거나 다음 예제와 같이 파일에서 로드할 수 있습니다.

이 파일들을 보유한 후 SSL을 활성화하세요:

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

    postgresql['ssl_cert_file'] = '/custom/path/to/server.crt'
postgresql['ssl_key_file'] = '/custom/path/to/server.key'
postgresql['ssl_ca_file'] = '/custom/path/to/bundle.pem'
postgresql['internal_certificate'] = File.read('/custom/path/to/server.crt')
postgresql['internal_key'] = File.read('/custom/path/to/server.key')

    상대 경로는 기본적으로 PostgreSQL 데이터 디렉터리(/var/opt/gitlab/postgresql/data)를 기준으로 설정됩니다.

  2. 설정 변경을 적용하기 위해 GitLab을 재구성합니다.

  3. 변경사항이 적용되도록 PostgreSQL을 재시작합니다: 

    gitlab-ctl restart postgresql

    PostgreSQL이 시작하지 않으면 자세한 내용을 확인하려면 로그(예: /var/log/gitlab/postgresql/current)를 확인하세요.

SSL 필요 여부

  1. /etc/gitlab/gitlab.rb에 다음을 추가합니다: 

     gitlab_rails['db_sslmode'] = 'require'

  2. 설정 변경을 적용하기 위해 GitLab을 재구성합니다.

  3. 변경사항이 적용되도록 PostgreSQL을 재시작합니다: 

    gitlab-ctl restart postgresql

    PostgreSQL이 시작하지 않으면 자세한 내용을 확인하려면 로그(예: /var/log/gitlab/postgresql/current)를 확인하세요.

SSL 비활성화

  1. /etc/gitlab/gitlab.rb에 다음을 추가합니다: 

    postgresql['ssl'] = 'off'

  2. 설정 변경을 적용하기 위해 GitLab을 재구성합니다.

  3. 변경사항이 적용되도록 PostgreSQL을 재시작합니다: 

    gitlab-ctl restart postgresql

    PostgreSQL이 시작하지 않으면 자세한 내용을 확인하려면 로그(예: /var/log/gitlab/postgresql/current)를 확인하세요.

SSL 사용 여부 확인

클라이언트가 SSL을 사용하는지 여부를 확인하려면 다음을 실행하세요: 

sudo gitlab-rails dbconsole --database main

시작시, 다음과 같은 배너가 표시됩니다: 

psql (13.14)
SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: on)
Type "help" for help.

클라이언트가 SSL을 사용하는지 확인하려면 다음 SQL 쿼리를 실행하세요: 

SELECT * FROM pg_stat_ssl;

예시: 

gitlabhq_production=> select * from pg_stat_ssl;
 pid  | ssl | version |         cipher         | bits | compression |  clientdn
------+-----+---------+------------------------+------+-------------+------------
  384 | f   |         |                        |      |             |
  386 | f   |         |                        |      |             |
  998 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
  933 | f   |         |                        |      |             |
 1003 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
 1016 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
 1022 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
 1211 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
 1214 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
 1213 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
 1215 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
 1252 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           |
 1280 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
  382 | f   |         |                        |      |             |
  381 | f   |         |                        |      |             |
  383 | f   |         |                        |      |             |
(16 rows)
  1. ssl 열에서 t로 나열된 행은 활성화된 상태입니다.
  2. clientdn에 값이 있는 행은 cert 인증 방법을 사용 중입니다.

SSL 클라이언트 인증 구성

클라이언트 SSL 인증서를 사용하여 데이터베이스 서버에 인증할 수 있습니다. 인증서를 생성하는 것은 omnibus-gitlab의 범위를 벗어납니다. 그러나 기존의 SSL 인증서 관리 솔루션을 사용할 수 있는 사용자는 이를 사용할 수 있습니다.

데이터베이스 서버 구성
  1. 서버용 인증서 및 키를 생성하십시오. 공통 이름은 서버의 DNS 이름과 같아야 합니다.
  2. 서버 인증서, 키 및 CA 파일을 PostgreSQL 서버로 복사하고, 권한이 올바른지 확인하십시오.
    1. 인증서는 데이터베이스 사용자(기본값: gitlab-psql)에 의해 소유되어야 합니다.
    2. 키 파일은 데이터베이스 사용자에 의해 소유되어야 하며 권한은 0400이어야 합니다.
    3. CA 파일은 데이터베이스 사용자에 의해 소유되어야 하며 권한은 0400이어야 합니다.
    note
    이러한 파일 이름을 server.crt 또는 server.key로 사용하지 마십시오. 이러한 파일 이름은 omnibus-gitlab의 내부 사용을 위해 예약되어 있습니다.

  3. 다음이 gitlab.rb에 설정되어 있는지 확인하십시오: 

    postgresql['ssl_cert_file'] = '인증서_경로'
postgresql['ssl_key_file'] = '키_파일_경로'
postgresql['ssl_ca_file'] = 'CA_파일_경로'
postgresql['listen_address'] = 'IP_주소'
postgresql['cert_auth_addresses'] = {
'IP_주소' => {
  'database' => 'gitlabhq_production',
  'user' => 'gitlab'
}

    listen_address를 클라이언트가 데이터베이스에 연결하는 데 사용할 서버의 IP 주소로 설정하십시오. cert_auth_addresses에는 데이터베이스에 연결할 수 있는 IP 주소 및 사용자가 포함된 디렉터리이 있어야 합니다. cert_auth_addresses의 키를 지정할 때 CIDR 표기법을 사용하여 IP 주소 범위를 포함할 수 있습니다.

  4. gitlab-ctl reconfigure를 실행한 후 변경된 설정이 적용되도록 gitlab-ctl restart postgresql를 실행하십시오.

레일스 클라이언트 구성

레일스 클라이언트가 서버에 연결하려면, ssl_ca_file에 지정된 CA 파일에서 신뢰하는 인증 기관에 의해 서명된 commonName으로 설정된 인증서와 키가 필요합니다.

  1. gitlab.rb 구성 

    gitlab_rails['db_host'] = '데이터베이스_서버의_IP_주소_또는_호스트_이름'
gitlab_rails['db_sslcert'] = '인증서_파일_경로'
gitlab_rails['db_sslkey'] = '키_파일_경로'
gitlab_rails['db_rootcert'] = 'CA_파일_경로'
  2. 레일스 클라이언트가 새 설정을 사용하도록 하려면 gitlab-ctl reconfigure를 실행하십시오.
  3. SSL이 사용되고 있는지 확인하기 위해 SSL 사용 여부 확인 단계를 따르십시오.

패키지된 PostgreSQL 서버를 TCP/IP로 수신 대기하도록 구성

패키지된 PostgreSQL 서버는 일부 비핵심 스크립트가 UNIX 소켓을 기대하고 문제가 발생할 수 있음에 유의하여 TCP/IP 연결을 수신 대기하도록 구성할 수 있습니다.

데이터베이스 서비스에 대한 TCP/IP 사용을 구성하려면 gitlab.rb의 postgresql 및 gitlab_rails 섹션 모두를 변경하십시오.

PostgreSQL 블록 구성

postgresql 블록에서 다음 설정이 영향을 받습니다:

  • listen_address: PostgreSQL이 수신 대기할 주소를 제어합니다.
  • port: PostgreSQL이 수신 대기할 포트를 제어합니다. 기본값은 5432입니다.
  • md5_auth_cidr_addresses: 비밀번호로 인증된 후 서버에 연결할 수 있는 CIDR 주소 블록 디렉터리입니다.
  • trust_auth_cidr_addresses: 어떠한 형태의 인증도 없이 서버에 연결할 수 있는 CIDR 주소 블록 디렉터리입니다. 이 설정은 GitLab 레일스 또는 Sidekiq과 같은 노드에서의 연결을 허용하기 위해 설정해야 합니다. 이는 동일한 노드에 배포되었거나 Postgres Exporter와 같은 컴포넌트로부터의 로컬 연결을 포함합니다(127.0.0.1/32 포함).
  • sql_user: MD5 인증을 위해 예상되는 사용자명을 제어합니다. 기본값은 gitlab이며 필수 설정은 아닙니다.
  • sql_user_password: PostgreSQL이 MD5 인증을 위해 허용할 비밀번호를 설정합니다. 다음 예제에서 securesqlpassword를 적절한 비밀번호로 바꿉니다.

  1. /etc/gitlab/gitlab.rb 파일을 편집하십시오: 

    postgresql['listen_address'] = '0.0.0.0'
postgresql['port'] = 5432
postgresql['md5_auth_cidr_addresses'] = %w()
postgresql['trust_auth_cidr_addresses'] = %w(127.0.0.1/24)
postgresql['sql_user'] = "gitlab"
   
##! SQL_USER_PASSWORD_HASH는 `gitlab-ctl pg-password-md5 'gitlab'` 명령을 사용하여 생성할 수 있습니다.
##! 여기서 'gitlab'은 GitLab에 연결하는 SQL 사용자의 이름입니다(쉘 보간을 피하기 위해 'gitlab'을 따옴표로 감쌉니다).
postgresql['sql_user_password'] = "SQL_USER_PASSWORD_HASH"
   
# trust_auth_cidr_addresses 및 md5_auth_cidr_addresses에 정의된 모든 연결에 대해 모든 연결을 강제로 ssl로 설정합니다.
postgresql['hostssl'] = true

  2. GitLab을 재구성하고 PostrgreSQL을 다시 시작합니다: 

    sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart postgresql

네트워크를 통해 연결할 모든 클라이언트 또는 GitLab 서비스에서는 사용자명으로 sql_user 값과 PostgreSQL 서버에 연결할 때 구성에 제공된 비밀번호의 값이 필요합니다. 또한 md5_auth_cidr_addresses 블록에서 제공된 인스턴스에서 127.0.0.1로 연결하고 postgresql['trust_auth_cidr_addresses']를 구성했다면 비밀번호가 필요하지 않습니다.

GitLab Rails 블록 구성

gitlab-rails 응용 프로그램이 네트워크를 통해 PostgreSQL 데이터베이스에 연결하도록하려면 여러 설정이 구성되어야 합니다:

  • db_host: 데이터베이스 서버의 IP 주소로 설정해야 합니다. 이것이 PostgreSQL 서비스가 있는 동일한 인스턴스인 경우, 127.0.0.1이 될 수 있습니다. 또한 비밀번호 인증이 필요하지 않습니다.
  • db_port: 연결할 PostgreSQL 서버의 포트를 설정하며 db_host가 설정된 경우 _필수_입니다.
  • db_username: PostgreSQL에 연결하기 위해 구성하는 사용자명입니다. 기본값은 gitlab입니다.
  • db_password: TCP/IP를 통해 PostgreSQL에 연결하려면 postgresql['md5_auth_cidr_addresses'] 블록에서 제공한 인스턴스에서 필요하며, 위의 설정에서 postgresql['trust_auth_cidr_addresses']에 포함되어 있지 않습니다.

  1. /etc/gitlab/gitlab.rb 파일을 편집하십시오: 

    gitlab_rails['db_host'] = '127.0.0.1'
gitlab_rails['db_port'] = 5432
gitlab_rails['db_username'] = "gitlab"
gitlab_rails['db_password'] = "securesqlpassword"

  2. GitLab을 재구성하고 PostrgreSQL을 다시 시작합니다: 

    sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart postgresql

설정 적용 및 서비스 재시작

이전 변경을 적용한 후, 관리자는 gitlab-ctl reconfigure을 실행해야 합니다. TCP에서 수신 대기 중인 서비스에 문제가 있는 경우, gitlab-ctl restart postgresql로 직접 서비스를 다시 시작하는 것을 시도해 보세요.

Linux 패키지에 포함된 스크립트(예: gitlab-psql) 중 일부는 PostgreSQL에 대한 연결을 UNIX 소켓을 통해 처리하도록 예상하며 정상적으로 작동하지 않을 수 있습니다. TCP/IP를 활성화하고 UNIX 소켓을 비활성화하지 않고도 TCP/IP를 사용할 수 있습니다.

PostgreSQL WAL (Write Ahead Log) 아카이빙 활성화

기본적으로, 패키지된 PostgreSQL의 WAL (Write Ahead Log) 아카이빙은 비활성화되어 있습니다. WAL 아카이빙을 활성화하려면 다음 사항을 고려해야 합니다.

  • WAL 레벨은 ‘replica’ 이상이어야 합니다 (9.6+ 옵션은 minimal, replica, 또는 logical 입니다).
  • WAL 레벨을 높이면 보통의 작업에서 사용되는 저장 공간의 양이 증가합니다.

WAL 아카이빙을 활성화하려면 다음을 수행하세요:

  1. /etc/gitlab/gitlab.rb 파일을 편집합니다. 

    # 복제 설정
postgresql['sql_replication_user'] = "gitlab_replicator"
postgresql['wal_level'] = "replica"
    ...
    ...
# 백업/아카이브 설정
postgresql['archive_mode'] = "on"
postgresql['archive_command'] = "/your/wal/archiver/here"
postgresql['archive_timeout'] = "60"

  2. 변경 사항이 적용되려면 GitLab 재구성을 수행하세요. 이로 인해 데이터베이스가 재시작됩니다.

PostgreSQL 데이터를 다른 디렉터리에 저장

기본적으로 모든 것이 /var/opt/gitlab/postgresql 하위에 저장되며, postgresql['dir'] 속성으로 제어됩니다.

여기에는 다음이 포함됩니다.

  • 데이터베이스 소켓은 /var/opt/gitlab/postgresql/.s.PGSQL.5432가 됩니다. 이는 postgresql['unix_socket_directory']로 제어됩니다.
  • gitlab-psql 시스템 사용자의 HOME 디렉터리가 여기로 설정됩니다. 이는 postgresql['home']에 의해 제어됩니다.
  • 실제 데이터는 /var/opt/gitlab/postgresql/data에 저장됩니다.

PostgreSQL 데이터의 위치를 변경하려면

caution
기존 데이터베이스가 있는 경우, 먼저 데이터를 새 위치로 이동해야 합니다.
caution
이는 침입적인 작업입니다. 기존 설치에서 다운타임 없이 수행할 수 없습니다.
  1. 기존 설치인 경우 GitLab을 중지합니다: gitlab-ctl stop.
  2. postgresql['dir']를 원하는 위치로 업데이트합니다.
  3. gitlab-ctl reconfigure를 실행합니다.
  4. GitLab을 시작합니다: gitlab-ctl start.

패키지된 PostgreSQL 서버 업그레이드

Linux 패키지는 gitlab-ctl pg-upgrade 명령을 제공하여 패키지된 PostgreSQL 서버를 나중 버전으로 업데이트할 수 있습니다 (패키지에 포함된 경우). 이는 패키지 업그레이드 중에 PostgreSQL을 기본 제공된 버전으로 업데이트합니다. PostgreSQL 업그레이드를 자동으로 하지 않으려면 선택하지 않음을 참조하세요.

더 높은 버전으로 GitLab을 업그레이드하기 전에 Linux 패키지의 특정 변경 사항을 확인하려면:

  • 데이터베이스 버전이 변경된 경우
  • 업그레이드가 필요한 경우
caution
업그레이드 전에 어떤 명령도 실행하기 전에 본 섹션을 완전히 읽는 것이 중요합니다. 단일 노드 설치의 경우, 데이터베이스는 업그레이드가 수행되는 동안 다운타임이 필요합니다. 시간은 데이터베이스 크기에 따라 다릅니다.
note
업그레이드 중에 문제가 발생하면, 완전한 설명과 함께 이슈를 omnibus-gitlab 이슈 트래커에 제기하십시오.

PostgreSQL 버전을 업그레이드하려면 다음을 확인하세요:

  • 현재 PostgreSQL 버전을 지원하는 GitLab의 최신 버전을 실행 중입니다.
  • 최근에 업그레이드한 경우, 진행하기 전에 sudo gitlab-ctl reconfigure를 성공적으로 실행했습니다.

  • 데이터베이스의 두 개의 사본에 충분한 디스크 공간이 있는지 확인합니다. 충분한 여유 공간이 없는 경우 업그레이드를 시도하지 마십시오.

    • 다음 명령을 사용하여 데이터베이스 크기를 확인합니다: sudo du -sh /var/opt/gitlab/postgresql/data (또는 데이터베이스 경로를 업데이트합니다).
    • sudo df -h를 사용하여 사용 가능한 공간을 확인합니다. 데이터베이스가 있는 파티션에 충분한 공간이 없는 경우, 명령에 --tmp-dir $DIR 인수를 전달하십시오. 업그레이드 작업에는 사용 가능한 디스크 공간 검사가 포함되며, 요구 사항이 충족되지 않는 경우 업그레이드가 중지됩니다.

위의 체크리스트를 충족하는지 확인한 후, 업그레이드를 진행할 수 있습니다: 

sudo gitlab-ctl pg-upgrade

특정 PostgreSQL 버전으로 업그레이드하려면 -V 플래그를 사용하여 버전을 추가합니다. 예를 들어, PostgreSQL 14로 업그레이드하려면: 

sudo gitlab-ctl pg-upgrade -V 14
note
pg-upgrade에는 인수를 사용할 수 있습니다. 예를 들어 배후 명령 (--timeout=1d2h3m4s5ms)의 실행 시간을 설정할 수 있습니다. 전체 디렉터리을 보려면 gitlab-ctl pg-upgrade -h를 실행하십시오.

gitlab-ctl pg-upgrade는 다음 단계를 수행합니다:

  1. 데이터베이스가 알려진 좋은 상태인지 확인합니다.
  2. 충분한 여유 공간이 있는지 확인하고, 그렇지 않은 경우 중단합니다. --skip-disk-check 플래그를 추가하여 이를 건너뛸 수 있습니다.
  3. 기존 데이터베이스와 불필요한 서비스를 종료하고 GitLab deploy 페이지를 활성화합니다.
  4. PostgreSQL을 최신 버전으로 가리 킬 수 있는 /opt/gitlab/embedded/bin/의 심볼릭 링크를 변경합니다.
  5. 새로운, 빈 데이터베이스를 만들어 기존 데이터베이스와 일치하는 로캘을 가진 새로운 디렉터리를 만듭니다.
  6. pg_upgrade 도구를 사용하여 이전 데이터베이스의 데이터를 새 데이터베이스로 복사합니다.
  7. 이전 데이터베이스를 밀어버립니다.
  8. 새 데이터베이스를 예상 위치로 이동합니다.
  9. 필요한 설정 변경을 위해 sudo gitlab-ctl reconfigure를 호출하고, 새 데이터베이스 서버를 시작합니다.
  10. 데이터베이스 통계를 생성하기 위해 ANALYZE를 실행합니다.
  11. 남은 서비스를 시작하고 deploy 페이지를 제거합니다.
  12. 이 프로세스 중 오류가 감지되면 데이터베이스의 이전 버전으로 되돌립니다.

업그레이드가 완료되면 모든 것이 예상대로 작동하는지 확인하십시오.

ANALYZE 단계를 실행하는 동안 출력에 오류가 있는 경우, 업그레이드는 계속 작동하지만 데이터베이스 통계를 생성할 때까지 데이터베이스 성능이 떨어집니다. gitlab-psql을 사용하여 매뉴얼으로 ANALYZE를 실행해야 하는지 여부를 확인할 수 있습니다: 

sudo gitlab-psql -c "SELECT relname, last_analyze, last_autoanalyze FROM pg_stat_user_tables WHERE last_analyze IS NULL AND last_autoanalyze IS NULL;"

위의 쿼리가 반환된 경우 매뉴얼으로 ANALYZE를 실행할 수 있습니다: 

sudo gitlab-psql -c 'SET statement_timeout = 0; ANALYZE VERBOSE;'

GitLab 인스턴스가 올바르게 실행 중인 것을 확인한 후, 이전 데이터베이스 파일을 정리할 수 있습니다: 

sudo rm -rf /var/opt/gitlab/postgresql/data.<old_version>
sudo rm -f /var/opt/gitlab/postgresql-version.old

GitLab 버전별로 포함된 PostgreSQL 버전에 대한 자세한 내용은 리눅스 패키지로 제공된 PostgreSQL 버전에서 확인할 수 있습니다.

자동 PostgreSQL 업그레이드 선택하지 않기

GitLab 패키지 업그레이드 중에 자동 PostgreSQL 업그레이드를 선택하지 않으려면 다음을 실행하세요: 

sudo touch /etc/gitlab/disable-postgresql-upgrade

패키지된 PostgreSQL 서버를 이전 버전으로 되돌리기

caution
이 작업은 현재 데이터베이스, 데이터를 포함한, 마지막 업그레이드 이전의 상태로 되돌립니다. 패키지된 PostgreSQL 데이터베이스를 다운그레이드하기 전에 반드시 백업을 만드십시오.

패키지된 여러 PostgreSQL 버전을 제공하는 GitLab 버전에서, 사용자는 gitlab-ctl revert-pg-upgrade 명령을 사용하여 이미 업그레이드된 PostgreSQL 버전을 패키지에 함께 제공된 다른 버전으로 되돌릴 수 있습니다 (gitlab-ctl revert-pg-upgrade 명령은 -V 플래그도 지원하여 패키지에 두 개 이상의 PostgreSQL 버전이 제공될 경우 대상 버전을 지정할 수 있습니다). 예를 들어, PostgreSQL 9.6.x, 10.x, 11.x이 패키지에 제공되는 GitLab 12.8에서 12 버전의 대상 PostgreSQL 버전을 지정하려면 다음과 같이 합니다: 

gitlab-ctl revert-pg-upgrade -V 12

대상 버전이 지정되지 않으면, 이용 가능하다면 /var/opt/gitlab/postgresql-version.old에 버전이 사용됩니다. 그렇지 않은 경우, GitLab과 함께 제공된 기본 버전으로 돌아갑니다.

단 하나의 PostgreSQL 버전만을 제공하는 다른 GitLab 버전에서, PostgreSQL 버전을 다운그레이드할 수 없습니다.O만일을 위해선 GitLab을 이전 버전으로 다운그레이드해야 합니다.

다중 데이터베이스 연결 구성

GitLab 16.0에서 GitLab은 기본적으로 동일한 PostgreSQL 데이터베이스를 가리키는 두 개의 데이터베이스 연결을 사용하도록 기본 설정됩니다.

GitLab 16.0으로 업그레이드하기 전에 PostgreSQL의 max_connections 설정이 충분히 높은지 확인하여 사용 가능한 연결의 50% 이상이 미사용으로 표시되도록 합니다. 예를 들어, max_connections가 100으로 설정되어 있고 사용 중인 연결이 75개이면 업그레이드하기 전에 max_connections를 적어도 150으로 늘려야 합니다. 그 이유는 업그레이드 후에 사용 중인 연결이 150으로 두 배로 늘어날 것이기 때문입니다.

다음의 Rake 작업을 실행하여 확인할 수 있습니다: 

sudo gitlab-rake gitlab:db:decomposition:connection_status

작업에서 max_connections가 충분히 높다고 나오면 업그레이드를 진행할 수 있습니다.

패키지로 제공되는 PostgreSQL 데이터베이스 관리 서버 사용하지 않음

기본적으로 GitLab은 Linux 패키지에 포함된 PostgreSQL 서버를 사용하도록 구성되어 있습니다. 또한 외부의 PostgreSQL 인스턴스를 사용하도록 재구성할 수도 있습니다.

caution
패키지로 제공되지 않는 PostgreSQL 서버를 사용 중이라면 PostgreSQL이 데이터베이스 요구 사항 문서에 따라 설정되어 있는지 확인해야 합니다.

  1. /etc/gitlab/gitlab.rb을 편집합니다: 

    # 내장 Postgres 비활성화
postgresql['enable'] = false
   
# database.yml의 연결 세부 정보 작성
gitlab_rails['db_adapter'] = 'postgresql'
gitlab_rails['db_encoding'] = 'utf8'
gitlab_rails['db_host'] = '127.0.0.1'
gitlab_rails['db_port'] = 5432
gitlab_rails['db_username'] = '사용자이름'
gitlab_rails['db_password'] = '비밀번호'

    이러한 줄의 시작에 있는 # 주석 문자를 제거하는 것을 잊지 마십시오.

    다음 사항에 주의해야 합니다:

    • /etc/gitlab/gitlab.rb은 평문 암호를 포함하고 있기 때문에 파일 권한을 0600으로 설정해야 합니다.

    • PostgreSQL은 여러 주소에서 대기할 수 있습니다.

      gitlab_rails['db_host']에 여러 주소를 사용하는 경우 콤마로 구분하여 첫 번째 주소가 연결에 사용됩니다.

  2. 변경 사항이 적용되려면 GitLab을 재구성합니다.

  3. 데이터베이스 시드 적용.

패키지로 제공되지 않는 PostgreSQL용 UNIX 소켓 구성

GitLab과 동일한 시스템에 설치된 시스템의 PostgreSQL 서버(패키지로 제공되지 않음)를 GitLab의 번들된 PostgreSQL 대신 사용하려면 UNIX 소켓을 사용할 수 있습니다:

  1. /etc/gitlab/gitlab.rb을 편집합니다: 

    # 내장 Postgres 비활성화
postgresql['enable'] = false
   
# database.yml의 연결 세부 정보 작성
gitlab_rails['db_adapter'] = 'postgresql'
gitlab_rails['db_encoding'] = 'utf8'
# 소켓이 존재하는 경로
gitlab_rails['db_host'] = '/var/run/postgresql/'

  2. 변경 사항이 적용되려면 GitLab을 재구성합니다: 

    sudo gitlab-ctl-reconfigure

SSL 구성

SSL 필수 요구

  1. /etc/gitlab/gitlab.rb에 다음을 추가합니다: 

    gitlab_rails['db_sslmode'] = 'require'

  2. GitLab을 재구성하여 구성 변경 사항을 적용합니다.

  3. 변경 사항이 적용되려면 PostgreSQL을 다시 시작합니다: 

    gitlab-ctl restart postgresql

    PostgreSQL이 시작에 실패하는 경우 더 자세한 내용을 확인하려면 로그를 확인합니다(예: /var/log/gitlab/postgresql/current).

SSL 필수 요구 및 CA 번들로 서버 인증 확인

PostgreSQL은 스푸핑을 방지하기 위해 SSL을 필수로 요구하고 서버 인증을 CA 번들에 대해 확인하도록 구성될 수 있습니다. gitlab_rails['db_sslrootcert']에서 지정된 CA 번들에는 루트 및 중간 인증서가 모두 포함되어야 합니다.

  1. /etc/gitlab/gitlab.rb에 다음을 추가합니다: 

    gitlab_rails['db_sslmode'] = "verify-full"
gitlab_rails['db_sslrootcert'] = "<CA-번들.pem의_전체_경로>"

    Amazon RDS를 사용하여 PostgreSQL 서버를 사용하는 경우, gitlab_rails['db_sslrootcert']에 combined CA bundle을 다운로드하고 사용해야 합니다. 자세한 정보는 AWS의 DB 인스턴스에 대한 연결을 암호화하기 위한 SSL/TLS 사용 문서에서 확인할 수 있습니다.

  2. 변경 사항이 적용되려면 GitLab을 재구성합니다.

  3. 변경 사항이 적용되려면 PostgreSQL을 다시 시작합니다: 

    gitlab-ctl restart postgresql

    PostgreSQL이 시작에 실패하는 경우 더 자세한 내용을 확인하려면 로그를 확인합니다(예: /var/log/gitlab/postgresql/current).

패키지로 제공되지 않는 PostgreSQL 데이터베이스의 백업 및 복원

백업 및 복원 명령을 사용할 때 GitLab은 패키지에 포함된 pg_dump 명령 및 psql 명령을 사용하여 데이터베이스 백업 파일을 생성하고 복원하려고 시도합니다. 이는 올바른 버전인 경우에만 작동합니다. 패키지에 포함된 pg_dump와 psql의 버전을 확인합니다: 

/opt/gitlab/embedded/bin/pg_dump --version
/opt/gitlab/embedded/bin/psql --version

이러한 버전이 패키지로 제공되지 않는 외부 PostgreSQL과 다른 경우, 백업 명령을 실행하려고 시도할 때 다음과 같은 오류 출력이 발생할 수 있습니다. 

PostgreSQL 데이터베이스 gitlabhq_production 덤프... pg_dump: 오류: 서버 버전: 13.3; pg_dump 버전: 12.6
pg_dump: 오류: 서버 버전 불일치로 인한 중단

본 예시에서는 PostgreSQL 버전 13.3을 사용 중인 GitLab 14.1에서 이와 같은 오류가 발생하며, 기본으로 제공되는 PostgreSQL 버전이 여기에 나와 있는 12.6과 다릅니다.

이 경우, 데이터베이스 버전과 일치하는 도구를 설치하고 다음 단계를 따릅니다. PostgreSQL 클라이언트 도구를 설치하는 여러 가지 방법이 있습니다. 옵션은 https://www.postgresql.org/download/에서 확인할 수 있습니다.

올바른 psql 및 pg_dump 도구가 시스템에 설치된 경우, 올바른 경로를 사용하여 다음 단계를 따릅니다:

  1. 패키지로 제공되지 않는 버전에 대한 심볼릭 링크 추가: 

    ln -s /새로운/경로/에/대한/심볼릭/링크/pg_dump /새로운/경로/에/대한/심볼릭/링크/psql /opt/gitlab/bin/

  2. 버전을 확인합니다: 

    /opt/gitlab/bin/pg_dump --version
/opt/gitlab/bin/psql --version

    이제 이들은 패키지로 제공되지 않는 외부 PostgreSQL과 동일해져야 합니다.

이 작업을 완료한 후에는 백업 및 복원 작업이 올바른 실행 파일을 사용하는지 확인합니다. 백업 및 복원 명령을 실행합니다.

비포장된 PostgreSQL 데이터베이스 업그레이드

데이터베이스에 연결된 모든 프로세스(Puma, Sidekiq)를 중지한 후에 외부 데이터베이스를 업그레이드할 수 있습니다. 

sudo gitlab-ctl stop puma
sudo gitlab-ctl stop sidekiq

업그레이드를 진행하기 전에 다음 사항을 주의하세요:

  • GitLab 릴리스와 PostgreSQL 버전의 호환성을 확인하세요:
    • 최소 PostgreSQL 버전에 대한 GitLab 버전 요구 사항을 확인하세요.
    • 리눅스 패키지와 함께 제공된 PostgreSQL 버전의 중요한 변경 사항에 대해 확인하세요: 리눅스 패키지는 함께 제공된 PostgreSQL의 주요 릴리스와의 호환성이 테스트되었습니다.
  • GitLab 백업 또는 복원을 사용할 때, 동일한 GitLab 버전을 유지해야합니다. 더 높은 GitLab 버전으로 업그레이드할 계획이 있다면 먼저 PostgreSQL을 업그레이드하세요.
  • 백업 및 복원 명령을 사용하여 데이터베이스를 후속 버전의 PostgreSQL로 백업하고 복원할 수 있습니다.
  • 리눅스 패키지 릴리스에 함께 제공되지 않는 postgresql['version']과 같은 PostgreSQL 버전이 지정된 경우, 호환성 테이블에 따라 클라이언트 바이너리(예: PostgreSQL 백업/복원 바이너리)가 활성화됩니다.

다음 예제는 PostgreSQL 13에서 실행 중인 데이터베이스 호스트에서 PostgreSQL 14로 업그레이드하는 것을 보여주며 다운타임이 발생합니다:

  1. 데이터베이스 요구 사항에 따라 설정된 새로운 PostgreSQL 14 데이터베이스 서버를 실행합니다.

  2. GitLab Rails 인스턴스에서 호환되는 버전의 pg_dump와 pg_restore가 사용되고 있는지 확인합니다. GitLab 구성을 수정하려면 /etc/gitlab/gitlab.rb을 편집하고 postgresql['version']의 값을 지정하세요: 

     postgresql['version'] = 14

  3. GitLab을 재구성하세요: 

    sudo gitlab-ctl reconfigure

  4. GitLab을 중지하세요 (주의: 이 단계는 다운타임을 발생시킵니다): 

    sudo gitlab-ctl stop
    caution
    백업 명령은 추가 매개변수가 필요합니다. 설치가 PgBouncer를 사용하는 경우.

  5. 백업 Rake 작업을 실행하여 데이터베이스만 백업하도록 SKIP 옵션을 사용하고 나중에 복원에 사용할 백업 파일 이름을 메모하세요. 

    sudo gitlab-backup create SKIP=repositories,uploads,builds,artifacts,lfs,pages,registry

  6. PostgreSQL 13 데이터베이스 호스트를 종료하세요.

  7. /etc/gitlab/gitlab.rb을 편집하고 gitlab_rails['db_host'] 설정을 업데이트하여 PostgreSQL 데이터베이스 14 호스트를 가리키도록 합니다.

  8. GitLab을 재구성하세요: 

    sudo gitlab-ctl reconfigure
    caution
    백업 명령은 추가 매개변수가 필요합니다. 설치가 PgBouncer를 사용하는 경우.

  9. 이전에 생성된 데이터베이스 백업 파일을 사용하여 데이터베이스를 복원하고 “이 작업은 지금 authorized_keys 파일을 다시 작성합니다”라는 질문에 아니요로 응답하세요. 

    # 백업 타임스탬프 사용 https://docs.gitlab.com/ee/administration/backup_restore/backup_gitlab.html#backup-timestamp
sudo gitlab-backup restore BACKUP=<백업-타임스탬프>

  10. GitLab을 시작하세요: 

    sudo gitlab-ctl start

  11. 새 주요 릴리스의 PostgreSQL을 업그레이드 한 후에 쿼리 계획이 효율적으로 선택되고 데이터베이스 서버 CPU 부하를 줄이기 위해 테이블 통계를 다시 생성하세요.

    pg_upgrade를 사용하여 업그레이드를 “인플레이스”한 경우, PostgreSQL 데이터베이스 콘솔에서 다음 쿼리를 실행하세요: 

    SET statement_timeout = 0; ANALYZE VERBOSE;

    pg_dump와 pg_restore를 사용하여 업그레이드 한 경우, PostgreSQL 데이터베이스 콘솔에서 다음 쿼리를 실행하세요: 

    SET statement_timeout = 0; VACUUM ANALYZE VERBOSE;

데이터베이스 시드 설정 (새로운 설치만 해당)

caution
이 명령은 파괴적인 명령입니다. 기존 데이터베이스에서 실행하지 마십시오.

리눅스 패키지 설치가 외부 데이터베이스를 시드로 설정하지 않습니다. 다음 명령을 실행하여 스키마를 가져오고 첫 번째 관리 사용자를 만드세요: 

# 'git' 사용자인 경우 'sudo'를 제거하세요
sudo gitlab-rake gitlab:setup

기본 root 사용자의 암호를 지정하려면 gitlab:setup 명령을 실행하기 전에 /etc/gitlab/gitlab.rb에서 initial_root_password 설정을 지정하세요: 

gitlab_rails['initial_root_password'] = 'nonstandardpassword'

공유 GitLab 러너의 초기 등록 토큰을 지정하려면 gitlab:setup 명령을 실행하기 전에 /etc/gitlab/gitlab.rb에서 initial_shared_runners_registration_token 설정을 지정하세요: 

gitlab_rails['initial_shared_runners_registration_token'] = 'token'

패키지된 PostgreSQL 버전 고정 (새로운 설치만 해당)

리눅스 패키지는 다른 PostgreSQL 버전과 함께 제공되며, 기본 버전이 지정되지 않은 경우 초기 구성레이션에서 초기화됩니다.

기본이 아닌 버전으로 PostgreSQL을 초기화하려면 초기 재구성 전에 postgresql['version']을 패키지된 PostgreSQL 버전의 주요 버전 중 하나로 설정할 수 있습니다. 예를 들어, GitLab 15.0에서 PostgreSQL 13 대신에 PostgreSQL 12를 사용하려면 postgresql['version'] = 12를 사용할 수 있습니다.

caution
초기 재구성 이후에 postgresql['version']을 설정하는 동안 리눅스 패키지로 제공된 PostgreSQL을 사용하는 경우, 데이터 디렉터리가 다른 버전의 PostgreSQL에서 초기화되었음을 알리는 오류가 발생합니다. 이 경우에는 패키지된 PostgreSQL 서버를 이전 버전으로 되돌리기를 참조하세요.

이전에 GitLab이 설치된 환경에서 새로운 설치를 수행하고 고정된 PostgreSQL 버전을 사용하는 경우에는 PostgreSQL과 관련된 폴더가 삭제되었는지 확인하고 해당 인스턴스에서 PostgreSQL 프로세스가 실행되고 있지 않은지 확인하세요.

GitLab Rails에 평문 저장없이 민감한 데이터 구성 제공

자세한 정보는 구성 문서의 예제를 참조하세요.

데이터베이스를 위한 애플리케이션 설정

자동 데이터베이스 마이그레이션 비활성화

여러 GitLab 서버가 데이터베이스를 공유하는 경우, 재구성 중에 마이그레이션 단계를 수행하는 노드의 수를 제한해야 합니다.

/etc/gitlab/gitlab.rb을 편집하여 다음을 추가하세요: 

# 지정된 배포 노드를 제외한 모든 호스트에서 자동 데이터베이스 마이그레이션 활성화 또는 비활성화
gitlab_rails['auto_migrate'] = false

/etc/gitlab/gitlab.rb은 평문 암호를 포함하고 있으므로 파일 권한은 0600이어야 합니다.

위 구성을 가진 호스트가 다시 구성되면 마이그레이션 단계가 수행되지 않습니다.

스키마 관련 업그레이드 이후 오류를 방지하기 위해 배포 노드로 표시된 호스트는 업그레이드 중에 gitlab_rails['auto_migrate'] = true를 가져야합니다.

클라이언트 statement_timeout 설정

Rails가 데이터베이스 트랜잭션이 완료될 때까지 기다릴 시간인 gitlab_rails['db_statement_timeout'] 설정으로 조정할 수 있습니다. 기본적으로 이 설정은 사용되지 않습니다.

/etc/gitlab/gitlab.rb 파일 편집: 

gitlab_rails['db_statement_timeout'] = 45000

이 경우, 클라이언트 statement_timeout은 45초로 설정됩니다. 값은 밀리초로 지정됩니다.

연결 시간 제한 설정

Rails가 PostgreSQL 연결 시도가 성공하기를 기다리는 시간을 시간초과하기 전에 조정할 수 있습니다. 기본적으로 이 설정은 사용되지 않습니다.

  1. /etc/gitlab/gitlab.rb 파일 편집: 

    gitlab_rails['db_connect_timeout'] = 5

  2. GitLab 재구성: 

    sudo gitlab-ctl reconfigure

이 경우, 클라이언트 connect_timeout은 5초로 설정됩니다. 값은 초로 지정됩니다. 최소 값은 2초입니다. 이를 <= 0으로 설정하거나 설정을 전혀 지정하지 않으면 시간 제한이 비활성화됩니다.

TCP 제어 설정

Rails PostgreSQL 어댑터는 성능을 향상시키기 위해 조정할 수 있는 일련의 TCP 연결 제어를 제공합니다. 각 매개변수에 대한 자세한 정보는 PostgreSQL 상위 문서를 참조하십시오.

Linux 패키지는 이러한 값에 대한 기본값을 설정하지 않으며 대신 PostgreSQL 어댑터에서 제공하는 기본값을 사용합니다. 아래 표에 나와 있는 매개변수를 gitlab.rb에서 덮어쓰고 나서 gitlab-ctl reconfigure를 실행하여 재구성하십시오.

PostgreSQL 매개변수 gitlab.rb 매개변수
keepalives gitlab_rails['db_keepalives']
keepalives_idle gitlab_rails['db_keepalives_idle']
keepalives_interval gitlab_rails['db_keepalives_interval']
keepalives_count gitlab_rails['db_keepalives_count']
tcp_user_timeout gitlab_rails['db_tcp_user_timeout']

자동 데이터베이스 재색인

caution
기본적으로 활성화되지 않은 실험적인 기능입니다.

데이터베이스 인덱스를 백그라운드에서 다시 생성합니다(재색인이라고 함). 이를 사용하여 쌓인 공간을 제거하고 건강하고 효율적인 인덱스를 유지하는 데 도움이 됩니다.

재색인 작업은 cron 작업을 통해 정기적으로 시작할 수 있습니다. cron 작업을 구성하려면 gitlab_rails['database_reindexing']['enable']을 true로 설정해야 합니다.

다중 노드 환경에서는 이 기능을 응용 프로그램 호스트에서만 활성화해야 합니다. 재색인 프로세스는 PgBouncer를 통과할 수 없으며 직접 데이터베이스 연결이 필요합니다.

기본적으로 이는 주말에 매 시간마다 시작합니다(일반적으로 트래픽이 적을 때).

다음 설정을 정밀하게 수정하여 일정을 변경할 수 있습니다:

  1. /etc/gitlab/gitlab.rb 파일 편집: 

    gitlab_rails['database_reindexing']['hour'] = '*'
gitlab_rails['database_reindexing']['minute'] = 0
gitlab_rails['database_reindexing']['month'] = '*'
gitlab_rails['database_reindexing']['day_of_month'] = '*'
gitlab_rails['database_reindexing']['day_of_week'] = '0,6'

  2. GitLab 재구성: 

    sudo gitlab-ctl reconfigure

HA/Geo 클러스터에 배포된 패키지 PostgreSQL

GitLab HA 클러스터 업그레이드

Patroni 클러스터에서 PostgreSQL 버전을 업그레이드하려면 Patroni 클러스터에서 PostgreSQL 주 버전 업그레이드을 참조하십시오.

GitLab HA Repmgr 클러스터 업그레이드

note
PostgreSQL 12로 업그레이드하는 경우, 먼저 Repmgr에서 Patroni로 전환해야 합니다. Repmgr에서 Patroni로 전환을 참조하십시오.

이 지침은 Repmgr을 사용할 때 이전 GitLab 클러스터를 PostgreSQL 11로 업그레이드하는 경우에 대해 제공됩니다.

만약 PostgreSQL을 고가용성으로 구성했다면 pg-upgrade를 모든 PostgreSQL을 실행하는 노드에서 실행해야 합니다. 다른 노드는 건너뛸 수 있지만 데이터베이스 노드와 동일한 GitLab 버전을 실행해야 합니다.

아래 단계에 따라 데이터베이스 노드를 업그레이드하십시오:

  1. 기본 노드 이전에 보조 노드를 업그레이드해야 합니다.
    1. 보조 노드에서 다음을 포함하여 /etc/gitlab/gitlab.rb를 편집하십시오: 
    # X는 DB 노드 수 + 1로 대체합니다
postgresql['max_replication_slots'] = X
    1. 구성을 업데이트하기 위해 gitlab-ctl reconfigure를 실행하십시오.
    2. 새 구성으로 PostgreSQL을 다시 시작하려면 sudo gitlab-ctl restart postgresql를 실행하십시오.
    3. PostgreSQL 보조 노드에서 pg-upgrade를 실행하면 노드가 클러스터에서 제거됩니다.
    4. pg-upgrade를 PostgreSQL 보조 노드에서 실행하면 새 버전에 맞게 기존 데이터를 업데이트하지 않습니다. 기존 데이터는 백업 위치로 이동됩니다만 새로운 버전의 데이터가 기존 데이터를 대체합니다.
  2. 모든 보조 노드를 업그레이드한 후, 기본 노드에서 pg-upgrade를 실행하십시오.
    1. 기본 노드에서 다음을 포함하여 /etc/gitlab/gitlab.rb를 편집하십시오: 
    # X는 DB 노드 수 + 1로 대체합니다
postgresql['max_replication_slots'] = X
    1. 구성을 업데이트하기 위해 gitlab-ctl reconfigure를 실행하십시오.
    2. 새 구성으로 PostgreSQL을 다시 시작하려면 sudo gitlab-ctl restart postgresql를 실행하십시오.
    3. 기본 노드에서 pg-upgrade는 기존 데이터를 새로운 PostgreSQL 버전에 맞게 업데이트합니다.

  3. 각각의 보조 노드에서 다음 명령을 실행하여 보조 노드를 재생성하십시오. 

    gitlab-ctl repmgr standby setup MASTER_NODE_NAME

  4. repmgr 클러스터가 원래 상태로 돌아왔는지 확인하십시오. 

    gitlab-ctl repmgr cluster show

HA 클러스터에서 업그레이드 문제 해결

만약 기존 PostgreSQL이 HA 설정으로 업그레이드되기 전에 노드에서 실행되고 있다면 이전 데이터 디렉터리가 남아 있을 수 있습니다. 이로 인해 gitlab-ctl reconfigure가 해당 노드에서 사용하는 PostgreSQL 유틸리티의 버전을 낮추게 됩니다. 이를 방지하려면 다음 디렉터리를 이동(또는 제거)하십시오:

  • mv /var/opt/gitlab/postgresql/data/ /var/opt/gitlab/postgresql/data.$(date +%s)

gitlab-ctl repmgr standby setup MASTER_NODE_NAME로 보조 노드를 재생성할 때 다음 오류가 발생하는 경우, /etc/gitlab/gitlab.rb에 postgresql['max_replication_slots'] = X (여기서 X는 DB 노드 + 1의 수)가 포함되어 있는지 확인하십시오: 

pg_basebackup: could not create temporary replication slot "pg_basebackup_12345": ERROR:  all replication slots are in use
HINT:  Free one or increase max_replication_slots.

Geo 인스턴스 업그레이드

Geo는 기본적으로 PostgreSQL 스트리밍 복제에 의존하기 때문에 GitLab을 업그레이드하거나 PostgreSQL을 업그레이드할 때 추가적인 고려 사항이 있습니다.

Geo와 함께 PostgreSQL을 업그레이드하는 경우의 주의 사항

caution
Geo를 사용할 때, PostgreSQL을 업그레이드하려면 모든 이중 노드에 다운타임이 필요합니다.

Geo를 사용할 때, PostgreSQL을 업그레이드하려면 모든 이중 노드에 다운타임이 필요합니다. 이는 PostgreSQL 스트리밍 복제 작동 방식으로 인해 Geo 이중 노드에 대한 복제를 다시 초기화해야 하기 때문입니다. 복제를 다시 초기화하면 기본 데이터 전체를 이중 노드로부터 복사하므로 데이터베이스 크기와 사용 가능 대역폭에 따라 시간이 오래 걸릴 수 있습니다. 예를 들어, 전송 속도가 30 Mbps이고 데이터베이스 크기가 100 GB인 경우, 다시 동기화하는 데 약 8시간이 소요될 수 있습니다. 자세한 내용은 PostgreSQL 문서를 참조하십시오.

Geo 사용 시 PostgreSQL 업그레이드 방법

PostgreSQL을 업그레이드하려면 복제 슬롯의 이름과 복제 사용자의 암호가 필요합니다.

  1. Geo 기본 데이터베이스 노드에서 기존 복제 슬롯의 이름을 찾으려면 다음 명령을 실행하십시오. 

    sudo gitlab-psql -qt -c 'select slot_name from pg_replication_slots'

    여기서 slot_name을 찾을 수 없거나 결과가 반환되지 않는 경우 Geo 이중 노드가 정상적이지 않을 수 있습니다. 이 경우 이중 노드의 상태를 확인하고 복제가 작동하는지 확인하십시오.

  2. 복제 사용자의 암호를 수집합니다. 이 암호는 Step 1. Configure the primary site에서 Geo를 설정할 때 설정되었습니다.

  3. Geo 기본 데이터베이스에서 PostgreSQL을 매뉴얼으로 업그레이드합니다. Geo 기본 데이터베이스 노드에서 다음 명령을 실행하십시오. 

    sudo gitlab-ctl pg-upgrade

    기본 데이터베이스의 업그레이드가 완료될 때까지 기다린 후 다음 단계를 시작하여 이중 노드를 백업 상태로 유지합니다. 그 후, 추적 데이터베이스를 이중 데이터베이스와 병렬로 업그레이드할 수 있습니다.

  4. Geo 이중 노드에서 PostgreSQL을 매뉴얼으로 업그레이드합니다. Geo 이중 데이터베이스 및 추적 데이터베이스에서 다음 명령을 실행하십시오. 

    sudo gitlab-ctl pg-upgrade

  5. 다음 명령을 사용하여 Geo 이중 데이터베이스에서 데이터베이스 복제를 다시 시작합니다. 

    sudo gitlab-ctl replicate-geo-database --slot-name=SECONDARY_SLOT_NAME --host=PRIMARY_HOST_NAME --sslmode=verify-ca

    복제 사용자의 기본 데이터베이스 암호가 요청됩니다. 위에서 첫 번째 단계에서 검색한 슬롯 이름으로 SECONDARY_SLOT_NAME을 대체하십시오.

  6. pg_hba.conf 파일을 업데이트하기 위해 Geo 이중 데이터베이스에서 GitLab을 재구성하십시오. 이 작업은 replicate-geo-database가 기본 파일을 이중 데이터베이스에 복제하기 때문에 필요합니다.

  7. puma, sidekiq, 및 geo-logcursor를 다시 시작합니다. 

    sudo gitlab-ctl hup puma
sudo gitlab-ctl restart sidekiq
sudo gitlab-ctl restart geo-logcursor

  8. https://your_primary_server/admin/geo/nodes로 이동하여 모든 노드가 정상인지 확인하십시오.

PostgreSQL 데이터베이스에 연결하기

PostgreSQL 데이터베이스에 연결해야 하는 경우, 응용 프로그램 사용자로 연결할 수 있습니다. 

sudo gitlab-rails dbconsole --database main

문제 해결

default_transaction_isolation을 read committed로 설정

production/sidekiq 로그에서 다음과 유사한 오류를 볼 경우: 

ActiveRecord::StatementInvalid PG::TRSerializationFailure: ERROR:  could not serialize access due to concurrent update

데이터베이스의 default_transaction_isolation 구성이 GitLab 응용프로그램 요구 사항과 일치하지 않을 수 있습니다. 이 구성은 PostgreSQL 데이터베이스에 설정되어 있으며, SHOW default_transaction_isolation; 명령을 실행하여 확인할 수 있습니다. GitLab 응용프로그램은 read committed가 구성되어 있다고 예상합니다.

이 default_transaction_isolation 구성은 postgresql.conf 파일에 설정되어 있습니다. 이 구성을 변경한 후 데이터베이스를 다시 시작해야 합니다. 이 구성은 Linux 패키지에 포함된 패키지된 PostgreSQL 서버에 기본적으로 제공됩니다.

plpgsql.so 라이브러리를 로드할 수 없음

데이터베이스 마이그레이션 중이나 PostgreSQL/Patroni 로그에서 다음과 유사한 오류가 발생할 수 있습니다: 

ERROR:  could not load library "/opt/gitlab/embedded/postgresql/12/lib/plpgsql.so": /opt/gitlab/embedded/postgresql/12/lib/plpgsql.so: undefined symbol: EnsurePortalSnapshotExists

이 오류는 기본 버전이 변경된 후 PostgreSQL을 다시 시작하지 않아 발생합니다. 이 오류를 수정하려면 다음을 수행하십시오:

  1. 다음 중 하나의 명령을 실행하십시오: 

    # PostgreSQL의 경우
sudo gitlab-ctl restart postgresql
   
# Patroni의 경우
sudo gitlab-ctl restart patroni
   
# Geo PostgreSQL의 경우
sudo gitlab-ctl restart geo-postgresql

  2. GitLab을 다시 구성하십시오: 

    sudo gitlab-ctl reconfigure