백업 및 복원
- Geo 보조 사이트가 있는 백업 및 복원
모든 인덱스 재작성
- Geo 보조 사이트와 함께 모든 인덱스 재작성
영향을 받은 인덱스만 재작성
- 영향을 받는 인덱스만 재구성하기, Geo 보조 사이트와 함께
glibc 버전 확인하기
스트리밍 복제
추가 Geo 변형

PostgreSQL용 운영 체제 업그레이드

경고:

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

PostgreSQL이 실행되는 운영 체제를 업그레이드하면, 로케일 데이터의 변경이 데이터베이스 인덱스를 손상시킬 수 있습니다. 특히 glibc 2.28로의 업그레이드는 이 문제가 발생할 가능성이 높습니다. 이 문제를 피하려면, 다음 옵션 중 하나를 사용하여 마이그레이션하십시오. 대략적인 복잡도 순서에 따라 나열됩니다:

권장. 백업 및 복원.
권장. 모든 인덱스 재구축.
영향을 받는 인덱스만 재구축.

마이그레이션을 시도하기 전에 반드시 백업을 수행하고, 생산 환경과 유사한 환경에서 마이그레이션 프로세스를 검증하십시오. 다운타임의 길이가 문제라면, 생산 데이터의 복사본을 사용해 다른 접근 방식을 타이밍을 고려하십시오.

확장된 GitLab 환경을 운영 중이며, PostgreSQL이 실행되는 노드에서 다른 서비스가 실행되고 있지 않은 경우, PostgreSQL 노드의 운영 체제만 업그레이드하는 것을 권장합니다. 복잡성과 위험을 줄이기 위해, 이 절차를 다른 변경 사항과 결합하지 마십시오. 특히 다운타임이 필요하지 않은 변경 사항, 예를 들어 Puma 또는 Sidekiq만 실행 중인 노드의 운영 체제를 업그레이드하는 경우입니다.

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

백업 및 복원

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

일정한 다운타임 창을 설정합니다. 모든 노드에서, 불필요한 GitLab 서비스를 중지합니다:
```
gitlab-ctl stop
gitlab-ctl start postgresql
```
pg_dump 또는 GitLab 백업 도구를 사용하여 PostgreSQL 데이터베이스를 백업합니다. 단, db 데이터 유형은 제외합니다 (그래서 데이터베이스만 백업됩니다).
모든 PostgreSQL 노드에서 운영 체제를 업그레이드합니다.
모든 PostgreSQL 노드에서, 운영 체제 업그레이드 후 GitLab 패키지 소스를 업데이트하십시오.
모든 PostgreSQL 노드에서, 동일한 GitLab 버전의 새로운 GitLab 패키지를 설치합니다.
백업에서 PostgreSQL 데이터베이스를 복원합니다.
모든 노드에서 GitLab을 시작합니다.

장점:

간단합니다.
인덱스와 테이블의 데이터베이스 부풀어 오른 것을 제거하여 디스크 사용량을 줄입니다.

단점:

데이터베이스 크기가 커짐에 따라 다운타임이 증가하며, 어느 시점에서는 문제가 될 수 있습니다. 이는 많은 요인에 따라 다르지만, 데이터베이스가 100GB를 초과하면 24시간 정도 걸릴 수 있습니다.

Geo 보조 사이트가 있는 백업 및 복원

일정한 다운타임 창을 설정합니다. 모든 사이트의 모든 노드에서, 불필요한 GitLab 서비스를 중지합니다:
```
gitlab-ctl stop
gitlab-ctl start postgresql
```
기본 사이트에서, pg_dump 또는 GitLab 백업 도구를 사용하여 PostgreSQL 데이터베이스를 백업합니다. 단, db 데이터 유형은 제외합니다 (그래서 데이터베이스만 백업됩니다).
모든 사이트의 모든 PostgreSQL 노드에서 운영 체제를 업그레이드합니다.
모든 사이트의 모든 PostgreSQL 노드에서, 운영 체제 업그레이드 후 GitLab 패키지 소스를 업데이트하십시오.
모든 사이트의 모든 PostgreSQL 노드에서, 동일한 GitLab 버전의 새로운 GitLab 패키지를 설치합니다.
기본 사이트에서 백업에서 PostgreSQL 데이터베이스를 복원합니다.
선택적으로, 이차 사이트가 웜 스탠바이 상태가 아닌 위험을 감수하고 기본 사이트를 사용하기 시작합니다.
PostgreSQL 스트리밍 복제를 이차 사이트에 다시 설정합니다.
이차 사이트가 사용자로부터 트래픽을 받는 경우, GitLab을 시작하기 전에 읽기 복제 데이터베이스가 따라잡도록 허용합니다.
모든 사이트의 모든 노드에서 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을 시작합니다.

영향을 받은 인덱스만 재작성

이것은 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로 업그레이드한다고 가정합니다. 이 경우, 업그레이드된 운영 체제에서 PostgreSQL을 사용하려면 언급된 두 가지 방법 중 하나를 사용해야 합니다, 왜냐하면 glibc가 2.17에서 2.28로 업그레이드되기 때문입니다. 정렬 변경 사항을 적절히 처리하지 않으면 GitLab에서 significant failures(중대한 오류)가 발생할 수 있으며, 예를 들어, 러너가 태그가 있는 작업을 선택하지 못하는 경우가 있습니다.

반면, PostgreSQL이 이미 아무 문제 없이 glibc 2.28 이상에서 실행되고 있다면, 인덱스는 추가 작업 없이 계속 작동해야 합니다. 예를 들어, PostgreSQL이 RedHat Enterprise 8 (glibc 2.28)에서 한동안 실행되고 있었고, 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 스트리밍 복제에 영향을 줍니다. 서로 다른 로케일 데이터를 가진 복제본에 대한 읽기를 허용하기 전에 모든 인덱스 재구축 또는 영향을 받은 인덱스만 재구축해야 합니다.

추가 Geo 변형

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

재해 발생 시 주요 사이트의 OS 업그레이드 중에 보조 사이트를 대기 상태로 유지하려면:

보조 사이트의 데이터를 주요 사이트의 변경 사항으로부터 분리합니다: 보조 사이트를 일시 정지합니다.
주요 사이트에서 OS 업그레이드를 수행합니다.
OS 업그레이드가 실패하고 주요 사이트가 복구 불가능한 경우 보조 사이트를 승격시킵니다.
사용자들을 그쪽으로 라우팅하고 나중에 다시 시도합니다.
이로 인해 최신 보조 사이트가 없게 됩니다는 점에 유의하세요.

OS 업그레이드 중 GitLab에 대한 읽기 전용 액세스를 사용자에게 제공하려면 (부분 다운타임):

주요 사이트를 중지하는 대신 유지 관리 모드를 활성화합니다.
보조 사이트를 승격시키지만 아직 사용자들을 그쪽으로 라우팅하지 않습니다.
승격된 사이트에서 OS 업그레이드를 수행합니다.
이전 주요 사이트 대신 승격된 사이트로 사용자들을 라우팅합니다.
이전 주요 사이트를 새로운 보조 사이트로 설정합니다.

경고: 보조 사이트에 이미 데이터베이스의 읽기 복제본이 있지만, 승격하기 전에 운영 체제를 업그레이드할 수 없습니다. 그렇게 시도하면 보조 사이트가 손상된 인덱스로 인해 일부 Git 레포지토리나 파일의 복제를 놓칠 수 있습니다. 스트리밍 복제를 참조하세요.

PostgreSQL용 운영 체제 업그레이드

백업 및 복원

Geo 보조 사이트가 있는 백업 및 복원

모든 인덱스 재작성

Geo 보조 사이트와 함께 모든 인덱스 재작성

영향을 받은 인덱스만 재작성

영향을 받는 인덱스만 재구성하기, Geo 보조 사이트와 함께

`glibc` 버전 확인하기

`glibc` 정렬 버전 확인하기

정렬 일치 예시

잘못된 정렬 예제

스트리밍 복제

추가 Geo 변형

도움말

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

도움받기

PostgreSQL용 운영 체제 업그레이드

백업 및 복원

Geo 보조 사이트가 있는 백업 및 복원

모든 인덱스 재작성

Geo 보조 사이트와 함께 모든 인덱스 재작성

영향을 받은 인덱스만 재작성

영향을 받는 인덱스만 재구성하기, Geo 보조 사이트와 함께

glibc 버전 확인하기

glibc 정렬 버전 확인하기

정렬 일치 예시

잘못된 정렬 예제

스트리밍 복제

추가 Geo 변형

도움말

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

도움받기

`glibc` 버전 확인하기

`glibc` 정렬 버전 확인하기