Grafana v11.2로 업그레이드

Grafana v11.2로 업그레이드 (Upgrade to Grafana v11.2)

최신 수정 사항과 개선 사항을 유지하려면 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 데이터 소스 UID 형식 적용 (Grafana data source UID format enforcement)

데이터 소스 UID가 올바른 표준을 따르는지 확인해요.

Grafana 객체의 UID를 정의하는 표준 방식이 수년간 있었어요(적어도 Grafana v5 이후). 내부 코드는 모두 이 형식을 따르지만, 데이터 소스의 생성과 업데이트를 허용하는 REST API와 프로비저닝 경로에서는 아직 이 형식을 엄격하게 적용하지 않았어요.

Grafana v11.1에서 잘못된 UID 형식으로 데이터 소스 인스턴스를 생성하거나 업데이트할 때마다 Grafana 서버 로그로 보내지는 경고를 도입했어요.

Grafana v11.2에서는 기본적으로 꺼져 있는 failWrongDSUID라는 새 기능 플래그를 추가했어요. 이 플래그를 활성화하면 REST API와 프로비저닝이 잘못된 UID를 가진 데이터 소스 인스턴스의 생성 또는 업데이트 요청을 거부하기 시작해요.

Grafana v11.5에서 failWrongDSUID 기능 플래그를 기본적으로 켤 예정이지만, 끌 수 있는 옵션은 여전히 제공할 거예요.

Grafana v12에서는 이것이 기본 동작이 되며 구성할 수 없게 돼요.

올바른 UID 형식 (Correct UID format)

정확한 정규식 정의는 grafana 저장소에서 찾을 수 있어요.

데이터 소스 UID에는 다음만 포함될 수 있어요:

라틴 문자(a-Z)
숫자(0-9)
대시 기호(-)

내가 영향을 받는지 어떻게 알 수 있나요? (How do I know if I'm affected?)

/api/datasources API로 모든 데이터 소스를 가져올 수 있어요. 문서에 나와 있는 것처럼 uid 필드를 올바른 형식과 비교해 검토해요. 다음은 도움이 되는 스크립트예요. 다만 직접 추가해야 하는 인증이 빠져 있다는 점에 유의해요:

curl http://localhost:3000/api/datasources | jq '.[] | select((.uid | test("^[a-zA-Z0-9\\-_]+$") | not) or (.uid | length > 40)) | {id, uid, name, type}'

또는 서버 로그에서 Invalid datasource uid 오류를 확인할 수 있어요.

영향을 받았다면 어떻게 해야 하나요? (What do I do if I'm affected?)

올바른 UID로 새 데이터 소스를 만들고, 대시보드와 알림 규칙이 그것을 사용하도록 업데이트해야 해요.

대시보드가 새 데이터 소스를 사용하도록 어떻게 업데이트하나요?

데이터 소스를 사용하는 대시보드로 이동해 패널 아래 선택기에서 새 데이터 소스 또는 업데이트된 데이터 소스를 선택해 업데이트해요.
대시보드의 JSON 모델을 검색·바꾸기로 직접 업데이트해요.

대시보드 JSON 모델로 이동해 기존 uid의 모든 인스턴스를 새로 만든 uid로 신중하게 바꿔요.

알림 규칙이 새 데이터 소스를 사용하도록 어떻게 업데이트하나요?

조정하려는 알림 규칙을 열고 쿼리/알림 조건에 사용되는 데이터 소스를 검색해요. 거기서 드롭다운 목록에서 새 데이터 소스를 선택하고 알림 규칙을 저장해요.

Grafana v11.2로 업그레이드