릴리즈
CNCF graduated·incubating 프로젝트 릴리즈 노트의 AI 분석.
v1.52.0은 discovery API 기본값 변경, immediate stitching 제거, BUI union 타입 변경 등 세 가지 breaking change와 함께 PostgreSQL 카탈로그 성능 개선 및 다수의 안정성 수정이 포함됩니다.
breakingdiscovery.endpoints 마이그레이션 및 immediate stitching 설정 제거
업그레이드 전에 두 가지 설정을 점검하세요. 첫째, `discovery.endpoints`에 내부 전용 문자열 타겟을 쓰고 있다면 객체 형태로 바꾸고 내부 URL은 `target.internal`에, 브라우저가 접근 가능한 URL은 `target.external`에 넣어야 합니다. 그렇지 않으면 프론트엔드가 내부 주소에 직접 요청을 보냅니다. 둘째, 설정 파일에서 `catalog.stitchingStrategy.mode: 'immediate'`를 삭제하세요. 이미 무시되지만 deprecation 경고가 발생합니다. 둘 다 설정 파일 수정으로 해결됩니다.
breakingComboboxProps / SelectProps 타입 확장 코드 업그레이드 전 수정 필요
`ComboboxProps`와 `SelectProps`가 union 타입으로 바뀌었습니다. 두 타입을 `extends`로 확장한 인터페이스가 있으면 타입 에러가 납니다 — 타입 교차(intersection)로 바꾸세요. `.bui-SelectPopover`의 직계 자식으로 리스트 내용을 선택하던 CSS 셀렉터도 확인이 필요합니다. 런타임 폴백 없이 컴파일 단계에서 바로 실패합니다.
enhancementPostgreSQL 카탈로그 쿼리 성능 개선 — 마이그레이션만 실행하면 적용
이번 릴리즈에 PostgreSQL 전용 쿼리 플래너 개선이 여러 건 포함됩니다. search 테이블에 다중 컬럼 통계 추가, 불필요한 레거시 인덱스 제거, vacuum 임계값 조정, count/list 쿼리 분리가 마이그레이션으로 자동 적용됩니다. 엔티티 수가 많은 환경에서 카탈로그 목록 조회가 10~40배 느렸다면 이 업그레이드가 직접적인 해결책입니다. 별도 설정 변경 없이 마이그레이션 실행만으로 적용됩니다. MySQL/SQLite 환경에는 해당되지 않습니다.
주요 변경 (7)
- @backstage/plugin-app의 기본 discovery API가 FrontendHostDiscovery로 변경 — discovery.endpoints의 내부 전용 문자열 타겟을 객체 형태로 마이그레이션 필요
- catalog.stitchingStrategy.mode: 'immediate' 제거 — 설정이 남아 있으면 경고 로그가 출력됨
- ComboboxProps·SelectProps가 union 타입으로 변경 — 인터페이스 상속 코드 수정 필요
- PostgreSQL 대상 카탈로그 백엔드 쿼리 플래너 개선 다수 포함 (다중 컬럼 통계, 레거시 인덱스 제거, count 쿼리 분리)
- @backstage/connections 실험적 패키지 추가 — 기존 integrations의 장기 대체제 예정, 현재는 프로덕션 사용 금지
- react-syntax-highlighter·@dagrejs/dagre 지연 로딩 전환으로 @backstage/core-components 초기 모듈 로드 약 10 MB 절감
- 새로 생성되는 앱에 Yarn 4.13.0 및 npmMinimalAgeGate: 3d 설정이 기본 적용
v1.51.0은 6개의 브레이킹 체인지와 카탈로그 쿼리 성능 대폭 개선, 새로운 AiResource 엔티티 종류, MCP/OIDC 보안 강화를 담고 있습니다. 업그레이드 전 마이그레이션 시간을 반드시 확보하세요.
breaking대규모 설치 환경은 배포 전 카탈로그 DB 마이그레이션 SQL 선행 실행 필수
이번 마이그레이션은 search 테이블에 커버링 인덱스와 UNIQUE 제약을 추가합니다. 데이터가 많은 환경에서는 처리 시간이 길어질 수 있어, 릴리즈 노트에서도 배포 전 SQL 명령을 수동으로 먼저 실행하도록 명시적으로 권고하고 있습니다. 그냥 배포하면 예측 불가한 다운타임이 생길 수 있으니 changelog에서 정확한 SQL을 확인하고 진행하세요.
breaking업그레이드 전 OIDC 패턴 및 MsgGraph 설정 반드시 검토
OIDC의 CIMD/DCR 기본 패턴이 와일드카드 '*'에서 특정 MCP 클라이언트 기본값으로 바뀌었습니다. 커스텀 MCP 클라이언트가 있다면 allow list에 명시적으로 추가하지 않으면 조용히 동작을 멈춥니다. Microsoft Graph는 이제 비활성 계정을 기본으로 제외하므로, 비활성 사용자를 인입해야 한다면 업그레이드 전에 필터를 명시적으로 설정해두세요. NavItemBlueprint는 PageBlueprint의 title/icon 파라미터로, PolicyQueryUser의 token/expiresInSeconds는 credentials로 각각 마이그레이션해야 합니다.
enhancement대규모 조직은 Microsoft Graph 증분 인입 모듈로 전환 검토
신규 msgraph-incremental 모듈은 사용자와 그룹을 한 페이지씩 처리하고 커서 상태를 저장합니다. 파드가 재시작되더라도 전체 재인입 없이 이전 지점부터 이어갈 수 있어, 수만 명 규모의 조직에서는 실질적인 운영 부담이 줄어듭니다. 기존 MicrosoftGraphOrgEntityProvider는 전체 데이터셋을 메모리에 올리는 방식이라 대규모 환경에서는 새 모듈로 전환하는 게 낫습니다.
주요 변경 (6)
- 6개 브레이킹 체인지: NavItemBlueprint 제거, PortableSchema.schema 메서드 전용 변경, OIDC/CIMD/DCR 패턴 강화, PolicyQueryUser 정리, 카탈로그 페이지네이션 동작 변경, Microsoft Graph 비활성 사용자 기본 제외
- 카탈로그 백엔드 쿼리 성능 대폭 개선 — PostgreSQL 인덱스 활용으로 페이지네이션 응답 시간이 수 초에서 수 밀리초 수준으로 단축; 대규모 설치 환경에서는 배포 전 SQL 마이그레이션 명령 선행 실행 권장
- 새로운 AiResource 카탈로그 엔티티 종류 및 mcp-server API 서브타입 추가로 AI 워크로드 모델링 지원 확대
- Microsoft Graph 증분 인입 모듈 신규 추가 — 커서 기반 메모리 효율적 인입, 파드 재시작 후 마지막 페이지부터 재개
- 스캐폴더 폼 데코레이터 안정(public) API로 승격; always()·failure() 스텝 제어 함수 추가
- TechDocs에 외부 폰트 다운로드 비활성화 옵션 추가(에어갭 환경 지원); 약 24.8일 이상 스케줄 태스크의 타이머 오버플로 버그 수정
v1.50.0은 인증, 프론트엔드 API, 카탈로그 전반에 걸친 다수의 브레이킹 체인지와 함께 AWS RDS IAM 인증, Auth0 federated logout, 카탈로그 데드락 수정, 보안 패치를 포함한 대규모 릴리스입니다.
securityrollup 경로 순회 취약점 패치 — CLI 및 빌드 도구 업데이트 필요
rollup v4.59 미만 버전에는 고위험도 경로 순회 취약점(GHSA-mw96-cpmx-2vgc)이 있습니다. @backstage/cli, repo-tools, 여러 CLI 모듈이 이미 업데이트됐습니다. 업그레이드 헬퍼를 실행하고 lockfile을 갱신하세요. 워크스페이스 어딘가에 rollup 버전을 직접 고정했다면 v4.59+로 올려야 합니다. glob 의존성도 v7/v8/v11의 취약점을 해소하기 위해 v13으로 업그레이드됐습니다.
breaking업그레이드 전 토큰 디코딩 코드 점검 필수 — ent 클레임 기본 제거
auth.omitIdentityTokenOwnershipClaim의 기본값이 true로 바뀌어 Backstage 사용자 토큰에 ent 소유권 클레임이 더 이상 포함되지 않습니다. 토큰을 직접 디코딩해 ent를 읽는 코드가 있다면 아무 값도 반환되지 않아 조용히 버그가 생깁니다. 코드베이스에서 raw 토큰 디코딩을 찾아 userInfo 코어 서비스로 교체하세요. 시간이 필요하다면 config에 auth.omitIdentityTokenOwnershipClaim: false를 일시적으로 추가할 수 있지만, 이 설정은 향후 릴리스에서 완전히 제거될 예정이므로 마이그레이션 계획을 세워야 합니다.
breakingfrontend-plugin-api 업그레이드 전 createSchemaFromZod를 configSchema로 교체
@backstage/[email protected]에서 deprecated된 createSchemaFromZod 헬퍼가 삭제됐습니다. 이를 사용하는 extension이나 blueprint는 런타임에서 즉시 실패합니다. backstage.io/docs/frontend-system/architecture/migrations#150의 마이그레이션 문서를 참고해 configSchema 옵션으로 전환하세요. zod v3 스키마는 직접 지원되지 않으므로 import { z } from 'zod/v4' 방식을 사용하거나 zod v4로 업그레이드해야 합니다.
주요 변경 (7)
- BREAKING: auth.omitIdentityTokenOwnershipClaim 기본값이 true로 변경 — 토큰에 ent 클레임이 더 이상 포함되지 않아 대규모 조직의 HTTP 헤더 크기 문제 해소
- BREAKING: frontend-plugin-api에서 deprecated된 createSchemaFromZod 헬퍼 제거 — configSchema 옵션(zod v4)으로 마이그레이션 필요
- BREAKING: @backstage/ui에서 React 17 지원 종료 — 최소 버전은 React 18
- 카탈로그 백엔드 데드락 수정: 다중 레플리카 환경에서 SELECT ... FOR UPDATE SKIP LOCKED가 트랜잭션 없이 호출되어 발생하던 PostgreSQL 40P01 오류 해결
- 보안 패치: rollup v4.59+(GHSA-mw96-cpmx-2vgc 경로 순회 취약점) 및 glob v13으로 업그레이드
- backend-defaults에서 PostgreSQL AWS RDS IAM 인증 지원 — 정적 비밀번호 대신 단기 토큰 사용 가능
- Auth0 프로바이더가 federated logout을 수행하도록 개선 — federatedLogout: true 설정 시 상위 IdP 세션도 함께 종료
v1.49.1은 새 프론트엔드 시스템의 레이아웃 문제를 수정하고, TechDocs/Scaffolder UI 버그를 잡은 패치 릴리스입니다.
enhancement미처리 엔티티 DevTools 탭, 이제 기본 제공
엔티티 수집 문제를 디버깅할 때 DevTools 탭을 수동으로 연결할 필요가 없어졌습니다. 업그레이드 후 바로 탭이 표시되므로, 개발·스테이징 환경에서 카탈로그 처리 실패를 더 빠르게 파악할 수 있습니다.
enhancement새 프론트엔드 시스템 전환 중이라면 1.49.1로 바로 올리세요
새 프론트엔드 시스템을 테스트하거나 마이그레이션 중인 팀이라면, Scaffolder와 카탈로그 엔티티 페이지의 레이아웃 깨짐 현상이 이번 패치에서 수정됐습니다. 1.49.0을 건너뛰고 바로 1.49.1로 업그레이드하는 게 낫습니다.
enhancement플러그인 헤더 타이틀에 네비게이션 링크 추가 가능
PageLayoutProps의 titleLink prop을 쓰면 플러그인 헤더 타이틀을 플러그인 루트로 이동하는 링크로 만들 수 있습니다. 커스텀 플러그인을 개발하거나 유지보수하는 팀이라면 Backstage의 플러그인 헤더 UX 패턴에 맞게 적용해 두는 것이 좋습니다.
주요 변경 (5)
- TechDocs 알파 플러그인 페이지를 BUI 헤더 시스템으로 마이그레이션해 이중 스크롤바 버그 해결
- 새 프론트엔드 시스템에서 Scaffolder 플러그인 페이지 레이아웃 수정
- 새 프론트엔드 시스템에서 카탈로그 엔티티 페이지 헤더 비활성화(레이아웃 충돌 방지)
- 미처리 엔티티가 DevTools 탭에 기본으로 표시됨 — 별도 설정 불필요
- PageLayoutProps에 titleLink prop 추가, 플러그인 헤더에서 루트로 이동 가능
v1.49.0은 새 프론트엔드 시스템이 1.0 RC에 도달하고, CLI가 모듈 시스템으로 전환되며, UI 컴포넌트·인테그레이션·엔티티 카드 전반에 걸쳐 다수의 breaking 변경이 포함된 대형 릴리스입니다.
breaking`@backstage/plugin-catalog` 업그레이드 전 엔티티 카드와 BUI 컴포넌트 마이그레이션 필수
`@backstage/plugin-catalog`가 메이저 버전 업됐으므로 즉각적인 조치가 필요합니다. EntityAboutCard, EntityLinksCard, EntityLabelsCard, GroupProfileCard, UserProfileCard에서 `variant` 프롭을 모두 제거하세요. React Router 컨텍스트 내에 `BUIProvider`를 래핑하지 않으면 Link, ButtonLink, Tabs, Menu, Table의 클라이언트 사이드 내비게이션이 동작하지 않습니다. CSS 셀렉터에서 `bui-HeaderPage` 클래스 패턴과 camelCase 데이터 속성을 찾아 수정하고, Checkbox의 `selected`/`indeterminate` 프롭도 `isSelected`/`isIndeterminate`로 교체해야 합니다.
breakingBitbucket 및 레거시 인테그레이션 설정 즉시 제거 필요
구 `bitbucket` 설정 키와 Azure DevOps의 `token`/`credential` 필드는 폐기 예고 상태가 아니라 완전히 제거됐습니다. `app-config.yaml`에 이 설정이 남아 있으면 업그레이드 후 백엔드가 시작되지 않습니다. `bitbucket`은 `bitbucketCloud` 또는 `bitbucketServer`로, Azure DevOps는 `credentials` 배열 방식으로 전환하세요. 스캐폴더 템플릿도 점검 대상입니다. `parseRepoUrl`이 더 이상 `bitbucket`을 처리하지 않기 때문입니다.
enhancement`@backstage/cli-defaults`를 지금 devDependency에 추가하세요
CLI 모듈 시스템이 정식 도입됐고, 기존 내장 명령으로 폴백되는 경우 이미 폐기 경고가 표시됩니다. 루트 `devDependencies`에 `@backstage/cli-defaults`를 추가하면 경고가 사라지고 향후 폴백 제거에도 대비할 수 있습니다. 커스텀 CLI 도구를 관리하고 있다면 `@backstage/cli-node`의 `createCliModule` API로 정식 CLI 확장 패키지를 만들어 두는 것이 좋습니다.
주요 변경 (7)
- 새 프론트엔드 시스템 1.0 RC 출시 — 신규 앱은 기본 적용, `--next` 플래그는 `--legacy`로 교체
- BUI에서 다수의 breaking 변경: Checkbox 프롭 이름 변경, CSS 클래스 이름 변경, 라우팅에 `BUIProvider` 필수화, 폐기 타입 제거
- 엔티티 카드들(`EntityAboutCard` 등) MUI → BUI 마이그레이션 완료, `variant` 프롭 제거 및 `@backstage/plugin-catalog` 메이저 버전 업
- Bitbucket 레거시 인테그레이션 및 관련 필드 완전 제거 — `@backstage/integration`, `@backstage/backend-defaults`, 스캐폴더 패키지 전반에 영향
- CLI가 `cli-module` 패키지 기반 모듈 시스템으로 전환 — 지금 바로 `@backstage/cli-defaults`를 devDependency에 추가해야 폴백 제거에 대비 가능
- `queryEntities()` 등 카탈로그 메서드에 프레디케이트 기반 필터링 지원 추가 (새 POST 엔드포인트)
- 퍼미션 검사 일괄 처리(batching) 도입으로 퍼미션이 많은 페이지 성능 개선