백업 및 복원
- 백업 및 복원, Geo 보조 사이트 함께 사용
모든 인덱스 다시 작성
- 모든 인덱스 다시 작성, Geo 보조 사이트 함께 사용
영향 받는 인덱스만 다시 빌드하기
- 영향을 받는 인덱스만 다시 빌드하기, Geo 이중 사이트와 함께
glibc 버전 확인
스트리밍 복제
추가 지오 변형

PostgreSQL 운영 체제 업그레이드

경고: Geo는 PostgreSQL 데이터베이스를 한 운영 체제에서 다른 운영 체제로 마이그레이션하는 데 사용할 수 없습니다. 이렇게 하려고 시도하면, 보조 사이트가 100% 복제된 것처럼 보일 수 있지만 실제로 일부 데이터가 복제되지 않아 데이터 손실이 발생할 수 있습니다. 이는 Geo가 PostgreSQL 스트리밍 복제에 의존하며, 이 문서에 설명된 제한 사항을 겪기 때문입니다. 또한 Geo 문제 해결 - OS 로캘 데이터 호환성 확인도 참조하십시오.

만약 PostgreSQL이 구동 중인 운영 체제를 업그레이드하면, 로케일 데이터 변경이 데이터베이스 인덱스를 손상시킬 수 있습니다(https://wiki.postgresql.org/wiki/Locale_data_changes). 특히, glibc 2.28로 업그레이드하면 이 문제가 발생할 가능성이 높습니다. 이 문제를 피하려면, 복잡도의 순서대로 다음 옵션 중 하나를 사용하여 마이그레이션하십시오.

권장 사항. 백업 및 복원.
권장 사항. 모든 인덱스 다시 작성.
영향 받는 인덱스만 다시 작성.

마이그레이션을 시도하기 전에 꼭 백업을 만들고, 프로덕션과 유사한 환경에서 마이그레이션 프로세스를 유효성 검사하십시오. 다운타임 기간이 문제가 될 수 있는 경우, 복잡한 접근 방식을 프로덕션 데이터의 사본과 함께 시간을 맞추는 것을 고려하십시오.

스케일 아웃된 GitLab 환경을 구동하고 있고, PostgreSQL이 구동 중인 노드에서 다른 서비스가 구동되지 않는 경우, PostgreSQL 노드의 운영 체제를 업그레이드하는 것을 권장합니다. 복잡성과 위험을 줄이기 위해 프로시저를 다른 변경 작업과 결합하지 마십시오. 특히 다운타임이 필요하지 않은 변경 사항(예: Puma 또는 Sidekiq만 실행하는 노드의 운영 체제를 업그레이드)과 결합하지 마십시오.

이 문제를 해결하기 위한 GitLab의 계획에 대한 자세한 정보는 epic 8573를 참조하십시오.

백업 및 복원

백업 및 복원은 인덱스를 포함한 전체 데이터베이스를 다시 생성합니다.

예약된 다운타임 창을 가져오십시오. 모든 노드에서 불필요한 GitLab 서비스를 중지하십시오:
```
gitlab-ctl stop
gitlab-ctl start postgresql
```
PostgreSQL 데이터베이스를 pg_dump로 백업하거나 모든 데이터 유형에서 ‘db’를 제외한 GitLab 백업 도구를 사용하여 데이터베이스만 백업하십시오.
모든 PostgreSQL 노드에서 OS를 업그레이드하십시오.
모든 PostgreSQL 노드에서, OS를 업그레이드한 후 GitLab 패키지 소스를 업데이트하십시오.
모든 PostgreSQL 노드에서, 동일한 GitLab 버전의 새로운 GitLab 패키지를 설치하십시오.
백업된 PostgreSQL 데이터베이스를 복원하십시오.
모든 노드에서, GitLab을 시작하십시오.

장점:

직접적입니다.
인덱스와 테이블의 데이터베이스 블로트를 제거하여 디스크 사용량을 줄입니다.

단점:

데이터베이스 크기가 클수록 다운타임이 증가하여 문제가 될 수 있습니다. 많은 요소에 따라 달라지지만, 데이터베이스가 100GB 이상이면 약 24시간이 소요될 수 있습니다.

백업 및 복원, Geo 보조 사이트 함께 사용

예약된 다운타임 창을 가져오십시오. 모든 사이트의 모든 노드에서 불필요한 GitLab 서비스를 중지하십시오:
```
gitlab-ctl stop
gitlab-ctl start postgresql
```
기본 사이트에서 PostgreSQL 데이터베이스를 pg_dump로 백업하거나 모든 데이터 유형에서 ‘db’를 제외한 GitLab 백업 도구를 사용하여 데이터베이스만 백업하십시오.
모든 사이트의 모든 PostgreSQL 노드에서 OS를 업그레이드하십시오.
모든 사이트의 모든 PostgreSQL 노드에서, OS를 업그레이드한 후 GitLab 패키지 소스를 업데이트하십시오.
모든 사이트의 모든 PostgreSQL 노드에서, 동일한 GitLab 버전의 새로운 GitLab 패키지를 설치하십시오.
기본 사이트에서 백업된 PostgreSQL 데이터베이스를 복원하십시오.
원할 경우, 기본 사이트를 사용하여 시작하십시오(보조 사이트로 따뜻한 백업이 없을 경우의 위험 포함).
다시 보조 사이트로 PostgreSQL 스트리밍 복제를 설정하십시오.
보조 사이트가 사용자로부터 트래픽을 받는 경우, 읽기 복제 데이터베이스가 시작하기 전에 기다리십시오.
모든 사이트의 모든 노드에서 GitLab을 시작하십시오.

모든 인덱스 다시 작성

모든 인덱스 다시 작성.

예약된 다운타임 창을 가져오십시오. 모든 노드에서 불필요한 GitLab 서비스를 중지하십시오:
```
gitlab-ctl stop
gitlab-ctl start postgresql
```
모든 PostgreSQL 노드에서 OS를 업그레이드하십시오.
모든 PostgreSQL 노드에서, OS를 업그레이드한 후 GitLab 패키지 소스를 업데이트하십시오.
모든 PostgreSQL 노드에서, 동일한 GitLab 버전의 새로운 GitLab 패키지를 설치하십시오.

데이터베이스 콘솔에서, 모든 인덱스 다시 작성:

SET statement_timeout = 0;
REINDEX DATABASE gitlabhq_production;

데이터베이스의 모든 영향을 받는 콜레이션의 버전을 새롭게 적용해야 합니다. 시스템 카탈로그에서 현재 콜레이션 버전을 기록하려면:
```
ALTER COLLATION <collation_name> REFRESH VERSION;
```
모든 노드에서, GitLab을 시작하십시오.

장점:

직접적입니다.
많은 요소에 따라 백업 및 복원보다 빠를 수 있습니다.
인덱스의 데이터베이스 블로트를 제거하므로 디스크 사용량을 줄입니다.

단점:

데이터베이스 크기가 클수록 다운타임이 증가하여 문제가 될 수 있습니다.

모든 인덱스 다시 작성, Geo 보조 사이트 함께 사용

예약된 다운타임 창을 가져오십시오. 모든 사이트의 모든 노드에서 불필요한 GitLab 서비스를 중지하십시오:
```
gitlab-ctl stop
gitlab-ctl start postgresql
```
모든 PostgreSQL 노드에서 OS를 업그레이드하십시오.
모든 PostgreSQL 노드에서, OS를 업그레이드한 후 GitLab 패키지 소스를 업데이트하십시오.
모든 PostgreSQL 노드에서, 동일한 GitLab 버전의 새로운 GitLab 패키지를 설치하십시오.
기본 사이트에서, 데이터베이스 콘솔에서 모든 인덱스 다시 작성:
```
SET statement_timeout = 0;
REINDEX DATABASE gitlabhq_production;
```
데이터베이스의 모든 영향을 받는 콜레이션의 버전을 새롭게 적용해야 합니다. 시스템 카탈로그에서 현재 콜레이션 버전을 기록하려면:
```
ALTER COLLATION <collation_name> REFRESH VERSION;
```
보조 사이트가 사용자로부터 트래픽을 받는 경우, 읽기 복제 데이터베이스가 시작하기 전에 기다리십시오.
모든 사이트의 모든 노드에서 GitLab을 시작하십시오.

영향 받는 인덱스만 다시 빌드하기

이것은 GitLab.com에서 사용되는 방식과 유사합니다. 이 프로세스 및 다양한 유형의 인덱스 처리 방법에 대해 자세히 알아보려면 PostgreSQL 데이터베이스 클러스터의 운영 체제를 업그레이드하는 블로그 게시물을 참조하십시오.

예정된 다운타임 윈도우를 사용합니다. 모든 노드에서 불필요한 GitLab 서비스를 중지합니다:
```
gitlab-ctl stop
gitlab-ctl start postgresql
```
모든 PostgreSQL 노드에서 OS를 업그레이드합니다.
모든 PostgreSQL 노드에서, OS를 업그레이드한 후 GitLab 패키지 소스를 업데이트합니다.
모든 PostgreSQL 노드에서, 동일한 GitLab 버전의 새로운 GitLab 패키지를 설치합니다.
어떤 인덱스가 영향을 받았는지 확인.
데이터베이스 콘솔에서 각 영향받는 인덱스를 다시 색인화합니다:
```
SET statement_timeout = 0;
REINDEX INDEX <index name> CONCURRENTLY;
```
잘못된 인덱스를 다시 색인화 한 후, 콜레이션을 새로 고쳐야 합니다. 시스템 카탈로그를 업데이트하여 현재 콜레이션 버전을 기록합니다:
```
ALTER COLLATION <collation_name> REFRESH VERSION;
```
모든 노드에서 GitLab을 시작합니다.

장점:

영향을 받지 않는 인덱스를 다시 빌드하는 데 소요되는 다운타임이 없습니다.

단점:

실수를 범할 가능성이 더 높습니다.
마이그레이션 중 예기치 않은 문제를 해결하기 위해 PostgreSQL의 전문 지식이 필요합니다.
데이터베이스 블로잇을 보존합니다.

영향을 받는 인덱스만 다시 빌드하기, Geo 이중 사이트와 함께

예정된 다운타임 창을 사용합니다. 모든 사이트의 모든 노드에서 불필요한 GitLab 서비스를 중지합니다:
```
gitlab-ctl stop
gitlab-ctl start postgresql
```
모든 PostgreSQL 노드에서 OS를 업그레이드합니다.
모든 PostgreSQL 노드에서, OS를 업그레이드한 후 GitLab 패키지 소스를 업데이트합니다.
모든 PostgreSQL 노드에서, 동일한 GitLab 버전의 새로운 GitLab 패키지를 설치합니다.
어떤 인덱스가 영향을 받았는지 확인.
주 사이트에서, 데이터베이스 콘솔에서 각 영향을 받는 인덱스를 다시 색인화합니다:
```
SET statement_timeout = 0;
REINDEX INDEX <index name> CONCURRENTLY;
```
잘못된 인덱스를 다시 색인화 한 후, 콜레이션을 새로 고쳐야 합니다. 시스템 카탈로그를 업데이트하여 현재 콜레이션 버전을 기록합니다:
```
ALTER COLLATION <collation_name> REFRESH VERSION;
```
기존의 PostgreSQL 스트리밍 복제는 재색인 변경 사항을 읽기 전용 복제 데이터베이스로 복제해야 합니다.
모든 사이트의 모든 노드에서 GitLab을 시작합니다.

`glibc` 버전 확인

glibc의 사용 버전을 확인하려면 ldd --version을 실행합니다.

다음 표는 다른 운영 체제에 대해 제공되는 glibc 버전을 보여줍니다:

운영 체제	`glibc` 버전
CentOS 7	2.17
RedHat Enterprise 8	2.28
RedHat Enterprise 9	2.34
Ubuntu 18.04	2.27
Ubuntu 20.04	2.31
Ubuntu 22.04	2.35
Ubuntu 24.04	2.39

예를 들어, CentOS 7에서 RedHat Enterprise 8로 업그레이드하는 경우, glibc가 2.17에서 2.28로 업그레이드되므로, 이를 처리하기 위해 두 가지 접근 방식 중 하나를 사용해야 합니다. 콜레이션 변경을 적절하게 처리하지 못하면, runners가 태그가 지정된 작업을 수행하지 못하는 등 GitLab에서 중대한 문제가 발생할 수 있습니다.

반면, 만약 PostgreSQL이 이미 glibc 2.28 이상에서 문제없이 실행 중이라면 추가 조치 없이 인덱스가 계속 작동해야 합니다. 예를 들어, 당신이 glibc 2.28에서 RedHat Enterprise 8( glibc 2.28)에서 PostgreSQL을 실행하고 있었고 RedHat Enterprise 9(glibc 2.34)으로 업그레이드하려고 하는 경우, 콜레이션 관련 문제가 없어야 합니다.

`glibc` 콜레이션 버전 확인

PostgreSQL 13 이상의 경우, 다음 SQL 쿼리를 사용하여 데이터베이스 콜레이션 버전이 시스템과 일치하는지 확인할 수 있습니다:

SELECT collname AS COLLATION_NAME,
       collversion AS VERSION,
       pg_collation_actual_version(oid) AS actual_version
FROM pg_collation
WHERE collprovider = 'c';

콜레이션 일치 예시

예를 들어, Ubuntu 22.04 시스템에서 올바르게 색인화된 시스템의 출력은 다음과 같습니다:

gitlabhq_production=# SELECT collname AS COLLATION_NAME,
       collversion AS VERSION,
       pg_collation_actual_version(oid) AS actual_version
FROM pg_collation
WHERE collprovider = 'c';
 collation_name | version | actual_version
----------------+---------+----------------
 C              |         |
 POSIX          |         |
 ucs_basic      |         |
 C.utf8         |         |
 en_US.utf8     | 2.35    | 2.35
 en_US          | 2.35    | 2.35
(6 rows)

콜레이션 불일치 예시

반면에, Ubuntu 18.04에서 22.04로 업그레이드하고 색인을 다시 생성하지 않은 경우 다음과 같은 결과를 얻을 수 있습니다:

gitlabhq_production=# SELECT collname AS COLLATION_NAME,
       collversion AS VERSION,
       pg_collation_actual_version(oid) AS actual_version
FROM pg_collation
WHERE collprovider = 'c';
 collation_name | version | actual_version
----------------+---------+----------------
 C              |         |
 POSIX          |         |
 ucs_basic      |         |
 C.utf8         |         |
 en_US.utf8     | 2.27    | 2.35
 en_US          | 2.27    | 2.35
(6 rows)

스트리밍 복제

PostgreSQL 스트리밍 복제에는 손상된 인덱스 문제가 영향을 미칩니다.
다른 지역 데이터를 가진 복제본에 대해 읽기를 허용하기 전에
모든 인덱스를 다시 빌드하거나
영향을 받는 인덱스만 다시 빌드해야 합니다.

추가 지오 변형

위의 업그레이드 절차는 절대적인 것이 아닙니다. 지오를 사용하면 중복된 인프라가 존재하기 때문에 잠재적으로 더 많은 옵션이 있습니다. 귀하의 사용 사례에 맞게 수정을 고려할 수 있지만, 추가된 복잡성에 대해 신중하게 고려해야 합니다. 여기 몇 가지 예시가 있습니다:

제1 사이트의 OS 업그레이드 중 재해가 발생할 경우 보조 사이트를 웜 스탠바이로 예약하는 경우:

제2 사이트의 데이터를 제1 사이트의 변경에서 격리: 제2 사이트를 일시 중지합니다.
제1 사이트에서 OS 업그레이드를 진행합니다.
만약 OS 업그레이드가 실패하고 제1 사이트가 복구할 수 없는 경우, 제2 사이트를 프로모션하고, 사용자를 그쪽으로 이동시킨 후 나중에 다시 시도합니다.
이로 인해 최신의 보조 사이트가 없어지는 것에 유의하십시오.

제1 사이트의 OS 업그레이드 동안 사용자에게 GitLab의 읽기 전용 액세스를 제공하는 경우 (일부 다운타임):

중단하기 대신에 제1 사이트에서 유지보수 모드를 활성화합니다.
보조 사이트를 프로모션하지만 사용자를 아직 그쪽으로 이동시키지 않습니다.
프로모션된 사이트에서 OS 업그레이드를 수행합니다.
이전의 제1 사이트 대신 사용자를 프로모션된 사이트로 이동합니다.
이전의 제1 사이트를 새로운 보조 사이트로 설정합니다.

경고:
데이터베이스의 읽기 복제본을 이미 가지고 있는 보조 사이트라 할지라도, 프로모션 전에 운영 체제를 업그레이드할 수 없습니다. 만약 시도한다면, 여러분은 데이터베이스의 일부 Git 리포지토리나 파일의 복제를 놓칠 수 있습니다. 이는 손상된 인덱스로 인해 스트리밍 복제의 누락으로 이어질 수 있습니다.

PostgreSQL 운영 체제 업그레이드

백업 및 복원

백업 및 복원, Geo 보조 사이트 함께 사용

모든 인덱스 다시 작성

모든 인덱스 다시 작성, Geo 보조 사이트 함께 사용

영향 받는 인덱스만 다시 빌드하기

영향을 받는 인덱스만 다시 빌드하기, Geo 이중 사이트와 함께

`glibc` 버전 확인

`glibc` 콜레이션 버전 확인

콜레이션 일치 예시

콜레이션 불일치 예시

스트리밍 복제

추가 지오 변형

도움말

기능 사용 가능성과 제품 평가판

도움받기

PostgreSQL 운영 체제 업그레이드

백업 및 복원

백업 및 복원, Geo 보조 사이트 함께 사용

모든 인덱스 다시 작성

모든 인덱스 다시 작성, Geo 보조 사이트 함께 사용

영향 받는 인덱스만 다시 빌드하기

영향을 받는 인덱스만 다시 빌드하기, Geo 이중 사이트와 함께

glibc 버전 확인

glibc 콜레이션 버전 확인

콜레이션 일치 예시

콜레이션 불일치 예시

스트리밍 복제

추가 지오 변형

도움말

기능 사용 가능성과 제품 평가판

도움받기

`glibc` 버전 확인

`glibc` 콜레이션 버전 확인