Backstage 최신 버전 유지하기
Backstage는 항상 개선되고 있어서 최신 릴리스와 동기화를 유지하는 것이 좋아요. 이 글에서는 backstage-cli를 이용한 버전 업그레이드와 Backstage yarn 플러그인을 통한 패키지 버전 관리 방법을 설명드릴게요.
출처: 문서
본문
대상 독자: 개발자 및 관리자
이 섹션의 개념을 더 잘 이해하려면 모노레포, 시맨틱 버저닝, CHANGELOG에 대한 이해가 권장돼요.
요약
Backstage는 항상 개선되고 있으므로 최신 릴리스와 동기화를 유지하는 것이 좋아요. Backstage는 애플리케이션이나 서비스보다는 라이브러리에 가까워요. create-react-app과 비슷하게 @backstage/create-app 도구는 진화하도록 설계된 출발점을 제공해요.
backstage-cli로 Backstage 버전 업데이트하기
Backstage CLI에는 사용 중인 모든 @backstage 패키지와 의존성을 최신 버전으로 올리는 명령인 versions:bump가 있어요.
yarn backstage-cli versions:bump
모든 @backstage 패키지를 한 번에 올리는 이유는 패키지 사이의 의존성을 유지하기 위해서예요.
버전 업그레이드 과정을 더 쉽고 간소화하려면 Backstage yarn 플러그인 사용을 적극 권장해요.
기본적으로 bump 명령은 @backstage 패키지를 월 단위로 릴리스되는 최신 main 릴리스 라인으로 업그레이드해요. 주 단위로 릴리스되는 next 릴리스 라인을 따라가고 싶다면 --release next 옵션을 사용하면 돼요.
yarn backstage-cli versions:bump --release next
--release 옵션을 사용해서 특정 버전을 대상으로 지정할 수도 있어요. 앱을 특정 릴리스에 고정해야 하거나 이전 버전으로 다운그레이드해야 할 때 유용해요(예: 1.45.0에서 1.43.0으로 이동).
큰 버전 차이(예: 2-3 릴리스)를 가로지르는 다운그레이드는 Backstage가 의존성을 관리하는 방식 때문에 패키지 불일치나 오류를 초래할 수 있어요. 이 방법은 작은 조정에 가장 적합해요.
yarn backstage-cli versions:bump --release 1.43.0
다른 플러그인을 사용한다면 --pattern 옵션을 전달해서 @backstage/* 의존성보다 더 많은 것을 업데이트할 수 있어요.
yarn backstage-cli versions:bump --pattern '@{backstage,roadiehq}/*'
create-app 템플릿 변경 사항 따라가기
@backstage/create-app 명령은 템플릿에서 Backstage 설치의 초기 구조를 만들어요. Backstage 저장소에 있는 이 템플릿의 소스는 주기적으로 업데이트되지만, 로컬 app과 backend 패키지는 create-app 시점에 확정되어 템플릿 업데이트를 자동으로 받지 않아요.
이런 이유로 템플릿에 대한 변경 사항은 @backstage/create-app 패키지의 변경 로그에 업그레이드 지침과 함께 문서화돼요. 패키지를 업그레이드할 때 이 변경 로그에서 적용할 수 있는 업데이트를 확인하는 것을 권장해요. 대안으로 Backstage Upgrade Helper는 Backstage의 두 버전 사이의 모든 변경 사항을 통합된 보기로 제공해요. 현재 Backstage 설치 버전은 backstage.json에서 확인할 수 있어요.
자동화된 codemod 적용하기
패키지 업그레이드와 create-app / Upgrade Helper diff 후에는 해당 릴리스에 맞는 버전이 지정된 Codemod Registry 레시피를 실행해요. Material-UI에서 Backstage UI로의 전환 같은 더 큰 작업에서는 준비가 되면 misc 레시피를 사용해요. 명령과 자세한 내용은 Codemods에서 확인할 수 있어요.
Backstage yarn 플러그인으로 패키지 버전 관리하기
Backstage yarn 플러그인은 backstage.json의 전체 Backstage 버전을 기준으로 각 패키지에 적절한 버전을 결정해서 Backstage 패키지 버전 관리를 더 쉽게 만들어줘요. 이렇게 하면 Backstage 모노레포 전체의 모든 package.json을 업데이트할 필요가 없어지고, 새 @backstage 의존성을 추가할 때 현재 설치된 Backstage 릴리스에 맞는 올바른 버전을 알아낼 걱정도 없어져요.
요구 사항
yarn 플러그인을 사용하려면 yarn 4.1.1 이상이 필요해요.
설치
yarn 플러그인을 설치하려면 Backstage 모노레포에서 다음 명령을 실행해요:
yarn plugin import https://versions.backstage.io/v1/tags/main/yarn-plugin
그 결과 파일 시스템의 변경 사항을 저장소에 커밋해야 해요.
최상의 결과를 얻으려면 Backstage 업그레이드를 진행할 때 Backstage yarn 플러그인을 추가하는 것이 이상적이에요. 모든 것이 잘 동작하는지 확인하기가 더 쉬워지기 때문이에요.
사용법
yarn 플러그인이 설치되면 현재 릴리스된 @backstage 패키지의 버전을 package.json에서 "backstage:^" 문자열로 대체할 수 있어요. 이 문자열은 yarn이 backstage.json의 전체 Backstage 버전을 기준으로 버전을 해석하도록 지시해요.
backstage.json은 플러그인이 동작하는 데 핵심이에요. 이 파일이 CI/CD 파이프라인이나 컨테이너 빌드에 포함되었는지 확인하세요.
위에서 설명한 backstage-cli versions:bump 명령은 yarn 플러그인 설치를 감지하고, 설치된 경우 모노레포 전체의 의존성을 자동으로 이 플러그인을 사용하도록 마이그레이션해요.
의존성 불일치에 대한 추가 정보
Backstage는 Yarn 워크스페이스가 있는 모노레포로 구조화되어 있어요. 즉, app과 backend 패키지, 그리고 추가한 맞춤 플러그인들은 각각 자체 package.json과 의존성을 가진 별도의 패키지예요.
특정 의존성 버전이 서로 다른 패키지 간에 같다면, 그 의존성은 모노레포 루트의 메인 node_modules 폴더로 호이스팅되어 패키지 간에 공유돼요. 같은 의존성의 다른 버전이 발견되면 yarn은 특정 패키지 안에 node_modules 폴더를 만들어요. 이로 인해 같은 패키지의 여러 버전이 같은 앱에 설치되어 사용될 수 있어요.
모든 Backstage 핵심 패키지는 패키지 중복이 문제가 되지 않도록 구현되어 있어요. 예를 들어 @backstage/core-plugin-api, @backstage/core-components, @backstage/plugin-catalog-react, @backstage/backend-plugin-api 같은 패키지의 중복 설치도 모두 허용돼요.
패키지 중복이 많은 경우 허용 가능하지만, 번들 크기와 설치 속도를 최적화하기 위해 패키지를 중복 제거하고 싶을 수도 있어요. 중복 패키지 수를 줄이려면 yarn dedupe 같은 중복 제거 도구 사용을 권장해요.
프록시
Backstage CLI는 NODE_USE_ENV_PROXY=1이 설정된 경우 표준 HTTP_PROXY, HTTPS_PROXY, NO_PROXY 환경 변수를 존중해요. 자세한 내용은 기업 프록시 가이드를 참고하세요.
또한 인터넷 접근이 제한된 환경에서는 yarn도 (때때로) 프록시가 필요해요. yarn은 다른 모듈과 다른 설정을 사용해요. 위에서 언급한 backstage yarn 플러그인을 사용하기로 했다면 추가 프록시 값을 설정해야 해요. 모든 환경과 상황에서 항상 프록시 설정이 필요하다면 yarnrc.yml 파일에 httpProxy와 httpsProxy 값을 추가할 수 있어요. 어떤 환경에서는 필요하지만(예: 개발자 워크스테이션) 다른 환경에서는 필요하지 않다면(AWS에서 실행되는 CI 빌드 서버 같은 경우), yarnrc.yml 파일을 업데이트하지 말고 프록시가 필요한 환경·상황에서 환경 변수 YARN_HTTP_PROXY와 YARN_HTTPS_PROXY만 설정하면 돼요.
backstage yarn 플러그인을 사용할 계획이라면, 플러그인을 설치할 때와 versions:bump 명령을 실행할 때 모두 이 추가 yarn 프록시 설정이 필요해요. backstage yarn 플러그인을 사용할 계획이 없다면, 프록시 설정만으로 충분한 것 같아요.
예시 구성
export HTTP_PROXY=http://proxy.company.com:8080export HTTPS_PROXY=http://proxy.company.com:8080export NO_PROXY=localhost,internal.company.comexport NODE_USE_ENV_PROXY=1export YARN_HTTP_PROXY=${HTTP_PROXY} # optionalexport YARN_HTTPS_PROXY=${HTTPS_PROXY} # optional
마이그레이션 롤백
어떤 문제로 인해 Backstage 인스턴스를 다운그레이드해야 하거나, 새 버전의 Backstage를 검증하기 위해 테스트 환경을 사용하고 있다면 마이그레이션을 롤백해야 할 수 있어요. Knex를 사용한 수동 롤백 가이드에서 Knex로 마이그레이션을 롤백하는 방법을 확인할 수 있어요.