Ruby 업그레이드 지침

우리는 성능 및 보안 업데이트 및 새로운 Ruby API의 이점을 얻기 위해 최신 Ruby MRI 릴리스를 사용하여 GitLab를 실행하려고 노력합니다. GitLab 전체에서 Ruby를 업그레이드할 때 다음과 같은 방식으로 진행해야 합니다.

기여자에게 가장 방해가 되지 않는 방식으로 진행합니다.
GitLab SaaS의 가용성을 최적화합니다.
GitLab의 모든 부분에서 Ruby 버전의 동등성을 유지합니다.

Ruby 버전에 변경을 가하기 전에, 이 문서를 주의 깊게 읽어 전체적인 변경 내용을 파악합니다. 아마도 매번 Ruby를 업그레이드할 때마다 약간씩 다른 점이 있을 것이므로 문서화된 단계들의 순서와 필요성을 평가합니다.

Ruby 업그레이드의 범위

Ruby를 업그레이드할 때 고려해야 할 첫 번째 사항은 범위입니다. 일반적으로 Ruby 업데이트가 발생할 수 있는 다음 영역을 고려합니다.

주요 GitLab 레일즈 저장소.
기타 Ruby 시스템 저장소.
이러한 저장소의 시스템에서 사용되는 타사 라이브러리.
이러한 저장소의 시스템에서 사용되는 GitLab 라이브러리.

이들 모두를 수정할 필요는 없을 수도 있습니다. 예를 들어, 패치 수준의 Ruby 업데이트는 타사 젬에서의 업데이트를 요구하지 않을 것입니다.

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

범위를 평가할 때 Ruby 버전 수준이 중요합니다. 예를 들어, Ruby 2.x에서 3.x로 GitLab를 업그레이드하는 것은 Ruby 2.7.2에서 2.7.4로 업그레이드하는 것보다 어렵고 위험합니다. 왜냐하면 패치 릴리스는 일반적으로 보안 또는 버그 수정에 제한되기 때문입니다. 업그레이드를 준비할 때 이를 고려하고 그에 따라 계획합니다.

미래 업그레이드의 범위를 추정하는 데 도움이 되도록 다음 업그레이드에 필요한 노력을 확인해보세요.

영향을 받는 대상 및 대상

어떠한 업그레이드 이전에, Ruby 업그레이드로 인해 어떻게 영향을 받을 지, 곧바로 영향을 받는 순서로 정렬하여 모든 대상을 고려합니다.

개발자. GitLab 및 관련 프로젝트에는 회사 내외부의 많은 기여자들이 있습니다. .ruby-version과 같은 파일을 해석하는 도구를 사용하는 모든 사용자에게 영향을 줍니다. 이러한 변경 내용이 병합된 저장소에서 정보를 가져오는 즉시, 개발자들은 영향을 받습니다.
GitLab CI/CD. 우리는 코드 통합 및 테스팅에 CI/CD를 많이 의존합니다. CI/CD 작업은 .ruby-version과 같은 파일을 해석하지 않습니다. 대신에, .gitlab-ci.yml에 정의된 Docker 컨테이너 내에 설치된 Ruby를 사용합니다. 이러한 작업에서 사용하는 컨테이너 이미지는 gitlab-build-images 저장소에서 유지됩니다. 이미지를 업데이트하면 CI/CD 작업은 이미지가 빌드됨과 동시에 영향을 받습니다.
GitLab SaaS. GitLab.com은 Cloud Native GitLab (CNG)에서 도커 이미지를 사용하는 사용자 정의 Helm 차트에서 배포됩니다. CI/CD와 마찬가지로, 이 환경에서는 .ruby-version이 무의미합니다. 대신, 이러한 도커 이미지는 Ruby를 업그레이드하기 위해 패치되어야 합니다. GitLab SaaS는 다음 배포에서 영향을 받습니다.
자체 관리 GitLab. Omnibus를 통해 GitLab을 설치하는 고객은 위의 방법을 사용하지 않습니다. 대신, Ruby 버전은 Omnibus의 Ruby 소프트웨어 번들에 의해 정의됩니다. 자체 관리 고객은 이 변경 사항이 포함된 릴리스로 업그레이드하는 즉시 영향을 받습니다.

Ruby 업그레이드 방식

Ruby 업그레이드의 모든 단계를 올바르게 타이밍하는 것이 중요합니다. 일반적인 지침으로, 다음을 고려해 보세요.

프로덕션 동작이 변경될 가능성이 적은 더 작은 업그레이드의 경우, 저장소와 프로덕션 간의 버전 갭을 가능한 한 최소화하도록 노력하세요. 변경 사항을 가능한 한 가깝게(하루 혹은 이틀 내) 병합하도록 이해 관계자와 협력합니다. 이러한 시나리오에서는 개발자 도구 및 환경을 먼저 업그레이드하고 나서 프로덕션을 업그레이드하는 것이 타당한 순서입니다.
큰 변경 사항의 경우, 새로운 Ruby로 프로덕션에 이동하는 위험은 상당합니다. 이런 경우에는 이미 알려진 새로운 Ruby 버전과의 호환성 문제를 이미 해결한 상태로 만든 뒤, GitLab 프로덕션 일부에 새 Ruby를 배포하도록 드립니다. 이러한 시나리오에서는 프로덕션을 먼저 업데이트한 후, 개발자 도구 및 환경을 두 번째로 업데이트합니다. 이렇게 하면 프로덕션에서 중요한 회귀가 발생했을 경우 롤백을 쉽게 할 수 있습니다.

어떤 방식이든, 우리는 과거의 경험으로부터 다음 접근 방식이 잘 작동한다는 것을 발견했습니다. 일부 단계가 마이너 및 마이저 업그레이드에만 필요할 수 있음을 유의하세요. 일부 단계는 병렬로 진행되거나 상기된 것처럼 순서가 뒤바뀔 수 있음에 유의하세요.

에픽 생성

이 작업을 에픽으로 추적하는 것은 진행 상황을 파악하기에 유용합니다. 큰 업그레이드의 경우, 에픽 설명에 타임라인을 포함하여 이 전환의 최종 예상 시기를 이해 관계자에게 알립니다. 업그레이드를 위한 성능 테스트 템플릿을 포함하여 성능 표준을 보장하는 데 도움이 됩니다.

별개의 저장소로의 변경 사항을 에픽 아래의 개별 이슈로 나누어 처리합니다.

업그레이드 의도 통보

특히 기능을 도입하거나 폐기하는 업그레이드의 경우, 가능하면 업그레이드가 예정되어 있음을 미리 통보합니다. 중요하거나 주목할 만한 변경 사항에 대한 링크를 제공하여, 개발자들이 변경 내용에 미리 익숙해지도록 합니다.

GitLab 팀원들은 소통에서 업그레이드 에픽에 대한 링크를 포함하여 관련한 Slack 채널(#backend 및 #development 최소한)과 Engineering Week In Review (EWIR)에 업그레이드의 의도를 알리게 됩니다.

새로운 Ruby를 CI/CD 및 개발 환경에 추가하기

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

변경 사항이 필요한 두 곳이 있습니다:

GitLab Build Images. 이들은 러너 및 기타 Docker 기반 사전 프로덕션 환경에 사용되는 Docker 이미지입니다. 필요한 변경의 종류는 범위에 따라 다릅니다.
- 패치 레벨 업데이트의 경우 RUBY_VERSION의 패치 레벨을 증가시키면 됩니다. 동일한 마이너 릴리스에 대해 빌드하는 모든 프로젝트가 새 패치 릴리스를 자동으로 다운로드합니다.
- 메이저 및 마이너 업데이트의 경우 기존 이미지와 병행하여 사용할 수 있는 새로운 Docker 이미지 세트를 만듭니다. 중요: 업그레이드하는 루비 버전과 일치하는 새 폴더에 /patches 디렉토리의 모든 Ruby 패치 파일을 복사해야 합니다. 그렇지 않으면 이들이 적용되지 않습니다.
GitLab Development Kit (GDK). 개발자가 선택할 수 있는 새로운 Ruby를 추가 옵션으로 GDK를 업데이트합니다. 이는 보통 .tool-versions에 추가하는 것으로 asdf 사용자들은 여기서 혜택을 볼 수 있습니다. 다른 사용자들은 수동으로 설치해야 합니다 (예시.)

큰 버전 업그레이드의 경우, Quality Engineering와 함께 작업하여 테스트 계획을 식별 및 설정하는 것을 고려하십시오.

써드파티 젬 업데이트

패치 릴리스의 경우 이 작업은 드물게 필요할 수 있지만, 마이너 및 메이저 릴리스의 경우, 특정 버전의 Ruby를 사용하도록 젬을 고정하는 경우에는 호환성 문제나 Bundler 의존성 문제가 발생할 수 있습니다. 이에 대한 좋은 방법은 gitlab-org/gitlab에 병합 요청을 생성하고 무엇이 실패하는지 확인하는 것입니다.

GitLab 젬 및 관련 시스템 업데이트

이것은 일반적으로 필요합니다. 왜냐하면 우리가 유지하는 젬 또는 Ruby 애플리케이션에 .ruby-version, .tool-versions, 또는 .gitlab-ci.yml 파일과 같은 빌드 설정이 포함되어 있기 때문입니다. 새로운 Ruby와 작업하도록 이러한 저장소들을 업데이트할 기술적 필요성이 항상 존재하는 것은 아니지만, 우리의 모든 저장소에서 Ruby 버전을 항상 동일하게 유지하는 것이 좋은 실천 방법입니다. 메이저 및 마이너 업그레이드의 경우, 이러한 저장소에 새로운 Ruby를 사용하는 CI/CD 작업을 추가하세요. 빌드 매트릭스 정의를 통해 효율적으로 이 작업을 수행할 수 있습니다.

업데이트할 저장소 결정

Ruby를 업그레이드하는 경우, ruby/gems 그룹에 있는 저장소들을 업데이트하는 것을 고려하십시오. 참고로, 이전에 이러한 프로젝트 중 일부에 대해 Ruby가 업데이트된 병합 요청 목록은 다음과 같습니다:

이 저장소들 중 어떤 것을 GitLab 애플리케이션과 함께 업데이트해야 하는지 평가할 때 다음을 고려해야 합니다:

Ruby 버전 범위.
서비스 또는 라이브러리가 GitLab의 전반적인 기능에 어떤 역할을 하는지.

어떤 저장소들을 업데이트해야 하는지에 대한 완벽한 계층 구조는 참고용 GitLab projects 목록을 참조하십시오. 작은 버전 업그레이드의 경우, 비필수적이거나 새로운 Ruby 버전에서의 회귀를 주요 애플리케이션 테스트 스위트가 감지할 것으로 확신하는 경우 라이브러리를 업데이트를 지연시키는 것이 허용될 수 있습니다.

참고: GitLab 애플리케이션을 업데이트하기 전에 해당 코드 소유자들과 상의하십시오. 변경 사항을 병합하는 것이 수용 가능한지 여부에 대해 상의하는 것이 가장 좋습니다. 그러나 모든 것이 준비되기 전에 변경 사항을 병합하는 것을 기다리는 것이 최선일 수 있습니다.

GitLab 애플리케이션 MR 준비

모든 종속성을 업데이트하고 새로운 젬 버전을 릴리스한 후, 주요 Rails 애플리케이션을 변경해야 할 필요가 있습니다. 또한, 설치 및 업데이트 지침에 새로운 버전 변경 내용을 반영하도록 문서를 업데이트합니다 (예시).

참고: 이 병합 요청을 타이밍에 특히 조심해야 합니다. 왜냐하면 한 번 병합되면, 모든 GitLab 기여자들에게 영향을 미치고 변경 사항이 배포됩니다. 이 MR이 모든 준비가 될 때까지 열려 있도록 보장해야 하지만 앞서 승인을 받아 리드 타임을 줄이는 데에 유용할 수 있습니다.

개발자가 업그레이드할 시간 제공하기 (유효기간)

새로운 Ruby가 옵션으로 제공되며, 모든 병합 요청이 준비되었거나 병합된 상태이면, 개발자들이 자신의 기계에 새로운 Ruby를 설치할 수 있는 기간 (최소 1주일)이 있어야 합니다. GDK 및 asdf 사용자의 경우, 이 작업은 gdk update를 통해 자동으로 이루어져야 합니다.

이 시간은 GitLab SaaS의 업그레이드의 위험을 평가하기에 좋은 시간입니다. 주요 버전 업그레이드와 같은 높은 위험성을 갖는 Ruby 업그레이드의 경우, 변경 관리 요청을 통해 변경 사항을 인프라 팀과 조정하는 것이 좋습니다. 모두가 충분한 시간을 가지고 일정을 조정하고 변경을 준비할 수 있도록 조기에 이 문제를 생성하세요.

기본 Ruby로 만들기

알려진 버전 호환성 문제가 없다면, 유효기간이 지나면 모든 영향을 받는 저장소와 개발자 도구를 새로운 Ruby로 업데이트하여 기본값으로 설정해야 합니다.

이 시점에서 GitLab Compose Kit (GCK)을 업데이트하세요. 이는 docker-compose에서 GitLab을 실행하길 선호하는 사용자들을 위한 대체 개발 환경입니다. 이 프로젝트는 러너와 동일한 Docker 이미지를 사용하므로 해당 저장소의 변경 사항과 일치해야 합니다. 이 변경 사항은 주 버전 또는 부 버전 변경시에만 필요합니다 (예시.)

위에서 언급된 바와 같이, Ruby 업그레이드가 SaaS 가용성에 미치는 영향이 불확실하다면, 본 단계를 건너뛰고 운영 환경에서 원활하게 실행되는지 확인한 후에 새 Ruby를 새로운 기본값으로 승격시키는 것이 현명합니다.

CNG, Omnibus, Self-compiled 업데이트 및 GitLab MR 병합

마지막 단계는 새로운 Ruby를 운영 환경에서 사용하는 것입니다. 새로운 버전을 사용하기 위해 Omnibus 및 운영 Docker 이미지를 업데이트해야 합니다.

새로운 Ruby를 운영 환경에서 사용하기 위해 다음 프로젝트를 업데이트하세요:

Cloud-native GitLab Docker Images (CNG) (예시)
Omnibus GitLab (예시)
자체 컴파일 설치: Ruby 시스템 버전 확인을 업데이트하세요.

GitLab Helm Chart와 같은 차트도 업데이트해야 할 수 있습니다. 예를 들어 테스트를 실행하기 위해 Ruby를 사용하는 경우 (이 예시 참조). 하지만 이것은 엄격히 말해서 필수적이지 않을 수 있습니다.

변경 관리 요청을 제출하면 인프라 엔지니어들과 함께 롤아웃을 조정하세요. 더 큰 업그레이드를 다룰 때, 롤아웃 계획에 릴리스 매니저를 참여시키세요.

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

업그레이드가 패치 릴리스이며 중요한 보안 패치를 포함한다면, 자체 관리 고객에게 GitLab 패치 릴리스로 출시되어야 합니다. 진행 방법에 대해서는 릴리스 매니저에게 상담하세요.

Ruby 업그레이드 도구

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

폐지 도구킷

Ruby 업그레이드의 일반적인 문제는 폐지 경고가 오류로 전환된다는 것입니다. 이는 새로운 경고가 기존 애플리케이션 브랜치로 들어가는 것을 방지하기 위해 모든 폐지 경고가 전환되어야 한다는 것을 의미합니다. 우리는 사양 실행에서 발생한 폐지 경고를 관찰하고 이를 테스트 실패로 전환하는 DeprecationToolkitEnv를 사용합니다. 이것은 새로운 Ruby에서 실패할 수 있는 새로운 코드를 확인하는데 도움이 됩니다.

때로는 우리가 제어할 수 없는 Ruby 젬에서 이러한 경고를 발생시킬 때처럼 새로운 경고를 도입하지 못하는 경우가 있습니다. 이런 경우에는 이 MR에서 하는 것처럼 폐지를 추가하세요.

폐지 기록기

우리는 또한 Ruby 및 Rails 폐지 경고를 log/deprecation_json.log라는 전용 로그 파일에 기록합니다 (깻발어 GitLab 로그 파일을 찾을 수 있는 GitLab 로깅 가이드를 참조하세요), 이것은 테스트로 충분히 커버리지되지 않은 코드가 있는지 알려주어 DeprecationToolkitEnv를 거칠 수 있습니다.

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

권장 사항

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

가능한 한 많은 변경을 최우선으로 하세요. 특히 주요 및 주 버전 릴리스의 경우, 애플리케이션 코드가 깨지거나 변경될 가능성이 높습니다. 하위 호환성이 있는 모든 변경 사항은 기본 브랜치로 병합되고 소규모로 릴리스되어야 합니다. 이렇게 함으로써 우리는 작은 단계로 이동하고 운영 환경에서 초기 피드백을 받을 수 있게 됩니다.
큰 업데이트를 위한 실험 브랜치를 만드세요. 일반적으로 우리는 지속적인 피드백과 실험을 위해 긴 시간 동안 유지되는 토픽 브랜치를 피하려고 합니다. 그러나 피드백과 실험을 위해 이러한 브랜치를 가지고 있으면 유용할 수 있습니다. 새로운 Ruby를 사용할 때 CI/CD에서 정기적으로 피드백을 받을 수 있게하여 우리가 마주할 문제를 처음으로 평가하는데 도움이 될 수 있습니다. 이러한 실험 브랜치는 병합되기 위한 것이 아닙니다; 필요한 변경 사항을 단독으로 분류하고 다시 독립적으로 병합되면 브랜치를 닫을 수 있습니다.
마일스톤 릴리스 이전에 문제를 해결할 충분한 시간을 제공하세요. GitLab은 빠르게 움직입니다. Ruby 업그레이드는 많은 MR을 전송하고 검토해야 하므로 릴리스 날 전에 모든 변경 사항이 반드시 병합되어 있도록하세요. 이렇게 함으로써 무언가가 깨졌을 때 대비할 수 있는 여분의 시간을 확보하게 됩니다. 의심스러운 경우, 가용성을 우선시하기 때문에 다음 달로 업그레이드를 연기하는 것이 좋습니다.