필수 중지 피하기

필수 중지는 GitLab 구성 요소 또는 의존성에 대한 변경으로 인해 GitLab을 업그레이드할 때 특정 major.minor 버전으로 업그레이드해야 하고 중지해야 하는 경우를 말합니다.

개발팀은 세 릴리스(3개월) 백포트 창을 초래하는 유지 보수 정책을 유지하지만, GitLab은 현재 주요 버전과 이전 두 개의 주요 버전을 포함하는 훨씬 더 긴 버전 지원 기간을 유지합니다. 이전 주요 릴리스의 일정에 따라 GitLab 고객은 현재 릴리스에 대해 최대 3년까지 지연될 수 있으며 여전히 업그레이드 지원을 받을 수 있습니다.

예를 들어, GitLab 14.0.12에서 GitLab 16.1로 업그레이드하는 GitLab 사용자는 다음과 같은 필수 중지가 있을 수 있습니다: 14.3.6, 14.9.5, 14.10.5, 15.0.5, 15.1.6, 15.4.6, 및 15.11.11 후에 최신 16.1.z 버전으로 업그레이드합니다.

과거의 필수 중지는 도입 후 몇 달이 지나서 발견된 경우가 많으며, 이는 종종 광범위한 문제 해결 및 지원 엔지니어, 고객 성공 관리자, 개발 엔지니어의 도움이 필요했습니다. 사용자가 1-3개 이상의 마이너 릴리스를 사이에 두고 업그레이드할 때 발생합니다.

가능한 경우 필수 중지는 피해야 합니다. 피할 수 없는 경우, 필수 중지는 예약된 필수 중지에 맞춰야 합니다.

예약된 필수 중지는 일반적으로 major 버전 릴리스 직전의 이전 major.minor 릴리스에 대해 구현되어 여러 예정된 폐지 및 알려진 중단 변경을 수용합니다.

또한, GitLab 16부터 우리는 예약된 major.minor 필수 중지를 도입했습니다:

GitLab 16.x 동안 우리는 두 세 개의 필수 업그레이드 중지를 예약하고 있습니다.

우리는 필수 업그레이드 중지를 예약할 때 최소 두 개의 마일스톤 통지를 제공할 것입니다. 첫 번째 예정된 필수 업그레이드 중지는 GitLab 16.3에 예약되어 있습니다. 업그레이드 중지를 요구하는 변경 사항이 도입되지 않으면 GitLab 16.3는 일반 업그레이드로 취급됩니다.

사후적으로 필수 중지 추가하기

예정되지 않은 필수 중지를 사후적으로 선언하는 것을 고려하는 경우, 다음 단계에 대해 조언하려면 분배 팀의 제품 관리자에게 문의하십시오. 필수 중지를 선언해야 하는지에 대한 불확실성이 있는 경우, 분배 제품 관리자가 GitLab 제품 리더십(VP 또는 Chief Product Officer)에게 에스컬레이션하여 최종 결정을 내리게 할 수 있습니다. 이는 예를 들어, 변경 사항이 매우 큰 자체 관리 설치의 소규모 하위 집합에 대해 중지를 요구할 수 있고, 고객이 문제에 직면할 경우 잘 정의된 해결 방법이 있을 때 발생할 수 있습니다.

필수 중지의 원인

완료된 마이그레이션에 대한 부정확한 가정

대부분의 필수 중지는 주어진 릴리스의 데이터 모델 상태에 대한 가정으로 인해 발생하며, 일반적으로 상호 의존적인 데이터베이스 마이그레이션이나 이전 마이그레이션에서 도입된 스키마 변경이 코드가 로드될 때까지 완료되었다고 가정하는 코드 변경 형태를 취합니다.

버전 간의 하위 호환성을 위해 변경사항 및 마이그레이션을 설계하면 지속적이거나 제로 다운타임 업그레이드에 대한 중지 우려를 완화할 수 있습니다. 그러나 계약 단계에서 마이그레이션/코드 변경 사항이 도입되면 백그라운드 마이그레이션이 완료된 후 실행 또는 로드해야 하는 필수 중지가 발생할 가능성이 높습니다.

경고:

마이그레이션을 추가하거나 제거하거나 마이그레이션이 주어진 릴리스에서 완료되었다고 가정하는 코드를 도입할 것을 고려하고 있다면, 먼저 필수 중지에 관한 데이터베이스 관련 문서를 검토하십시오.

예시

  • GitLab 12.1: state 값에 따라 MergeRequests에서 merge_status를 변경하는 백그라운드 마이그레이션이 도입되었습니다. state 속성은 12.10에서 제거되었습니다. 필요한 중지 문서화는 13.6까지 걸렸습니다.

  • GitLab 13.8: 중복 서비스 기록을 처리하기 위한 백그라운드 마이그레이션이 포함되었습니다. 13.9에서는 백그라운드 마이그레이션 완료에 의존하는 다른 마이그레이션에서 고유 인덱스가 적용되었습니다. GitLab 14.3까지 발견되지 않고 문서화되지 않았습니다.

  • GitLab 14.3: merge_request_diff_commits에 대한 잠재적으로 오랜 시간 실행되는 백그라운드 마이그레이션이 포함되었으며, 이는 14.5에서 전면적으로 나타났습니다. 이 변경으로 인해 대규모 GitLab 설치 사용자는 광범위한 다운타임을 경험하게 되었습니다. GitLab 15.1까지 문서화되지 않았습니다.

  • GitLab 14.9: namespaces 및 projects에 대한 배치 백그라운드 마이그레이션이 포함되어 있으며, 이는 14.10에서 추가된 다른 배치 백그라운드 마이그레이션이 실행되기 전에 완료되어야 하므로 필수 중지를 강요합니다. 이 마이그레이션은 대규모 GitLab 설치에서는 몇 시간 또는 며칠이 걸릴 수 있습니다.

추가 세부사항과 관련된 이슈 및 머지 요청 링크는 다음에서 확인할 수 있습니다: 이슈: GitLab 업그레이드 경로 중지의 추가/확산을 피하기 위한 조치를 취합니다

코드 우회 및 완화 조치 제거

데이터 모델/스키마/마이그레이션 상태에 대한 가정과 유사하게, 이전에 발견된 문제를 우회하기 위해 구현된 코드의 의도적인 제거로 인해 필수 major.minor 중지가 도입되었습니다.

예시

  • GitLab 13.1: Rails 6.0.3.1에서 보안 수정으로 인해 CSRF 토큰 변경이 도입되었습니다 (카나리 환경 사고를 초래함). 우리는 이전에 생성된 토큰의 수용을 유지하기 위해 코드를 도입하였고, 13.2에서 해당 코드를 제거하여 13.1에서 알려진 필수 중지를 생성했습니다.

  • GitLab 15.4: GitLab 14.9 이후 코드에서 완화되었던 작업 아티팩트의 부정확한 expires_at 타임스탬프를 수정하기 위한 마이그레이션을 도입합니다. 우회 조치는 GitLab 15.6에서 제거되어 15.4가 필수 중지가 되었습니다.

사용 중단

특히 중대한 변경 사항과 같은 사용 중단은 긴 마이그레이션 지연을 초래하거나 GitLab 관리자의 수동 작업을 요구할 경우 필수 중지를 발생시킬 수 있습니다.

이들은 일반적으로 주요 릴리스 주변에서 필수 중지로 받아들여지며, 새로운 major 릴리스가 실시되기 직전의 최신 major.minor 릴리스에서 중지하거나 최신 major.0 패치 릴리스에서 중지할 수 있습니다. 현재까지 발견된 사용 중단과 관련된 필수 중지는 이러한 릴리스로 제한되어 있습니다.

모든 사용 중단에 필수 중지가 부여되는 것은 아니며, 대부분의 경우 사용자는 다운타임이나 기타 주요 문제를 초래하지 않고 업그레이드를 시작하기 전에 구성을 조정할 수 있습니다.

예시

사용 중단의 예시는 여기에 나열하기에는 너무 많지만 다음에서 확인할 수 있습니다:

필수 정거장 추가

필수 정거장 이정표 계획

모든 이정표에 필수 정거장을 추가할 수는 없습니다. 이는 GitLab 업그레이드 시 사용자 경험에 영향을 미치기 때문입니다.

배포 그룹은 필수 정거장을 계획하고 정의하는 데 도움을 줍니다.

GitLab 17.5부터 X.2, X.5, X.8 및 X.11 마이너 이정표에서 필수 정거장을 도입할 것입니다. 업그레이드 정거장을 필요로 하는 코드 변경이나 기능을 도입하는 경우, 이러한 이정표를 염두에 두고 변경 사항을 조정해야 합니다.

필수 정거장이 출시되기 전에

알려진 필수 정거장을 출시하기 전에 다음 단계를 완료하세요. 필수 정거장이 출시 후 식별되면, 다음 단계를 여전히 완료해야 합니다:

  1. 동일한 MR에서 업그레이드 경로 문서를 업데이트하여 새 필수 정거장을 포함하고 upgrade_path.yml을 업데이트합니다. upgrade_path.yml은 모든 필수 정거장에 대한 단일 진실 출처(SSoT)입니다.

  2. 고객 지원 및 릴리스 관리 팀과 변경 사항을 커뮤니케이션합니다.

  3. 데이터베이스 그룹에 문제를 제기하여 다음 릴리스에서 해당 버전으로 마이그레이션을 통합하도록 요청합니다. 문제에 대해 다음 템플릿을 사용하십시오:

    Title: `Squash migrations to <Required stop version>`
<required stop version>에 대해 추가된 필수 정거장으로 인해 해당 버전까지 마이그레이션을 통합하고
최소 스키마 버전을 업데이트해야 합니다.

Deliverables:
- [ ] <required stop version>까지 마이그레이션이 통합되었습니다.
- [ ] `Gitlab::Database::MIN_SCHEMA_VERSION`이 init_schema 버전과 일치합니다.

/label ~"group::database" ~"section::enablement" ~"devops::data_stores" ~"Category:Database" ~"type::maintenance"
/cc @gitlab-org/database-team/triage

필수 정거장 후 출시

  1. charts 프로젝트에서 업그레이드 체크 훅을 필수 정거장 버전으로 업데이트합니다.

upgrade_path.yml에 의존하는 GitLab 유지 관리 프로젝트

우리는 upgrade_path.yml SSoT에 의존하는 여러 프로젝트를 보유하고 있습니다. 따라서 이 파일의 구조에 대한 변경은 다음 프로젝트 중 하나에 영향을 미칠 수 있음을 고려해야 합니다:

추가 읽기