InfoGrab DocsInfoGrab Docs

Ruby 업그레이드 가이드라인

요약

성능 및 보안 업데이트와 새로운 Ruby API의 혜택을 누리기 위해 GitLab은 최신 Ruby MRI 릴리즈를 사용하는 것을 목표로 합니다. 기여자들에게 최소한의 혼란을 야기해야 합니다. GitLab.com 가용성을 최적화해야 합니다.

성능 및 보안 업데이트와 새로운 Ruby API의 혜택을 누리기 위해 GitLab은 최신 Ruby MRI 릴리즈를 사용하는 것을 목표로 합니다. GitLab 전체에서 Ruby를 업그레이드할 때는 다음 조건을 만족하는 방식으로 진행해야 합니다:

  • 기여자들에게 최소한의 혼란을 야기해야 합니다.

  • GitLab.com 가용성을 최적화해야 합니다.

  • GitLab의 모든 부분에서 Ruby 버전 일관성을 유지해야 합니다.

Ruby 버전 변경을 시작하기 전에 이 문서를 주의 깊게 처음부터 끝까지 읽어 어떤 변경이 필요할 수 있는지 전반적인 이해를 얻으세요. Ruby 업그레이드는 이전 업그레이드와 조금씩 다를 수 있으므로, 문서화된 단계의 순서와 필요성을 각 상황에 맞게 평가하세요.

Ruby 업그레이드 범위#

Ruby를 업그레이드할 때 가장 먼저 고려해야 할 것은 범위입니다. 일반적으로 Ruby 업데이트가 발생해야 할 수 있는 다음 영역을 고려합니다:

  • 메인 GitLab Rails 리포지터리.

  • 보조 Ruby 시스템 리포지터리.

  • 이러한 리포지터리의 시스템에서 사용하는 서드파티 라이브러리.

  • 이러한 리포지터리의 시스템에서 사용하는 GitLab 라이브러리.

항상 이 모두를 다룰 필요는 없습니다. 예를 들어, 패치 수준 Ruby 업데이트는 서드파티 gem 업데이트가 필요하지 않을 수 있습니다.

패치, 마이너, 메이저 업그레이드#

범위를 평가할 때 Ruby 버전 수준이 중요합니다. 예를 들어, 패치 릴리즈는 일반적으로 보안 또는 버그 수정으로 제한되므로, GitLab을 Ruby 2.7.2에서 2.7.4로 업그레이드하는 것보다 Ruby 2.x에서 3.x로 업그레이드하는 것이 더 어렵고 위험합니다. 업그레이드를 준비할 때 이 점을 인지하고 그에 따라 계획을 세우세요.

향후 업그레이드의 범위를 예측하는 데 도움이 되도록 다음 업그레이드에 필요한 노력을 참고하세요:

영향을 받는 대상 및 타깃#

업그레이드 전에 Ruby 업그레이드의 영향을 즉각적으로 받는 순서에 따라 모든 대상과 타깃을 고려하세요:

  • 개발자. 회사 내외부에 GitLab 및 관련 프로젝트의 많은 기여자가 있습니다. .ruby-version과 같은 파일을 변경하면 이러한 파일을 해석하는 도구를 사용하는 모든 사람에게 영향을 줍니다. 개발자는 병합된 변경 사항이 포함된 리포지터리를 pull하는 즉시 영향을 받습니다.

  • GitLab CI/CD. 코드 통합 및 테스트에 CI/CD를 많이 활용합니다. CI/CD job은 .ruby-version과 같은 파일을 해석하지 않습니다. 대신 .gitlab-ci.yml에 정의된 Docker 컨테이너에 설치된 Ruby를 사용합니다. 이 job에서 사용하는 컨테이너 이미지는 gitlab-build-images 리포지터리에서 관리됩니다. 이미지 업데이트를 병합하면 이미지가 빌드되는 즉시 CI/CD job에 영향이 미칩니다.

  • GitLab.com. GitLab.com은 Cloud Native GitLab (CNG)의 Docker 이미지를 사용하는 커스터마이즈된 Helm 차트로 배포됩니다. CI/CD와 마찬가지로 이 환경에서는 .ruby-version이 의미 없습니다. 대신 Ruby를 업그레이드하려면 해당 Docker 이미지를 패치해야 합니다. GitLab.com은 다음 배포 시 영향을 받습니다.

  • GitLab Self-Managed. Omnibus를 통해 GitLab을 설치하는 고객은 위의 것들을 사용하지 않습니다. 대신 Ruby 버전은 Omnibus의 Ruby 소프트웨어 번들에 의해 정의됩니다. GitLab Self-Managed 고객은 이 변경 사항이 포함된 릴리즈로 업그레이드하는 즉시 영향을 받습니다.

Ruby 업그레이드 접근 방식#

Ruby 업그레이드의 모든 단계를 올바른 타이밍에 수행하는 것이 중요합니다. 일반적인 가이드라인으로 다음을 고려하세요:

  • 프로덕션 동작이 변경될 가능성이 낮은 소규모 업그레이드의 경우, 리포지터리와 프로덕션 간의 버전 격차를 최소화하는 것을 목표로 하세요. 이해관계자들과 조율하여 드리프트를 방지하기 위해 모든 변경 사항을 가까이 (하루나 이틀 이내에) 병합하세요. 이 시나리오에서는 개발자 도구 및 환경을 먼저 업그레이드한 후 프로덕션을 업그레이드하는 순서가 적합합니다.

  • 대규모 변경의 경우, 새로운 Ruby를 프로덕션에 적용하는 리스크가 큽니다. 이 경우 새로운 Ruby 버전의 알려진 비호환성을 모두 수정한 후, 프로덕션 엔지니어들과 협력하여 GitLab 프로덕션 플릿의 일부에 새로운 Ruby를 배포하세요. 이 시나리오에서는 먼저 프로덕션을 업데이트한 후 개발자 도구 및 환경을 업데이트하는 순서가 적합합니다. 이렇게 하면 프로덕션에서 심각한 회귀가 발생했을 때 롤백이 더 쉬워집니다.

어느 쪽이든 과거 경험에서 다음 접근 방식이 잘 작동하는 것으로 확인되었으며, 일부 단계는 마이너 및 메이저 업그레이드에서만 필요할 수 있습니다. 일부 단계는 병렬로 진행하거나 위에 설명된 대로 순서를 변경할 수 있습니다.

에픽 생성#

이 작업을 에픽에서 추적하면 진행 상황을 파악하는 데 유용합니다. 더 큰 업그레이드의 경우 이해관계자들이 최종 전환이 언제 적용될 예정인지 알 수 있도록 에픽 설명에 타임라인을 포함하세요. 업그레이드의 성능 기준 충족을 돕기 위해 지정된 성능 테스트 템플릿을 포함하세요.

개별 리포지터리에 대한 변경 사항은 이 에픽 아래 별도의 이슈로 분리하세요.

업그레이드 의사 전달#

특히 기능을 도입하거나 지원 중단하는 업그레이드의 경우, 가능하면 관련 타임라인과 함께 업그레이드가 예정되어 있음을 일찍 알리세요. 개발자들이 미리 변경 사항에 익숙해질 수 있도록 중요하거나 주목할 만한 변경 사항에 대한 링크를 제공하세요.

GitLab 팀원은 관련 Slack 채널 (최소 #backend 및 #development)과 Engineering Week In Review (EWIR)에서 의사를 발표해야 합니다. 커뮤니케이션에 업그레이드 에픽 링크를 포함하세요.

CI/CD 및 개발 환경에 새 Ruby 추가#

새로운 Ruby로 Ruby gem과 GitLab Rails 애플리케이션을 빌드하고 실행하려면 먼저 새 Ruby 버전을 포함하도록 CI/CD 및 개발자 환경을 준비해야 합니다. 이 단계에서는 아직 기본 Ruby로 설정해서는 안 되며 대신 선택 사항으로 만들어야 합니다. 이렇게 하면 일정 기간 동안 이전 Ruby와 새 Ruby 버전을 모두 지원하여 더 원활한 전환이 가능합니다.

변경이 필요한 두 가지 장소가 있습니다:

  • GitLab Build Images. 러너 및 기타 Docker 기반 사전 프로덕션 환경에 사용하는 Docker 이미지입니다. 필요한 변경 유형은 범위에 따라 다릅니다.

패치 수준 업데이트의 경우 RUBY_VERSION의 패치 수준을 증가시키는 것으로 충분합니다. 동일한 마이너 릴리즈에 대해 빌드하는 모든 프로젝트는 자동으로 새 패치 릴리즈를 다운로드합니다.

  • 메이저 및 마이너 업데이트의 경우 업그레이드 프로세스 중에 기존 이미지와 나란히 사용할 수 있는 새 Docker 이미지 세트를 생성합니다. 중요: /patches 디렉터리의 모든 Ruby 패치 파일을 업그레이드할 Ruby 버전에 맞는 새 폴더로 복사해야 합니다. 그렇지 않으면 적용되지 않습니다.

  • GitLab Development Kit (GDK). 개발자가 선택할 수 있는 추가 옵션으로 새 Ruby를 추가하도록 GDK를 업데이트합니다. 이는 일반적으로 asdf 사용자가 혜택을 누릴 수 있도록 .tool-versions에 추가하는 것만 필요합니다. 다른 사용자는 수동으로 설치해야 합니다 (예시.)

더 큰 버전 업그레이드의 경우 Quality Engineering과 협력하여 테스트 계획을 식별하고 설정하는 것을 고려하세요.

서드파티 gem 업데이트#

패치 릴리즈의 경우 이 작업이 필요하지 않을 수 있지만, 마이너 및 메이저 릴리즈의 경우 gem이 특정 버전의 Ruby를 고정(pin)할 때 breaking 변경이나 Bundler 의존성 문제가 발생할 수 있습니다. 이를 확인하는 좋은 방법은 gitlab-org/gitlab에서 머지 리퀘스트를 생성하고 무엇이 깨지는지 확인하는 것입니다.

GitLab gem 및 관련 시스템 업데이트#

이는 일반적으로 필요합니다. 우리가 직접 관리하는 gem 또는 Ruby 애플리케이션에는 .ruby-version, .tool-versions, .gitlab-ci.yml 파일과 같은 빌드 설정이 포함되어 있기 때문입니다. GitLab Rails 애플리케이션이 새 Ruby와 작동하기 위해 기술적으로 이 리포지터리들을 업데이트할 필요가 항상 있는 것은 아니지만, 모든 리포지터리에서 Ruby 버전을 일관되게 유지하는 것이 좋은 관행입니다. 마이너 및 메이저 업그레이드의 경우 새 Ruby를 사용하는 새 CI/CD job을 이 리포지터리에 추가하세요. 빌드 매트릭스 정의를 사용하면 이를 효율적으로 수행할 수 있습니다.

업데이트할 리포지터리 결정#

Ruby를 업그레이드할 때 ruby/gems 그룹의 리포지터리도 업데이트하는 것을 고려하세요. 참고로 다음은 과거에 이 프로젝트들 중 일부의 Ruby를 업데이트한 머지 리퀘스트 목록입니다:

이 리포지터리들 중 메인 GitLab 애플리케이션과 함께 업데이트하는 것이 중요한 리포지터리를 평가하려면 다음을 고려하세요:

  • Ruby 버전 범위.

  • GitLab 전체 기능에서 서비스 또는 라이브러리가 수행하는 역할.

영향을 받을 수 있는 리포지터리의 전체 목록은 GitLab 프로젝트 목록을 참조하세요. 소규모 버전 업그레이드의 경우, 필수적이지 않거나 메인 애플리케이션 테스트 스위트가 새 Ruby 버전에서 회귀를 잡아낼 것이 확실한 라이브러리의 업데이트를 지연하는 것도 허용될 수 있습니다.

각 코드 소유자와 GitLab 애플리케이션을 업데이트하기 전에 이러한 변경 사항을 먼저 병합하는 것이 허용 가능한지 협의하세요. 필요한 승인을 받되 모든 것이 준비될 때까지 변경 사항 병합을 기다리는 것이 최선일 수 있습니다.

GitLab 애플리케이션 머지 리퀘스트 준비#

의존성이 업데이트되고 새 gem 버전이 릴리즈되면, gem 및 관련 시스템과 유사하게 필요한 변경 사항으로 메인 Rails 애플리케이션을 업데이트할 수 있습니다. 그 외에도 설치 및 업데이트 지침에 버전 변경을 반영하도록 문서를 업데이트하세요 (예시).

이 머지 리퀘스트를 병합하는 타이밍에 특히 주의하세요. 병합되는 즉시 모든 GitLab 기여자들이 영향을 받고 변경 사항이 배포됩니다. 모든 것이 준비될 때까지 이 머지 리퀘스트를 열어 두어야 하지만, 리드 타임을 줄이기 위해 일찍 승인을 받는 것이 유용할 수 있습니다.

개발자에게 업그레이드 시간 제공 (유예 기간)#

새 Ruby가 옵션으로 제공되고 모든 머지 리퀘스트가 준비되었거나 병합된 상태에서, 개발자들이 자신의 머신에 새 Ruby를 설치할 수 있는 유예 기간 (최소 1주)이 있어야 합니다. GDK 및 asdf 사용자의 경우 gdk update를 통해 자동으로 업데이트가 이루어집니다.

이 일시 정지 기간은 GitLab.com에 대한 이 업그레이드의 리스크를 평가할 좋은 시간입니다. 메이저 버전 업그레이드와 같이 리스크가 높은 Ruby 업그레이드의 경우, 변경 관리 요청을 통해 인프라 팀과 변경 사항을 조율하는 것을 권장합니다. 모든 사람이 변경 사항을 일정에 맞추고 준비할 충분한 시간을 제공하기 위해 이 이슈를 일찍 생성하세요.

기본 Ruby로 설정#

알려진 버전 호환성 문제가 없고 유예 기간이 지나면, 영향받는 모든 리포지터리와 개발자 도구를 새 Ruby를 기본으로 사용하도록 업데이트해야 합니다.

이 시점에서 GitLab Compose Kit (GCK)을 업데이트하세요. 이는 docker-compose에서 GitLab을 실행하는 것을 선호하는 사용자를 위한 대안 개발 환경입니다. 이 프로젝트는 러너와 동일한 Docker 이미지에 의존하므로 해당 리포지터리의 변경 사항과 동기화를 유지해야 합니다. 이 변경은 마이너 또는 메이저 버전이 변경될 때만 필요합니다 (예시.)

위에서 언급했듯이, SaaS 가용성에 대한 Ruby 업그레이드의 영향이 불확실하다면, 단계적 롤아웃을 통해 프로덕션에서 원활하게 실행됨을 확인할 때까지 이 단계를 건너뛰는 것이 신중합니다. 이 경우 먼저 다음 단계로 이동하고, 검증 기간이 지난 후 새 Ruby를 새 기본값으로 승격하세요.

CNG, Omnibus, Self-compiled 업데이트 및 GitLab 머지 리퀘스트 병합#

마지막 단계는 프로덕션에서 새 Ruby를 사용하는 것입니다. 이를 위해서는 Omnibus와 프로덕션 Docker 이미지를 새 버전을 사용하도록 업데이트해야 합니다.

프로덕션에서 새 Ruby를 사용하려면 다음 프로젝트를 업데이트하세요:

GitLab Helm Chart와 같은 차트도 Ruby를 어떤 방식으로든 사용하는 경우 업데이트해야 합니다. 예를 들어 테스트 실행 시 (이 예시 참조), 엄밀히 필요하지 않을 수도 있습니다.

변경 관리 요청을 제출하는 경우 인프라 엔지니어들과 롤아웃을 조율하세요. 대규모 업그레이드를 처리할 때는 롤아웃 계획에 릴리즈 매니저를 참여시키세요.

보안 패치를 위한 패치 릴리즈 및 백포트 생성#

업그레이드가 패치 릴리즈이고 중요한 보안 수정 사항이 포함된 경우, Self-managed 고객을 위한 GitLab 패치 릴리즈로 배포해야 합니다. 진행 방법에 대해서는 릴리즈 매니저에게 문의하세요.

Ruby 업그레이드 도구#

업그레이드 프로세스를 용이하게 하는 여러 도구가 있습니다.

Deprecation Logger#

Ruby 및 Rails 지원 중단 경고를 전용 로그 파일 log/deprecation_json.log에 기록합니다 (GitLab 로그 파일의 위치는 GitLab 개발자 로깅 가이드 참조). 이는 테스트로 충분히 커버되지 않는 코드가 있을 때 단서를 제공할 수 있습니다.

GitLab.com의 경우 GitLab 팀원은 Kibana에서 이 로그 이벤트를 검사할 수 있습니다 (https://log.gprd.gitlab.net/goto/f7cebf1ff05038d901ba2c45925c7e01).

권장 사항#

업그레이드 프로세스 중에 다음 권장 사항을 고려하세요:

  • 가능한 한 많은 변경 사항을 사전에 처리하세요. 특히 마이너 및 메이저 릴리즈의 경우 애플리케이션 코드가 깨지거나 변경될 가능성이 있습니다. 하위 호환성이 있는 모든 변경 사항은 Ruby 버전 업그레이드보다 먼저 메인 브랜치에 병합되어 독립적으로 릴리즈되어야 합니다. 이렇게 하면 작은 단위로 진행하고 프로덕션 환경에서 일찍 피드백을 받을 수 있습니다.

  • 대규모 업데이트를 위한 실험 브랜치를 생성하세요. 일반적으로 장기 실행 토픽 브랜치를 피하려고 하지만, 피드백과 실험을 목적으로 이러한 브랜치를 두어 새로운 Ruby를 실행할 때 CI/CD로부터 정기적인 피드백을 받는 것이 유용할 수 있습니다. 어떤 문제를 겪을 수 있는지 처음 평가할 때 도움이 될 수 있으며, 이 머지 리퀘스트가 이를 보여줍니다. 이러한 실험 브랜치는 병합되는 것이 아니라, 필요한 모든 변경 사항이 분리되어 독립적으로 병합되면 닫힐 수 있습니다.

  • 마일스톤 릴리즈 전에 문제를 수정할 충분한 시간을 확보하세요. GitLab은 빠르게 움직입니다. Ruby 업그레이드는 많은 머지 리퀘스트를 전송하고 검토해야 하므로, 릴리즈일 최소 1주 전에 모든 변경 사항이 병합되도록 하세요. 이렇게 하면 무언가 깨졌을 때 대처할 추가 시간이 생깁니다. 확신이 없다면 가용성을 속도보다 우선시하므로 업그레이드를 다음 달로 연기하는 것이 더 나을 수 있습니다.

Ruby 업그레이드 가이드라인

GitLab v19.1
원문 보기
요약

성능 및 보안 업데이트와 새로운 Ruby API의 혜택을 누리기 위해 GitLab은 최신 Ruby MRI 릴리즈를 사용하는 것을 목표로 합니다. 기여자들에게 최소한의 혼란을 야기해야 합니다. GitLab.com 가용성을 최적화해야 합니다.

성능 및 보안 업데이트와 새로운 Ruby API의 혜택을 누리기 위해 GitLab은 최신 Ruby MRI 릴리즈를 사용하는 것을 목표로 합니다. GitLab 전체에서 Ruby를 업그레이드할 때는 다음 조건을 만족하는 방식으로 진행해야 합니다:

  • 기여자들에게 최소한의 혼란을 야기해야 합니다.

  • GitLab.com 가용성을 최적화해야 합니다.

  • GitLab의 모든 부분에서 Ruby 버전 일관성을 유지해야 합니다.

Ruby 버전 변경을 시작하기 전에 이 문서를 주의 깊게 처음부터 끝까지 읽어 어떤 변경이 필요할 수 있는지 전반적인 이해를 얻으세요. Ruby 업그레이드는 이전 업그레이드와 조금씩 다를 수 있으므로, 문서화된 단계의 순서와 필요성을 각 상황에 맞게 평가하세요.

Ruby 업그레이드 범위#

Ruby를 업그레이드할 때 가장 먼저 고려해야 할 것은 범위입니다. 일반적으로 Ruby 업데이트가 발생해야 할 수 있는 다음 영역을 고려합니다:

  • 메인 GitLab Rails 리포지터리.

  • 보조 Ruby 시스템 리포지터리.

  • 이러한 리포지터리의 시스템에서 사용하는 서드파티 라이브러리.

  • 이러한 리포지터리의 시스템에서 사용하는 GitLab 라이브러리.

항상 이 모두를 다룰 필요는 없습니다. 예를 들어, 패치 수준 Ruby 업데이트는 서드파티 gem 업데이트가 필요하지 않을 수 있습니다.

패치, 마이너, 메이저 업그레이드#

범위를 평가할 때 Ruby 버전 수준이 중요합니다. 예를 들어, 패치 릴리즈는 일반적으로 보안 또는 버그 수정으로 제한되므로, GitLab을 Ruby 2.7.2에서 2.7.4로 업그레이드하는 것보다 Ruby 2.x에서 3.x로 업그레이드하는 것이 더 어렵고 위험합니다. 업그레이드를 준비할 때 이 점을 인지하고 그에 따라 계획을 세우세요.

향후 업그레이드의 범위를 예측하는 데 도움이 되도록 다음 업그레이드에 필요한 노력을 참고하세요:

영향을 받는 대상 및 타깃#

업그레이드 전에 Ruby 업그레이드의 영향을 즉각적으로 받는 순서에 따라 모든 대상과 타깃을 고려하세요:

  • 개발자. 회사 내외부에 GitLab 및 관련 프로젝트의 많은 기여자가 있습니다. .ruby-version과 같은 파일을 변경하면 이러한 파일을 해석하는 도구를 사용하는 모든 사람에게 영향을 줍니다. 개발자는 병합된 변경 사항이 포함된 리포지터리를 pull하는 즉시 영향을 받습니다.

  • GitLab CI/CD. 코드 통합 및 테스트에 CI/CD를 많이 활용합니다. CI/CD job은 .ruby-version과 같은 파일을 해석하지 않습니다. 대신 .gitlab-ci.yml에 정의된 Docker 컨테이너에 설치된 Ruby를 사용합니다. 이 job에서 사용하는 컨테이너 이미지는 gitlab-build-images 리포지터리에서 관리됩니다. 이미지 업데이트를 병합하면 이미지가 빌드되는 즉시 CI/CD job에 영향이 미칩니다.

  • GitLab.com. GitLab.com은 Cloud Native GitLab (CNG)의 Docker 이미지를 사용하는 커스터마이즈된 Helm 차트로 배포됩니다. CI/CD와 마찬가지로 이 환경에서는 .ruby-version이 의미 없습니다. 대신 Ruby를 업그레이드하려면 해당 Docker 이미지를 패치해야 합니다. GitLab.com은 다음 배포 시 영향을 받습니다.

  • GitLab Self-Managed. Omnibus를 통해 GitLab을 설치하는 고객은 위의 것들을 사용하지 않습니다. 대신 Ruby 버전은 Omnibus의 Ruby 소프트웨어 번들에 의해 정의됩니다. GitLab Self-Managed 고객은 이 변경 사항이 포함된 릴리즈로 업그레이드하는 즉시 영향을 받습니다.

Ruby 업그레이드 접근 방식#

Ruby 업그레이드의 모든 단계를 올바른 타이밍에 수행하는 것이 중요합니다. 일반적인 가이드라인으로 다음을 고려하세요:

  • 프로덕션 동작이 변경될 가능성이 낮은 소규모 업그레이드의 경우, 리포지터리와 프로덕션 간의 버전 격차를 최소화하는 것을 목표로 하세요. 이해관계자들과 조율하여 드리프트를 방지하기 위해 모든 변경 사항을 가까이 (하루나 이틀 이내에) 병합하세요. 이 시나리오에서는 개발자 도구 및 환경을 먼저 업그레이드한 후 프로덕션을 업그레이드하는 순서가 적합합니다.

  • 대규모 변경의 경우, 새로운 Ruby를 프로덕션에 적용하는 리스크가 큽니다. 이 경우 새로운 Ruby 버전의 알려진 비호환성을 모두 수정한 후, 프로덕션 엔지니어들과 협력하여 GitLab 프로덕션 플릿의 일부에 새로운 Ruby를 배포하세요. 이 시나리오에서는 먼저 프로덕션을 업데이트한 후 개발자 도구 및 환경을 업데이트하는 순서가 적합합니다. 이렇게 하면 프로덕션에서 심각한 회귀가 발생했을 때 롤백이 더 쉬워집니다.

어느 쪽이든 과거 경험에서 다음 접근 방식이 잘 작동하는 것으로 확인되었으며, 일부 단계는 마이너 및 메이저 업그레이드에서만 필요할 수 있습니다. 일부 단계는 병렬로 진행하거나 위에 설명된 대로 순서를 변경할 수 있습니다.

에픽 생성#

이 작업을 에픽에서 추적하면 진행 상황을 파악하는 데 유용합니다. 더 큰 업그레이드의 경우 이해관계자들이 최종 전환이 언제 적용될 예정인지 알 수 있도록 에픽 설명에 타임라인을 포함하세요. 업그레이드의 성능 기준 충족을 돕기 위해 지정된 성능 테스트 템플릿을 포함하세요.

개별 리포지터리에 대한 변경 사항은 이 에픽 아래 별도의 이슈로 분리하세요.

업그레이드 의사 전달#

특히 기능을 도입하거나 지원 중단하는 업그레이드의 경우, 가능하면 관련 타임라인과 함께 업그레이드가 예정되어 있음을 일찍 알리세요. 개발자들이 미리 변경 사항에 익숙해질 수 있도록 중요하거나 주목할 만한 변경 사항에 대한 링크를 제공하세요.

GitLab 팀원은 관련 Slack 채널 (최소 #backend 및 #development)과 Engineering Week In Review (EWIR)에서 의사를 발표해야 합니다. 커뮤니케이션에 업그레이드 에픽 링크를 포함하세요.

CI/CD 및 개발 환경에 새 Ruby 추가#

새로운 Ruby로 Ruby gem과 GitLab Rails 애플리케이션을 빌드하고 실행하려면 먼저 새 Ruby 버전을 포함하도록 CI/CD 및 개발자 환경을 준비해야 합니다. 이 단계에서는 아직 기본 Ruby로 설정해서는 안 되며 대신 선택 사항으로 만들어야 합니다. 이렇게 하면 일정 기간 동안 이전 Ruby와 새 Ruby 버전을 모두 지원하여 더 원활한 전환이 가능합니다.

변경이 필요한 두 가지 장소가 있습니다:

  • GitLab Build Images. 러너 및 기타 Docker 기반 사전 프로덕션 환경에 사용하는 Docker 이미지입니다. 필요한 변경 유형은 범위에 따라 다릅니다.

패치 수준 업데이트의 경우 RUBY_VERSION의 패치 수준을 증가시키는 것으로 충분합니다. 동일한 마이너 릴리즈에 대해 빌드하는 모든 프로젝트는 자동으로 새 패치 릴리즈를 다운로드합니다.

  • 메이저 및 마이너 업데이트의 경우 업그레이드 프로세스 중에 기존 이미지와 나란히 사용할 수 있는 새 Docker 이미지 세트를 생성합니다. 중요: /patches 디렉터리의 모든 Ruby 패치 파일을 업그레이드할 Ruby 버전에 맞는 새 폴더로 복사해야 합니다. 그렇지 않으면 적용되지 않습니다.

  • GitLab Development Kit (GDK). 개발자가 선택할 수 있는 추가 옵션으로 새 Ruby를 추가하도록 GDK를 업데이트합니다. 이는 일반적으로 asdf 사용자가 혜택을 누릴 수 있도록 .tool-versions에 추가하는 것만 필요합니다. 다른 사용자는 수동으로 설치해야 합니다 (예시.)

더 큰 버전 업그레이드의 경우 Quality Engineering과 협력하여 테스트 계획을 식별하고 설정하는 것을 고려하세요.

서드파티 gem 업데이트#

패치 릴리즈의 경우 이 작업이 필요하지 않을 수 있지만, 마이너 및 메이저 릴리즈의 경우 gem이 특정 버전의 Ruby를 고정(pin)할 때 breaking 변경이나 Bundler 의존성 문제가 발생할 수 있습니다. 이를 확인하는 좋은 방법은 gitlab-org/gitlab에서 머지 리퀘스트를 생성하고 무엇이 깨지는지 확인하는 것입니다.

GitLab gem 및 관련 시스템 업데이트#

이는 일반적으로 필요합니다. 우리가 직접 관리하는 gem 또는 Ruby 애플리케이션에는 .ruby-version, .tool-versions, .gitlab-ci.yml 파일과 같은 빌드 설정이 포함되어 있기 때문입니다. GitLab Rails 애플리케이션이 새 Ruby와 작동하기 위해 기술적으로 이 리포지터리들을 업데이트할 필요가 항상 있는 것은 아니지만, 모든 리포지터리에서 Ruby 버전을 일관되게 유지하는 것이 좋은 관행입니다. 마이너 및 메이저 업그레이드의 경우 새 Ruby를 사용하는 새 CI/CD job을 이 리포지터리에 추가하세요. 빌드 매트릭스 정의를 사용하면 이를 효율적으로 수행할 수 있습니다.

업데이트할 리포지터리 결정#

Ruby를 업그레이드할 때 ruby/gems 그룹의 리포지터리도 업데이트하는 것을 고려하세요. 참고로 다음은 과거에 이 프로젝트들 중 일부의 Ruby를 업데이트한 머지 리퀘스트 목록입니다:

이 리포지터리들 중 메인 GitLab 애플리케이션과 함께 업데이트하는 것이 중요한 리포지터리를 평가하려면 다음을 고려하세요:

  • Ruby 버전 범위.

  • GitLab 전체 기능에서 서비스 또는 라이브러리가 수행하는 역할.

영향을 받을 수 있는 리포지터리의 전체 목록은 GitLab 프로젝트 목록을 참조하세요. 소규모 버전 업그레이드의 경우, 필수적이지 않거나 메인 애플리케이션 테스트 스위트가 새 Ruby 버전에서 회귀를 잡아낼 것이 확실한 라이브러리의 업데이트를 지연하는 것도 허용될 수 있습니다.

각 코드 소유자와 GitLab 애플리케이션을 업데이트하기 전에 이러한 변경 사항을 먼저 병합하는 것이 허용 가능한지 협의하세요. 필요한 승인을 받되 모든 것이 준비될 때까지 변경 사항 병합을 기다리는 것이 최선일 수 있습니다.

GitLab 애플리케이션 머지 리퀘스트 준비#

의존성이 업데이트되고 새 gem 버전이 릴리즈되면, gem 및 관련 시스템과 유사하게 필요한 변경 사항으로 메인 Rails 애플리케이션을 업데이트할 수 있습니다. 그 외에도 설치 및 업데이트 지침에 버전 변경을 반영하도록 문서를 업데이트하세요 (예시).

이 머지 리퀘스트를 병합하는 타이밍에 특히 주의하세요. 병합되는 즉시 모든 GitLab 기여자들이 영향을 받고 변경 사항이 배포됩니다. 모든 것이 준비될 때까지 이 머지 리퀘스트를 열어 두어야 하지만, 리드 타임을 줄이기 위해 일찍 승인을 받는 것이 유용할 수 있습니다.

개발자에게 업그레이드 시간 제공 (유예 기간)#

새 Ruby가 옵션으로 제공되고 모든 머지 리퀘스트가 준비되었거나 병합된 상태에서, 개발자들이 자신의 머신에 새 Ruby를 설치할 수 있는 유예 기간 (최소 1주)이 있어야 합니다. GDK 및 asdf 사용자의 경우 gdk update를 통해 자동으로 업데이트가 이루어집니다.

이 일시 정지 기간은 GitLab.com에 대한 이 업그레이드의 리스크를 평가할 좋은 시간입니다. 메이저 버전 업그레이드와 같이 리스크가 높은 Ruby 업그레이드의 경우, 변경 관리 요청을 통해 인프라 팀과 변경 사항을 조율하는 것을 권장합니다. 모든 사람이 변경 사항을 일정에 맞추고 준비할 충분한 시간을 제공하기 위해 이 이슈를 일찍 생성하세요.

기본 Ruby로 설정#

알려진 버전 호환성 문제가 없고 유예 기간이 지나면, 영향받는 모든 리포지터리와 개발자 도구를 새 Ruby를 기본으로 사용하도록 업데이트해야 합니다.

이 시점에서 GitLab Compose Kit (GCK)을 업데이트하세요. 이는 docker-compose에서 GitLab을 실행하는 것을 선호하는 사용자를 위한 대안 개발 환경입니다. 이 프로젝트는 러너와 동일한 Docker 이미지에 의존하므로 해당 리포지터리의 변경 사항과 동기화를 유지해야 합니다. 이 변경은 마이너 또는 메이저 버전이 변경될 때만 필요합니다 (예시.)

위에서 언급했듯이, SaaS 가용성에 대한 Ruby 업그레이드의 영향이 불확실하다면, 단계적 롤아웃을 통해 프로덕션에서 원활하게 실행됨을 확인할 때까지 이 단계를 건너뛰는 것이 신중합니다. 이 경우 먼저 다음 단계로 이동하고, 검증 기간이 지난 후 새 Ruby를 새 기본값으로 승격하세요.

CNG, Omnibus, Self-compiled 업데이트 및 GitLab 머지 리퀘스트 병합#

마지막 단계는 프로덕션에서 새 Ruby를 사용하는 것입니다. 이를 위해서는 Omnibus와 프로덕션 Docker 이미지를 새 버전을 사용하도록 업데이트해야 합니다.

프로덕션에서 새 Ruby를 사용하려면 다음 프로젝트를 업데이트하세요:

GitLab Helm Chart와 같은 차트도 Ruby를 어떤 방식으로든 사용하는 경우 업데이트해야 합니다. 예를 들어 테스트 실행 시 (이 예시 참조), 엄밀히 필요하지 않을 수도 있습니다.

변경 관리 요청을 제출하는 경우 인프라 엔지니어들과 롤아웃을 조율하세요. 대규모 업그레이드를 처리할 때는 롤아웃 계획에 릴리즈 매니저를 참여시키세요.

보안 패치를 위한 패치 릴리즈 및 백포트 생성#

업그레이드가 패치 릴리즈이고 중요한 보안 수정 사항이 포함된 경우, Self-managed 고객을 위한 GitLab 패치 릴리즈로 배포해야 합니다. 진행 방법에 대해서는 릴리즈 매니저에게 문의하세요.

Ruby 업그레이드 도구#

업그레이드 프로세스를 용이하게 하는 여러 도구가 있습니다.

Deprecation Logger#

Ruby 및 Rails 지원 중단 경고를 전용 로그 파일 log/deprecation_json.log에 기록합니다 (GitLab 로그 파일의 위치는 GitLab 개발자 로깅 가이드 참조). 이는 테스트로 충분히 커버되지 않는 코드가 있을 때 단서를 제공할 수 있습니다.

GitLab.com의 경우 GitLab 팀원은 Kibana에서 이 로그 이벤트를 검사할 수 있습니다 (https://log.gprd.gitlab.net/goto/f7cebf1ff05038d901ba2c45925c7e01).

권장 사항#

업그레이드 프로세스 중에 다음 권장 사항을 고려하세요:

  • 가능한 한 많은 변경 사항을 사전에 처리하세요. 특히 마이너 및 메이저 릴리즈의 경우 애플리케이션 코드가 깨지거나 변경될 가능성이 있습니다. 하위 호환성이 있는 모든 변경 사항은 Ruby 버전 업그레이드보다 먼저 메인 브랜치에 병합되어 독립적으로 릴리즈되어야 합니다. 이렇게 하면 작은 단위로 진행하고 프로덕션 환경에서 일찍 피드백을 받을 수 있습니다.

  • 대규모 업데이트를 위한 실험 브랜치를 생성하세요. 일반적으로 장기 실행 토픽 브랜치를 피하려고 하지만, 피드백과 실험을 목적으로 이러한 브랜치를 두어 새로운 Ruby를 실행할 때 CI/CD로부터 정기적인 피드백을 받는 것이 유용할 수 있습니다. 어떤 문제를 겪을 수 있는지 처음 평가할 때 도움이 될 수 있으며, 이 머지 리퀘스트가 이를 보여줍니다. 이러한 실험 브랜치는 병합되는 것이 아니라, 필요한 모든 변경 사항이 분리되어 독립적으로 병합되면 닫힐 수 있습니다.

  • 마일스톤 릴리즈 전에 문제를 수정할 충분한 시간을 확보하세요. GitLab은 빠르게 움직입니다. Ruby 업그레이드는 많은 머지 리퀘스트를 전송하고 검토해야 하므로, 릴리즈일 최소 1주 전에 모든 변경 사항이 병합되도록 하세요. 이렇게 하면 무언가 깨졌을 때 대처할 추가 시간이 생깁니다. 확신이 없다면 가용성을 속도보다 우선시하므로 업그레이드를 다음 달로 연기하는 것이 더 나을 수 있습니다.