Grafana v9.0으로 업그레이드

Grafana v9.0으로 업그레이드 (Upgrade to Grafana v9.0)

최신 수정 사항과 개선 사항을 유지하려면 Grafana를 자주 업그레이드하는 것이 좋아요. Grafana 업그레이드는 하위 호환되므로 업그레이드 과정은 간단하며, 대시보드와 그래프는 변경되지 않아요.

출처: 문서

본문

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

Note

일부 릴리스에는 호환성이 깨지는 변경(breaking changes)이 있을 수 있어요. 대부분의 릴리스의 경우 What's New 문서에, 호환성이 깨지는 변경이 많은 릴리스의 경우 별도의 Breaking changes 문서에 이러한 변경 사항을 정리해 두고 있어요.

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

가능할 때 모든 변경 사항을 pull request 또는 이슈 링크와 함께 Changelog에 나열해요.

Note

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

Grafana 백업 (Back up Grafana)

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

Grafana 구성 파일 백업 (Back up the Grafana configuration file)

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

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

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

구성 파일을 찾을 수 있는 위치에 대한 자세한 내용은 구성 파일 위치를 참조해요.

Note

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

플러그인 데이터 백업 (Back up plugin data)

Grafana에서 플러그인을 설치하면 각 플러그인마다 관련 파일과 데이터가 담긴 폴더가 만들어져요. 이 위치의 모든 파일과 폴더를 백업 저장소에 재귀적으로 복사해요.

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

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

Grafana 데이터베이스 백업 (Back up the Grafana database)

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

SQLite

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

Note

데이터 무결성을 보장하려면 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 < grafana_backup.sql

Postgres

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

backup:
> pg_dump grafana > grafana_backup

restore:
> psql grafana < grafana_backup

Grafana 업그레이드 (Upgrade Grafana)

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

Debian

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

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

이렇게 하면 구성 변경 사항을 잃을 위험 없이 Grafana를 업그레이드할 수 있어요.
최신 버전의 Grafana를 다운로드해요.
다음 dpkg -i 명령을 실행해요.

wget <debian package url>
sudo apt-get install -y adduser
sudo dpkg -i grafana_<version>_amd64.deb

APT 저장소

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

현재 Grafana 설치에서 사용자 지정 구성 변경 사항을 <grafana_install_dir>/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_install_dir>/grafana.ini라는 파일에 저장해요.

이렇게 하면 구성 변경 사항을 잃을 위험 없이 Grafana를 업그레이드할 수 있어요.
설치 방법에 따라 다음 중 하나를 수행해요.

RPM 패키지를 다운로드해 Grafana를 설치했다면, Red Hat, RHEL 또는 Fedora에 Grafana 설치 또는 SUSE 또는 openSUSE에 Grafana 설치 문서에 있는 단계에 따라 Grafana를 업그레이드해요.
Grafana YUM 저장소를 사용했다면 다음 명령을 실행해요:

sudo yum update grafana

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

sudo zypper update

Docker

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

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

이렇게 하면 구성 변경 사항을 잃을 위험 없이 Grafana를 업그레이드할 수 있어요.
다음 명령과 유사한 명령을 실행해요.

Note

이것은 예시예요. 입력하는 매개변수는 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 설치에서 사용자 지정 구성 변경 사항을 <grafana_install_dir>/conf/custom.ini라는 파일에 저장해요.

이렇게 하면 구성 변경 사항을 잃을 위험 없이 Grafana를 업그레이드할 수 있어요.
Windows 바이너리 패키지를 다운로드해요.
패키지의 내용을 Grafana를 설치한 위치에 추출해요.

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

Mac

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

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

이렇게 하면 구성 변경 사항을 잃을 위험 없이 Grafana를 업그레이드할 수 있어요.
Mac 바이너리 패키지를 다운로드해요.
패키지의 내용을 Grafana를 설치한 위치에 추출해요.

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

Grafana 플러그인 업데이트 (Update Grafana plugins)

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

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

grafana cli plugins update-all

기술 노트 (Technical notes)

이 섹션은 이번 Grafana 릴리스와 관련된 기술 변경 사항을 설명해요.

역할 기반 접근 제어: 일반 공급(GA) 변경 사항 (Role-based access control: changes for general release)

세밀한 접근 제어는 이제 "역할 기반 접근 제어(RBAC, Role-based access control)"라고 불려요. Grafana 9.0 릴리스의 일부로 이 기능이 일반 공급(GA)되었고, 몇 가지 호환성이 깨지는 변경 사항이 있어요:

기본 제공 역할(built-in roles)은 이제 기본 역할(basic roles)이라고 불려요. 이제 역할이 아닌 권한으로 구성돼요.
Terraform builtin_role_assignment 리소스는 더 이상 사용되지 않아요. 대신 grafana_role 리소스를 사용해요.
Grafana 프로비저닝은 새 스키마를 사용해요. 프로비저닝에 대한 자세한 내용은 Grafana로 RBAC 프로비저닝을 참조해요.
기본 역할은 더 이상 권한 상속을 지원하지 않아요. 이전에는 Viewer 기본 역할의 권한이 수정되면 Editor와 Admin 기본 역할로 전파됐지만, Grafana 9.0 릴리스부터는 그렇지 않아요.
여러 역할 기반 접근 제어 작업의 이름이 바뀌었어요. 기존 작업 이름을 사용하는 모든 데이터베이스 항목은 새 이름으로 마이그레이션되지만, 프로비저닝 파일과 스크립트는 사용자가 업데이트해야 해요. 이 변경은 Grafana를 9.0에서 더 낮은 버전으로 다운그레이드하면 일부 역할 기반 접근 제어 권한이 올바르게 해석되지 않는다는 의미이기도 해요.

Loki: 로그 데이터 형식 변경 (Loki: logs data format changed)

Loki 데이터 소스에서 Loki 로그 데이터를 나타내는 데 사용되는 데이터 형식이 더 효율적인 형식으로 변경됐어요. (참고: 이 변경은 로그 데이터에만 적용되며 숫자 데이터에는 적용되지 않아요) 로그는 모든 레이블 조합에 대한 별도의 데이터프레임 대신 "labels" 필드가 추가된 단일 데이터프레임으로 표현돼요. explore 또는 로그 패널을 사용하는 대시보드에서 로그 데이터를 표시하는 것은 변경 없이 계속 작동해요. 그러나 테이블 시각화 같은 다른 대시보드 패널에서 로그 데이터를 표시할 때는 변경 내용이 보이고 구성 조정이 필요할 수 있어요. 예를 들어 "Labels to fields" 변환을 사용했다면, "labels" 필드를 소스로 선택한 "Extract fields" 변환으로 교체해야 해요.

Loki: 숫자 데이터의 NaN 값 표현 변경 (Loki: NaN values representation changed in numeric data)

Loki 데이터 소스에서 Grafana가 Loki로부터 숫자 데이터를 받을 때 NaN(숫자가 아님) 값이 포함될 수 있어요. 일관성과 성능을 위해 Grafana에서 이러한 값을 표현하는 방식을 변경했어요. 이전 버전에서는 알림 쿼리와 다른 쿼리(대시보드 쿼리나 explore 쿼리 등) 사이의 동작이 달랐어요. 알림 쿼리는 NaN 값을 변경하지 않고 유지했지만, 다른 쿼리는 이 값을 "null"로 변환했어요. grafana 9.0.0부터는 이 값을 항상 변경하지 않고 유지해요. 즉, 대시보드와 explore의 쿼리는 이 점에서 알림 쿼리와 동일하게 동작해요.

Elasticsearch: 수명이 끝난 버전에 대한 지원 제거 (Elasticsearch: Support for versions after their end of life was removed)

수명이 끝난(after their end of life, https://www.elastic.co/support/eol 기준) Elasticsearch 버전에 대한 지원이 제거됐어요. 즉, Elasticsearch 7.10.0보다 오래된 버전은 Grafana 9.0.0에서 지원되지 않아요.

Elasticsearch: 브라우저 액세스 모드 지원 제거 (Elasticsearch: Support for browser access mode removed)

Elasticsearch 데이터 소스에서 브라우저 액세스 모드는 grafana 7.4.0에서 폐기되었고 9.0.0에서 제거됐어요. 이 모드를 사용했다면 데이터 소스 구성 페이지에서 서버 액세스 모드로 전환해요.

Prometheus: 숫자 데이터의 NaN 값 표현 변경 (Prometheus: NaN values representation changed in numeric data)

Prometheus 데이터 소스에서 Grafana가 Prometheus로부터 숫자 데이터를 받을 때 NaN(숫자가 아님) 값이 포함될 수 있어요. 일관성과 성능을 위해 Grafana에서 이러한 값을 표현하는 방식을 변경했어요. 이전 버전에서는 알림 쿼리와 다른 쿼리(대시보드 쿼리나 explore 쿼리 등) 사이의 동작이 달랐어요. 알림 쿼리는 NaN 값을 변경하지 않고 유지했지만, 다른 쿼리는 이 값을 "null"로 변환했어요. grafana 9.0.0부터는 모든 쿼리에 대해 NaN 값을 항상 변경하지 않고 유지해요.

변환: rename by regex에서 더 복잡한 정규식 허용 (Transformations: Allow more complex regex expressions in rename by regex)

rename by regex 변환은 /<stringToReplace>/g 형태의 전역 패턴을 허용하도록 개선됐어요. 사용된 정규식 매칭에 따라 일부 변환의 동작이 약간 달라질 수 있어요. 매칭 문자열을 슬래시(/)로 감싸면 이전과 동일한 동작을 보장할 수 있어요. 예를 들어 (.*)는 /(.*)/가 돼요. (Github Issue #48179)

Clock 패널 (Clock Panel)

clock panel을 Grafana 9와 호환되도록 버전 2.0.0으로 업데이트했어요. 이전 버전 1.3.1은 대시보드에서 사용할 때 Grafana 9가 충돌하도록 만들 수 있으므로, Grafana 9로 마이그레이션하기 전에 패널을 업데이트할 것을 권장해요.

Polystat 패널 (Polystat Panel)

polystat panel을 Grafana 9와 호환되도록 버전 1.2.10으로 업데이트했어요. 이전 버전 1.2.8 이하는 Grafana 9에서 빈 상태로 렌더링돼요. Grafana 9로 마이그레이션하기 전이나 직후에 패널을 업데이트할 것을 권장해요.

기본적으로 활성화되는 Envelope 암호화 (Envelope encryption enabled by default)

v8.3부터 Grafana 데이터베이스에 저장되는 비밀(데이터 소스 자격 증명, 알림 알림 채널 자격 증명, oauth 토큰 등)을 위해 envelopeEncryption이라는 기능 토글 뒤에서 "envelope encryption"이라는 새로운 암호화 방식이 추가됐어요.

v9.0에서는 envelopeEncryption 기능 토글이 disableEnvelopeEncryption으로 대체되었고, envelope encryption이 기본적으로 사용되는 암호화 메커니즘이 됐어요.

따라서 Grafana v9.0에서 생성되거나 업데이트된 모든 비밀은, 이전 버전에서 envelopeEncryption 기능 토글이 활성화되지 않는 한(v8.3 이후에서만 사용 가능) 이전 Grafana 버전으로는 복호화할 수 없어요. 이는 고가용성 설정, 점진적 롤아웃, 또는 어떤 이유로든 이전 Grafana 버전으로 롤백해야 하는 경우에 고려해야 해요.

여기서 권장하는 것은 이전 버전에서 envelopeEncryption을 활성화하거나, v9.0으로 업그레이드하기 전에 disableEnvelopeEncryption을 활성화하는 것까지예요. 다만 후자는 다음 릴리스 중 하나에서 제거될 가능성이 높으므로, envelope encryption으로 전환할 것을 강력히 권장해요.

원하지 않는 상황에 빠졌을 때 더 자세한 내용과 가능한 해결 방법은 여기에서 찾아볼 수 있어요.

Grafana Enterprise 라이선싱에 대한 참고 (A note on Grafana Enterprise licensing)

6월 14일에 Grafana 9.0을 릴리스할 때 Grafana는 더 이상 viewer와 editor-admin을 다르게 적용하지 않아요. 즉, Grafana Enterprise 라이선스가 계층형(tiered)이든 결합형(combined)이든, Stats & Licensing 페이지에서 다음과 같이 표시되는 대신:

별도 라이선스 (Separate license)

다음과 같이 표시돼요:

결합 라이선스 (Combined license)

또한 Grafana가 역할에 관계없이 모든 사용자를 동일하게 집계한다는 뜻이기도 해요. 여기에는 조직 역할(Viewer, Editor, Admin)과 세밀한 역할(Dashboard Editor, Reports Editor 등)이 모두 포함돼요. viewer 또는 editor-admin 한도에 도달해도 별도의 경고 배너가 표시되거나 사용자가 잠기지 않으며, 활성 사용자의 총 결합 한도만 적용돼요.

예를 들어 Grafana Enterprise 라이선스에 활성 관리자 10명과 활성 viewer 100명에 대한 라이선스가 있다면, v9.0부터 활성 사용자 110명의 한도가 적용되며 사용자 역할이 무엇이든 상관없이 모두 동일하게 집계되고 적용돼요.

이것은 이전보다 더 관대한 정책이에요.

Grafana v9.0으로 업그레이드