GitLab 유지 보수 모드

Tier: Premium, Ultimate Offering: Self-Managed

유지 보수 모드를 활성화하면 유지 보수 작업이 수행되는 동안 쓰기 작업을 최소화할 수 있습니다. 주요 목표는 내부 상태를 변경하는 모든 외부 작업을 차단하는 것입니다. 내부 상태에는 PostgreSQL 데이터베이스뿐만 아니라 파일, Git 리포지터리 및 컨테이너 리포지터리가 특히 포함됩니다.

유지 보수 모드가 활성화되면 진행 중인 작업이 비교적 빨리 완료되며 새 작업이 없기 때문에 내부 상태 변경이 최소화됩니다. 그 상태에서는 여러 유지 보수 작업이 쉬워집니다. 서비스를 완전히 중지하거나 필요한 것보다 짧은 시간 동안 더 많이 저하시킬 수 있습니다. 예를 들어 cron 작업을 중지하고 대기열을 처리하는 것이 상당히 빠를 것입니다.

유지 보수 모드를 통해 내부 상태를 변경하지 않는 대부분의 외부 작업을 허용할 수 있습니다. 고수준에서 HTTP POST, PUT, PATCH, 및 DELETE 요청이 차단되며 특수 케이스가 처리되는 방법에 대한 자세한 개요가 제공됩니다.

유지 보수 모드 활성화

다음 중 하나의 방법으로 관리자로서 유지 보수 모드를 활성화할 수 있습니다:

  • 웹 UI:
    1. 왼쪽 사이드바에서 하단에 있는 관리 영역을 선택합니다.
    2. 왼쪽 사이드바에서 설정 > 일반을 선택합니다.
    3. 유지 보수 모드를 확장하고 유지 보수 모드 활성화를 토글합니다. 선택사항으로 배너에 메시지를 추가할 수도 있습니다.
    4. 변경 사항 저장을 선택합니다.

  • API: 

    curl --request PUT --header "PRIVATE-TOKEN:$ADMIN_TOKEN" "<gitlab-url>/api/v4/application/settings?maintenance_mode=true"

  • Rails 콘솔: 

    ::Gitlab::CurrentSettings.update!(maintenance_mode: true)
::Gitlab::CurrentSettings.update!(maintenance_mode_message: "새로운 메시지")

유지 보수 모드 비활성화

다음 세 가지 방법 중 하나로 유지 보수 모드를 비활성화할 수 있습니다:

  • 웹 UI:
    1. 왼쪽 사이드바에서 하단에 있는 관리 영역을 선택합니다.
    2. 왼쪽 사이드바에서 설정 > 일반을 선택합니다.
    3. 유지 보수 모드를 확장하고 유지 보수 모드 활성화를 토글합니다. 선택사항으로 배너에 메시지를 추가할 수도 있습니다.
    4. 변경 사항 저장을 선택합니다.

  • API: 

    curl --request PUT --header "PRIVATE-TOKEN:$ADMIN_TOKEN" "<gitlab-url>/api/v4/application/settings?maintenance_mode=false"

  • Rails 콘솔: 

    ::Gitlab::CurrentSettings.update!(maintenance_mode: false)

유지 보수 모드에서의 GitLab 기능 동작

유지 보수 모드가 활성화되면 페이지 상단에 배너가 표시됩니다. 배너에는 특정 메시지를 사용자 정의할 수 있습니다.

사용자가 허용되지 않는 쓰기 작업을 수행하려고 하면 오류가 표시됩니다.

유지 보수 모드 배너 및 오류 메시지

note
특정 경우에 작업으로부터의 시각적 피드백이 잘못 이해될 수 있습니다. 예를 들어 프로젝트를 스타로 표시할 때 스타 버튼이 언스타 작업을 보여주도록 변경됩니다. 그러나 이것은 단순히 프론트엔드 업데이트이며 POST 요청의 실패 상태를 고려하지 않습니다. 이러한 시각적 버그는 후속 반복에서 수정됩니다.

관리자 기능

시스템 관리자는 응용 프로그램 설정을 편집할 수 있습니다. 이를 통해 활성화된 후 유지 보수 모드를 비활성화할 수 있습니다.

인증

모든 사용자는 GitLab 인스턴스에 서명하고 나갈 수 있지만 새로운 사용자를 만들 수 없습니다.

해당 시간에 LDAP 동기화가 예약되어 있다면 사용자 생성이 비활성화되므로 실패합니다. 마찬가지로 SAML을 기반으로 하는 사용자 생성도 실패합니다.

Git 작업

모든 읽기 전용 Git 작업은 계속해서 작동합니다. 예를 들어 git clone 및 git pull과 같은 모든 쓰기 작업이 실패합니다. 이는 CLI 및 웹 IDE를 통해 Git push is not allowed because this GitLab instance is currently in (read-only) maintenance mode.라는 오류 메시지가 표시됩니다.

Geo가 활성화된 경우, 기본 및 보조로의 Git push가 실패합니다.

Merge Request, 이슈, 에픽

이미 언급된 작업 외에는 모든 쓰기 작업이 실패합니다. 예를 들어 사용자는 Merge Request나 이슈를 업데이트할 수 없습니다.

수신 이메일

이메일을 통해 새로운 이슈 답변, 이슈(서비스 데스크 이슈 포함), Merge Request 전송 작업이 실패합니다.

발신 이메일

알림 이메일은 계속 수신되지만 비밀번호 재설정과 같은 데이터베이스 쓰기를 요구하는 이메일은 수신되지 않습니다.

REST API

대부분의 JSON 요청에 대해 POST, PUT, PATCH, 및 DELETE가 차단되며 API는 You cannot perform write operations on a read-only instance라는 오류 메시지와 함께 403 응답을 반환합니다. 다음의 요청만 허용됩니다:

HTTP 요청 허용된 라우트 비고
POST /admin/application_settings/general 관리자 UI에서 애플리케이션 설정 업데이트를 허용
PUT /api/v4/application/settings API로 애플리케이션 설정 업데이트를 허용
POST /users/sign_in 사용자 로그인을 허용
POST /users/sign_out 사용자 로그아웃을 허용
POST /oauth/token 사용자가 첫 번째로 Geo 보조에 로그인할 수 있게 함
POST /admin/session, /admin/session/destroy GitLab 관리자용 관리 모드 허용
POST /compare로 끝나는 경로 Git 리비전 라우트
POST .git/git-upload-pack Git pull/clone을 허용
POST /api/v4/internal 내부 API 라우트 허용
POST /admin/sidekiq 관리 영역에서 백그라운드 작업 관리 허용
POST /admin/geo 관리자 UI에서 Geo 노드 업데이트 허용
POST /api/v4/geo_replication 보조 사이트에서 특정 Geo 관련 관리자 UI 작업 허용

GraphQL API

  • GeoRegistriesUpdate 변이 추가 사항이 GitLab 16.2에서 도입되었습니다.

POST /api/graphql 요청은 허용되지만 변이는 You cannot perform write operations on a read-only instance라는 오류 메시지로 차단됩니다.

허용되는 유일한 변이는 레지스트리를 재동기화 및 재확인하기 위해 사용되는 GeoRegistriesUpdate입니다.

지속적 통합

  • 새로운 작업이나 파이프라인이 시작되지 않습니다.
  • 이미 실행 중인 작업은 GitLab UI에서 running 상태를 유지하며, GitLab Runner에서 실행이 완료되더라도 변경되지 않습니다.
  • 프로젝트의 시간 제한을 넘어서 running 상태에 있는 작업은 타임아웃되지 않습니다.
  • 파이프라인을 시작, 다시 시도 또는 취소할 수 없습니다. 새로운 작업을 생성할 수도 없습니다.
  • /admin/runners에서 Runner의 상태는 업데이트되지 않습니다.
  • gitlab-runner verify는 ERROR: Verifying runner... is removed 오류를 반환합니다.

유지 보수 모드가 비활성화 된 후에는 새로운 작업이 다시 진행됩니다. 유지 보수 모드를 활성화하기 전에 running 상태에 있던 작업은 재개되고 그 로그가 다시 업데이트됩니다.

note
유지 보수 모드를 비활성화한 후 이전에 running 상태였던 파이프라인을 다시 시작해야 합니다.

배포

파이프라인이 완료되지 않아 배포가 진행되지 않습니다.

유지 보수 모드 동안 자동 배포를 비활성화하고, 비활성화되었을 때 활성화해야 합니다.

Terraform 통합

Terraform 통합은 CI 파이프라인 실행에 의존하므로 차단됩니다.

컨테이너 레지스트리

docker push가 denied: requested access to the resource is denied 오류로 실패하지만 docker pull은 작동합니다.

패키지 레지스트리

패키지 레지스트리를 통해 패키지를 설치할 수는 있지만 발행할 수는 없습니다.

백그라운드 작업

백그라운드 작업(크론 작업, Sidekiq)은 백그라운드 작업이 자동으로 비활성화되지 않기 때문에 계속 실행됩니다. 백그라운드 작업은 인스턴스의 내부 상태를 변경할 수 있는 작업을 수행하므로 유지 보수 모드가 활성화된 동안 일부 또는 전체 작업을 비활성화할 수 있습니다.

계획된 Geo 장애 조치 실행 중에 주요 사이트에 대한 모든 크론 작업을 비활성화해야 합니다. 대체로 Geo와 관련 없는 모든 크론 작업을 비활성화해야 합니다.

큐 모니터링 및 작업 비활성화:

  1. 왼쪽 사이드바에서 가장 아래에서 관리자 영역(Admin Area)을 선택합니다.
  2. 모니터링 > 백그라운드 작업(Monitoring > Background Jobs)을 선택합니다.
  3. Sidekiq 대시보드에서 Cron을 선택하고 비활성화 모두 선택(Disable All) 또는 개별적으로 작업을 비활성화합니다.

사건 관리

사건 관리 기능이 제한됩니다. 알림과 사건의 생성이 완전히 일시 중지됩니다. 따라서 알림 및 사건의 알림 및 호출도 비활성화됩니다.

피처 플래그

  • 개발 피처 플래그는 API를 통해 켜거나 끌 수 없지만 Rails 콘솔을 통해 토글할 수 있습니다.
  • 피처 플래그 서비스는 피처 플래그 확인에 응답하지만 피처 플래그를 토글할 수는 없습니다.

Geo Secondaries

기본이 유지 보수 모드인 경우 보조도 자동으로 유지 보수 모드로 전환됩니다.

유지 보수 모드를 활성화하기 전에 복제를 비활성화하지 않도록 주의해야 합니다.

관리자 UI를 통한 레지스트리의 복제, 검증 및 매뉴얼 조치, 그리고 동기화 및 재검증 작업은 계속해서 작동하지만 기본으로의 프록시된 Git 푸시는 작동하지 않습니다.

보안 기능

이슈 생성, Merge Request의 생성 또는 승인에 따라 동작하는 기능들은 작동하지 않습니다.

취약점 보고서 페이지에서 취약점 디렉터리을 내보내는 것도 작동하지 않습니다.

UI에 오류가 표시되지 않더라도 취약점 객체의 상태를 변경하는 것도 작동하지 않습니다.

CI 작업을 통과하여 생성된 artifact에 의존하기 때문에 SAST 및 Secret Detection을 시작할 수 없습니다.

예시 사용 사례: 계획된 장애 조치 실행

계획된 장애 조치 실행의 경우, 주요 데이터베이스에 일부 기록이 허용됩니다. 이 기록들은 신속하게 복제되며 수량적으로도 중요하지 않습니다.

이와 같은 이유로 유지 보수 모드가 활성화되었을 때 우리는 백그라운드 작업을 자동으로 차단하지 않습니다.

결과적으로 데이터베이스 기록은 허용됩니다. 여기서는 더 많은 서비스 저하와 복제의 완료 사이의 균형을 이루게 됩니다.

그러나 계획된 장애 조치 실행 중에는 데이터베이스 쓰기와 Geo와 관련 없는 크론 작업을 매뉴얼으로 모두 비활성화할 것을 사용자들에게 요청합니다. 새로운 데이터베이스 쓰기와 비-Geo 크론 작업이 없거나 최소화될 수 있습니다.