• 중단 사항이 필요한 일반적인 시나리오
  • 실행되어야 하는 장기 실행 마이그레이션이 완료될 때
  • 올바르게 완료되지 않은 백그라운드 마이그레이션
  • 마이그레이션 제거
  • 마이그레이션의 타임스탬프가 매우 오래됨
  • 마이그레이션 관련 도구의 버그
• 필수 중단이 릴리스되기 전
• 필수 중단 이후 릴리스에서

필수 중단 사항 추가

필수 중단 사항은 종종 고객들에게 혼란을 초래하여 절대적으로 필요한 경우에만 추가되어야 합니다. 필수 중단 사항을 추가하기 전에 필수 중단을 피할 대안이 있는지 고려해보세요. 때로는 필수 중단이 피할 수 없을 수도 있습니다. 이러한 경우에는 아래 지침을 따르세요.

중단 사항이 필요한 일반적인 시나리오

실행되어야 하는 장기 실행 마이그레이션이 완료될 때

마이그레이션이 오랜 시간이 걸린다면, 많은 고객들이 업그레이드 중에 타임아웃을 경험할 수 있습니다. 증가된 지원 건 수는 필수 중단을 도입하게 만들 수 있습니다. 특히 큰 고객들이 배경 마이그레이션으로 인해 이러한 문제를 겪을 수 있지만, 우리는 일반적으로 영향이 널리 퍼져 있을 때에만 중단을 도입합니다.

• 원인: 업그레이드가 1시간 이상 걸릴 경우 옴니버스에서 타임아웃.
• 완화 방안: 다음 필수 중단 이후 첫 번째 마이너 버전에 대한 완료 예정일을 예약하세요.

올바르게 완료되지 않은 백그라운드 마이그레이션

백그라운드 마이그레이션이 완료되지 않은 경우와 해당 백그라운드 마이그레이션에 의존하는 마이그레이션이 작성된 경우에 합의를 위해 필수 중단을 도입해야 할 수 있습니다.

• 원인: 의존하는 마이그레이션이 완료되지 않은 경우, 그 백그라운드 마이그레이션이 실패할 수 있음.
• 완화 방안: 의존하는 마이그레이션을 작성하기 전에 모든 백그라운드 마이그레이션이 완료되었는지 확인하세요.

마이그레이션 제거

마이그레이션이 제거되면 필수 변경 사항을 고객이 놓치지 않도록 하기 위해 필수 중단을 도입해야 할 수 있습니다.

• 원인: 종속 마이그레이션이 실패할 수 있거나 필수 마이그레이션이 제거되었기 때문에 애플리케이션이 작동하지 않을 수 있음.
• 완화 방안: 마이그레이션은 계획된 필수 중단에 포함된 후에만 제거될 수 있도록 보장하세요.

마이그레이션의 타임스탬프가 매우 오래됨

마이그레이션의 타임스탬프가 매우 오래될 경우(> 3주, 또는 마지막 중단 이후), 다음과 같은 시나리오로 인해 문제가 발생할 수 있습니다:

• 만약 마이그레이션이 이전 릴리스에서 필수 중단 이후에 도입된 새로운 타임스탬프가 있는 다른 마이그레이션에 의존한다면, 새로운 마이그레이션은 선행 마이그레이션보다 빨리 순차 실행될 수 있고, 이에 따라 실패할 수 있음.

• 만약 마이그레이션 타임스탬프 ID가 마지막 타임스탬프 이전에 있는 경우, 팀이 필수 중단에서 다른 마이그레이션을 스퀴시할 때 무심코 스퀴시될 수 있음.

• 원인: 마이그레이션이 이전 버전에서 소개된 이 후의 타임스탬프를 가진 마이그레이션에 의존하는 경우 실패할 수 있음. 또한 마이그레이션은 필수 중단 이후로 무심코 스퀴시될 수 있음.
• 완화 방안: 마이그레이션 타임스탬프가 릴리즈 날짜에 속하고, 마지막 필수 중단 이전으로 날짜가 지정되지 않도록 하세요.

마이그레이션 관련 도구의 버그

일부 경우에는 마이그레이션 관련 도구의 버그로 인해 중단을 도입할 필요가 있었습니다. 테스트에서 이를 방지하려고 노력하지만, 때로는 발생합니다.

• 원인: 우리는 이러한 문제를 너무 늦게 알아채게 된 경우가 있었습니다.
• 완화 방안: 보통 우리는 마이그레이션용 수정 사항을 되돌리려고 노력하지만, 경우에 따라 가능하지 않을 수 있습니다.

필수 중단이 릴리스되기 전

알려진 필수 중단을 릴리스하기 전에 다음 단계를 완료하세요. 필수 중단이 릴리스 후에 식별되는 경우에도 다음 단계는 여전히 완료되어야 합니다:

1. 업그레이드 경로를 업데이트하여 새로운 필수 중단을 포함시키세요.
2. 변경 사항을 고객 지원 및 릴리스 관리 팀과 공유하세요.

3. 데이터베이스 그룹에 해당 버전의 마이그레이션을 스퀴시하기 위한 이슈를 등록하세요. 다음 템플릿을 사용하세요:

   제목: `Squash migrations to <필수 중단 버전>`
   <필수 중단 버전>을 추가한 결과로 해당 버전까지 마이그레이션을 스퀴시하고, 최소 스키마 버전을 업데이트해야합니다.
      
   결과물:
   - [ ] <필수 중단 버전>까지 마이그레이션이 스퀴시됨
   - [ ] `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. lib/gitlab/database.rb의 Gitlab::Database::MIN_SCHEMA_GITLAB_VERSION을 새로운 필수 중단 버전으로 업데이트하세요. Gitlab::Database::MIN_SCHEMA_VERSION을 변경하지 마세요.
2. charts 프로젝트에서 업그레이드 확인 후크를 필수 중단 버전으로 업데이트하세요.
3. omnibus-gitlab 프로젝트에서 설치 전 버전 확인을 필수 중단 버전으로 업데이트하세요.