GitLab 유지 보수 모드

Tier: Premium, Ultimate Offering: Self-Managed

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

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

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

유지 보수 모드 활성화

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

  • 웹 UI:
    1. 왼쪽 사이드바에서 맨 아래에서 Admin을 선택합니다.
    2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
    3. 유지 보수 모드를 확장하고 유지 보수 모드 활성화를 토글합니다. 선택적으로 배너에 메시지를 추가할 수도 있습니다.
    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. 유지 보수 모드를 확장하고 유지 보수 모드 활성화를 토글합니다. 선택적으로 배너에 메시지를 추가할 수도 있습니다.
    4. 변경 사항 저장을 선택합니다.

  • API: 

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

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

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

사용자가 내부 상태를 변경할 수 없는 쓰기 작업을 시도하면 오류가 표시됩니다.

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

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

관리자 기능

시스템 관리자는 애플리케이션 설정을 편집할 수 있습니다. 이를 통해 활성화된 후 유지 보수 모드를 비활성화할 수 있습니다.

인증

모든 사용자는 GitLab 인스턴스에 등록 및 로그아웃할 수 있지만 새로운 사용자를 생성할 수 없습니다.

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

Git 작업

모든 읽기 전용 Git 작업은 계속 작동하지만 CLI 및 웹 IDE를 통한 모든 쓰기 작업은 실패하며 오류 메시지는 다음과 같습니다: Git push is not allowed because this GitLab instance is currently in (read-only) maintenance mode.

Geo가 활성화된 경우, 기본 및 보조 사이트로의 Git 푸시가 실패합니다.

병합 요청, 이슈, 이픽스

병합 요청 또는 이슈를 업데이트할 수 없는 등 모든 쓰기 작업이 실패합니다.

이메일 수신

이메일을 통해 새로운 이슈 답변, 이슈 (Service Desk 이슈 포함), 이메일을 통한 병합 요청이 실패합니다.

이메일 발신

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

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 풀/클론을 허용하기 위함
POST /api/v4/internal 내부 API 라우트
POST /admin/sidekiq Admin 영역에서 백그라운드 작업 관리를 허용하기 위함
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입니다.

CI/CD(Continuous Integration/Continuous Deployment)

  • 새 작업 또는 파이프라인은 시작되지 않음, 예약됐던 것도 아님.
  • 이미 실행 중이던 작업은 GitLab UI에서 계속 running 상태를 유지하며, GitLab Runner에서 실행을 완료해도 그대로임.
  • 프로젝트의 시간 제한을 초과한 running 상태의 작업은 타임아웃되지 않음.
  • 파이프라인을 시작, 다시 시도 또는 취소할 수 없음. 새 작업도 생성할 수 없음.
  • /admin/runners의 러너 상태가 업데이트되지 않음.
  • gitlab-runner verify은 오류 ERROR: Verifying runner... is removed를 반환.

유지 관리 모드가 비활성화된 후, 새 작업이 다시 시작됨. 유지 관리 모드를 활성화하기 전에 running 상태에 있던 작업들은 다시 시작되고 그들의 로그가 다시 업데이트됨.

참고: 유지 관리 모드를 비활성화한 후 이전에 running이었던 파이프라인을 다시 시작해야 함.

배포(Deployments)

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

유지 관리 모드 중에는 자동 배포를 비활성화하고, 비활성화되면 활성화해야 함.

Terraform 통합(Terraform integration)

Terraform 통합은 실행 중인 CI 파이프라인에 의존하기 때문에 차단됨.

컨테이너 레지스트리(Container registry)

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

패키지 레지스트리(Package registry)

패키지 레지스트리는 패키지를 설치할 수는 있지만 발행할 수는 없음.

백그라운드 작업(Background jobs)

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

계획된 Geo 장애 조치 중에는, 관련있는 크론 작업을 제외하고 모든 크론 작업을 비활성화해야 함.

대기열을 모니터링하고 작업을 비활성화하려면:

  1. 왼쪽 사이드바에서 운영자를 선택합니다.
  2. 모니터링 > 백그라운드 작업을 선택합니다.
  3. Sidekiq 대시보드에서 Cron을 선택하고 모든 작업을 선택하여 일괄적으로 비활성화하거나 개별적으로 비활성화할 수 있습니다.

사건 관리(Incident management)

사건 관리(Incident management) 기능이 제한됨. 알림(alerts) 및 사건(incidents)의 생성이 완전히 일시 중지됨. 그 결과로 알림 및 사건에 대한 알림 및 페이징이 비활성화됨.

기능 플래그(Feature flags)

Geo secondaries

기본이 유지 관리 모드인 경우, 보조도 자동으로 유지 관리 모드로 전환됨.

유지 관리 모드를 활성화하기 전에 레플리케이션을 비활성화해서는 안 됨.

레플리케이션, 검증 및 관리자 UI를 통한 레지스트리의 재동기화 및 재확인, 그러나 프록시된 Git 푸시는 초기 사이트로 전송되지 않음.

보안 기능(Secure features)

이슈 생성 또는 병합 요청 생성 또는 승인에 의존하는 기능은 작동하지 않음.

취약점 보고서 페이지에서 취약점 목록을 내보내는 것은 작동하지 않음.

UI에 오류가 표시되지 않더라도, 발견 또는 취약점 개체의 상태를 변경하는 것은 작동하지 않음.

SAST 및 비밀 검출은 아티팩트를 만들기 위해 CI 작업을 통과해야하기 때문에 시작되지 않음.

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

계획된 장애 조치의 사용 사례에서, 기본 데이터베이스에 대한 일부 쓰기가 허용되며, 빠르게 복제되어 개수적으로 중요하지 않습니다.

이와 유사한 이유로 유지 관리 모드가 활성화된 경우에는 백그라운드 작업을 자동으로 차단하지 않습니다.

그러나 계획된 장애 조치 중에는 데이터베이스에 대한 업데이트를 막기 위해 관련 없는 크론 작업을 사용자가 수동으로 비활성화하도록 요청합니다. 새 데이터베이스 쓰기와 비-Geo 크론 작업이 없으면, 새 백그라운드 작업은 전혀 생성되지 않을 수도 최소할 수도 있습니다.