InfoGrab DocsInfoGrab Docs

필수 업그레이드 중단점 방지

요약

필수 중단점(required stop)은 GitLab 컴포넌트 또는 의존성에 대한 변경으로 인해 GitLab을 업그레이드할 때 특정 major.minor 버전으로 업그레이드하고 해당 버전에서 반드시 멈춰야 하는 상황을 말합니다.

필수 중단점(required stop)은 GitLab 컴포넌트 또는 의존성에 대한 변경으로 인해 GitLab을 업그레이드할 때 특정 major.minor 버전으로 업그레이드하고 해당 버전에서 반드시 멈춰야 하는 상황을 말합니다.

Development 팀은 3개 릴리스(3개월) 백포트 기간을 정한 유지 관리 정책을 유지하고 있지만, GitLab은 현재 메이저 버전과 이전 두 메이저 버전을 포함하는 훨씬 더 긴 버전 지원 기간을 유지합니다. 이전 메이저 릴리스 일정에 따르면, GitLab 고객은 현재 릴리스보다 최대 3년 뒤처져 있어도 여전히 업그레이드 지원을 받을 수 있습니다.

예를 들어, GitLab 14.0.12에서 GitLab 16.1로 업그레이드하는 사용자의 경우, 이는 완전히 지원되는 업그레이드 경로이며, 최신 16.1.z 버전으로 업그레이드하기 전에 14.3.6, 14.9.5, 14.10.5, 15.0.5, 15.1.6, 15.4.6, 15.11.11과 같은 필수 중단점이 있을 수 있습니다.

과거의 필수 중단점은 도입 후 수개월이 지나서야 발견된 경우가 많았습니다. 이는 종종 1~3개 이상의 마이너 릴리스를 넘어 업그레이드하는 사용자들을 지원하는 Support 엔지니어, Customer Success 매니저, Development 엔지니어들의 광범위한 문제 해결 지원의 결과였습니다.

가능한 한 필수 중단점은 피해야 합니다. 피할 수 없는 경우에는, 필수 중단점을 예정된 필수 중단점에 맞춰야 합니다.

예정된 필수 중단점은 종종 major 버전 릴리스 직전의 이전 major.minor 릴리스에 대해 다수의 계획된 지원 중단 및 알려진 주요 변경 사항을 수용하기 위해 구현됩니다.

또한 GitLab 16부터 예정된 major.minor 필수 중단점을 도입했습니다:

GitLab 16.x 기간 동안 두 개 또는 세 개의 필수 업그레이드 중단점을 예약하고 있습니다.

필수 업그레이드 중단점을 예약할 때 최소 두 개의 마일스톤 전에 공지합니다. 첫 번째 계획된 필수 업그레이드 중단점은 GitLab 16.3으로 예정되어 있습니다. 업그레이드 중단점을 필요로 하는 사항이 없다면, GitLab 16.3은 일반 업그레이드로 처리됩니다.

필수 중단점 소급 추가#

계획에 없던 필수 중단점을 소급 선언하는 것을 검토하는 경우, Distribution 팀 제품 매니저에게 연락하여 다음 단계에 대한 조언을 구하세요. 필수 중단점을 선언해야 하는지 불확실한 경우, Distribution 제품 매니저는 최종 결정을 위해 GitLab 제품 리더십(VP 또는 최고 제품 책임자)에게 에스컬레이션할 수 있습니다. 예를 들어, 변경 사항이 매우 큰 GitLab Self-Managed 인스턴스의 일부에만 중단점을 요구하고 고객이 문제를 겪을 경우 잘 정의된 우회 방법이 있는 경우에 이런 일이 발생할 수 있습니다.

필수 중단점의 원인#

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

대부분의 필수 중단점은 특정 릴리스에서의 데이터 모델 상태에 대한 가정 때문입니다. 일반적으로 상호 의존적인 데이터베이스 마이그레이션, 또는 코드가 로드될 때 이전 마이그레이션에서 도입된 스키마 변경이 완료되었다고 가정하는 코드 변경 형태로 나타납니다.

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

마이그레이션을 추가하거나 제거하거나, 특정 릴리스에서 마이그레이션이 완료되었다고 가정하는 코드를 도입하는 것을 검토하는 경우, 먼저 필수 중단점에 관한 데이터베이스 관련 문서를 검토하세요.

예시#

  • GitLab 12.1: state 값에 따라 MergeRequest의 merge_status를 변경하는 백그라운드 마이그레이션이 도입되었습니다. state 속성은 12.10에서 제거되었습니다. 필수 중단점이 문서화된 것은 13.6에 이르러서였습니다.

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

  • GitLab 14.3: 14.5에서 포그라운드로 전환된 merge_request_diff_commits에 대한 잠재적으로 오래 실행되는 백그라운드 마이그레이션이 포함되어 있습니다. 이 변경으로 인해 대규모 GitLab 설치 사용자들이 광범위한 다운타임을 경험했습니다. GitLab 15.1까지 문서화되지 않았습니다.

  • GitLab 14.9: 14.10에 추가된 또 다른 일괄 백그라운드 마이그레이션이 실행되기 전에 완료되어야 하는 namespaces와 projects에 대한 일괄 백그라운드 마이그레이션이 포함되어 있으며, 이로 인해 필수 중단점이 강제됩니다. 대규모 GitLab 설치에서 이 마이그레이션은 완료까지 수 시간 또는 수 일이 걸릴 수 있습니다.

추가적인 세부 정보 및 관련 이슈와 머지 리퀘스트 링크는 다음에서 확인할 수 있습니다: 이슈: GitLab 업그레이드 경로 중단점의 추가/증가를 방지하기 위한 조치 마련

코드 우회 방법 및 완화 조치 제거#

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

예시#

  • GitLab 13.1: Rails 6.0.3.1의 보안 수정으로 CSRF 토큰 변경이 도입되었습니다(카나리 환경 인시던트 발생). 이전에 생성된 토큰의 수락을 유지하기 위한 코드를 도입했으며, 13.2에서 해당 코드를 제거하여 13.1에 알려진 필수 중단점이 생성되었습니다.

  • GitLab 15.4: GitLab 14.9부터 코드에서 완화되었던 job 아티팩트의 부정확한 expires_at 타임스탬프를 수정하는 마이그레이션이 도입되었습니다. 우회 방법은 GitLab 15.6에서 제거되어 15.4가 필수 중단점이 되었습니다.

지원 중단(Deprecation)#

지원 중단(deprecation), 특히 주요 변경 사항은 긴 마이그레이션 지연을 유발하거나 GitLab 관리자의 수동 작업을 요구하는 경우 필수 중단점을 야기할 수 있습니다.

이는 일반적으로 메이저 릴리스 전후의 필수 중단점으로 수용되며, 새로운 major 릴리스 직전의 최신 major.minor 릴리스에서 중단하거나 최신 major.0 패치 릴리스에서 중단합니다. 지금까지 지원 중단과 관련된 발견된 필수 중단점은 이러한 릴리스들로 제한되었습니다.

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

예시#

지원 중단 사례는 너무 많아 여기에 나열하기 어렵지만, 다음에서 확인할 수 있습니다:

GitLab 17

필수 중단점 추가#

필수 중단점 마일스톤 계획#

모든 마일스톤에 필수 중단점을 추가할 수는 없으며, 이는 GitLab 업그레이드 사용자 경험을 저하시킵니다. Distribution 그룹은 필수 중단점이 도입되는 시점을 계획하고 정의하는 데 책임이 있습니다.

GitLab 17.5부터 X.2, X.5, X.8, X.11 마이너 마일스톤에 필수 중단점을 도입합니다. 업그레이드 중단점을 필요로 하는 코드 변경이나 기능을 도입하는 경우, 이러한 마일스톤을 고려하여 변경 사항을 맞춰야 합니다.

필수 중단점 릴리스 전#

알려진 필수 중단점을 릴리스하기 전에 다음 단계를 완료하세요. 릴리스 후에 필수 중단점이 확인된 경우에도 아래 단계는 반드시 완료되어야 합니다:

동일한 MR에서 새로운 필수 중단점을 포함하여 업그레이드 경로 문서와 upgrade_path.yml을 업데이트하세요. upgrade_path.yml은 모든 필수 중단점의 단일 진실 공급원(Single Source Of Truth, SSoT)입니다.

고객 Support 팀과 Release Management 팀에 변경 사항을 전달하세요.

다음 릴리스에서 해당 버전까지 마이그레이션을 스쿼시하도록 Database 그룹에 이슈를 제출하세요. 이슈에는 다음 템플릿을 사용하세요:

Title: `Squash migrations to `
As a result of the required stop added for <required stop version> we should squash
migrations up to that version, and update the minimum schema version.

Deliverables:
- [ ] Migrations are squashed up to <required stop version>
- [ ] `Gitlab::Database::MIN_SCHEMA_VERSION` matches init_schema version

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

필수 중단점 이후 릴리스#

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

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

추가 읽기 자료#

패키지(Omnibus) 업그레이드

필수 업그레이드 중단점 방지

GitLab v19.1
원문 보기
요약

필수 중단점(required stop)은 GitLab 컴포넌트 또는 의존성에 대한 변경으로 인해 GitLab을 업그레이드할 때 특정 major.minor 버전으로 업그레이드하고 해당 버전에서 반드시 멈춰야 하는 상황을 말합니다.

필수 중단점(required stop)은 GitLab 컴포넌트 또는 의존성에 대한 변경으로 인해 GitLab을 업그레이드할 때 특정 major.minor 버전으로 업그레이드하고 해당 버전에서 반드시 멈춰야 하는 상황을 말합니다.

Development 팀은 3개 릴리스(3개월) 백포트 기간을 정한 유지 관리 정책을 유지하고 있지만, GitLab은 현재 메이저 버전과 이전 두 메이저 버전을 포함하는 훨씬 더 긴 버전 지원 기간을 유지합니다. 이전 메이저 릴리스 일정에 따르면, GitLab 고객은 현재 릴리스보다 최대 3년 뒤처져 있어도 여전히 업그레이드 지원을 받을 수 있습니다.

예를 들어, GitLab 14.0.12에서 GitLab 16.1로 업그레이드하는 사용자의 경우, 이는 완전히 지원되는 업그레이드 경로이며, 최신 16.1.z 버전으로 업그레이드하기 전에 14.3.6, 14.9.5, 14.10.5, 15.0.5, 15.1.6, 15.4.6, 15.11.11과 같은 필수 중단점이 있을 수 있습니다.

과거의 필수 중단점은 도입 후 수개월이 지나서야 발견된 경우가 많았습니다. 이는 종종 1~3개 이상의 마이너 릴리스를 넘어 업그레이드하는 사용자들을 지원하는 Support 엔지니어, Customer Success 매니저, Development 엔지니어들의 광범위한 문제 해결 지원의 결과였습니다.

가능한 한 필수 중단점은 피해야 합니다. 피할 수 없는 경우에는, 필수 중단점을 예정된 필수 중단점에 맞춰야 합니다.

예정된 필수 중단점은 종종 major 버전 릴리스 직전의 이전 major.minor 릴리스에 대해 다수의 계획된 지원 중단 및 알려진 주요 변경 사항을 수용하기 위해 구현됩니다.

또한 GitLab 16부터 예정된 major.minor 필수 중단점을 도입했습니다:

GitLab 16.x 기간 동안 두 개 또는 세 개의 필수 업그레이드 중단점을 예약하고 있습니다.

필수 업그레이드 중단점을 예약할 때 최소 두 개의 마일스톤 전에 공지합니다. 첫 번째 계획된 필수 업그레이드 중단점은 GitLab 16.3으로 예정되어 있습니다. 업그레이드 중단점을 필요로 하는 사항이 없다면, GitLab 16.3은 일반 업그레이드로 처리됩니다.

필수 중단점 소급 추가#

계획에 없던 필수 중단점을 소급 선언하는 것을 검토하는 경우, Distribution 팀 제품 매니저에게 연락하여 다음 단계에 대한 조언을 구하세요. 필수 중단점을 선언해야 하는지 불확실한 경우, Distribution 제품 매니저는 최종 결정을 위해 GitLab 제품 리더십(VP 또는 최고 제품 책임자)에게 에스컬레이션할 수 있습니다. 예를 들어, 변경 사항이 매우 큰 GitLab Self-Managed 인스턴스의 일부에만 중단점을 요구하고 고객이 문제를 겪을 경우 잘 정의된 우회 방법이 있는 경우에 이런 일이 발생할 수 있습니다.

필수 중단점의 원인#

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

대부분의 필수 중단점은 특정 릴리스에서의 데이터 모델 상태에 대한 가정 때문입니다. 일반적으로 상호 의존적인 데이터베이스 마이그레이션, 또는 코드가 로드될 때 이전 마이그레이션에서 도입된 스키마 변경이 완료되었다고 가정하는 코드 변경 형태로 나타납니다.

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

마이그레이션을 추가하거나 제거하거나, 특정 릴리스에서 마이그레이션이 완료되었다고 가정하는 코드를 도입하는 것을 검토하는 경우, 먼저 필수 중단점에 관한 데이터베이스 관련 문서를 검토하세요.

예시#

  • GitLab 12.1: state 값에 따라 MergeRequest의 merge_status를 변경하는 백그라운드 마이그레이션이 도입되었습니다. state 속성은 12.10에서 제거되었습니다. 필수 중단점이 문서화된 것은 13.6에 이르러서였습니다.

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

  • GitLab 14.3: 14.5에서 포그라운드로 전환된 merge_request_diff_commits에 대한 잠재적으로 오래 실행되는 백그라운드 마이그레이션이 포함되어 있습니다. 이 변경으로 인해 대규모 GitLab 설치 사용자들이 광범위한 다운타임을 경험했습니다. GitLab 15.1까지 문서화되지 않았습니다.

  • GitLab 14.9: 14.10에 추가된 또 다른 일괄 백그라운드 마이그레이션이 실행되기 전에 완료되어야 하는 namespaces와 projects에 대한 일괄 백그라운드 마이그레이션이 포함되어 있으며, 이로 인해 필수 중단점이 강제됩니다. 대규모 GitLab 설치에서 이 마이그레이션은 완료까지 수 시간 또는 수 일이 걸릴 수 있습니다.

추가적인 세부 정보 및 관련 이슈와 머지 리퀘스트 링크는 다음에서 확인할 수 있습니다: 이슈: GitLab 업그레이드 경로 중단점의 추가/증가를 방지하기 위한 조치 마련

코드 우회 방법 및 완화 조치 제거#

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

예시#

  • GitLab 13.1: Rails 6.0.3.1의 보안 수정으로 CSRF 토큰 변경이 도입되었습니다(카나리 환경 인시던트 발생). 이전에 생성된 토큰의 수락을 유지하기 위한 코드를 도입했으며, 13.2에서 해당 코드를 제거하여 13.1에 알려진 필수 중단점이 생성되었습니다.

  • GitLab 15.4: GitLab 14.9부터 코드에서 완화되었던 job 아티팩트의 부정확한 expires_at 타임스탬프를 수정하는 마이그레이션이 도입되었습니다. 우회 방법은 GitLab 15.6에서 제거되어 15.4가 필수 중단점이 되었습니다.

지원 중단(Deprecation)#

지원 중단(deprecation), 특히 주요 변경 사항은 긴 마이그레이션 지연을 유발하거나 GitLab 관리자의 수동 작업을 요구하는 경우 필수 중단점을 야기할 수 있습니다.

이는 일반적으로 메이저 릴리스 전후의 필수 중단점으로 수용되며, 새로운 major 릴리스 직전의 최신 major.minor 릴리스에서 중단하거나 최신 major.0 패치 릴리스에서 중단합니다. 지금까지 지원 중단과 관련된 발견된 필수 중단점은 이러한 릴리스들로 제한되었습니다.

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

예시#

지원 중단 사례는 너무 많아 여기에 나열하기 어렵지만, 다음에서 확인할 수 있습니다:

GitLab 17

필수 중단점 추가#

필수 중단점 마일스톤 계획#

모든 마일스톤에 필수 중단점을 추가할 수는 없으며, 이는 GitLab 업그레이드 사용자 경험을 저하시킵니다. Distribution 그룹은 필수 중단점이 도입되는 시점을 계획하고 정의하는 데 책임이 있습니다.

GitLab 17.5부터 X.2, X.5, X.8, X.11 마이너 마일스톤에 필수 중단점을 도입합니다. 업그레이드 중단점을 필요로 하는 코드 변경이나 기능을 도입하는 경우, 이러한 마일스톤을 고려하여 변경 사항을 맞춰야 합니다.

필수 중단점 릴리스 전#

알려진 필수 중단점을 릴리스하기 전에 다음 단계를 완료하세요. 릴리스 후에 필수 중단점이 확인된 경우에도 아래 단계는 반드시 완료되어야 합니다:

동일한 MR에서 새로운 필수 중단점을 포함하여 업그레이드 경로 문서와 upgrade_path.yml을 업데이트하세요. upgrade_path.yml은 모든 필수 중단점의 단일 진실 공급원(Single Source Of Truth, SSoT)입니다.

고객 Support 팀과 Release Management 팀에 변경 사항을 전달하세요.

다음 릴리스에서 해당 버전까지 마이그레이션을 스쿼시하도록 Database 그룹에 이슈를 제출하세요. 이슈에는 다음 템플릿을 사용하세요:

Title: `Squash migrations to `
As a result of the required stop added for <required stop version> we should squash
migrations up to that version, and update the minimum schema version.

Deliverables:
- [ ] Migrations are squashed up to <required stop version>
- [ ] `Gitlab::Database::MIN_SCHEMA_VERSION` matches init_schema version

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

필수 중단점 이후 릴리스#

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

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

추가 읽기 자료#

패키지(Omnibus) 업그레이드