Grafana v11.0의 주요 변경 사항
Grafana v11.0의 주요 변경 사항 (Breaking changes in Grafana v11.0)
다음은 Grafana v11.0으로 업그레이드할 때 알아야 할 주요 변경 사항이에요.
여기서 주요 변경 사항이란 사용자나 운영자가 뭔가를 해야 하는 모든 변경을 의미해요. 여기에는 다음이 포함돼요:
- 시스템 한 부분의 변경으로 다른 구성 요소가 실패할 수 있는 변경
- 기능의 폐기(deprecation)나 제거
- 자동화를 깨뜨릴 수 있는 API 변경
- Grafana의 일부 플러그인이나 기능에 영향을 주는 변경
- 되돌릴 수 없는 마이그레이션
각 변경에 대해 제공되는 정보는:
- 영향을 받는지 확인하는 데 도움을 줘요
- 변경 사항이나 관련 배경 정보를 설명해요
- 변경에 대한 완화 또는 마이그레이션 방법을 안내해요
- 더 많은 학습 자료를 제공해요
릴리스 하이라이트와 폐기 사항은 v11.0 What's new를 참고해요. v11.0으로 업그레이드할 때 권장하는 구체적인 단계는 Upgrade guide를 확인해요.
출처: 문서
본문
다음은 Grafana v11.0으로 업그레이드할 때 알아야 할 주요 변경 사항이에요.
여기서 주요 변경 사항이란 사용자나 운영자가 뭔가를 해야 하는 모든 변경을 의미해요. 여기에는 다음이 포함돼요:
- 시스템 한 부분의 변경으로 다른 구성 요소가 실패할 수 있는 변경
- 기능의 폐기(deprecation)나 제거
- 자동화를 깨뜨릴 수 있는 API 변경
- Grafana의 일부 플러그인이나 기능에 영향을 주는 변경
- 되돌릴 수 없는 마이그레이션
각 변경에 대해 제공되는 정보는:
- 영향을 받는지 확인하는 데 도움을 줘요
- 변경 사항이나 관련 배경 정보를 설명해요
- 변경에 대한 완화 또는 마이그레이션 방법을 안내해요
- 더 많은 학습 자료를 제공해요
릴리스 하이라이트와 폐기 사항은 v11.0 What's new를 참고해요. v11.0으로 업그레이드할 때 권장하는 구체적인 단계는 Upgrade guide를 확인해요.
사용자와 운영자 (Users and Operators)
AngularJS 지원이 기본적으로 꺼짐 (AngularJS support is turned off by default)
설명 (Description)
Grafana v11에서는 더 이상 사용되지 않는 AngularJS 프레임워크에 대한 지원이 모든 자체 관리(온프레미스) 및 Cloud Grafana 인스턴스에서 기본적으로 꺼져 있어요. 이로 인해 AngularJS에 의존하는 데이터 소스나 패널 시각화는 로드되지 않으며, 따라서 대시보드가 크게 중단될 가능성이 있어요. 지원은 Grafana의 다음 메이저 릴리스에서 완전히 제거될 거예요.
마이그레이션/완화 (Migration/mitigation)
중단을 피하려면 모든 플러그인을 최신 상태로 유지하고 남아 있는 AngularJS 플러그인을 React 기반 대안으로 마이그레이션해요. 플러그인이 AngularJS에 의존한다면 Grafana의 plugins catalog과 그것이 사용되는 모든 대시보드 패널에 경고 아이콘과 메시지가 표시돼요. 또한 영향을 받는 대시보드에 경고 배너가 나타나요. detect-angular-dashboards 도구로 영향을 받는 모든 대시보드 목록을 생성할 수도 있어요.
우리 문서는 알려진 모든 공개 플러그인을 나열하고 가능할 때 마이그레이션 조언을 제공해요.
Grafana 자체 관리 사용자와 기존 Grafana Cloud 인스턴스의 경우 구성 매개변수 angular_support_enabled=false로 지원을 일시적으로 다시 활성화할 수 있어요. 그러나 AngularJS 기반 플러그인은 더 이상 업데이트를 받지 못하며 가능한 한 빨리 마이그레이션을 강력히 권장해요. 이 구성 매개변수도 Grafana v11 다음 메이저 릴리스에서 제거될 거예요.
새 Grafana Cloud 사용자는 인스턴스에 지원이 추가되도록 요청할 수 없어요.
더 알아보기 (Learn more)
자세한 내용은 블로그 게시물을 참고해요.
Grafana Enterprise: 익명 기기가 사용자로 청구됨 (Grafana Enterprise: Anonymous devices are billed as users)
설명 (Description)
Grafana v11부터 익명 사용자가 Grafana Enterprise에서 사용자로 집계되고 청구돼요. v11로 업그레이드하면 익명 사용자가 Grafana Enterprise 라이선스에 대해 활성 사용자로 자동 집계돼요.
마이그레이션/완화 (Migration/mitigation)
익명 접근을 끄고, 공개적으로 접근 가능한 대시보드에 보기 전용 접근을 허용하려면 공개 대시보드를 사용하는 것을 고려해요.
더 알아보기 (Learn more)
레거시 알림이 완전히 제거됨 (Legacy alerting is entirely removed)
레거시 알림은 수명이 다했어요. Grafana v11에서는 레거시 알림을 더 이상 활성화할 수 없으며, 새 Grafana Alerting을 실행하도록 설정이 업데이트되지 않으면 Grafana가 시작에 실패해요. 이는 또한 Grafana v11부터 레거시 알림에서 새 알림으로 마이그레이션하는 것이 더 이상 불가능하다는 뜻이에요. Grafana v10.4.x는 마이그레이션을 제공하는 마지막 버전이므로, Grafana v11로 업그레이드하기 전에 새 Grafana Alerting 시스템으로 마이그레이션해야 해요. 레거시 알림 폐기 문서에서 Grafana Alerting과 새 시스템의 이점에 대해 더 배워보세요. 업그레이드 알림 문서에서 마이그레이션에 대해 더 배워보세요.
코드 제거에 대한 자세한 내용은 다음 PR을 검토해요:
Reporting의 폐기된 엔드포인트와 필드 제거 (Deprecated endpoints and fields in Reporting removed)
설명 (Description)
Grafana v11에서는 이전 스케줄링 형식, 이메일, 대시보드와 관련된 Reporting의 폐기된 엔드포인트와 필드에 대한 지원이 완전히 제거돼요. 이로 인해 폐기된 엔드포인트에 대한 호출과 폐기된 필드에 값 전달이 방지돼요. 이 기능은 API로 보고서를 생성하는 Cloud와 Enterprise 고객에게만 영향을 줘요.
마이그레이션/완화 (Migration/mitigation)
폐기된 엔드포인트를 새 해당 엔드포인트로 업데이트하고 폐기된 필드를 제거해 새 해당 필드로 교체해요.
더 알아보기 (Learn more)
Reporting API 문서는 지원되는 모든 엔드포인트와 필드를 나열해요.
커스텀 브랜딩 공개 대시보드 푸터 동작 변경 (Change custom branding public dashboard footer behavior)
설명 (Description)
Grafana v11에서는 푸터 로고나 푸터 텍스트가 설정되지 않으면 커스텀 브랜딩 공개 대시보드 푸터 동작이 기본적으로 Grafana 로고로 변경돼요. 더 이상 공개 대시보드 푸터를 숨길 옵션이 없어요. 이 기능은 Cloud Advanced와 Enterprise 고객에게만 영향을 줘요.
마이그레이션/완화 (Migration/mitigation)
기본 Grafana 푸터를 표시하고 싶지 않다면 공개 대시보드 푸터 로고나 푸터 텍스트가 설정되어 있는지 확인해요.
더 알아보기 (Learn more)
공개 대시보드용 커스텀 브랜딩 구성 문서
하위 폴더가 이름에 슬래시가 있는 폴더에서 매우 드물게 문제를 일으킴 (Subfolders cause very rare issues with folders that have forward slashes in their names)
설명 및 마이그레이션/완화 (Description and migration/mitigation)
하위 폴더를 활성화하는 업그레이드는 특정 경우 알림에 문제를 일으킬 수 있어요. 이전에 이름에 슬래시를 사용하는 폴더를 설정하고, 그 폴더에 알림 규칙이 있으며, 알림 정책이 그 폴더의 이름과 일치하도록 설정되어 있다면, 알림이 구성된 수신자 대신 기본 수신자에게 전송돼요.
이런 경우 하위 폴더를 활성화하는 업그레이드 전에 다음 단계를 따르는 것을 권장해요:
- 영향을 받는 라우트의 복사본을 만들고 새 복사본의 매처를 다시 작성해요. 예를 들어 원래 매처가
grafana_folder=MyFolder/sub-folder였다면 새 라우트 매처는grafana_folder=MyFolder\/sub-folder가 돼요. - 하위 폴더를 활성화한 후에는 이전 라우트를 삭제할 수 있어요.
파일 프로비저닝을 사용한다면 업그레이드와 라우트 업데이트를 동시에 할 수 있음을 참고해요.
더 알아보기 (Learn more)
Input 데이터 소스가 제거됨 (The Input data source is removed)
직접 입력 데이터 소스 플러그인이 Grafana v11에서 제거됐어요. 4년 동안 alpha 상태였고 Grafana와 함께 제공되는 TestData로 대체됐어요. 이는 작은 폐기예요.
자세한 내용은 이 PR을 검토해요.
데이터 소스: 쿼리 필터링 변경 (Data sources: Query filtering changes)
쿼리 편집기 행의 Disable query 버튼은 데이터 소스 개발자와 최종 사용자 사이에 많은 혼란을 일으켰어요. 지금까지 숨겨진 쿼리를 실행 전이나 후에 필터링하는 것은 데이터 소스 개발자의 몫이었어요. Grafana v11부터 이 버튼의 툴팁이 Disable query에서 Hide response/Show response로 변경됐어요. 숨겨진 쿼리와 연결된 응답은 패널에 전달되기 전에 Grafana가 제거해요.
이전에 숨겨진 쿼리를(실행 전이나 후에) 제거하지 않던 데이터 소스 플러그인 사용자는 동작 변화를 보게 될 거예요. 이전에는 Disable query 버튼을 클릭해도 쿼리 결과에 영향을 주지 않았는데, Grafana v11부터 숨겨진 쿼리와 연결된 응답은 더 이상 패널에 반환되지 않아요.
또한 datasource.filterQuery 메서드 호출을 쿼리 러너로 옮기고 있어요. 이는 프론트엔드 전용 데이터 소스(또는 DataSourceWithBackend 클래스를 확장하지 않는 모든 데이터 소스)가 이 메서드를 구현할 수 있게 해요. 이는 데이터 소스 플러그인 동작을 간소화해 모든 종류의 데이터 소스 플러그인에서 필터링이 같은 방식으로 작동하도록 보장해요.
마이그레이션/완화 (Migration/mitigation)
패널에서 데이터가 누락된다면 쿼리 편집기의 Hide response 버튼이 클릭되지 않았는지 확인해요.
DataSourceWithBackend를 확장하는 데이터 소스의 경우 filterQuery 메서드가 이제 데이터 소스 쿼리 메서드 전에 호출돼요. filterQuery 메서드가 이 메서드가 호출되기 전에 어떤 종류의 쿼리 마이그레이션이 일어난다고 가정한다면, 이제 이 메서드 안에서도 마이그레이션을 수행해야 해요.
더 알아보기 (Learn more)
Chore: 새 인스턴스에서 oauth 정보 쿼리 (Chore: Query oauth info from a new instance)
추가 보안 계층으로 ID 토큰 HD 매개변수의 응답과 허용 도메인 목록 사이에 검증을 추가했어요. HD 매개변수가 허용 도메인 목록과 일치하지 않으면 Grafana에 대한 접근을 거부해요.
api_url로 Google OAuth 구성을 설정했다면, 승인된 토큰이 나온 조직을 설명하는 HD 매개변수가 없는 레거시 OAuth 구현을 사용하고 있을 수 있어요. 이는 로그인 흐름을 깨뜨릴 수 있어요.
validate_hd 구성 토글을 통해 이 기능을 끌 수 있어요. 레거시 Google OAuth 구성을 사용하는 사람은 ID 토큰 응답에 HD 매개변수가 없다면 이 검증을 꺼야 해요.
반복 패널의 패널 보기 URL 생성 방식 변경 (Changes to how the panel view URL is generated for repeated panels)
설명 (Description)
Scenes 라이브러리가 대시보드에 도입되면서 개별 반복 패널을 볼 때 생성되는 URL이 변경됐어요. 이 패널들을 참조하는 방식을 변경했고, 이전에 &viewPanel=panel-5였던 것이 이제 &viewPanel=panel-3-clone1이 됐어요.
이는 이전 URL이 더 이상 작동하지 않고 대신 대시보드 보기로 리다이렉트되며 Panel not found 오류가 표시된다는 뜻이에요. 이 시점부터 대시보드는 예상대로 계속 작동해요.
마이그레이션/완화 (Migration/mitigation)
보기 모드에서 패널을 다시 열면 새 URL을 얻을 수 있어요.
플러그인 개발자 (Plugin developers)
React Router가 폐기됨 (React Router is deprecated)
설명 (Description)
Grafana v11에서 react-router v5를 폐기로 표시하고 있어요. App 플러그인은 react-router v6를 사용하도록 마이그레이션을 시작해야 해요.
마이그레이션/완화 (Migration/mitigation)
전체 가이드는 개발자 포털의 마이그레이션 문서를 따라주세요.
더 알아보기 (Learn more)
- Grafana v9.x에서 v10.x로 마이그레이션 가이드
- 공식 react-router v5에서 v6로 마이그레이션 가이드
- Grafana 커뮤니티 포럼 토픽
grafana/e2e 테스트 도구가 폐기됨 (The grafana/e2e testing tool is deprecated)
설명 (Description)
Cypress 기반 그래픽 grafana/e2e 엔드투엔드 테스트 도구가 이제 폐기됐어요.
마이그레이션/완화 (Migration/mitigation)
모든 플러그인 작성자가 엔드투엔드 테스트를 새 Playwright 기반 grafana/plugin-e2e 패키지를 사용하도록 마이그레이션할 것을 권장해요. grafana/e2e에서 grafana/plugin-e2e로 마이그레이션하는 방법에 대한 세부 사항은 마이그레이션 가이드에서 확인해요.
Chore: ArrayVector를 never로 오염시켜 더 이상 사용을 권장하지 않음 (Chore: Taint ArrayVector with never to further discourage)
Grafana v10에서 폐기된 Vector 인터페이스가 더 폐기됐어요. 이제 이 인터페이스를 사용하면 빌드 타임 Typescript 오류가 발생하지만 런타임에는 계속 작동해요. 코드에서 아직 ArrayVector를 사용한다면 즉시 제거하고 일반 배열로 교체해야 해요. get/set 호출에 의존하는 구버전에 대해 컴파일된 플러그인은 Array 프로토타입에 여전히 수정된 프로토타입이 있으므로 계속 작동해요. 이는 향후 제거될 거예요.
Chore: React 17 peer deps 제거 (Chore: Remove React 17 peer deps)
패키지에서 React 17을 peer dependency로 제거했어요. 이 패키지의 새 버전을 사용하는 사람은 업그레이드 단계에 따라 React 18로 업그레이드했는지 확인해야 해요.
Chore: Grafana/Runtime에서 SystemJS 제거 (Chore: Remove SystemJS from Grafana/Runtime)
SystemJS는 더 이상 @grafana/runtime에서 내보내지지 않아요. 플러그인 개발자는 대신 표준 TS import 문법과 npm/yarn을 사용한 패키지 설치로 모듈/패키지를 가져와야 해요.