GitLab 유지 보수 모드

Tier: Premium, Ultimate Offering: Self-managed

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

유지 보수 모드가 활성화되면 진행 중인 작업이 상대적으로 빠르게 끝납니다. 새 작업이 들어오지 않기 때문에 내부 상태 변경은 최소화됩니다.

이 상태에서 다양한 유지 보수 작업이 더 쉬워집니다. 서비스는 완전히 중지되거나 필요할 수 있는 것보다 더 짧은 시간 동안 추가로 저하될 수 있습니다. 예를 들어, cron 작업을 중지하고 대기열을 비우는 것은 상당히 빠를 것입니다.

유지 보수 모드는 내부 상태를 변경하지 않는 대부분의 외부 작업을 허용합니다. 전체적으로 HTTP POST, PUT, PATCH 및 DELETE 요청은 차단되며, 특별한 사례가 처리되는 방법에 대한 자세한 개요를 확인할 수 있습니다.

유지 보수 모드 활성화

관리자 권한으로 다음 방법 중 하나로 유지 보수 모드를 활성화하세요:

  • 웹 UI:
    1. 왼쪽 사이드바 하단에서 Admin을 선택합니다.
    2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
    3. Maintenance Mode를 확장하고 Enable Maintenance Mode를 전환합니다.
      배너에 메시지를 추가할 수도 있습니다.
    4. 변경 사항 저장을 선택합니다.

  • API:

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

유지 보수 모드 비활성화

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

  • 웹 UI:
    1. 왼쪽 사이드바 하단에서 Admin을 선택합니다.
    2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
    3. Maintenance Mode를 확장하고 Enable Maintenance Mode를 전환합니다.
      배너에 메시지를 추가할 수도 있습니다.
    4. 변경 사항 저장을 선택합니다.

  • API:

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

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

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

사용자가 허용되지 않은 쓰기 작업을 시도할 때 오류가 표시됩니다.

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

note
경우에 따라 작업에서 시각적 피드백이 오해를 일으킬 수 있습니다. 예를 들어, 프로젝트에 별을 다는 경우 Star 버튼이 Unstar 작업을 표시하도록 변경됩니다. 그러나 이것은 오직 프론트엔드 업데이트일 뿐이며 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 푸시는 실패합니다.

병합 요청, 이슈, 에픽

위에서 언급한 것 외의 모든 쓰기 작업이 실패합니다. 예를 들어, 사용자는 병합 요청이나 이슈를 업데이트할 수 없습니다.

수신 이메일

새 이슈 답장, 이슈(새 서비스 데스크 이슈 포함), 병합 요청 이메일로는 실패합니다.

발신 이메일

알림 이메일은 계속 도착하지만, 비밀번호 재설정과 같이 데이터베이스 쓰기가 필요한 이메일은 도착하지 않습니다.

REST API

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

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

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

허용되는 유일한 변이는 레지스트리를 다시 동기화하고 재검증하는 데 사용되는 GeoRegistriesUpdate입니다.

지속적 통합

  • 새로운 작업이나 파이프라인은 시작되지 않으며, 예약되지 않은 것도 포함입니다.
  • 이미 실행 중인 작업은 GitLab UI에서 running 상태를 유지하며, GitLab Runner에서 실행이 완료되더라도 마찬가지입니다.
  • 프로젝트 시간 제한을 초과하여 running 상태인 작업은 시간 초과되지 않습니다.
  • 파이프라인은 시작, 재시도 또는 취소할 수 없습니다. 새로운 작업도 생성할 수 없습니다.
  • /admin/runners의 러너 상태는 업데이트되지 않습니다.
  • gitlab-runner verify는 오류를 반환합니다: ERROR: Verifying runner... is removed.

유지 관리 모드가 비활성화된 후, 새로운 작업이 다시 선택됩니다. 유지 관리 모드 활성화 전에 running 상태였던 작업은 재개되며 로그 업데이트가 시작됩니다.

참고: 유지 관리 모드가 꺼진 후 이전에 running 상태였던 파이프라인을 재시작해야 합니다.

배포

배포는 파이프라인이 완료되지 않았기 때문에 진행되지 않습니다.

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

Terraform 통합

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

컨테이너 레지스트리

docker push는 다음과 같은 오류로 실패합니다: denied: requested access to the resource is denied, 그러나 docker pull은 작동합니다.

패키지 레지스트리

패키지 레지스트리는 패키지를 설치할 수는 있지만 게시할 수는 없습니다.

백그라운드 작업

백그라운드 작업(크론 작업, Sidekiq)은 자동으로 비활성화되지 않기 때문에 현재대로 계속 실행됩니다.

백그라운드 작업이 인스턴스의 내부 상태를 변경할 수 있는 작업을 수행하기 때문에, 유지 보수 모드가 활성화된 동안 일부 또는 모든 작업을 비활성화할 수 있습니다.

계획된 Geo 장애 조치 동안 Geo와 관련된 작업을 제외한 모든 크론 작업을 비활성화해야 합니다.

큐를 모니터링하고 작업을 비활성화하려면:

  1. 왼쪽 사이드바에서 맨 아래에 있는 Admin을 선택합니다.

  2. 모니터링 > 백그라운드 작업을 선택합니다.

  3. Sidekiq 대시보드에서 Cron을 선택하고 개별적으로 또는 모두 비활성화를 선택하여 한 번에 모든 작업을 비활성화합니다.

사고 관리

사고 관리 기능은 제한적입니다. 알림 및 사고의 생성은 완전히 일시 중지됩니다. 따라서 알림 및 사고에 대한 통지 및 페이지 매김이 비활성화됩니다.

기능 플래그

Geo 보조

주(primary)가 유지 보수 모드에 있을 때 보조(secondary)도 자동으로 유지 보수 모드로 전환됩니다.

유지 보수 모드를 활성화하기 전에 복제를 비활성화하지 않는 것이 중요합니다.

관리 UI를 통한 복제, 검증 및 레지스트리의 재동기화 및 재검증을 위한 수동 작업은 계속 작동하지만, 원격 Git 푸시는 주로 전송되지 않습니다.

보안 기능

문제를 생성하거나 병합 요청을 생성하거나 승인하는 데 의존하는 기능은 작동하지 않습니다.

취약성 보고서 페이지에서 취약성 목록을 내보내는 것은 작동하지 않습니다.

발견 또는 취약성 객체에서 상태를 변경하는 것은 작동하지 않으며, UI에 오류가 표시되지 않더라도 마찬가지입니다.

SAST 및 비밀 감지는 아티팩트를 생성하기 위해 CI 작업이 통과해야 하므로 시작할 수 없습니다.

예제 사용 사례: 계획된 장애 조치

계획된 장애 조치의 사용 사례에서 주 데이터베이스의 몇 가지 쓰기는 허용됩니다. 이는 빠르게 복제되며 수적으로 중요하지 않기 때문입니다.

따라서 유지 보수 모드가 활성화된 경우 백그라운드 작업을 자동으로 차단하지 않습니다.

결과적으로 생성된 데이터베이스 쓰기는 허용됩니다. 여기서 절충은 더 많은 서비스 저하와 복제 완료 사이의 균형입니다.

그러나 계획된 장애 조치 중에는 Geo와 관련 없는 크론 작업을 수동으로 끄도록 사용자에게 요청합니다. 새로운 데이터베이스 쓰기 및 비Geo 크론 작업이 없으면 새로운 백그라운드 작업이 아예 생성되지 않거나 최소한으로 생성될 것입니다.