InfoGrab DocsInfoGrab Docs

제로 다운타임으로 멀티 노드 인스턴스 업그레이드

요약

멀티 노드 GitLab 환경을 제로 다운타임으로 업그레이드하는 과정은 업그레이드 순서에 따라 각 노드를 순차적으로 거치는 방식으로 진행됩니다. 제로 다운타임 업그레이드를 시작하기 전에 다운타임 옵션을 검토합니다. 업그레이드 과정에서 제로 다운타임을 달성하는 것은 분산 애플리케이션이라면 어디서든 특히 어려운 일입니다.

멀티 노드 GitLab 환경을 제로 다운타임으로 업그레이드하는 과정은 업그레이드 순서에 따라 각 노드를 순차적으로 거치는 방식으로 진행됩니다. 로드 밸런서와 HA 메커니즘이 각 노드가 다운되는 상황을 그에 맞게 처리합니다.

제로 다운타임 업그레이드를 시작하기 전에 다운타임 옵션을 검토합니다.

시작하기 전에#

업그레이드 과정에서 제로 다운타임을 달성하는 것은 분산 애플리케이션이라면 어디서든 특히 어려운 일입니다. 이 문서 는 당사의 HA 참조 아키텍처를 대상으로 주어진 그대로 테스트되었으며, 실질적으로 관측 가능한 다운타임 없이 완료되었습니다. 다만 구체적인 시스템 구성에 따라 결과는 달라질 수 있다는 점에 유의합니다.

추가적인 확신을 얻기 위해 일부 고객은 특정 로드 밸런서나 인프라 기능을 사용해 노드를 수동으로 드레인하는 등의 추가 기법으로 성공을 거두기도 했습니다. 이러한 기법은 기반 인프라 기능에 크게 좌우됩니다.

추가 정보가 필요하면 GitLab 담당자 또는 지원 팀에 문의합니다.

요구 사항#

제로 다운타임 업그레이드 프로세스를 수행하려면 Linux 패키지로 구축된 멀티 노드 GitLab 환경에 다음과 같이 로드 밸런싱과 사용 가능한 HA 메커니즘이 구성되어 있어야 합니다.

  • GitLab 애플리케이션 노드용 외부 로드 밸런서가 구성되어 있고, readiness (/-/readiness) 엔드포인트에 대한 상태 확인이 활성화되어 있어야 합니다.
  • PgBouncer와 Praefect 컴포넌트용 내부 로드 밸런서가 구성되어 있고 TCP 상태 확인이 활성화되어 있어야 합니다.
  • Consul, Postgres, Redis 컴포넌트가 있다면 HA 메커니즘이 구성되어 있어야 합니다.

제로 다운타임 업그레이드를 수행하려면 다음을 지켜야 합니다.

  • 마이너 릴리스를 한 번에 하나씩만 업그레이드합니다. 즉 16.1에서 16.2로 이동하며, 16.3으로 바로 이동하지 않습니다. 릴리스를 건너뛰면 데이터베이스 수정 사항이 잘못된 순서로 실행되어 데이터베이스 스키마가 손상된 상태로 남을 수 있습니다.
  • 배포 후 마이그레이션(post-deployment migrations)을 사용합니다.

고려 사항#

제로 다운타임 업그레이드를 고려할 때는 다음 사항에 유의합니다.

  • 대부분의 경우 패치 릴리스가 최신 버전이 아니더라도 다음 마이너 릴리스로 안전하게 업그레이드할 수 있습니다. 예를 들어 16.3.3이 릴리스된 이후라도 16.3.2에서 16.4.1로 업그레이드하는 것은 안전해야 합니다. 업그레이드 경로에 해당하는 버전별 업그레이드 노트를 확인하고 필요한 업그레이드 정지 지점이 있는지 확인해야 합니다.

  • 일부 릴리스에는 백그라운드 마이그레이션이 포함될 수 있습니다. 이 마이그레이션은 Sidekiq이 백그라운드에서 수행하며 주로 데이터 이관에 사용됩니다. 백그라운드 마이그레이션은 월간 릴리스에만 추가됩니다.

    • 특정 메이저 또는 마이너 릴리스는 일련의 백그라운드 마이그레이션이 완료되어야 할 수 있습니다. 앞서 언급한 조건이 충족된다면 이 자체로 다운타임이 필요하지는 않지만, 각 메이저 또는 마이너 릴리스 업그레이드 사이에는 백그라운드 마이그레이션이 완료될 때까지 기다려야 합니다.
    • 이 마이그레이션을 완료하는 데 필요한 시간은 background_migration 큐의 작업을 처리할 수 있는 Sidekiq 워커 수를 늘려 줄일 수 있습니다. 이 큐의 크기를 확인하려면 업그레이드 전에 백그라운드 마이그레이션을 확인합니다.

  • Gitaly는 정상 종료 후 재로드(graceful reload) 메커니즘 덕분에 제로 다운타임 업그레이드가 가능합니다. Gitaly Cluster(Praefect) 컴포넌트 역시 다운타임 없이 직접 업그레이드할 수 있습니다. 다만 Linux 패키지는 Praefect 데이터베이스에 대해 HA나 제로 다운타임을 지원하지 않으며, 다운타임을 피하려면 서드 파티 데이터베이스 솔루션이 필요합니다.

  • PostgreSQL 메이저 버전 업그레이드는 별도의 프로세스이며 제로 다운타임 업그레이드 범위에 포함되지 않습니다. 그보다 작은 단위의 업그레이드는 이 범위에 포함됩니다.

  • 제로 다운타임 업그레이드는 Linux 패키지로 배포한, 앞서 언급한 GitLab 컴포넌트에 대해서만 지원됩니다. AWS RDS의 PostgreSQL이나 GCP Memorystore의 Redis처럼 지원되는 서드 파티 서비스를 통해 일부 컴포넌트를 배포한 경우, 해당 서비스의 업그레이드는 각 서비스의 표준 프로세스에 따라 별도로 수행해야 합니다.

  • 일반적인 지침으로, 데이터 양이 많을수록 업그레이드를 완료하는 데 더 많은 시간이 필요합니다. 테스트 결과 10GB 미만의 데이터베이스는 일반적으로 1시간을 넘기지 않았지만, 실제 결과는 환경에 따라 달라질 수 있습니다.

업그레이드 순서#

제로 다운타임으로 업그레이드할 컴포넌트의 순서는 후방에서 전방으로(back-to-front) 접근하는 방식을 따라야 합니다.

  1. 상태를 갖는 백엔드(Stateful backends)
  2. 백엔드 의존 컴포넌트(Backend dependents)
  3. 프론트엔드(Frontends)

배포 순서는 변경할 수 있지만, GitLab 애플리케이션 코드를 실행하는 컴포넌트(예: Rails와 Sidekiq)는 함께 배포해야 합니다. 이 컴포넌트들은 메이저 릴리스의 버전 업그레이드에서 도입된 변경 사항에 의존하지 않으므로, 가능하다면 지원 인프라는 별도로 업그레이드합니다.

GitLab 컴포넌트는 다음 순서로 업그레이드해야 합니다.

  1. Consul
  2. PostgreSQL
  3. PgBouncer
  4. Redis
  5. Gitaly
  6. Praefect
  7. Rails
  8. Sidekiq

Consul, PostgreSQL, PgBouncer, Redis 노드 업그레이드#

Consul, PostgreSQL, PgBouncer, Redis 컴포넌트는 모두 다운타임 없이 업그레이드하는 동일한 기본 프로세스를 따릅니다.

각 컴포넌트의 노드에서 다음과 같이 업그레이드를 수행합니다.

  1. /etc/gitlab/skip-auto-reconfigure에 빈 파일을 생성합니다. 이렇게 하면 업그레이드가 gitlab-ctl reconfigure를 실행하지 않도록 막을 수 있습니다. 기본적으로 이 명령은 GitLab을 자동으로 중지하고, 모든 데이터베이스 마이그레이션을 실행한 뒤 GitLab을 재시작합니다.

    sudo touch /etc/gitlab/skip-auto-reconfigure

  2. Linux 패키지로 업그레이드하여 노드를 업그레이드합니다.

  3. 재구성(reconfigure) 후 재시작하여 최신 코드를 적용합니다.

    sudo gitlab-ctl reconfigure

Consul 클라이언트를 먼저 재시작한 다음 나머지 모든 서비스를 재시작하여 PostgreSQL 페일오버가 정상적으로 이루어지도록 합니다.

sudo gitlab-ctl restart consul
sudo gitlab-ctl restart-except consul

   sudo gitlab-ctl restart

Gitaly 노드 업그레이드#

Gitaly는 업그레이드에서 동일한 핵심 프로세스를 따르지만, 가장 이른 시점에 정상적으로 재로드하는 내장 프로세스를 갖고 있어 Gitaly 프로세스 자체는 재시작되지 않는다는 중요한 차이가 있습니다. 다른 컴포넌트는 여전히 재시작해야 합니다.

이 프로세스는 Gitaly Sharded 구성과 Cluster 구성 모두에 적용됩니다. 업그레이드를 수행하려면 각 Gitaly 노드에서 다음 단계를 순서대로 진행합니다.

  1. /etc/gitlab/skip-auto-reconfigure에 빈 파일을 생성합니다. 이렇게 하면 업그레이드가 gitlab-ctl reconfigure를 실행하지 않도록 막을 수 있습니다. 기본적으로 이 명령은 GitLab을 자동으로 중지하고, 모든 데이터베이스 마이그레이션을 실행한 뒤 GitLab을 재시작합니다.

    sudo touch /etc/gitlab/skip-auto-reconfigure

  2. Linux 패키지로 업그레이드하여 노드를 업그레이드합니다.

  3. reconfigure 명령을 실행하여 최신 코드를 적용하고, 다음 기회에 Gitaly가 정상적으로 재로드하도록 지시합니다.

    sudo gitlab-ctl reconfigure

  4. 마지막으로, Gitaly가 정상적으로 재로드되는 동안 배포된 다른 컴포넌트는 여전히 재시작해야 합니다.

    # Get a list of what other components have been deployed beside Gitaly
sudo gitlab-ctl status

# Restart each component except Gitaly. Example given for Consul, Node Exporter and Logrotate
sudo gitlab-ctl restart consul node-exporter logrotate

Gitaly Cluster(Praefect) 노드 업그레이드#

Note

이 섹션은 필요한 PostgreSQL 데이터베이스가 아니라 Praefect 컴포넌트에만 초점을 맞춥니다. GitLab Linux 패키지는 HA를 제공하지 않으며, 그에 따라 Praefect 데이터베이스에 대한 제로 다운타임도 지원하지 않습니다. 다운타임을 피하려면 서드 파티 데이터베이스 솔루션이 필요합니다.

Gitaly Cluster(Praefect) 구성에서는 정상 재로드(graceful reload)를 사용하는 유사한 방식으로 Praefect를 배포하고 업그레이드해야 합니다.

Note

업그레이드 프로세스는 새로운 Praefect 프로세스로 정상적인 핸드오버를 시도합니다. 업그레이드 이전에 시작되어 오래 실행 중이던 Git 요청은 이 핸드오버가 진행되는 동안 결국 중단될 수 있습니다.

Gitaly Cluster(Praefect)를 사용하는 인스턴스를 업그레이드할 때는 다음 순서로 컴포넌트를 업그레이드합니다.

  1. Praefect PostgreSQL 데이터베이스. Linux 패키지는 이 데이터베이스에 대해 HA를 제공하지 않으므로, 서드 파티 HA 데이터베이스 솔루션을 사용하지 않는 한 이 단계에는 다운타임이 필요합니다.
  2. Gitaly 노드. Gitaly 업그레이드 단계를 사용하여 순차적으로 업그레이드합니다.
  3. Praefect 노드. 아래 설명에 따라 업그레이드하며, 한 노드를 데이터베이스 마이그레이션을 실행하는 배포 노드로 지정합니다.

Praefect도 기존 데이터를 업그레이드하기 위해 데이터베이스 마이그레이션을 수행해야 합니다. 충돌을 피하려면 마이그레이션은 하나의 Praefect 노드에서만 실행해야 합니다. 이를 위해 마이그레이션을 실행할 Praefect 배포 노드를 지정합니다.

  1. Praefect 배포 노드에서 다음을 수행합니다.

    1. /etc/gitlab/skip-auto-reconfigure에 빈 파일을 생성합니다. 이렇게 하면 업그레이드가 gitlab-ctl reconfigure를 실행하지 않도록 막을 수 있습니다. 기본적으로 이 명령은 GitLab을 자동으로 중지하고, 모든 데이터베이스 마이그레이션을 실행한 뒤 GitLab을 재시작합니다.

      sudo touch /etc/gitlab/skip-auto-reconfigure

    2. Linux 패키지로 업그레이드하여 노드를 업그레이드합니다.

    3. 데이터베이스 마이그레이션이 실행되도록 /etc/gitlab/gitlab.rb에 praefect['auto_migrate'] = true가 설정되어 있는지 확인합니다.

    4. reconfigure 명령을 실행하여 최신 코드를 적용하고, Praefect 데이터베이스 마이그레이션을 적용한 뒤 정상적으로 재시작합니다.

      sudo gitlab-ctl reconfigure

    5. 계속 진행하기 전에 모든 Praefect 데이터베이스 마이그레이션이 적용되었는지 확인합니다.

      sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml sql-migrate-status

      모든 마이그레이션이 적용됨으로 표시되어야 합니다. 이를 확인하기 전까지는 나머지 Praefect 노드로 진행하지 않습니다.

  2. 나머지 모든 Praefect 노드에서 다음을 수행합니다.

    1. /etc/gitlab/skip-auto-reconfigure에 빈 파일을 생성합니다. 이렇게 하면 업그레이드가 gitlab-ctl reconfigure를 실행하지 않도록 막을 수 있습니다. 기본적으로 이 명령은 GitLab을 자동으로 중지하고, 모든 데이터베이스 마이그레이션을 실행한 뒤 GitLab을 재시작합니다.

      sudo touch /etc/gitlab/skip-auto-reconfigure

    2. Linux 패키지로 업그레이드하여 노드를 업그레이드합니다.

    3. reconfigure가 데이터베이스 마이그레이션을 자동으로 실행하지 않도록 /etc/gitlab/gitlab.rb에 praefect['auto_migrate'] = false가 설정되어 있는지 확인합니다.

    4. reconfigure 명령을 실행하여 최신 코드를 적용하고 정상적으로 재시작합니다.

      sudo gitlab-ctl reconfigure

  3. 마지막으로, Praefect가 정상적으로 재로드되는 동안 배포된 다른 컴포넌트는 여전히 재시작해야 합니다. 모든 Praefect 노드에서 다음을 수행합니다.

    # Get a list of what other components have been deployed beside Praefect
sudo gitlab-ctl status

# Restart each component except Praefect. Example given for Consul, Node Exporter and Logrotate
sudo gitlab-ctl restart consul node-exporter logrotate

GitLab 애플리케이션(Rails) 노드 업그레이드#

웹 서버로서의 Rails는 주로 Puma, Workhorse, NGINX로 구성됩니다.

이 컴포넌트들은 라이브 업그레이드를 수행할 때 각각 다른 동작을 보입니다. Puma는 정상 재로드를 허용할 수 있지만 Workhorse는 그렇지 않습니다. 가장 좋은 방법은 로드 밸런서 사용 등 다른 수단을 통해 노드를 정상적으로 드레인하는 것입니다. 노드에서 NGINX의 정상 종료(graceful shutdown) 기능을 사용해 이를 수행할 수도 있습니다. 이 섹션에서는 NGINX 방식을 설명합니다.

앞서 설명한 내용에 더해, Rails는 주요 데이터베이스 마이그레이션이 실행되어야 하는 지점이기도 합니다. Praefect와 마찬가지로 가장 좋은 방법은 배포 노드를 사용하는 것입니다. 현재 PgBouncer를 사용하고 있다면 이 역시 우회해야 합니다. Rails는 동일한 데이터베이스에서 동시에 마이그레이션이 실행되는 것을 막기 위해 마이그레이션을 실행할 때 권고 잠금(advisory lock)을 사용하기 때문입니다. 이 잠금은 트랜잭션 간에 공유되지 않으므로, 트랜잭션 풀링 모드의 PgBouncer를 사용해 데이터베이스 마이그레이션을 실행하면 ActiveRecord::ConcurrentMigrationError를 비롯한 문제가 발생합니다.

  1. Rails 배포 노드에서 다음을 수행합니다.

    1. 노드의 트래픽을 정상적으로 드레인합니다. 다양한 방법이 있지만, 한 가지 방법은 NGINX에 QUIT 신호를 보낸 다음 서비스를 중지하는 것입니다. 예를 들어 다음과 같은 셸 스크립트로 이를 수행할 수 있습니다.

      # Send QUIT to NGINX master process to drain and exit
NGINX_PID=$(cat /var/opt/gitlab/nginx/nginx.pid)
kill -QUIT $NGINX_PID

# Wait for drain to complete
while kill -0 $NGINX_PID 2>/dev/null; do sleep 1; done

# Stop NGINX service to prevent automatic restarts
gitlab-ctl stop nginx

    2. /etc/gitlab/skip-auto-reconfigure에 빈 파일을 생성합니다. 이렇게 하면 업그레이드가 gitlab-ctl reconfigure를 실행하지 않도록 막을 수 있습니다. 기본적으로 이 명령은 GitLab을 자동으로 중지하고, 모든 데이터베이스 마이그레이션을 실행한 뒤 GitLab을 재시작합니다.

      sudo touch /etc/gitlab/skip-auto-reconfigure

    3. Linux 패키지로 업그레이드하여 GitLab을 업그레이드합니다.

    4. /etc/gitlab/gitlab.rb 설정 파일에 gitlab_rails['auto_migrate'] = true를 설정하여 일반 마이그레이션이 실행되도록 구성합니다.

      • 배포 노드가 PgBouncer를 거쳐 데이터베이스에 접근하는 경우, 마이그레이션을 실행하기 전에 이를 우회하여 데이터베이스 리더에 직접 연결해야 합니다.
      • 데이터베이스 리더는 아무 데이터베이스 노드에서 sudo gitlab-ctl patroni members 명령을 실행하여 확인할 수 있습니다.

    5. 일반 마이그레이션을 실행하고 최신 코드를 적용합니다.

      sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-ctl reconfigure

    6. 이후 배포 후 마이그레이션을 실행하기 위해 다시 돌아올 것이므로, 지금은 이 노드를 그대로 둡니다.

  2. 그 외 모든 Rails 노드에서 순차적으로 다음을 수행합니다.

    1. 노드의 트래픽을 정상적으로 드레인합니다. 다양한 방법이 있지만, 한 가지 방법은 NGINX에 QUIT 신호를 보낸 다음 서비스를 중지하는 것입니다. 예를 들어 다음과 같은 셸 스크립트로 이를 수행할 수 있습니다.

      # Send QUIT to NGINX master process to drain and exit
NGINX_PID=$(cat /var/opt/gitlab/nginx/nginx.pid)
kill -QUIT $NGINX_PID

# Wait for drain to complete
while kill -0 $NGINX_PID 2>/dev/null; do sleep 1; done

# Stop NGINX service to prevent automatic restarts
gitlab-ctl stop nginx

    2. /etc/gitlab/skip-auto-reconfigure에 빈 파일을 생성합니다. 이렇게 하면 업그레이드가 gitlab-ctl reconfigure를 실행하지 않도록 막을 수 있습니다. 기본적으로 이 명령은 GitLab을 자동으로 중지하고, 모든 데이터베이스 마이그레이션을 실행한 뒤 GitLab을 재시작합니다.

      sudo touch /etc/gitlab/skip-auto-reconfigure

    3. Linux 패키지로 업그레이드하여 GitLab을 업그레이드합니다.

    4. reconfigure가 데이터베이스 마이그레이션을 자동으로 실행하지 않도록 /etc/gitlab/gitlab.rb에 gitlab_rails['auto_migrate'] = false가 설정되어 있는지 확인합니다.

    5. reconfigure 명령을 실행하여 최신 코드를 적용하고 재시작합니다.

      sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

  3. Rails 배포 노드에서 배포 후 마이그레이션을 실행합니다.

    1. 배포 노드가 여전히 데이터베이스 리더를 직접 가리키고 있는지 확인합니다. 노드가 PgBouncer를 거쳐 데이터베이스에 접근하는 경우, 마이그레이션을 실행하기 전에 이를 우회하여 데이터베이스 리더에 직접 연결해야 합니다.

      • 데이터베이스 리더는 아무 데이터베이스 노드에서 sudo gitlab-ctl patroni members 명령을 실행하여 확인할 수 있습니다.

    2. 배포 후 마이그레이션을 실행합니다.

      sudo gitlab-rake gitlab:db:configure

      이 작업은 ClickHouse 마이그레이션도 함께 실행하며, 스키마를 로드하여 현재 상태에 맞게 데이터베이스를 구성합니다.

    3. /etc/gitlab/gitlab.rb 설정 파일에 gitlab_rails['auto_migrate'] = false를 설정하여 구성을 원래대로 되돌립니다.

      • PgBouncer를 사용 중이라면 데이터베이스 설정이 다시 PgBouncer를 가리키도록 해야 합니다.

    4. 정상 구성을 다시 적용하기 위해 reconfigure를 다시 실행하고 재시작합니다.

      sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

Sidekiq 노드 업그레이드#

Sidekiq는 다운타임 없이 업그레이드하는 데 있어 다른 컴포넌트와 동일한 기본 프로세스를 따릅니다.

업그레이드를 수행하려면 각 컴포넌트 노드에서 다음 단계를 순서대로 진행합니다.

  1. /etc/gitlab/skip-auto-reconfigure에 빈 파일을 생성합니다. 이렇게 하면 업그레이드가 gitlab-ctl reconfigure를 실행하지 않도록 막을 수 있습니다. 기본적으로 이 명령은 GitLab을 자동으로 중지하고, 모든 데이터베이스 마이그레이션을 실행한 뒤 GitLab을 재시작합니다.

    sudo touch /etc/gitlab/skip-auto-reconfigure

  2. Linux 패키지로 업그레이드하여 노드를 업그레이드합니다.

  3. reconfigure 명령을 실행하여 최신 코드를 적용하고 재시작합니다.

    sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

멀티 노드 Geo 인스턴스 업그레이드#

이 섹션에서는 Geo를 사용하는 라이브 GitLab 환경 배포를 업그레이드하는 데 필요한 단계를 설명합니다.

전반적으로 이 방식은 일반 프로세스와 대체로 동일하지만, 각 보조 사이트(secondary site)에 몇 가지 추가 단계가 필요합니다. 필요한 순서는 먼저 프라이머리를 업그레이드한 다음 보조 사이트를 업그레이드하는 것입니다. 또한 모든 보조 사이트가 업데이트된 후에는 프라이머리에서 배포 후 마이그레이션을 실행해야 합니다.

Note

Geo를 사용하는 라이브 GitLab 환경을 업그레이드할 때도 동일한 요구 사항과 고려 사항이 적용됩니다.

기본 사이트#

기본 사이트의 업그레이드 프로세스는 모든 보조 사이트가 업데이트될 때까지 배포 후 마이그레이션을 실행하지 않는다는 점을 제외하면 일반 프로세스와 동일합니다.

기본 사이트에서는 앞서 설명한 것과 동일한 단계를 진행하되, Rails 노드에서 배포 후 마이그레이션을 실행하는 단계 직전까지만 진행합니다.

보조 사이트#

보조 사이트의 업그레이드 프로세스는 Rails 노드를 제외하면 일반 프로세스와 동일한 단계를 따릅니다. 업그레이드 프로세스는 기본 사이트와 보조 사이트 모두 동일합니다. 다만 보조 사이트의 Rails 노드에는 다음과 같은 추가 단계를 수행해야 합니다.

Rails#

  1. Rails 배포 노드에서 다음을 수행합니다.

    1. 노드의 트래픽을 정상적으로 드레인합니다. 다양한 방법이 있지만, 한 가지 방법은 NGINX에 QUIT 신호를 보낸 다음 서비스를 중지하는 것입니다. 예를 들어 다음과 같은 셸 스크립트로 이를 수행할 수 있습니다.

      # Send QUIT to NGINX master process to drain and exit
NGINX_PID=$(cat /var/opt/gitlab/nginx/nginx.pid)
kill -QUIT $NGINX_PID

# Wait for drain to complete
while kill -0 $NGINX_PID 2>/dev/null; do sleep 1; done

# Stop NGINX service to prevent automatic restarts
gitlab-ctl stop nginx

    2. Geo Log Cursor 프로세스를 중지하여 다른 노드로 페일오버되도록 합니다.

      gitlab-ctl stop geo-logcursor

    3. /etc/gitlab/skip-auto-reconfigure에 빈 파일을 생성합니다. 이렇게 하면 업그레이드가 gitlab-ctl reconfigure를 실행하지 않도록 막을 수 있습니다. 기본적으로 이 명령은 GitLab을 자동으로 중지하고, 모든 데이터베이스 마이그레이션을 실행한 뒤 GitLab을 재시작합니다.

      sudo touch /etc/gitlab/skip-auto-reconfigure

    4. Linux 패키지로 업그레이드하여 GitLab을 업그레이드합니다.

    5. 기본 사이트의 Rails 노드와 보조 사이트의 Rails 노드에서 /etc/gitlab/gitlab-secrets.json 파일이 서로 다르다면 기본 사이트에서 보조 사이트로 이 파일을 복사합니다. 이 파일은 한 사이트의 모든 노드에서 동일해야 합니다.

    6. /etc/gitlab/gitlab.rb 설정 파일에 gitlab_rails['auto_migrate'] = false와 geo_secondary['auto_migrate'] = false를 설정하여 마이그레이션이 자동으로 실행되도록 구성되지 않았는지 확인합니다.

    7. reconfigure 명령을 실행하여 최신 코드를 적용하고 재시작합니다.

      sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

    8. 일반 Geo Tracking 마이그레이션을 실행하고 최신 코드를 적용합니다.

      sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-rake db:migrate:geo

  2. 그 외 모든 Rails 노드에서 순차적으로 다음을 수행합니다.

    1. 노드의 트래픽을 정상적으로 드레인합니다. 다양한 방법이 있지만, 한 가지 방법은 NGINX에 QUIT 신호를 보낸 다음 서비스를 중지하는 것입니다. 예를 들어 다음과 같은 셸 스크립트로 이를 수행할 수 있습니다.

      # Send QUIT to NGINX master process to drain and exit
NGINX_PID=$(cat /var/opt/gitlab/nginx/nginx.pid)
kill -QUIT $NGINX_PID

# Wait for drain to complete
while kill -0 $NGINX_PID 2>/dev/null; do sleep 1; done

# Stop NGINX service to prevent automatic restarts
gitlab-ctl stop nginx

    2. Geo Log Cursor 프로세스를 중지하여 다른 노드로 페일오버되도록 합니다.

      gitlab-ctl stop geo-logcursor

    3. /etc/gitlab/skip-auto-reconfigure에 빈 파일을 생성합니다. 이렇게 하면 업그레이드가 gitlab-ctl reconfigure를 실행하지 않도록 막을 수 있습니다. 기본적으로 이 명령은 GitLab을 자동으로 중지하고, 모든 데이터베이스 마이그레이션을 실행한 뒤 GitLab을 재시작합니다.

      sudo touch /etc/gitlab/skip-auto-reconfigure

    4. Linux 패키지로 업그레이드하여 GitLab을 업그레이드합니다.

    5. /etc/gitlab/gitlab.rb 설정 파일에 gitlab_rails['auto_migrate'] = false와 geo_secondary['auto_migrate'] = false를 설정하여 마이그레이션이 자동으로 실행되도록 구성되지 않았는지 확인합니다.

    6. reconfigure 명령을 실행하여 최신 코드를 적용하고 재시작합니다.

      sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

Sidekiq#

메인 프로세스를 따랐다면 이제 남은 작업은 Sidekiq을 업그레이드하는 것뿐입니다.

메인 섹션에서 설명한 것과 동일한 방식으로 Sidekiq을 업그레이드합니다.

배포 후 마이그레이션#

마지막으로 기본 사이트로 돌아가 배포 후 마이그레이션을 실행하여 업그레이드를 마무리합니다.

  1. 기본 사이트의 Rails 배포 노드에서 배포 후 마이그레이션을 실행합니다.

    1. 배포 노드가 여전히 데이터베이스 리더를 직접 가리키고 있는지 확인합니다. 노드가 PgBouncer를 거쳐 데이터베이스에 접근하는 경우, 마이그레이션을 실행하기 전에 이를 우회하여 데이터베이스 리더에 직접 연결해야 합니다.

      • 데이터베이스 리더는 아무 데이터베이스 노드에서 sudo gitlab-ctl patroni members 명령을 실행하여 확인할 수 있습니다.

    2. 배포 후 마이그레이션을 실행합니다.

      sudo gitlab-rake gitlab:db:configure

    3. Geo 구성과 의존성을 확인합니다.

      sudo gitlab-rake gitlab:geo:check

    4. /etc/gitlab/gitlab.rb 설정 파일에 gitlab_rails['auto_migrate'] = false를 설정하여 구성을 원래대로 되돌립니다.

      • PgBouncer를 사용 중이라면 데이터베이스 설정이 다시 PgBouncer를 가리키도록 해야 합니다.

    5. 정상 구성을 다시 적용하기 위해 reconfigure를 다시 실행하고 재시작합니다.

      sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

  2. 보조 사이트의 Rails 배포 노드에서 배포 후 Geo Tracking 마이그레이션을 실행합니다.

    1. 배포 후 Geo Tracking 마이그레이션을 실행합니다.

      sudo gitlab-rake db:migrate:geo

    2. Geo 상태를 확인합니다.

      sudo gitlab-rake gitlab:geo:status

제로 다운타임으로 멀티 노드 인스턴스 업그레이드

GitLab v19.5
Tier: Premium, Ultimate
Offering: GitLab Self-Managed
원문 보기

요약

멀티 노드 GitLab 환경을 제로 다운타임으로 업그레이드하는 과정은 업그레이드 순서에 따라 각 노드를 순차적으로 거치는 방식으로 진행됩니다. 제로 다운타임 업그레이드를 시작하기 전에 다운타임 옵션을 검토합니다. 업그레이드 과정에서 제로 다운타임을 달성하는 것은 분산 애플리케이션이라면 어디서든 특히 어려운 일입니다.

멀티 노드 GitLab 환경을 제로 다운타임으로 업그레이드하는 과정은 업그레이드 순서에 따라 각 노드를 순차적으로 거치는 방식으로 진행됩니다. 로드 밸런서와 HA 메커니즘이 각 노드가 다운되는 상황을 그에 맞게 처리합니다.

제로 다운타임 업그레이드를 시작하기 전에 다운타임 옵션을 검토합니다.

시작하기 전에#

업그레이드 과정에서 제로 다운타임을 달성하는 것은 분산 애플리케이션이라면 어디서든 특히 어려운 일입니다. 이 문서 는 당사의 HA 참조 아키텍처를 대상으로 주어진 그대로 테스트되었으며, 실질적으로 관측 가능한 다운타임 없이 완료되었습니다. 다만 구체적인 시스템 구성에 따라 결과는 달라질 수 있다는 점에 유의합니다.

추가적인 확신을 얻기 위해 일부 고객은 특정 로드 밸런서나 인프라 기능을 사용해 노드를 수동으로 드레인하는 등의 추가 기법으로 성공을 거두기도 했습니다. 이러한 기법은 기반 인프라 기능에 크게 좌우됩니다.

추가 정보가 필요하면 GitLab 담당자 또는 지원 팀에 문의합니다.

요구 사항#

제로 다운타임 업그레이드 프로세스를 수행하려면 Linux 패키지로 구축된 멀티 노드 GitLab 환경에 다음과 같이 로드 밸런싱과 사용 가능한 HA 메커니즘이 구성되어 있어야 합니다.

  • GitLab 애플리케이션 노드용 외부 로드 밸런서가 구성되어 있고, readiness (/-/readiness) 엔드포인트에 대한 상태 확인이 활성화되어 있어야 합니다.
  • PgBouncer와 Praefect 컴포넌트용 내부 로드 밸런서가 구성되어 있고 TCP 상태 확인이 활성화되어 있어야 합니다.
  • Consul, Postgres, Redis 컴포넌트가 있다면 HA 메커니즘이 구성되어 있어야 합니다.

제로 다운타임 업그레이드를 수행하려면 다음을 지켜야 합니다.

  • 마이너 릴리스를 한 번에 하나씩만 업그레이드합니다. 즉 16.1에서 16.2로 이동하며, 16.3으로 바로 이동하지 않습니다. 릴리스를 건너뛰면 데이터베이스 수정 사항이 잘못된 순서로 실행되어 데이터베이스 스키마가 손상된 상태로 남을 수 있습니다.
  • 배포 후 마이그레이션(post-deployment migrations)을 사용합니다.

고려 사항#

제로 다운타임 업그레이드를 고려할 때는 다음 사항에 유의합니다.

  • 대부분의 경우 패치 릴리스가 최신 버전이 아니더라도 다음 마이너 릴리스로 안전하게 업그레이드할 수 있습니다. 예를 들어 16.3.3이 릴리스된 이후라도 16.3.2에서 16.4.1로 업그레이드하는 것은 안전해야 합니다. 업그레이드 경로에 해당하는 버전별 업그레이드 노트를 확인하고 필요한 업그레이드 정지 지점이 있는지 확인해야 합니다.

  • 일부 릴리스에는 백그라운드 마이그레이션이 포함될 수 있습니다. 이 마이그레이션은 Sidekiq이 백그라운드에서 수행하며 주로 데이터 이관에 사용됩니다. 백그라운드 마이그레이션은 월간 릴리스에만 추가됩니다.

    • 특정 메이저 또는 마이너 릴리스는 일련의 백그라운드 마이그레이션이 완료되어야 할 수 있습니다. 앞서 언급한 조건이 충족된다면 이 자체로 다운타임이 필요하지는 않지만, 각 메이저 또는 마이너 릴리스 업그레이드 사이에는 백그라운드 마이그레이션이 완료될 때까지 기다려야 합니다.
    • 이 마이그레이션을 완료하는 데 필요한 시간은 background_migration 큐의 작업을 처리할 수 있는 Sidekiq 워커 수를 늘려 줄일 수 있습니다. 이 큐의 크기를 확인하려면 업그레이드 전에 백그라운드 마이그레이션을 확인합니다.

  • Gitaly는 정상 종료 후 재로드(graceful reload) 메커니즘 덕분에 제로 다운타임 업그레이드가 가능합니다. Gitaly Cluster(Praefect) 컴포넌트 역시 다운타임 없이 직접 업그레이드할 수 있습니다. 다만 Linux 패키지는 Praefect 데이터베이스에 대해 HA나 제로 다운타임을 지원하지 않으며, 다운타임을 피하려면 서드 파티 데이터베이스 솔루션이 필요합니다.

  • PostgreSQL 메이저 버전 업그레이드는 별도의 프로세스이며 제로 다운타임 업그레이드 범위에 포함되지 않습니다. 그보다 작은 단위의 업그레이드는 이 범위에 포함됩니다.

  • 제로 다운타임 업그레이드는 Linux 패키지로 배포한, 앞서 언급한 GitLab 컴포넌트에 대해서만 지원됩니다. AWS RDS의 PostgreSQL이나 GCP Memorystore의 Redis처럼 지원되는 서드 파티 서비스를 통해 일부 컴포넌트를 배포한 경우, 해당 서비스의 업그레이드는 각 서비스의 표준 프로세스에 따라 별도로 수행해야 합니다.

  • 일반적인 지침으로, 데이터 양이 많을수록 업그레이드를 완료하는 데 더 많은 시간이 필요합니다. 테스트 결과 10GB 미만의 데이터베이스는 일반적으로 1시간을 넘기지 않았지만, 실제 결과는 환경에 따라 달라질 수 있습니다.

업그레이드 순서#

제로 다운타임으로 업그레이드할 컴포넌트의 순서는 후방에서 전방으로(back-to-front) 접근하는 방식을 따라야 합니다.

  1. 상태를 갖는 백엔드(Stateful backends)
  2. 백엔드 의존 컴포넌트(Backend dependents)
  3. 프론트엔드(Frontends)

배포 순서는 변경할 수 있지만, GitLab 애플리케이션 코드를 실행하는 컴포넌트(예: Rails와 Sidekiq)는 함께 배포해야 합니다. 이 컴포넌트들은 메이저 릴리스의 버전 업그레이드에서 도입된 변경 사항에 의존하지 않으므로, 가능하다면 지원 인프라는 별도로 업그레이드합니다.

GitLab 컴포넌트는 다음 순서로 업그레이드해야 합니다.

  1. Consul
  2. PostgreSQL
  3. PgBouncer
  4. Redis
  5. Gitaly
  6. Praefect
  7. Rails
  8. Sidekiq

Consul, PostgreSQL, PgBouncer, Redis 노드 업그레이드#

Consul, PostgreSQL, PgBouncer, Redis 컴포넌트는 모두 다운타임 없이 업그레이드하는 동일한 기본 프로세스를 따릅니다.

각 컴포넌트의 노드에서 다음과 같이 업그레이드를 수행합니다.

  1. /etc/gitlab/skip-auto-reconfigure에 빈 파일을 생성합니다. 이렇게 하면 업그레이드가 gitlab-ctl reconfigure를 실행하지 않도록 막을 수 있습니다. 기본적으로 이 명령은 GitLab을 자동으로 중지하고, 모든 데이터베이스 마이그레이션을 실행한 뒤 GitLab을 재시작합니다.

    sudo touch /etc/gitlab/skip-auto-reconfigure

  2. Linux 패키지로 업그레이드하여 노드를 업그레이드합니다.

  3. 재구성(reconfigure) 후 재시작하여 최신 코드를 적용합니다.

    sudo gitlab-ctl reconfigure

Consul 클라이언트를 먼저 재시작한 다음 나머지 모든 서비스를 재시작하여 PostgreSQL 페일오버가 정상적으로 이루어지도록 합니다.

sudo gitlab-ctl restart consul
sudo gitlab-ctl restart-except consul

   sudo gitlab-ctl restart

Gitaly 노드 업그레이드#

Gitaly는 업그레이드에서 동일한 핵심 프로세스를 따르지만, 가장 이른 시점에 정상적으로 재로드하는 내장 프로세스를 갖고 있어 Gitaly 프로세스 자체는 재시작되지 않는다는 중요한 차이가 있습니다. 다른 컴포넌트는 여전히 재시작해야 합니다.

이 프로세스는 Gitaly Sharded 구성과 Cluster 구성 모두에 적용됩니다. 업그레이드를 수행하려면 각 Gitaly 노드에서 다음 단계를 순서대로 진행합니다.

  1. /etc/gitlab/skip-auto-reconfigure에 빈 파일을 생성합니다. 이렇게 하면 업그레이드가 gitlab-ctl reconfigure를 실행하지 않도록 막을 수 있습니다. 기본적으로 이 명령은 GitLab을 자동으로 중지하고, 모든 데이터베이스 마이그레이션을 실행한 뒤 GitLab을 재시작합니다.

    sudo touch /etc/gitlab/skip-auto-reconfigure

  2. Linux 패키지로 업그레이드하여 노드를 업그레이드합니다.

  3. reconfigure 명령을 실행하여 최신 코드를 적용하고, 다음 기회에 Gitaly가 정상적으로 재로드하도록 지시합니다.

    sudo gitlab-ctl reconfigure

  4. 마지막으로, Gitaly가 정상적으로 재로드되는 동안 배포된 다른 컴포넌트는 여전히 재시작해야 합니다.

    # Get a list of what other components have been deployed beside Gitaly
sudo gitlab-ctl status

# Restart each component except Gitaly. Example given for Consul, Node Exporter and Logrotate
sudo gitlab-ctl restart consul node-exporter logrotate

Gitaly Cluster(Praefect) 노드 업그레이드#

Note

이 섹션은 필요한 PostgreSQL 데이터베이스가 아니라 Praefect 컴포넌트에만 초점을 맞춥니다. GitLab Linux 패키지는 HA를 제공하지 않으며, 그에 따라 Praefect 데이터베이스에 대한 제로 다운타임도 지원하지 않습니다. 다운타임을 피하려면 서드 파티 데이터베이스 솔루션이 필요합니다.

Gitaly Cluster(Praefect) 구성에서는 정상 재로드(graceful reload)를 사용하는 유사한 방식으로 Praefect를 배포하고 업그레이드해야 합니다.

Note

업그레이드 프로세스는 새로운 Praefect 프로세스로 정상적인 핸드오버를 시도합니다. 업그레이드 이전에 시작되어 오래 실행 중이던 Git 요청은 이 핸드오버가 진행되는 동안 결국 중단될 수 있습니다.

Gitaly Cluster(Praefect)를 사용하는 인스턴스를 업그레이드할 때는 다음 순서로 컴포넌트를 업그레이드합니다.

  1. Praefect PostgreSQL 데이터베이스. Linux 패키지는 이 데이터베이스에 대해 HA를 제공하지 않으므로, 서드 파티 HA 데이터베이스 솔루션을 사용하지 않는 한 이 단계에는 다운타임이 필요합니다.
  2. Gitaly 노드. Gitaly 업그레이드 단계를 사용하여 순차적으로 업그레이드합니다.
  3. Praefect 노드. 아래 설명에 따라 업그레이드하며, 한 노드를 데이터베이스 마이그레이션을 실행하는 배포 노드로 지정합니다.

Praefect도 기존 데이터를 업그레이드하기 위해 데이터베이스 마이그레이션을 수행해야 합니다. 충돌을 피하려면 마이그레이션은 하나의 Praefect 노드에서만 실행해야 합니다. 이를 위해 마이그레이션을 실행할 Praefect 배포 노드를 지정합니다.

  1. Praefect 배포 노드에서 다음을 수행합니다.

    1. /etc/gitlab/skip-auto-reconfigure에 빈 파일을 생성합니다. 이렇게 하면 업그레이드가 gitlab-ctl reconfigure를 실행하지 않도록 막을 수 있습니다. 기본적으로 이 명령은 GitLab을 자동으로 중지하고, 모든 데이터베이스 마이그레이션을 실행한 뒤 GitLab을 재시작합니다.

      sudo touch /etc/gitlab/skip-auto-reconfigure

    2. Linux 패키지로 업그레이드하여 노드를 업그레이드합니다.

    3. 데이터베이스 마이그레이션이 실행되도록 /etc/gitlab/gitlab.rb에 praefect['auto_migrate'] = true가 설정되어 있는지 확인합니다.

    4. reconfigure 명령을 실행하여 최신 코드를 적용하고, Praefect 데이터베이스 마이그레이션을 적용한 뒤 정상적으로 재시작합니다.

      sudo gitlab-ctl reconfigure

    5. 계속 진행하기 전에 모든 Praefect 데이터베이스 마이그레이션이 적용되었는지 확인합니다.

      sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml sql-migrate-status

      모든 마이그레이션이 적용됨으로 표시되어야 합니다. 이를 확인하기 전까지는 나머지 Praefect 노드로 진행하지 않습니다.

  2. 나머지 모든 Praefect 노드에서 다음을 수행합니다.

    1. /etc/gitlab/skip-auto-reconfigure에 빈 파일을 생성합니다. 이렇게 하면 업그레이드가 gitlab-ctl reconfigure를 실행하지 않도록 막을 수 있습니다. 기본적으로 이 명령은 GitLab을 자동으로 중지하고, 모든 데이터베이스 마이그레이션을 실행한 뒤 GitLab을 재시작합니다.

      sudo touch /etc/gitlab/skip-auto-reconfigure

    2. Linux 패키지로 업그레이드하여 노드를 업그레이드합니다.

    3. reconfigure가 데이터베이스 마이그레이션을 자동으로 실행하지 않도록 /etc/gitlab/gitlab.rb에 praefect['auto_migrate'] = false가 설정되어 있는지 확인합니다.

    4. reconfigure 명령을 실행하여 최신 코드를 적용하고 정상적으로 재시작합니다.

      sudo gitlab-ctl reconfigure

  3. 마지막으로, Praefect가 정상적으로 재로드되는 동안 배포된 다른 컴포넌트는 여전히 재시작해야 합니다. 모든 Praefect 노드에서 다음을 수행합니다.

    # Get a list of what other components have been deployed beside Praefect
sudo gitlab-ctl status

# Restart each component except Praefect. Example given for Consul, Node Exporter and Logrotate
sudo gitlab-ctl restart consul node-exporter logrotate

GitLab 애플리케이션(Rails) 노드 업그레이드#

웹 서버로서의 Rails는 주로 Puma, Workhorse, NGINX로 구성됩니다.

이 컴포넌트들은 라이브 업그레이드를 수행할 때 각각 다른 동작을 보입니다. Puma는 정상 재로드를 허용할 수 있지만 Workhorse는 그렇지 않습니다. 가장 좋은 방법은 로드 밸런서 사용 등 다른 수단을 통해 노드를 정상적으로 드레인하는 것입니다. 노드에서 NGINX의 정상 종료(graceful shutdown) 기능을 사용해 이를 수행할 수도 있습니다. 이 섹션에서는 NGINX 방식을 설명합니다.

앞서 설명한 내용에 더해, Rails는 주요 데이터베이스 마이그레이션이 실행되어야 하는 지점이기도 합니다. Praefect와 마찬가지로 가장 좋은 방법은 배포 노드를 사용하는 것입니다. 현재 PgBouncer를 사용하고 있다면 이 역시 우회해야 합니다. Rails는 동일한 데이터베이스에서 동시에 마이그레이션이 실행되는 것을 막기 위해 마이그레이션을 실행할 때 권고 잠금(advisory lock)을 사용하기 때문입니다. 이 잠금은 트랜잭션 간에 공유되지 않으므로, 트랜잭션 풀링 모드의 PgBouncer를 사용해 데이터베이스 마이그레이션을 실행하면 ActiveRecord::ConcurrentMigrationError를 비롯한 문제가 발생합니다.

  1. Rails 배포 노드에서 다음을 수행합니다.

    1. 노드의 트래픽을 정상적으로 드레인합니다. 다양한 방법이 있지만, 한 가지 방법은 NGINX에 QUIT 신호를 보낸 다음 서비스를 중지하는 것입니다. 예를 들어 다음과 같은 셸 스크립트로 이를 수행할 수 있습니다.

      # Send QUIT to NGINX master process to drain and exit
NGINX_PID=$(cat /var/opt/gitlab/nginx/nginx.pid)
kill -QUIT $NGINX_PID

# Wait for drain to complete
while kill -0 $NGINX_PID 2>/dev/null; do sleep 1; done

# Stop NGINX service to prevent automatic restarts
gitlab-ctl stop nginx

    2. /etc/gitlab/skip-auto-reconfigure에 빈 파일을 생성합니다. 이렇게 하면 업그레이드가 gitlab-ctl reconfigure를 실행하지 않도록 막을 수 있습니다. 기본적으로 이 명령은 GitLab을 자동으로 중지하고, 모든 데이터베이스 마이그레이션을 실행한 뒤 GitLab을 재시작합니다.

      sudo touch /etc/gitlab/skip-auto-reconfigure

    3. Linux 패키지로 업그레이드하여 GitLab을 업그레이드합니다.

    4. /etc/gitlab/gitlab.rb 설정 파일에 gitlab_rails['auto_migrate'] = true를 설정하여 일반 마이그레이션이 실행되도록 구성합니다.

      • 배포 노드가 PgBouncer를 거쳐 데이터베이스에 접근하는 경우, 마이그레이션을 실행하기 전에 이를 우회하여 데이터베이스 리더에 직접 연결해야 합니다.
      • 데이터베이스 리더는 아무 데이터베이스 노드에서 sudo gitlab-ctl patroni members 명령을 실행하여 확인할 수 있습니다.

    5. 일반 마이그레이션을 실행하고 최신 코드를 적용합니다.

      sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-ctl reconfigure

    6. 이후 배포 후 마이그레이션을 실행하기 위해 다시 돌아올 것이므로, 지금은 이 노드를 그대로 둡니다.

  2. 그 외 모든 Rails 노드에서 순차적으로 다음을 수행합니다.

    1. 노드의 트래픽을 정상적으로 드레인합니다. 다양한 방법이 있지만, 한 가지 방법은 NGINX에 QUIT 신호를 보낸 다음 서비스를 중지하는 것입니다. 예를 들어 다음과 같은 셸 스크립트로 이를 수행할 수 있습니다.

      # Send QUIT to NGINX master process to drain and exit
NGINX_PID=$(cat /var/opt/gitlab/nginx/nginx.pid)
kill -QUIT $NGINX_PID

# Wait for drain to complete
while kill -0 $NGINX_PID 2>/dev/null; do sleep 1; done

# Stop NGINX service to prevent automatic restarts
gitlab-ctl stop nginx

    2. /etc/gitlab/skip-auto-reconfigure에 빈 파일을 생성합니다. 이렇게 하면 업그레이드가 gitlab-ctl reconfigure를 실행하지 않도록 막을 수 있습니다. 기본적으로 이 명령은 GitLab을 자동으로 중지하고, 모든 데이터베이스 마이그레이션을 실행한 뒤 GitLab을 재시작합니다.

      sudo touch /etc/gitlab/skip-auto-reconfigure

    3. Linux 패키지로 업그레이드하여 GitLab을 업그레이드합니다.

    4. reconfigure가 데이터베이스 마이그레이션을 자동으로 실행하지 않도록 /etc/gitlab/gitlab.rb에 gitlab_rails['auto_migrate'] = false가 설정되어 있는지 확인합니다.

    5. reconfigure 명령을 실행하여 최신 코드를 적용하고 재시작합니다.

      sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

  3. Rails 배포 노드에서 배포 후 마이그레이션을 실행합니다.

    1. 배포 노드가 여전히 데이터베이스 리더를 직접 가리키고 있는지 확인합니다. 노드가 PgBouncer를 거쳐 데이터베이스에 접근하는 경우, 마이그레이션을 실행하기 전에 이를 우회하여 데이터베이스 리더에 직접 연결해야 합니다.

      • 데이터베이스 리더는 아무 데이터베이스 노드에서 sudo gitlab-ctl patroni members 명령을 실행하여 확인할 수 있습니다.

    2. 배포 후 마이그레이션을 실행합니다.

      sudo gitlab-rake gitlab:db:configure

      이 작업은 ClickHouse 마이그레이션도 함께 실행하며, 스키마를 로드하여 현재 상태에 맞게 데이터베이스를 구성합니다.

    3. /etc/gitlab/gitlab.rb 설정 파일에 gitlab_rails['auto_migrate'] = false를 설정하여 구성을 원래대로 되돌립니다.

      • PgBouncer를 사용 중이라면 데이터베이스 설정이 다시 PgBouncer를 가리키도록 해야 합니다.

    4. 정상 구성을 다시 적용하기 위해 reconfigure를 다시 실행하고 재시작합니다.

      sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

Sidekiq 노드 업그레이드#

Sidekiq는 다운타임 없이 업그레이드하는 데 있어 다른 컴포넌트와 동일한 기본 프로세스를 따릅니다.

업그레이드를 수행하려면 각 컴포넌트 노드에서 다음 단계를 순서대로 진행합니다.

  1. /etc/gitlab/skip-auto-reconfigure에 빈 파일을 생성합니다. 이렇게 하면 업그레이드가 gitlab-ctl reconfigure를 실행하지 않도록 막을 수 있습니다. 기본적으로 이 명령은 GitLab을 자동으로 중지하고, 모든 데이터베이스 마이그레이션을 실행한 뒤 GitLab을 재시작합니다.

    sudo touch /etc/gitlab/skip-auto-reconfigure

  2. Linux 패키지로 업그레이드하여 노드를 업그레이드합니다.

  3. reconfigure 명령을 실행하여 최신 코드를 적용하고 재시작합니다.

    sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

멀티 노드 Geo 인스턴스 업그레이드#

이 섹션에서는 Geo를 사용하는 라이브 GitLab 환경 배포를 업그레이드하는 데 필요한 단계를 설명합니다.

전반적으로 이 방식은 일반 프로세스와 대체로 동일하지만, 각 보조 사이트(secondary site)에 몇 가지 추가 단계가 필요합니다. 필요한 순서는 먼저 프라이머리를 업그레이드한 다음 보조 사이트를 업그레이드하는 것입니다. 또한 모든 보조 사이트가 업데이트된 후에는 프라이머리에서 배포 후 마이그레이션을 실행해야 합니다.

Note

Geo를 사용하는 라이브 GitLab 환경을 업그레이드할 때도 동일한 요구 사항과 고려 사항이 적용됩니다.

기본 사이트#

기본 사이트의 업그레이드 프로세스는 모든 보조 사이트가 업데이트될 때까지 배포 후 마이그레이션을 실행하지 않는다는 점을 제외하면 일반 프로세스와 동일합니다.

기본 사이트에서는 앞서 설명한 것과 동일한 단계를 진행하되, Rails 노드에서 배포 후 마이그레이션을 실행하는 단계 직전까지만 진행합니다.

보조 사이트#

보조 사이트의 업그레이드 프로세스는 Rails 노드를 제외하면 일반 프로세스와 동일한 단계를 따릅니다. 업그레이드 프로세스는 기본 사이트와 보조 사이트 모두 동일합니다. 다만 보조 사이트의 Rails 노드에는 다음과 같은 추가 단계를 수행해야 합니다.

Rails#

  1. Rails 배포 노드에서 다음을 수행합니다.

    1. 노드의 트래픽을 정상적으로 드레인합니다. 다양한 방법이 있지만, 한 가지 방법은 NGINX에 QUIT 신호를 보낸 다음 서비스를 중지하는 것입니다. 예를 들어 다음과 같은 셸 스크립트로 이를 수행할 수 있습니다.

      # Send QUIT to NGINX master process to drain and exit
NGINX_PID=$(cat /var/opt/gitlab/nginx/nginx.pid)
kill -QUIT $NGINX_PID

# Wait for drain to complete
while kill -0 $NGINX_PID 2>/dev/null; do sleep 1; done

# Stop NGINX service to prevent automatic restarts
gitlab-ctl stop nginx

    2. Geo Log Cursor 프로세스를 중지하여 다른 노드로 페일오버되도록 합니다.

      gitlab-ctl stop geo-logcursor

    3. /etc/gitlab/skip-auto-reconfigure에 빈 파일을 생성합니다. 이렇게 하면 업그레이드가 gitlab-ctl reconfigure를 실행하지 않도록 막을 수 있습니다. 기본적으로 이 명령은 GitLab을 자동으로 중지하고, 모든 데이터베이스 마이그레이션을 실행한 뒤 GitLab을 재시작합니다.

      sudo touch /etc/gitlab/skip-auto-reconfigure

    4. Linux 패키지로 업그레이드하여 GitLab을 업그레이드합니다.

    5. 기본 사이트의 Rails 노드와 보조 사이트의 Rails 노드에서 /etc/gitlab/gitlab-secrets.json 파일이 서로 다르다면 기본 사이트에서 보조 사이트로 이 파일을 복사합니다. 이 파일은 한 사이트의 모든 노드에서 동일해야 합니다.

    6. /etc/gitlab/gitlab.rb 설정 파일에 gitlab_rails['auto_migrate'] = false와 geo_secondary['auto_migrate'] = false를 설정하여 마이그레이션이 자동으로 실행되도록 구성되지 않았는지 확인합니다.

    7. reconfigure 명령을 실행하여 최신 코드를 적용하고 재시작합니다.

      sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

    8. 일반 Geo Tracking 마이그레이션을 실행하고 최신 코드를 적용합니다.

      sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-rake db:migrate:geo

  2. 그 외 모든 Rails 노드에서 순차적으로 다음을 수행합니다.

    1. 노드의 트래픽을 정상적으로 드레인합니다. 다양한 방법이 있지만, 한 가지 방법은 NGINX에 QUIT 신호를 보낸 다음 서비스를 중지하는 것입니다. 예를 들어 다음과 같은 셸 스크립트로 이를 수행할 수 있습니다.

      # Send QUIT to NGINX master process to drain and exit
NGINX_PID=$(cat /var/opt/gitlab/nginx/nginx.pid)
kill -QUIT $NGINX_PID

# Wait for drain to complete
while kill -0 $NGINX_PID 2>/dev/null; do sleep 1; done

# Stop NGINX service to prevent automatic restarts
gitlab-ctl stop nginx

    2. Geo Log Cursor 프로세스를 중지하여 다른 노드로 페일오버되도록 합니다.

      gitlab-ctl stop geo-logcursor

    3. /etc/gitlab/skip-auto-reconfigure에 빈 파일을 생성합니다. 이렇게 하면 업그레이드가 gitlab-ctl reconfigure를 실행하지 않도록 막을 수 있습니다. 기본적으로 이 명령은 GitLab을 자동으로 중지하고, 모든 데이터베이스 마이그레이션을 실행한 뒤 GitLab을 재시작합니다.

      sudo touch /etc/gitlab/skip-auto-reconfigure

    4. Linux 패키지로 업그레이드하여 GitLab을 업그레이드합니다.

    5. /etc/gitlab/gitlab.rb 설정 파일에 gitlab_rails['auto_migrate'] = false와 geo_secondary['auto_migrate'] = false를 설정하여 마이그레이션이 자동으로 실행되도록 구성되지 않았는지 확인합니다.

    6. reconfigure 명령을 실행하여 최신 코드를 적용하고 재시작합니다.

      sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

Sidekiq#

메인 프로세스를 따랐다면 이제 남은 작업은 Sidekiq을 업그레이드하는 것뿐입니다.

메인 섹션에서 설명한 것과 동일한 방식으로 Sidekiq을 업그레이드합니다.

배포 후 마이그레이션#

마지막으로 기본 사이트로 돌아가 배포 후 마이그레이션을 실행하여 업그레이드를 마무리합니다.

  1. 기본 사이트의 Rails 배포 노드에서 배포 후 마이그레이션을 실행합니다.

    1. 배포 노드가 여전히 데이터베이스 리더를 직접 가리키고 있는지 확인합니다. 노드가 PgBouncer를 거쳐 데이터베이스에 접근하는 경우, 마이그레이션을 실행하기 전에 이를 우회하여 데이터베이스 리더에 직접 연결해야 합니다.

      • 데이터베이스 리더는 아무 데이터베이스 노드에서 sudo gitlab-ctl patroni members 명령을 실행하여 확인할 수 있습니다.

    2. 배포 후 마이그레이션을 실행합니다.

      sudo gitlab-rake gitlab:db:configure

    3. Geo 구성과 의존성을 확인합니다.

      sudo gitlab-rake gitlab:geo:check

    4. /etc/gitlab/gitlab.rb 설정 파일에 gitlab_rails['auto_migrate'] = false를 설정하여 구성을 원래대로 되돌립니다.

      • PgBouncer를 사용 중이라면 데이터베이스 설정이 다시 PgBouncer를 가리키도록 해야 합니다.

    5. 정상 구성을 다시 적용하기 위해 reconfigure를 다시 실행하고 재시작합니다.

      sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

  2. 보조 사이트의 Rails 배포 노드에서 배포 후 Geo Tracking 마이그레이션을 실행합니다.

    1. 배포 후 Geo Tracking 마이그레이션을 실행합니다.

      sudo gitlab-rake db:migrate:geo

    2. Geo 상태를 확인합니다.

      sudo gitlab-rake gitlab:geo:status