Grafana v13.0으로 업그레이드

최신 수정 사항과 개선 사항을 반영하려면 Grafana를 자주 업그레이드하는 것을 권장해요. Grafana 업그레이드는 하위 호환(backward compatible)되므로 업그레이드 과정은 간단하며, 대시보드와 그래프는 변하지 않아요.

모든 버전의 Grafana에서 완료해야 하는 공통 작업 외에도, 특정 버전에서 완료해야 하는 추가 업그레이드 작업이 있을 수 있어요.

참고

일부 릴리스에는 호환성이 깨지는 변경(breaking changes)이 있을 수 있어요. 이러한 변경 사항은 모두 What's New 문서에 정리되어 있어요.

v9.2 이전 버전의 Grafana에 대해서는 Release Notes에서 추가 정보를 제공했어요.

가능할 때 모든 변경 사항을 풀 리퀘스트 또는 이슈 링크와 함께 Changelog에 나열해요.

가능하다면 테스트 또는 개발 환경에서 Grafana 업그레이드 과정을 먼저 테스트해 볼 것을 권장해요.

출처: 문서

본문

Grafana 백업하기

이 주제에서는 구성(configuration), 플러그인 데이터, Grafana 데이터베이스를 포함한 로컬 Grafana 배포(deployment)를 백업하는 방법을 설명해요.

Grafana 구성 파일 백업

Grafana 배포에서 수정했을 수 있는 구성 파일을 백업 디렉터리에 복사하세요.

Grafana 구성 파일은 다음 디렉터리에 있어요:

기본 구성: $WORKING_DIR/defaults.ini (이 파일은 변경하지 마세요)
사용자 지정 구성: $WORKING_DIR/custom.ini

구성 파일을 찾는 위치에 대한 자세한 내용은 구성 파일 위치 문서를 참고하세요.

참고

deb 또는 rpm 패키지로 Grafana를 설치했다면 구성 파일은 /etc/grafana/grafana.ini에 있어요. 이 경로는 Grafana init.d 스크립트에서 --config 파일 매개변수를 사용해 지정돼요.

플러그인 데이터 백업

Grafana에서 플러그인을 설치하면 각 플러그인에 대한 폴더가 해당 파일과 데이터와 함께 생성돼요. 이 위치에서 모든 파일과 폴더를 재귀적으로 복사해 백업 저장소에 옮기세요.

Grafana 플러그인 파일은 다음 디렉터리에 있어요:

바이너리 또는 소스 설치의 플러그인 기본 위치: $WORKING_DIR/data/plugins
deb 또는 rpm 패키지의 플러그인 기본 위치: /var/lib/grafana/plugins. 이 경로는 Grafana init.d 스크립트에서 --config 파일 매개변수를 사용해 지정돼요.

Grafana 데이터베이스 백업

필요할 때 이전 버전으로 롤백할 수 있도록 Grafana 데이터베이스를 백업하는 것을 권장해요.

SQLite

Grafana의 기본 데이터베이스는 SQLite이며, 데이터를 디스크의 단일 파일에 저장해요. 이 파일을 백업하려면 백업 저장소에 복사하세요.

참고

데이터 무결성을 보장하려면 SQLite 데이터베이스를 백업하기 전에 Grafana 서비스를 종료하세요.

SQLite 데이터베이스 파일은 다음 디렉터리 중 하나에 있어요:

바이너리 또는 소스 설치의 SQLite 데이터 기본 위치: $WORKING_DIR/data/grafana.db
deb 또는 rpm 패키지의 SQLite 데이터 기본 위치: /var/lib/grafana/grafana.db. 이 경로는 Grafana init.d 스크립트에서 --config 파일 매개변수를 사용해 지정돼요.

MySQL

MySQL Grafana 데이터베이스를 백업하거나 복원하려면 다음 명령을 실행하세요:

backup:
> mysqldump -u root -p[root_password] [grafana] > grafana_backup.sql

restore:
> mysql -u root -p grafana

Postgres

Postgres Grafana 데이터베이스를 백업하거나 복원하려면 다음 명령을 실행하세요:

backup:
> pg_dump grafana > grafana_backup

restore:
> psql grafana

Grafana 업그레이드

다음 섹션은 설치 방식에 따라 Grafana를 업그레이드하는 방법을 설명해요. 구성 파일을 찾는 위치에 대한 자세한 내용은 구성 파일 위치 문서를 참고하세요.

Debian

Debian 패키지(.deb)로 설치한 Grafana를 업그레이드하려면 다음 단계를 완료하세요:

현재 Grafana 설치에서 사용자 지정 구성 변경 사항을 /grafana.ini라는 파일에 저장하세요.

이렇게 하면 구성 변경 사항을 잃을 위험 없이 Grafana를 업그레이드할 수 있어요.

최신 버전의 Grafana를 다운로드하세요.
다음 dpkg -i 명령을 실행하세요.

wget
sudo apt-get install -y adduser
sudo dpkg -i grafana__amd64.deb

APT 저장소

Grafana Labs APT 저장소에서 설치한 Grafana를 업그레이드하려면 다음 단계를 완료하세요:

현재 Grafana 설치에서 사용자 지정 구성 변경 사항을 /grafana.ini라는 파일에 저장하세요.

이렇게 하면 구성 변경 사항을 잃을 위험 없이 Grafana를 업그레이드할 수 있어요.

다음 명령을 실행하세요:

sudo apt-get update
sudo apt-get upgrade

apt-get upgrade를 실행하면 Grafana가 자동으로 업데이트돼요.

바이너리 .tar 파일

바이너리 .tar.gz 패키지로 설치한 Grafana를 업그레이드하려면 다음 단계를 완료하세요:

현재 Grafana 설치에서 사용자 지정 구성 변경 사항을 사용자 지정 구성 파일인 custom.ini 또는 grafana.ini에 저장하세요.

이렇게 하면 구성 변경 사항을 잃을 위험 없이 Grafana를 업그레이드할 수 있어요.

바이너리 .tar.gz 패키지를 다운로드하세요.
다운로드한 패키지를 추출하고 기존 파일을 덮어쓰세요.

RPM 또는 YUM

RPM 또는 YUM을 사용해 설치한 Grafana를 업그레이드하려면 다음 단계를 완료하세요:

현재 Grafana 설치에서 사용자 지정 구성 변경 사항을 /grafana.ini라는 파일에 저장하세요.

이렇게 하면 구성 변경 사항을 잃을 위험 없이 Grafana를 업그레이드할 수 있어요.

설치 방식에 따라 다음 중 하나를 수행하세요.
Grafana를 설치하기 위해 RPM 패키지를 다운로드했다면, Grafana를 업그레이드하려면 Red Hat, RHEL, Fedora에 Grafana 설치 또는 SUSE, openSUSE에 Grafana 설치에 문서화된 단계를 완료하세요.
Grafana YUM 저장소를 사용했다면 다음 명령을 실행하세요:

sudo yum update grafana

openSUSE 또는 SUSE에 Grafana를 설치했다면 다음 명령을 실행하세요:

sudo zypper update

Docker

Docker 컨테이너에서 실행 중인 Grafana를 업그레이드하려면 다음 단계를 완료하세요:

Grafana 환경 변수를 사용해 사용자 지정 구성을 저장하세요. 이것이 권장되는 방법이에요. 또는 배포된 컨테이너에 접근해 구성 파일을 수동으로 확인할 수 있어요.

이렇게 하면 구성 변경 사항을 잃을 위험 없이 Grafana를 업그레이드할 수 있어요.

다음 명령과 유사한 명령을 실행하세요.

참고

이는 예시일 뿐이며, 입력하는 매개변수는 Grafana 컨테이너를 구성한 방식에 따라 달라져요.

docker pull grafana/grafana
docker stop my-grafana-container
docker rm my-grafana-container
docker run -d --name=my-grafana-container --restart=always -v /var/lib/grafana:/var/lib/grafana grafana/grafana

Windows

Windows에 설치한 Grafana를 업그레이드하려면 다음 단계를 완료하세요:

현재 Grafana 설치에서 사용자 지정 구성 변경 사항을 /conf/custom.ini라는 파일에 저장하세요.

이렇게 하면 구성 변경 사항을 잃을 위험 없이 Grafana를 업그레이드할 수 있어요.

Windows 바이너리 패키지를 다운로드하세요.
패키지 내용물을 Grafana를 설치한 위치에 추출하세요.

메시지가 표시되면 기존 파일과 폴더를 덮어쓸 수 있어요.

Mac

Mac에 설치한 Grafana를 업그레이드하려면 다음 단계를 완료하세요:

현재 Grafana 설치에서 사용자 지정 구성 변경 사항을 사용자 지정 구성 파일인 custom.ini에 저장하세요.

이렇게 하면 구성 변경 사항을 잃을 위험 없이 Grafana를 업그레이드할 수 있어요.

Mac 바이너리 패키지를 다운로드하세요.
패키지 내용물을 Grafana를 설치한 위치에 추출하세요.

메시지가 표시되면 기존 파일과 폴더를 덮어쓸 수 있어요.

Grafana 플러그인 업데이트

Grafana를 업그레이드한 후에는 모든 플러그인을 업데이트하는 것을 권장해요. 새 버전의 Grafana는 이전 플러그인이 제대로 작동하지 않게 만들 수 있기 때문이에요.

플러그인을 업데이트하려면 다음 명령을 실행하세요:

grafana cli plugins update-all

기술 참고 사항 (Technical notes)

경고

Git Sync 얼리 어답터 주의: Grafana v13.0.0의 마이그레이션 버그로 인해 Git Sync가 활성화된 상태에서 Grafana v12.x.x에서 업그레이드할 때 대시보드와 폴더가 손실되거나 되돌아갈(revert) 수 있어요. v13.0.0에서 v13.0.1로 업그레이드해도 손실된 데이터는 복구되지 않으며, 이미 업그레이드했다면 먼저 데이터베이스를 복원한 다음 v13.0.1로 업그레이드해야 해요.

이 버그는 Grafana v12.x.x에서 Git Sync 기능 플래그(provisioning, kubernetesClientDashboardsFolders, kubernetesDashboards)가 활성화된 자체 관리형 인스턴스에만 영향을 미쳐요.

Grafana v13.0.0은 배포에서 제거되었으며 수정 사항은 Grafana v13.0.1에서 배포됐어요.

영향받는 경우 다음 복구 경로를 사용하세요:

인스턴스가 로컬 콘텐츠와 Git Sync 콘텐츠를 혼합해 사용한 경우: 업그레이드 전에 만든 데이터베이스 백업에서 복원한 다음 Grafana v13.0.1로 업그레이드하세요.

인스턴스가 전체 인스턴스 Git Sync를 사용한 경우: Grafana v13.0.1로 업그레이드하고 Git 저장소에서 다시 동기화하세요.

확실하지 않은 경우: v13.0.1로 업그레이드하기 전에 데이터베이스 백업에서 복원하세요.

React 19 관련 업데이트

Grafana 13에서 React 19로 마이그레이션하는 과정의 일환으로, 플러그인이 제대로 작동하고 Grafana 13 업그레이드 중 중단이 발생하지 않도록 다음 업데이트를 수행하세요.

최상의 결과를 위해 다음 순서를 따르세요:

실행 중인 버전의 최신 패치 버전으로 Grafana를 업그레이드하세요

React 19로의 업그레이드에 필요한 변경 사항이 Grafana 버전에 반영되도록, Grafana 인스턴스에서 사용 가능한 최신 마이너 버전으로 업데이트하세요. 사용 가능한 버전은 다운로드 페이지에서 확인할 수 있어요.

모든 플러그인을 업데이트하세요

설치된 모든 플러그인을 업데이트하고 여전히 제대로 작동하는지 확인하세요. 최신 버전의 플러그인을 사용하면 React 19를 지원할 수 있어요.

Grafana 13으로 업그레이드하세요

마지막으로 Grafana 13으로 업그레이드를 계속할 수 있어요.

레거시 /api 엔드포인트가 이제 사용 중단(deprecated)됨

Grafana는 기존 API를 표준화된 API 구조와 일관된 API 버전 관리를 따르는 Kubernetes 스타일 API 계층인 새 /apis 모델로 이전하고 있어요. 자세한 내용은 Grafana 문서의 새 API 구조를 참고하세요.

레거시 API는 현재 비활성화되지 않아요. 레거시 API 제거는 향후 주요 릴리스에서 계획되어 있으며, 어떠한 호환성 손상 변경도 중단을 피하기 위해 사전에 충분히 공지될 거예요.

자세한 내용과 마이그레이션 안내는 새 API로 마이그레이션을 참고하세요.

사용 중단된 데이터 소스 API 비활성화됨

데이터 소스를 숫자 id로 참조하는 데이터 소스 API는 Grafana 9부터 사용 중단됐어요. Grafana 13에서는 기본적으로 비활성화돼요.

다음 경우에 영향받아요

데이터 소스를 uid가 아닌 숫자 id로 참조하는 데이터 소스 API 엔드포인트를 사용하는 경우예요.

마이그레이션

API 호출이 데이터 소스를 숫자 id 대신 uid로 참조하도록 업데이트하세요. 사용 중단된 API를 일시적으로 다시 활성화하려면 datasourceLegacyIdApi 기능 플래그를 활성화하세요. 사용 중단된 API와 기능 토글은 모두 향후 릴리스에서 제거될 거예요.

Image Renderer 플러그인 지원 제거됨

Grafana 13에서는 Image Renderer 플러그인에 대한 지원이 제거됐어요.

다음 경우에 영향받아요

Image Renderer를 Grafana 플러그인으로 실행하는 경우예요. 업그레이드 후 플러그인은 스크린샷이나 예약된 보고서 렌더링에 더 이상 작동하지 않아요.

마이그레이션

이미지 렌더러를 Grafana 옆에 별도 서비스로 배포하세요. 설정 지침은 이미지 렌더링 설정을 참고하세요.

Image Renderer 기본 인증이 JWT로 변경됨

Image Renderer는 이전에 스크린샷과 PDF를 생성할 때 데이터베이스에 저장된 불투명 토큰(opaque token)으로 Grafana에 인증했어요. Grafana v13.0은 renderAuthJWT 기능 토글을 기본적으로 활성화해, 인증을 데이터베이스에 의존하지 않는 무상태(stateless) JSON Web Token(JWT)으로 전환해요.

필요한 조치

Grafana v13.0으로 업그레이드한 후 Image Renderer를 사용한다면 Grafana 구성 파일의 [rendering]renderer_token을 비어 있지 않거나 기본값(-)이 아닌 값으로 설정하고, Image Renderer를 동일한 토큰 값으로 구성해야 해요. 변경 사항을 적용하려면 Grafana 인스턴스를 다시 시작하세요.

자세한 내용은 Image Renderer 보안 구성 문서를 참고하세요.

이전 동작으로 되돌리기

Grafana v13.0으로 업그레이드한 후 불투명 토큰 인증으로 되돌리려면 Grafana 구성 파일에서 기능 토글을 비활성화하세요:

[feature_toggles]
renderAuthJWT = false

변경 사항을 적용하려면 Grafana 인스턴스를 다시 시작하세요.

폴더와 대시보드의 통합 저장소(unified storage)

Grafana v13.0은 시작 시 레거시 SQL 데이터베이스에서 통합 저장소로 폴더와 대시보드를 자동으로 마이그레이션해요. 마이그레이션은 한 번 실행되며 unifiedstorage_migration_log 테이블에 추적돼요.

마이그레이션이 완료된 후 다음 레거시 테이블은 사용 중단돼요:

dashboard
dashboard_acl
dashboard_provisioning
dashboard_version
dashboard_tag
library_element_connection
folder

이 테이블은 향후 릴리스에서 제거될 거예요.

마이그레이션 후 이전 Grafana 버전으로 다운그레이드하면, 이전 버전은 오래된 레거시 테이블을 읽어 통합 저장소에서 이루어진 변경 사항을 반영하지 않아요. 롤백하려면 업그레이드 전에 만든 데이터베이스 백업에서 복원하세요.

백업을 복원하지 않고 다운그레이드한 후 다시 업그레이드하면, 다운그레이드 중에 생성되거나 수정된 폴더나 대시보드는 자동으로 마이그레이션되지 않아요. 백업이 없다면 Grafana 지원팀에 문의해 도움을 받으세요.

SQLite 배포

SQLite를 사용한다면 잠금 경합(lock contention)으로 인해 database is locked 또는 database table is locked 오류로 마이그레이션이 실패할 수 있어요. Grafana는 Parquet 버퍼를 사용해 자동으로 재시도하지만, 오류가 계속되면 구성 파일의 [unified_storage] 섹션에서 migration_cache_size_kb를 늘리거나 migration_parquet_buffer를 활성화하세요:

설정	설명	기본값
migration_cache_size_kb	마이그레이션 중 SQLite 페이지 캐시 크기	1000000 (~1 GB)
migration_parquet_buffer	읽기·쓰기 단계를 분리해 잠금 경합을 피하기 위해 임시 Parquet 파일로 데이터를 단계적으로 저장	false

grafana-cli 및 grafana-server 명령 제거됨

Grafana v10.0부터 사용 중단된 grafana-cli 및 grafana-server 명령은 Grafana v13.0에서 제거됐어요. 스크립트, systemd 유닛, Docker 진입점, CI 파이프라인 또는 기타 자동화에서 grafana cli 및 grafana server를 사용하도록 업데이트하세요.

레거시 Alertmanager 구성 API 엔드포인트 변경됨

Grafana v13.0에서는 여러 레거시 Alertmanager 구성 API 엔드포인트가 제거되거나 제한돼요:

DELETE /api/alertmanager/grafana/config/api/v1/alerts가 제거됐어요.
POST /api/alertmanager/grafana/config/api/v1/receivers/test가 제거됐어요.
GET /api/alertmanager/grafana/config/api/v1/alerts는 관리자 사용자로 제한돼요.
GET /api/alertmanager/grafana/config/history는 관리자 사용자로 제한돼요.
POST /api/alertmanager/grafana/config/history/{id}/_activate는 관리자 사용자로 제한돼요.

다음 경우에 영향받아요

자동화 스크립트, Terraform 프로바이더 또는 사용자 지정 도구에서 이러한 엔드포인트 중 하나를 호출하는 경우예요.

마이그레이션

notifications.alerting.grafana.app/v1beta1 아래의 Kubernetes 스타일 리소스 API로 마이그레이션하세요:

리소스	API 경로
Receivers	/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers
Notification policies	/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/routingtrees
Templates	/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/templategroups
Mute timings	/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/timeintervals
Inhibition rules	/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/inhibitionrules
Receiver testing	/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers/{uid}/test

Alertmanager 상태 엔드포인트에 새 권한 필요

다음 경우에 영향받아요

GET /api/alertmanager/grafana/api/v2/status 엔드포인트를 사용하고 이에 접근하기 위해 alert.notifications:read 권한에 의존하는 경우예요.

설명

GET /api/alertmanager/grafana/api/v2/status 엔드포인트는 이전에 레거시 alert.notifications:read 권한을 요구했어요. 이제 전용 alert.notifications.system-status:read 권한을 요구해요. 이 새 권한은 기본적으로 Admin 사용자에게 부여되는 fixed:alerting.notifications:writer 역할에 포함돼요.

마이그레이션

이 엔드포인트에 접근해야 하는 사용자 지정 역할이 있다면 해당 역할에 alert.notifications.system-status:read 작업(action)을 추가하세요. Admin 사용자는 기본 제공되는 알림 작성자 역할을 통해 이 권한을 자동으로 받으므로 영향받지 않아요.

사용자 지정 역할의 RBAC 적용 변경

Grafana v13.0은 사용자 지정 역할, Terraform 관리 역할, 역할 프로비저닝에 대한 RBAC 적용을 강화해요. 사용 중단된 권한을 포함하는 역할은 생성, 업데이트, 삭제 또는 할당 작업 중 실패할 수 있어요. 영향받는 역할을 사전에 검토하고 업데이트하는 것을 권장해요.

다음 경우에 영향받아요

Terraform, API 또는 프로비저닝을 통해 사용자 지정 RBAC 역할을 관리하고 해당 역할에 다음 중 하나가 포함된 경우:

전역 역할의 데이터 소스 UID 범위 권한(datasources:uid:)
fixed:annotations.dashboard:writer 또는 fixed:annotations.dashboard:reader
annotations:type:dashboard
annotations:*

마이그레이션

전역 역할의 데이터 소스 권한: Terraform 관리 grafana_role이 global = true와 datasources:uid:를 결합하는 경우 새 UID로 비전역 역할로 다시 생성하세요. Grafana는 기존 역할의 범위를 그 자리에서 변경할 수 없어요. 가능하면 데이터 소스 권한 리소스에 datasource_type을 설정하세요.

대시보드 annotation 고정 역할: 구성에서 fixed:annotations.dashboard:writer 및 fixed:annotations.dashboard:reader를 제거하세요. 대신 대시보드 또는 폴더 권한(View, Edit, Admin)을 사용해 대시보드 annotation 접근을 제어하세요. 조직 수준 annotation에는 annotations:type:organization을 사용하세요.

annotations:* 와일드카드 범위: 특정 범위로 바꾸세요. 조직 annotation에는 annotations:type:organization을, 대시보드 annotation에는 대시보드 또는 폴더 권한을 사용하세요. 제거된 후에는 Terraform에서 annotations:*를 다시 만들지 마세요.

Grafana가 역할 업데이트나 삭제를 거부해 역할이 막혔다면, 역할에 Terraform 또는 API 업데이트가 성공하기 전에 제거해야 할 사용 중단된 권한이 포함된 것일 수 있어요. Grafana 지원팀에 문의해 도움을 받으세요.

자세한 예시와 문제 해결은 Grafana 13의 RBAC 동작 변경을 참고하세요.

Grafana v13.0으로 업그레이드