필수 중지 사항 회피하기

필수 중지 사항은 GitLab 구성 요소 또는 의존성에 대한 변경으로 발생하는데, 이로 인해 GitLab 업그레이드시 특정 major.minor 버전으로 업그레이드하고 중지해야 합니다.

개발은 유지 정책을 유지하여 세 가지 릴리스(3개월) 백포트 창을 유지합니다. GitLab은 현재 주요 버전 및 이전 두 주요 버전을 포함한 버전 지원을 더 오랜 기간 유지합니다. 이전 주요 릴리스의 일정을 기반으로, GitLab 고객은 최신 릴리스에서 최대 3년까지 지연될 수 있고 업그레이드를 지원받을 수 있습니다.

예를 들어, GitLab 사용자가 GitLab 14.0.12에서 완전히 지원되는 업그레이드 경로인 GitLab 16.1로 업그레이드할 때 다음과 같은 필수 중지 사항이 있을 수 있습니다: 14.3.6, 14.9.5, 14.10.5, 15.0.5, 15.1.6, 15.4.6, 그리고 최신 16.1.z 버전으로 업그레이드하기 전까지 15.11.11입니다.

과거의 필수 중지 사항은 종종 발견되지 않았으며, 종종 광범위한 문제 해결 및 지원 엔지니어, 고객 성공 관리자 및 개발 엔지니어의 지원을 통해 사용자가 1-3개의 마이너 릴리스를 초과하여 업그레이드하는 경우에 발견됩니다.

가능하다면 필수 중지 사항을 피해야 합니다. 피할 수 없는 경우, 필수 중지 사항은 예정된 필수 중지 사항과 일치해야 합니다.

예정된 필수 중지 사항은 일반적으로 major.minor 릴리스 전에 이전 major 버전 릴리스를 위해 자주 구현됩니다. 이는 여러 계획된 사용 중단 및 알려진 파괴적 변경 사항을 수용하기 위한 것입니다.

또한, GitLab 16부터 예정된 major.minor 필수 중지가 소개되었습니다.

::: GitLab 16.x에서 두 또는 세 개의 필수 업그레이드 중지를 예정하고 있습니다.

필수 업그레이드 중지를 예정할 때 적어도 두 개의 마일스톤을 사전에 알립니다. 첫 번째 계획된 필수 업그레이드 중지는 GitLab 16.3에 예정되어 있습니다. 업그레이드 중지가 필요한 변경 사항이 소개되지 않으면, GitLab 16.3은 일반적인 업그레이드로 처리됩니다. :::

필수 중지 사항을 나중에 추가하는 방법

우리가 비예정적으로 필수 중지 사항을 선언하는 것을 고려할 때, 배포 팀 제품 관리자에게 연락하여 다음 단계에 대해 상의하십시오. 필수 중지 사항을 선언해야 하는지에 대한 불확실성이 있다면, 배포 제품 관리자는 GitLab 제품 리더쉽(VP 또는 최고 제품 책임자)에게 최종 결정을 내리도록 업그레이드 할 수 있습니다. 예를 들어, 변경 사항이 매우 큰 자체 관리 설치의 작은 하위 집합에 중지가 필요하고 문제가 발생했을 때 명확한 해결책이 있는 경우가 있습니다.

필수 중지 사항의 원인

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

필수 중지 사항의 대부분은 특정 릴리스에서 데이터 모델의 상태에 대한 가정 때문에 발생하며, 보통 상호 의존하는 데이터베이스 마이그레이션 형태로 발생합니다. 또는 많은 경우 코드 변경에서는 코드가 로드되는 시점에 이전 마이그레이션에서 도입된 스키마 변경이 완료되었다고 가정합니다. 버전 간 호환성을 위한 변경 및 마이그레이션을 설계하면 지속적인 또는 영구 중단 없이 중지에 대한 우려를 완화할 수 있습니다. 그러나 계약 단계에서는 배경 마이그레이션이 완료된 상태인 것을 요구하는 마이그레이션이 도입될 때 필수 중지 사항이 발생할 가능성이 있습니다.

경고: 마이그레이션을 추가 또는 제거하거나 특정 릴리스에서 마이그레이션이 완료되었다고 가정하는 코드를 도입하기 전에 먼저 필수 중지에 관한 데이터베이스 관련 문서를 확인하십시오.

예시

  • 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에 대한 잠재적으로 긴 지속시간 백그라운드 마이그레이션을 포함하고 있습니다. 이 변경으로 인해 대형 GitLab 설치를 사용하는 사용자들에게 많은 다운 타임이 발생했습니다. 이 사항은 GitLab 15.1에 문서화되기 전까지는 알려지지 않았습니다.
  • GitLab 14.9: namespaces 및 projects에 대한 배치형 백그라운드 마이그레이션을 포함하고 있습니다. 14.10에 추가된 다른 배치형 백그라운드 마이그레이션이 실행되기 전에 마이그레이션이 완료되야 하는 마이그레이션으로 인해 필수 중지가 발생했습니다. 큰 규모의 GitLab 설치에서 몇 시간이나 몇 일이 걸릴 수 있는 마이그레이션을 완료해야 합니다.

관련된 자세한 내용 및 관련 이슈 및 머지 요청에 대한 링크는 다음 위치에서 확인할 수 있습니다: Issue: Put in place measures to avoid addition/proliferation of GitLab upgrade path stops

코드 해결책 및 완화 조치의 제거

데이터 모델/스키마/마이그레이션 상태에 대한 가정과 유사하게, 수동으로 처리되었던 문제를 해결하기 위해 구현된 코드의 의도적인 삭제로 인해 필수 major.minor 중지 사항이 도입되었습니다.

예시

  • GitLab 13.1: Rails 6.0.3.1에서 보안 수정이 CSRF 토큰 변경을 도입했습니다(캐나리 환경 사건 발생). 이로 인해 이전에 생성된 토큰의 수용을 유지하는 코드가 도입되었으며, 이 코드는 13.2에서 제거되어 13.1에 필수 중지 사항을 만들었습니다.
  • GitLab 15.4: 작업 아티팩트의 잘못된 expires_at 타임스탬프를 수정하는 마이그레이션을 도입했습니다. 이 문제는 GitLab 14.9 이후로 코드로 해결되어 왔습니다. 이러한 해결 방법은 15.6에서 제거되어 15.4가 필수 중지로 만들었습니다.

사용 중단

사용 중단 사항은 특히 파괴적 변경의 경우, 경우에 따라 느린 마이그레이션 지연을 도입하거나 GitLab 관리자가 수동 조치를 취해야 하는 경우 필수 중지를 야기할 수 있습니다.

이러한 경우 보통 새로운 major 릴리스 전에 필수 중지 사항을 수용하며, 현재 최신 major.minor 릴리스와 최신 major.0 패치 릴리스에서 중지되는 사례가 있습니다. 지금까지 발견된 사용 중단과 관련된 필수 중지 사항은 주로 이러한 릴리스로 제한되어 왔습니다.

모든 사용 중단을 필수 중지로 취급하는 것은 아니며 대부분의 경우 사용자는 업그레이드를 시작하기 전에 설정을 조정하여 다운타임이나 다른 주요 문제를 유발하지 않고 업그레이드할 수 있습니다.

예제

deprecation의 예는 여기에 나열하기에 너무 많지만 다음에서 찾을 수 있습니다.:

필수 중지 추가

필수 중지 마일스톤 계획

모든 마일스톤에 필수 중지를 추가할 수는 없으며, 이로 인해 GitLab의 업그레이드 경험이 훼손됩니다. Distribution 팀은 필수 중지를 계획하고 정의하는 데 도움을 주는 것에 책임이 있습니다.

GitLab 17.5부터 우리는 X.2, X.5, X.8 및 X.11의 마이너 마일스톤에 필수 중지를 도입할 것입니다. 업그레이드 중지가 필요한 코드 변경이나 기능을 도입하는 경우에는 이러한 마일스톤을 염두에 두고 변경사항을 맞추어야 합니다.

필수 중지가 출시되기 전

알려진 필수 중지를 출시하기 전에 다음 단계를 완료하세요. 출시 후에 필수 중지가 식별되는 경우에도 다음 단계를 완료해야 합니다:

  1. 동일한 MR에서 업그레이드 경로 문서를 업데이트하여 새로운 필수 중지 및 upgrade_path.yml를 포함시킵니다. upgrade_path.yml은 모든 필수 중지의 단일 소스인(SSoT)입니다.
  2. 변경사항을 고객 지원 및 릴리스 관리 팀과 공유하세요.

  3. 다음 릴리스에서 해당 버전으로의 마이그레이션을 squash하기 위해 Database 그룹에 이슈를 등록하세요. 이 문제에 대한 템플릿은 다음과 같습니다: 

    제목: `Squash migrations to <필수 중지 버전>`
<필수 중지 버전>을(를) 추가함으로써 <필수 중지 버전>에 대한 마이그레이션을 squash하고 최소 스키마 버전을 업데이트해야 합니다.
   
결과물:
- [ ] <필수 중지 버전>까지 마이그레이션이 squash됨
- [ ] `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 의존하는 여러 프로젝트가 있습니다. 따라서 이 파일 구조에 대한 변경은 다음 프로젝트 중 하나에 영향을 미칠 수 있음을 고려해야 합니다:

더 많은 읽기