Grafana v10.0의 주요 변경 사항
Grafana v10.0의 주요 변경 사항 (Breaking changes in Grafana v10.0)
다음은 Grafana v10.0으로 업그레이드할 때 알아야 할 주요 변경 사항이에요.
여기서 주요 변경 사항이란 사용자나 운영자가 뭔가를 해야 하는 모든 변경을 의미해요. 여기에는 다음이 포함돼요:
- 시스템 한 부분의 변경으로 다른 구성 요소가 실패할 수 있는 변경
- 기능의 폐기(deprecation)나 제거
- 자동화를 깨뜨릴 수 있는 API 변경
- Grafana의 일부 플러그인이나 기능에 영향을 주는 변경
- 되돌릴 수 없는 마이그레이션
각 변경에 대해 제공되는 정보는:
- 영향을 받는지 확인하는 데 도움을 줘요
- 변경 사항이나 관련 배경 정보를 설명해요
- 변경에 대한 완화 또는 마이그레이션 방법을 안내해요
- 더 많은 학습 자료를 제공해요
릴리스 하이라이트와 폐기 사항은 v10.0 What's new를 참고해요. v10.0으로 업그레이드할 때 권장하는 구체적인 단계는 Upgrade guide를 확인해요.
출처: 문서
본문
다음은 Grafana v10.0으로 업그레이드할 때 알아야 할 주요 변경 사항이에요.
여기서 주요 변경 사항이란 사용자나 운영자가 뭔가를 해야 하는 모든 변경을 의미해요. 여기에는 다음이 포함돼요:
- 시스템 한 부분의 변경으로 다른 구성 요소가 실패할 수 있는 변경
- 기능의 폐기(deprecation)나 제거
- 자동화를 깨뜨릴 수 있는 API 변경
- Grafana의 일부 플러그인이나 기능에 영향을 주는 변경
- 되돌릴 수 없는 마이그레이션
각 변경에 대해 제공되는 정보는:
- 영향을 받는지 확인하는 데 도움을 줘요
- 변경 사항이나 관련 배경 정보를 설명해요
- 변경에 대한 완화 또는 마이그레이션 방법을 안내해요
- 더 많은 학습 자료를 제공해요
릴리스 하이라이트와 폐기 사항은 v10.0 What's new를 참고해요. v10.0으로 업그레이드할 때 권장하는 구체적인 단계는 Upgrade guide를 확인해요.
일반 주요 변경 사항 (General breaking changes)
Angular가 폐기되고 새 Grafana Cloud 스택에서 기본적으로 꺼짐 (Angular is deprecated and turned off by default for new Grafana Cloud stacks)
다음 경우에 영향을 받아요: (You are affected if:)
새 Grafana Cloud 스택을 만들고 Angular.js JavaScript 프레임워크로 작성된 패널이나 데이터 소스 플러그인을 사용하려는 경우예요. Angular 플러그인 목록을 참고해요.
배경 (Background)
AngularJS는 수년 전 활동적인 개발이 중단된 오래된 프론트엔드 프레임워크예요. 그 때문에 보안 위험이에요. AngularJS는 또한 CSP(Content Security Policy) 설정에서 unsafe-eval을 요구하며, 이는 브라우저에서 javascript가 실행되는 방식의 보안 수준도 낮춰요.
Grafana의 Angular 플러그인 지원은 폐기되어 향후 릴리스에서 제거될 예정이에요. 여전히 Angular로 만든 커뮤니티 및 사설 플러그인이 일부 있어요. v9.0부터 Grafana에는 Angular 플러그인 지원이 사용 가능한지 제어하는 angular_support_enabled라는 서버 구성 옵션이 있어요.
Grafana v10에서의 변경 (Change in Grafana v10)
Angular는 모든 새 Grafana Cloud 스택에서 기본적으로 비활성화돼요. Grafana Cloud의 기존 스택, Grafana Enterprise 온프레미스 인스턴스, Grafana OSS 인스턴스는 자동으로 영향을 받지 않아요.
완화 방법 (How to mitigate)
Grafana에서 Angular 플러그인을 사용한다면 Angular를 사용하지 않는 대체 패널이나 데이터 소스를 시도해요. 이 감지된 Angular 플러그인 목록은 존재하는 곳의 대안을 제공해요.
Angular를 사용하는 플러그인을 유지 관리하는 개발자라면 대신 React.js를 사용해 프론트엔드를 리팩터링하거나 다시 작성할 것을 권장해요. Grafana 팀이 도구와 지침을 제공하며 도울 준비가 되어 있어요. Slack이나 Forum에서 연락할 수 있어요.
더 알아보기 (Learn more)
Grafana 레거시 알림이 폐기되고 더 이상 내부 또는 외부 기여를 받지 않음 (Grafana legacy alerting is deprecated and no longer accepts internal or external contributions)
다음 경우에 영향을 받아요: (You are affected if:)
Grafana 레거시 알림을 사용하고 새 기능이나 변경 사항을 요청한 경우예요.
설명 (Description)
Grafana 레거시 알림(대시보드 알림)은 새롭고 개선된 Grafana Alerting을 위해 Grafana v9.0부터 폐기되었어요. Grafana v10에서는 Angular에 의존하는 레거시 알림 코드베이스가 여전히 사용 가능하지만, 더 이상 기여하거나 외부 기여를 받지 않을 거예요. 마이그레이션이 필요한 남은 사용자를 위해 레거시 알림에서 Grafana Alerting으로의 마이그레이션 경로 작업은 계속할 거예요.
마이그레이션 경로 (Migration path)
새 Grafana Alerting은 Grafana 8에서 도입되었고 레거시 알림의 상위 집합이에요. Upgrade Alerting 문서에서 알림 마이그레이션 방법을 배워보세요.
API 키가 서비스 계정으로 마이그레이션됨 (API keys are migrating to service accounts)
다음 경우에 영향을 받아요: (You are affected if:)
Grafana API 키를 사용하고 아직 서비스 계정으로 마이그레이션하지 않은 경우예요.
설명 (Description)
Grafana v8.5에서 service accounts를 도입했는데, 이는 토큰 회전과 역할 기반 접근 제어(RBAC)를 지원하는 API 키의 상위 집합이에요. v9.1에서 일반 공개(GA)로 승격되었고, 그 이후로 UI와 API를 통해 API 키를 서비스 계정으로 수동 마이그레이션할 수 있는 옵션이 있었어요. Grafana v10으로 업그레이드하면 Grafana가 모든 API 키를 서비스 계정으로 자동 마이그레이션하고 Admin 섹션 아래에 있던 API 키 화면을 숨길 거예요.
이것은 "주요" 변경인데, 사용자가 API 키를 보고 상호작용하는 데 익숙하다면 더 이상 탐색에서 그 페이지를 볼 수 없고 대신 Service accounts 페이지로 이동해야 하기 때문이에요. 그러나 기존 API 토큰은 완전히 기능하며 서비스 계정으로 마이그레이션되므로 자동화는 깨지지 않아요. 이전 Grafana 버전으로 롤백하면 API 키는 그대로 유지돼요.
Grafana의 API 키 생성 및 관리용 HTTP API 엔드포인트는 계속 작동하지만, 머신 인증을 생성하고 관리하려면 Service account HTTP API를 사용하기 시작할 것을 권장해요.
마이그레이션 경로 (Migration path)
Grafana v10으로 업그레이드하는 동안 아무 조치도 필요 없어요. API 키는 자동으로 마이그레이션돼요. Grafana v10으로 업그레이드하기 전에 API 키에서 서비스 계정으로의 마이그레이션을 테스트하거나 수행하려면 마이그레이션 문서를 따라요.
더 알아보기 (Learn more)
실험적 "dashboard previews" 기능 제거 (The experimental "dashboard previews" feature is removed)
다음 경우에 영향을 받아요: (You are affected if:)
dashboardPreviews 기능 토글을 켠 경우예요.
설명 (Description)
개발을 계속할 수 없게 만든 사용자 권한과 성능 문제 때문에 실험적 대시보드 미리보기 기능을 제거하고 있어요. 대시보드 미리보기는 Grafana v9.0부터 기능 토글 뒤에 있었어요.
마이그레이션 경로 (Migration path)
전체 기능이 Grafana에서 제거되었어요. dashboardPreviews 기능 플래그를 활성화한 사용자에게 Grafana는 대시보드 미리보기 없이 그대로 계속 작동해요. Grafana 구성에서 dashboardPreviews 기능 플래그를 제거할 것을 권장해요.
더 알아보기 (Learn more)
RBAC가 Grafana Enterprise에서 기본적으로 켜지고 비활성화할 수 없음 (RBAC is on by default in Grafana Enterprise and cannot be disabled)
다음 경우에 영향을 받아요: (You are affected if:)
Grafana 구성에서 RBAC를 적극적으로 비활성화한 경우예요.
설명 (Description)
Grafana 9부터 RBAC는 기본적으로 활성화되었어요. RBAC를 비활성화하는 옵션은 비상 메커니즘으로 도입되었고 드문 경우에만 사용되었어요. Grafana v10으로 RBAC를 비활성화하는 구성 옵션을 제거했어요. 이로써 Grafana가 여러 기능에서 일관되게 작동하고 Grafana의 레거시 접근 제어에 문제가 생길 위험이 줄어들어요. 또한 일부 Grafana v10 기능에 대한 접근 제어는 RBAC로만 작동하므로 비활성화는 더 이상 옵션이 아니에요.
마이그레이션 경로 (Migration path)
조치가 필요 없어요. 마이그레이션은 자동이에요. 사용자의 현재 역할, 권한, SSO 매핑, 기타 권한 부여 기능은 이전처럼 계속 작동해요.
사용자 이름이 이제 기본적으로 대소문자를 구분하지 않음 (Usernames are now case-insensitive by default)
다음 경우에 영향을 받아요: (You are affected if:)
Postgres나 sqlite 데이터베이스로 Grafana를 실행하고, 서로 다른 SSO ID 제공자(예: Google, Active Directory)에서 사용자를 가져오며, 서로 다른 제공자에서 로그인한 사용자가 대소문자 차이로(예: "[email protected]" 대 "[email protected]") 이전에 두 번 생성된 경우예요.
배경 (Background)
누군가 Grafana 계정에 가입할 때 이메일이나 로그인으로 가입할 수 있어요. 필드는 대소문자를 구분했기 때문에 같은 사용자에 대해 두 개 이상의 계정이 생성될 수 있었어요. 또한 Grafana는 사용자가 인증 제공자를 설정하게 하며, 그 제공자는 개인의 가입 이메일을 대문자 도메인 이름이나 대소문자 조합으로 반환할 수 있어요.
여러 계정이 있으면 사용자 권한이 분리되고 가입 흐름이 혼란스러워지며 데이터베이스에 사용되지 않는 "좀비" 계정이 생겨요. 게다가 여러 계정은 인증 제공자 사이를 전환할 때 문제를 일으킬 수 있어요. 우리는 사용자 고유성의 이런 불일치를 사용자 ID 충돌이라고 부르죠.
Grafana v10에서의 변경 (Change in Grafana v10)
Grafana는 대소문자와 무관하게 사용자를 일치시키기 시작할 거예요. 충돌하는 사용자는 로그인할 수 없어요.
마이그레이션 경로 (Migration path)
사용자가 잠재적 충돌을 미리 해결할 수 있는 CLI 도구를 만들었어요. 이 주요 변경 사항은 이미 Grafana v9.3에서 공지되었어요.
더 알아보기 (Learn more)
Grafana OAuth 통합이 더 이상 이메일 조회로 작동하지 않음 (Grafana OAuth integrations do not work anymore with email lookups)
다음 경우에 영향을 받아요: (You are affected if:)
- Grafana를 여러 ID 제공자를 사용하도록 구성했고, 여러 ID 제공자에 같은 이메일 주소를 가진 사용자가 있는 경우.
- 고유 ID 필드를 지원하지 않는 ID 제공자와 함께 Generic OAuth를 사용하도록 Grafana를 구성한 경우.
배경 (Background)
Grafana는 예전에 이메일 클레임을 기준으로 ID 제공자 계정을 검증했어요. 많은 ID 제공자에서 이메일 필드는 고유하지 않으며, 이는 특정 시나리오에서 계정 탈취와 인증 우회를 수행할 수 있는 가능한 계정 벡터를 열 수 있었어요. 이 변경은 또한 Grafana가 CVE-2023-3128 취약점으로부터 보호되도록 보장해요.
Grafana v10에서의 변경 (Change in Grafana v10)
Grafana는 영향을 받는 사용자가 로그인하는 것을 허용하지 않아요.
마이그레이션 경로 (Migration path)
오류를 해결하기 위해 이메일 조회를 활성화할 수 있는 탈출구를 제공했어요. Grafana 인스턴스에서 다음 구성을 사용해 이전 동작으로 돌아갈 수 있어요.
[auth]
oauth_allow_insecure_email_lookup = true
Azure AD를 멀티테넌트 앱으로 ID 제공자로 사용하고 있다면 이 작업을 하지 않을 것을 강력히 권장해요.
더 알아보기 (Learn more)
CloudWatch 데이터 소스의 "Alias" 필드가 제거됨 (The "Alias" field in the CloudWatch data source is removed)
다음 경우에 영향을 받아요: (You are affected if:)
동적 레이블 대신 CloudWatch 데이터 소스의 "Alias" 필드를 사용하는 경우예요.
설명 (Description)
CloudWatch 쿼리 편집기의 Alias 패턴은 기능 토글 뒤의 Label(동적 레이블)로 대체되었어요. Grafana v9부터 Label은 기본적으로 활성화되었어요. Grafana v10으로 Label을 비활성화하는 옵션을 제거하고 Alias 필드를 완전히 제거했어요.
마이그레이션 경로 (Migration path)
Alias 필드를 사용하는 각 대시보드를 열고 저장해요. 대시보드를 로드할 때 Alias는 Label로 자동 마이그레이션돼요.
더 알아보기 (Learn more)
Athena 데이터 소스 플러그인을 버전 >=2.9.3으로 업데이트해야 함 (Athena data source plugin must be updated to version >=2.9.3)
다음 경우에 영향을 받아요: (You are affected if:)
Athena 데이터 소스 플러그인을 설치해 사용하고 있는 경우예요.
설명 (Description)
Grafana v10.0.0은 새 React 18 업그레이드를 포함해 출시돼요. 그로 인해 React 18의 상태 업데이트 일괄 처리 변경이 Athena 플러그인 버전 <=2.9.2의 쿼리 편집기에서 버그를 일으켜요.
마이그레이션 경로 (Migration path)
Grafana 인스턴스 관리 콘솔에서 플러그인을 버전 2.9.3 이상으로 업데이트해요. 이렇게 하면 플러그인 쿼리 편집기가 의도한 대로 작동해요.
Redshift 데이터 소스 플러그인을 버전 >=1.8.3으로 업데이트해야 함 (Redshift data source plugin must be updated to version >=1.8.3)
다음 경우에 영향을 받아요: (You are affected if:)
Redshift 데이터 소스 플러그인을 설치해 사용하고 있는 경우예요.
설명 (Description)
Grafana v10.0.0은 새 React 18 업그레이드를 포함해 출시돼요. 그로 인해 React 18의 상태 업데이트 일괄 처리 변경이 Redshift 플러그인 버전 <=1.8.3의 쿼리 편집기에서 버그를 일으켜요.
마이그레이션 경로 (Migration path)
Grafana 인스턴스 관리 콘솔에서 플러그인을 버전 1.8.3 이상으로 업데이트해요. 이렇게 하면 플러그인 쿼리 편집기가 의도한 대로 작동해요.
DoiT International BigQuery 플러그인이 더 이상 지원되지 않음 (DoiT International BigQuery plugin no longer supported)
다음 경우에 영향을 받아요: (You are affected if:)
DoiT International BigQuery 데이터 소스 플러그인을 설치해 사용하고 있는 경우예요.
설명 (Description)
v10.0.0에서 Grafana는 2022년 하반기에 "은퇴" 상태로 이동되었고 2022년 12월에 GitHub 저장소가 보관된 DoiT International BigQuery 데이터 소스 플러그인의 사용을 더 이상 지원하지 않아요. BigQuery 데이터 소스가 계속 작동하려면 공식 Grafana BigQuery 데이터 소스 플러그인으로 마이그레이션해야 해요.
마이그레이션 경로 (Migration path)
Grafana v8.5+를 사용하는 모든 사용자는 영향을 받는 패널의 데이터 소스 선택기에서 데이터 소스를 Grafana BigQuery로 변경하기만 하면 DoiT International BigQuery 커뮤니티 플러그인으로 만든 쿼리를 가져올 수 있어요. 쿼리는 원시 SQL 쿼리로 가져와진다는 점을 참고해요.
더 알아보기 (Learn more)
플러그인 개발자를 위해 (For Plugin Developers)
React 18로 업그레이드 (Upgrading to React 18)
다음 경우에 영향을 받아요: (You are affected if:)
React JS 프레임워크를 사용하는 Grafana 플러그인(대부분의 app, panel, data source 플러그인 포함)을 개발한 경우예요.
설명 (Description)
Grafana가 React 18로 업그레이드되어 이제 새 React 클라이언트 렌더링 API를 활용해요. 특히 플러그인 작성자는 상태 업데이트의 자동 일괄 처리와 일관된 useEffect 타이밍 주변의 변경으로 의도하지 않은 부작용이 있을 수 있으므로 주의해야 해요.
마이그레이션 경로 (Migration path)
플러그인 개발자로서: canary 빌드가(9.5.0 이후) 릴리스되면 여기(예: 이것)의 grafana-dev docker 빌드 중 하나에 대해 플러그인을 테스트해요. React 18이 수행한 추가 최적화 때문에 이전 동작을 유지하려면 일부 변경이 필요할 수 있어요.
더 알아보기 (Learn more)
"@grafana/data"와 "@grafana/ui" 패키지에서 폐기된 로그 관련 함수와 변수 제거 (Deprecated logs-related functions and variables have been removed from the "@grafana/data" and "@grafana/ui" packages)
다음 경우에 영향을 받아요: (You are affected if:)
다음 로그 관련 함수 중 하나를 사용하는 플러그인 작성자인 경우예요:
- grafana-data의 인터페이스 유형 LogsParser
- grafana-ui 패키지의 다음 로그 관련 함수와 클래스:
1LogLabels,LogMessageAnsi,LogRows,getLogRowStyles.,getLogLevel,getLogLevelFromKey,addLogLevelToSeries,LogsParsers,calculateFieldStats,calculateLogsLabelStats,calculateStats,getParser,sortInAscendingOrder,sortInDescendingOrder,sortLogsResult,sortLogRows,checkLogsError,escapeUnescapedString.
설명 (Description)
드물게 사용되는 일부 로그 관련 함수와 변수가 grafana-packages에서 핵심 grafana 코드베이스로 이동했어요. 이 항목들은 이전에 폐기로 표시되었고 grafana changelog에서 폐기 공지가 발행되었어요. 이 함수와 변수를 사용할 수 있다는 것에 의존해 온 플러그인 작성자는 코드베이스를 조정해야 해요.
마이그레이션 경로 (Migration path)
데이터 소스나 패널 플러그인을 작성했다면 폐기되고 제거된 함수와 변수를 사용하지 않는지 확인해요.
더 알아보기 (Learn more)
DataFrame: 필드 값에 Array 또는 Vector 사용 (DataFrame: Use Array or Vector for field values)
다음 경우에 영향을 받아요: (You are affected if:)
데이터 프레임용 자체 버전의 Vector를 구현한 플러그인 작성자인 경우예요.
설명 (Description)
DataFrame 작업은 데이터가 단순한 Array가 아닌 Vector 인터페이스에 저장되었기 때문에 필요 이상으로 복잡했어요. Grafana v10에서 인터페이스를 변경해 개발자가 간단한 배열이나 Vector를 사용할 수 있게 됐어요.
마이그레이션 경로 (Migration path)
Vector를 사용하는 모든 코드는 문제 없이 계속 작동해요. 자체 버전의 Vector를 구현했다면 업데이트해야 해요. 가장 쉬운 방법은 코드를 리팩터링해 MutableVector를 확장하는 것이에요. 이는 Grafana v9와 v10 모두에서 작동해요.
더 알아보기 (Learn more)
grafana/toolkit CLI 명령어가 제거되고 create-plugin 패키지로 마이그레이션됨 (grafana/toolkit CLI commands have been removed and migrated to the create-plugin package)
다음 경우에 영향을 받아요: (You are affected if:)
@grafana/toolkit CLI 명령어로 플러그인을 개발하는 경우예요.
설명 (Description)
v9.3(2022년 11월)에서 grafana/toolkit의 폐기를 발표했고, 이제 create-plugin이라는 새 도구를 대안으로 사용할 수 있어요. 마이그레이션하고 업데이트된 도구를 사용할 것을 권장해요. build를 제외한 모든 grafana/toolkit 명령어가 Grafana v10에서 제거됐어요.
create-plugin의 몇 가지 이점은 다음과 같아요:
- 더 유연함: @grafana/create-plugin을 사용하면 플러그인과 그 의존성을 더 잘 제어하고 특정 요구 사항에 맞게 도구를 더 쉽게 커스터마이징할 수 있어요.
- 더 빠른 개발 시간: 기본 제공 개발 환경으로 @grafana/create-plugin은 @grafana/toolkit보다 개발 시간을 크게 줄일 수 있어요.
- 향상된 테스트 기능: @grafana/create-plugin으로 플러그인을 테스트하는 것은 변경 사항이 GitHub에 푸시될 때마다 단위 및 e2e 테스트 실행을 자동화하는 GitHub 워크플로로 훨씬 쉬워요.
- 더 나은 문서: @grafana/create-plugin용 문서는 @grafana/toolkit보다 더 포괄적이고 찾기 쉬워요.
마이그레이션 경로 (Migration path)
이미 새 도구를 사용하고 있을 수도 있어요. @grafana/toolkit으로 만든 기존 플러그인이 있다면 다음 명령어로 새 빌드 도구로 마이그레이션할 수 있어요:
# 플러그인의 루트에서 이 명령어를 실행해요
cd ./my-plugin
npx @grafana/create-plugin@latest migrate
더 알아보기 (Learn more)
폐기 사항 (Deprecations)
API를 통해 폴더 UID를 변경하는 것은 폐기됐어요. 이 기능은 향후 릴리스에서 제거될 거예요.