PostgreSQL이 실행되는 운영 체제를 업그레이드하면 로케일 데이터의 변경이 데이터베이스 인덱스를 손상시킬 수 있습니다. 특히 glibc 2.28로의 업그레이드는 이 문제를 유발할 가능성이 높습니다. 이 문제를 방지하려면 복잡도 순서로 다음 옵션 중 하나를 사용하여 마이그레이션하세요:

• 권장. 백업 및 복원.
• 권장. 전체 인덱스 재빌드.
• 영향받은 인덱스만 재빌드.

마이그레이션을 시도하기 전에 반드시 백업하고, 프로덕션과 유사한 환경에서 마이그레이션 프로세스를 검증하세요. 다운타임 길이가 문제가 될 수 있다면, 프로덕션과 유사한 환경에서 프로덕션 데이터 복사본으로 다른 방법을 시험해 보세요.

스케일 아웃된 GitLab 환경을 실행 중이고 PostgreSQL이 실행되는 노드에 다른 서비스가 없는 경우, PostgreSQL 노드의 운영 체제만 별도로 업그레이드하는 것을 권장합니다. 복잡성과 위험을 줄이기 위해, Puma나 Sidekiq만 실행하는 노드의 운영 체제 업그레이드와 같이 다운타임이 필요하지 않은 변경 사항과 이 절차를 병행하지 마세요.

GitLab이 이 문제를 해결하기 위한 계획에 대한 자세한 내용은 에픽 8573을 참조하세요.

백업 및 복원#

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

1. 예약된 다운타임 창을 확보합니다. 모든 노드에서 불필요한 GitLab 서비스를 중지합니다:

   gitlab-ctl stop
   gitlab-ctl start postgresql
   

2. pg_dump 또는 GitLab 백업 도구(db를 제외한 모든 데이터 유형 제외)로 PostgreSQL 데이터베이스를 백업합니다(데이터베이스만 백업됩니다).

3. 모든 PostgreSQL 노드에서 OS를 업그레이드합니다.

4. 모든 PostgreSQL 노드에서 운영 체제 업그레이드 후 GitLab 패키지 소스를 업데이트합니다.

5. 모든 PostgreSQL 노드에서 동일한 GitLab 버전의 새 GitLab 패키지를 설치합니다.

6. 백업에서 PostgreSQL 데이터베이스를 복원합니다.

7. 모든 노드에서 GitLab을 시작합니다.

장점:

• 간단명료합니다.
• 인덱스와 테이블의 데이터베이스 부풀림을 제거하여 디스크 사용량을 줄입니다.

단점:

• 다운타임은 데이터베이스 크기에 따라 증가하며, 어느 시점에는 문제가 될 수 있습니다. 여러 요소에 따라 다르지만, 데이터베이스가 100GB를 초과하면 약 24시간이 소요될 수 있습니다.

Geo 보조 사이트를 이용한 백업 및 복원#

1. 예약된 다운타임 창을 확보합니다. 모든 사이트의 모든 노드에서 불필요한 GitLab 서비스를 중지합니다:

   gitlab-ctl stop
   gitlab-ctl start postgresql
   

2. 기본 사이트에서 pg_dump 또는 GitLab 백업 도구(db를 제외한 모든 데이터 유형 제외)로 PostgreSQL 데이터베이스를 백업합니다(데이터베이스만 백업됩니다).

3. 모든 사이트의 모든 PostgreSQL 노드에서 OS를 업그레이드합니다.

4. 모든 사이트의 모든 PostgreSQL 노드에서 운영 체제 업그레이드 후 GitLab 패키지 소스를 업데이트합니다.

5. 모든 사이트의 모든 PostgreSQL 노드에서 동일한 GitLab 버전의 새 GitLab 패키지를 설치합니다.

6. 기본 사이트에서 백업으로부터 PostgreSQL 데이터베이스를 복원합니다.

7. 선택적으로, 보조 사이트가 웜 스탠바이로 없다는 위험을 감수하고 기본 사이트 사용을 시작합니다.

8. 보조 사이트에 다시 PostgreSQL 스트리밍 복제를 설정합니다.

9. 보조 사이트가 사용자 트래픽을 받는 경우, GitLab을 시작하기 전에 읽기 전용 복제본 데이터베이스가 따라잡을 때까지 기다립니다.

10. 모든 사이트의 모든 노드에서 GitLab을 시작합니다.

전체 인덱스 재빌드#

전체 인덱스 재빌드.

1. 예약된 다운타임 창을 확보합니다. 모든 노드에서 불필요한 GitLab 서비스를 중지합니다:

   gitlab-ctl stop
   gitlab-ctl start postgresql
   

2. 모든 PostgreSQL 노드에서 OS를 업그레이드합니다.

3. 모든 PostgreSQL 노드에서 운영 체제 업그레이드 후 GitLab 패키지 소스를 업데이트합니다.

4. 모든 PostgreSQL 노드에서 동일한 GitLab 버전의 새 GitLab 패키지를 설치합니다.

5. 데이터베이스 콘솔에서 모든 인덱스를 재빌드합니다:

   SET statement_timeout = 0;
   REINDEX DATABASE gitlabhq_production;
   

6. 데이터베이스를 재인덱싱한 후 영향받은 모든 콜레이션에 대한 버전을 갱신해야 합니다. 현재 콜레이션 버전을 기록하도록 시스템 카탈로그를 업데이트하려면:

   ALTER DATABASE gitlabhq_production REFRESH COLLATION VERSION;
   

   template1이나 postgres와 같은 시스템 데이터베이스도 PostgreSQL 시작 시 콜레이션 문제가 있을 수 있습니다. 오류 메시지의 힌트를 확인하고 해당 데이터베이스에서도 콜레이션을 갱신하세요.

7. 모든 노드에서 GitLab을 시작합니다.

장점:

• 간단명료합니다.
• 여러 요소에 따라 백업 및 복원보다 빠를 수 있습니다.
• 인덱스의 데이터베이스 부풀림을 제거하여 디스크 사용량을 줄입니다.

단점:

• 다운타임은 데이터베이스 크기에 따라 증가하며, 어느 시점에는 문제가 될 수 있습니다.

Geo 보조 사이트를 이용한 전체 인덱스 재빌드#

1. 예약된 다운타임 창을 확보합니다. 모든 사이트의 모든 노드에서 불필요한 GitLab 서비스를 중지합니다:

   gitlab-ctl stop
   gitlab-ctl start postgresql
   

2. 모든 PostgreSQL 노드에서 OS를 업그레이드합니다.

3. 모든 PostgreSQL 노드에서 운영 체제 업그레이드 후 GitLab 패키지 소스를 업데이트합니다.

4. 모든 PostgreSQL 노드에서 동일한 GitLab 버전의 새 GitLab 패키지를 설치합니다.

5. 기본 사이트의 데이터베이스 콘솔에서 모든 인덱스를 재빌드합니다:

   SET statement_timeout = 0;
   REINDEX DATABASE gitlabhq_production;
   

6. 데이터베이스를 재인덱싱한 후 영향받은 모든 콜레이션에 대한 버전을 갱신해야 합니다. 현재 콜레이션 버전을 기록하도록 시스템 카탈로그를 업데이트하려면:

   ALTER DATABASE <database_name> REFRESH COLLATION VERSION;
   

7. 보조 사이트가 사용자 트래픽을 받는 경우, GitLab을 시작하기 전에 읽기 전용 복제본 데이터베이스가 따라잡을 때까지 기다립니다.

8. 모든 사이트의 모든 노드에서 GitLab을 시작합니다.

영향받은 인덱스만 재빌드#

이것은 GitLab.com에서 사용되는 방식과 유사합니다. 이 프로세스와 다양한 유형의 인덱스가 어떻게 처리되었는지에 대한 자세한 내용은 PostgreSQL 데이터베이스 클러스터의 운영 체제 업그레이드에 관한 블로그 포스트를 참조하세요.

1. 예약된 다운타임 창을 확보합니다. 모든 노드에서 불필요한 GitLab 서비스를 중지합니다:

   gitlab-ctl stop
   gitlab-ctl start postgresql
   

2. 모든 PostgreSQL 노드에서 OS를 업그레이드합니다.

3. 모든 PostgreSQL 노드에서 운영 체제 업그레이드 후 GitLab 패키지 소스를 업데이트합니다.

4. 모든 PostgreSQL 노드에서 동일한 GitLab 버전의 새 GitLab 패키지를 설치합니다.

5. 영향받은 인덱스를 확인합니다.

6. 데이터베이스 콘솔에서 영향받은 각 인덱스를 재인덱싱합니다:

   SET statement_timeout = 0;
   REINDEX INDEX <index name> CONCURRENTLY;
   

7. 잘못된 인덱스를 재인덱싱한 후 콜레이션을 갱신해야 합니다. 현재 콜레이션 버전을 기록하도록 시스템 카탈로그를 업데이트하려면:

   ALTER DATABASE <database_name> REFRESH COLLATION VERSION;
   

8. 모든 노드에서 GitLab을 시작합니다.

장점:

• 영향받지 않은 인덱스를 재빌드하는 데 다운타임을 쓰지 않습니다.

단점:

• 실수할 가능성이 더 높습니다.
• 마이그레이션 중 예상치 못한 문제를 처리하기 위해 PostgreSQL에 대한 전문 지식이 필요합니다.
• 데이터베이스 부풀림이 유지됩니다.

Geo 보조 사이트를 이용한 영향받은 인덱스만 재빌드#

1. 예약된 다운타임 창을 확보합니다. 모든 사이트의 모든 노드에서 불필요한 GitLab 서비스를 중지합니다:

   gitlab-ctl stop
   gitlab-ctl start postgresql
   

2. 모든 PostgreSQL 노드에서 OS를 업그레이드합니다.

3. 모든 PostgreSQL 노드에서 운영 체제 업그레이드 후 GitLab 패키지 소스를 업데이트합니다.

4. 모든 PostgreSQL 노드에서 동일한 GitLab 버전의 새 GitLab 패키지를 설치합니다.

5. 영향받은 인덱스를 확인합니다.

6. 기본 사이트의 데이터베이스 콘솔에서 영향받은 각 인덱스를 재인덱싱합니다:

   SET statement_timeout = 0;
   REINDEX INDEX <index name> CONCURRENTLY;
   

7. 잘못된 인덱스를 재인덱싱한 후 콜레이션을 갱신해야 합니다. 현재 콜레이션 버전을 기록하도록 시스템 카탈로그를 업데이트하려면:

   ALTER DATABASE <database_name> REFRESH COLLATION VERSION;
   

8. 기존 PostgreSQL 스트리밍 복제는 재인덱스 변경 사항을 읽기 전용 복제본 데이터베이스에 복제합니다.

9. 모든 사이트의 모든 노드에서 GitLab을 시작합니다.

glibc 버전 확인#

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

다음 표는 다양한 운영 체제에서 제공되는 glibc 버전을 보여줍니다:

예를 들어, CentOS 7에서 RedHat Enterprise 8로 업그레이드한다고 가정합니다. 이 경우 glibc가 2.17에서 2.28로 업그레이드되므로 언급된 두 가지 방법 중 하나를 사용하여 업그레이드된 운영 체제에서 PostgreSQL을 사용해야 합니다. 콜레이션 변경 사항을 제대로 처리하지 않으면 태그가 있는 작업을 러너가 선택하지 못하는 등 GitLab에서 심각한 장애가 발생합니다.

반면에 PostgreSQL이 이미 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 스트리밍 복제에 영향을 미칩니다. 다른 로케일 데이터를 사용하는 복제본에 대한 읽기를 허용하기 전에 전체 인덱스를 재빌드하거나 영향받은 인덱스만 재빌드해야 합니다.

추가 Geo 변형#

이전에 설명한 업그레이드 절차는 고정된 것이 아닙니다. Geo에서는 중복 인프라가 존재하기 때문에 잠재적으로 더 많은 옵션이 있습니다. 사용 사례에 맞게 수정을 고려할 수 있지만, 추가 복잡성과 비교하여 신중하게 검토하세요. 다음은 몇 가지 예시입니다:

기본 사이트와 다른 보조 사이트의 OS 업그레이드 중 재해에 대비한 웜 스탠바이로 보조 사이트를 유지하려면:

1. 기본 사이트의 변경 사항으로부터 보조 사이트의 데이터를 격리합니다: 보조 사이트를 일시 중지합니다.
2. 기본 사이트에서 OS 업그레이드를 수행합니다.
3. OS 업그레이드가 실패하고 기본 사이트를 복구할 수 없는 경우, 보조 사이트를 승격하고 사용자를 그곳으로 라우팅한 후 나중에 다시 시도합니다. 이렇게 하면 최신 상태의 보조 사이트 없이 남게 됩니다.

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

1. 기본 사이트를 중지하는 대신 기본 사이트에서 유지 관리 모드를 활성화합니다.
2. 보조 사이트를 승격하되 아직 사용자를 라우팅하지 않습니다.
3. 승격된 사이트에서 OS 업그레이드를 수행합니다.
4. 기존 기본 사이트 대신 승격된 사이트로 사용자를 라우팅합니다.
5. 기존 기본 사이트를 새 보조 사이트로 설정합니다.