그라파나 v8.0으로 업그레이드

그라파나를 v8.0 버전으로 업그레이드하는 방법을 안내합니다. 백업 절차부터 설치 방식별 업그레이드 방법, 플러그인 업데이트까지 다루고, 이 버전에서 바뀐 기술적 사항도 함께 설명해요.

출처: 문서

본문

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

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

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

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

가능한 경우, 모든 변경 사항을 pull request 또는 issue 링크와 함께 Changelog에 정리해 두었어요.

참고: 가능하다면 그라파나 업그레이드 과정을 테스트나 개발 환경에서 먼저 시도해 보는 것을 권장해요.

그라파나 백업

이 항목은 로컬 그라파나 배포를 백업하는 방법을 설명해요. 구성(configuration), 플러그인 데이터, 그리고 그라파나 데이터베이스가 백업 대상이에요.

그라파나 구성 파일 백업

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

그라파나 구성 파일은 다음 디렉터리에 있어요.

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

구성 파일의 위치에 대한 자세한 내용은 Configuration file location을 참조하세요.

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

플러그인 데이터 백업

그라파나에 플러그인을 설치하면 각 플러그인마다 관련 파일과 데이터가 들어 있는 폴더가 생성돼요. 이 위치의 모든 파일과 폴더를 재귀적으로 백업 저장소에 복사하세요.

그라파나 플러그인 파일은 다음 디렉터리에 있어요.

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

그라파나 데이터베이스 백업

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

SQLite

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

참고: 데이터 무결성을 보장하려면 SQLite 데이터베이스를 백업하기 전에 그라파나 서비스를 종료하세요.

SQLite 데이터베이스 파일은 다음 디렉터리 중 한 곳에 있어요.

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

MySQL

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

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

restore:
> mysql -u root -p grafana < grafana_backup.sql

Postgres

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

backup:
> pg_dump grafana > grafana_backup

restore:
> psql grafana < grafana_backup

그라파나 업그레이드

다음 절에서는 설치 방법에 따라 그라파나를 업그레이드하는 방법을 안내해요. 구성 파일의 위치에 대한 자세한 내용은 Configuration file location을 참조하세요.

Debian

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

현재 설치된 그라파나에서 사용자 지정 구성 변경 사항을 <grafana_install_dir>/grafana.ini라는 파일에 저장하세요. 이렇게 하면 구성 변경 사항을 잃을 위험 없이 그라파나를 업그레이드할 수 있어요.
그라파나의 최신 버전을 다운로드하세요.
다음 dpkg -i 명령을 실행하세요. wget <debian package url> sudo apt-get install -y adduser sudo dpkg -i grafana_<version>_amd64.deb

APT 저장소

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

현재 설치된 그라파나에서 사용자 지정 구성 변경 사항을 <grafana_install_dir>/grafana.ini라는 파일에 저장하세요. 이렇게 하면 구성 변경 사항을 잃을 위험 없이 그라파나를 업그레이드할 수 있어요.
다음 명령을 실행하세요. sudo apt-get update sudo apt-get upgrade

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

바이너리 .tar 파일

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

현재 설치된 그라파나에서 사용자 지정 구성 변경 사항을 사용자 지정 구성 파일인 custom.ini 또는 grafana.ini에 저장하세요. 이렇게 하면 구성 변경 사항을 잃을 위험 없이 그라파나를 업그레이드할 수 있어요.
바이너리 .tar.gz 패키지를 다운로드하세요.
다운로드한 패키지를 압축 해제하고 기존 파일을 덮어쓰세요.

RPM 또는 YUM

RPM 또는 YUM으로 설치한 그라파나를 업그레이드하려면 다음 단계를 완료하세요.

현재 설치된 그라파나에서 사용자 지정 구성 변경 사항을 <grafana_install_dir>/grafana.ini라는 파일에 저장하세요. 이렇게 하면 구성 변경 사항을 잃을 위험 없이 그라파나를 업그레이드할 수 있어요.
설치 방식에 따라 다음 중 하나를 수행하세요.
- RPM 패키지를 다운로드해서 그라파나를 설치했다면, Red Hat, RHEL, Fedora에 그라파나 설치 또는 SUSE, openSUSE에 그라파나 설치 문서의 단계를 완료해서 그라파나를 업그레이드하세요.
- Grafana YUM 저장소를 사용했다면 다음 명령을 실행하세요. sudo yum update grafana
- openSUSE나 SUSE에 그라파나를 설치했다면 다음 명령을 실행하세요. sudo zypper update

Docker

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

그라파나 환경 변수를 사용해 사용자 지정 구성을 저장하세요. 이 방법이 권장되는 방법이에요. 또는 배포된 컨테이너에 접속해 구성 파일을 수동으로 확인할 수도 있어요. 이렇게 하면 구성 변경 사항을 잃을 위험 없이 그라파나를 업그레이드할 수 있어요.
다음 명령과 유사한 명령을 실행하세요. 참고로 이는 예시이며, 입력하는 매개변수는 그라파나 컨테이너를 어떻게 구성했는지에 따라 달라져요. 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_install_dir>/conf/custom.ini라는 파일에 저장하세요. 이렇게 하면 구성 변경 사항을 잃을 위험 없이 그라파나를 업그레이드할 수 있어요.
Windows 바이너리 패키지를 다운로드하세요.
패키지의 내용물을 그라파나를 설치한 위치에 압축 해제하세요. 메시지가 표시되면 기존 파일과 폴더를 덮어쓸 수 있어요.

Mac

Mac에 설치한 그라파나를 업그레이드하려면 다음 단계를 완료하세요.

현재 설치된 그라파나에서 사용자 지정 구성 변경 사항을 사용자 지정 구성 파일인 custom.ini에 저장하세요. 이렇게 하면 구성 변경 사항을 잃을 위험 없이 그라파나를 업그레이드할 수 있어요.
Mac 바이너리 패키지를 다운로드하세요.
패키지의 내용물을 그라파나를 설치한 위치에 압축 해제하세요. 메시지가 표시되면 기존 파일과 폴더를 덮어쓸 수 있어요.

그라파나 플러그인 업데이트

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

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

grafana cli plugins update-all

기술 참고 사항

이 절에서는 이번 그라파나 릴리스와 관련된 기술적 변경 사항을 설명해요.

플러그인

이제 그라파나는 모든 플러그인이 서명(signed)되어 있어야 해요. 플러그인이 서명되지 않으면 그라파나가 해당 플러그인을 로드하거나 시작하지 않아요. 이는 플러그인 파일과 바이너리가 변조되지 않았는지 확인하기 위한 추가 보안 조치예요. Grafana Labs가 작성한 모든 플러그인(엔터프라이즈 플러그인 포함)은 이제 서명되어 있어요. 구성 설정을 사용해 서명되지 않은 플러그인을 허용하는 것도 가능하지만, 이는 강력히 권장하지 않아요. 이 설정에 대한 자세한 내용은 allow loading unsigned plugins을 참조하세요.

Grafana Live

그라파나는 이제 실시간 메시징 요구를 위해 지속적인(persistent) WebSocket 연결을 유지해요.

WebSocket 연결이 수립되면 보안상의 이유(예: WebSocket 연결 탈취 방지)로 그라파나는 요청의 Origin 헤더를 확인해요. root_url 서버 옵션으로 공용 URL을 올바르게 정의했다면 공용 URL 페이지에서 시작된 WebSocket 요청은 origin 검사를 통과할 거예요. origin 검사에 실패하면 그라파나는 403 오류를 반환해요. 또한 origin 검사를 위해 추가 origin 패턴 목록을 추가할 수도 있어요.

많은 동시 WebSocket 연결을 처리하려면 OS 설정이나 인프라를 조정해야 할 수도 있어요. Grafana Live는 기본적으로 활성화되어 있으며, 파일 서술자(file descriptor) OS 제한 문제를 피하기 위해 최대 100개의 동시 WebSocket 연결을 지원해요. 설정이 지속 연결 수를 확장할 요건을 충족하면 이 제한을 늘릴 수 있어요. Grafana Live를 비활성화하는 옵션도 있어요.

자세한 내용은 Grafana Live 구성 문서를 참조하세요.

Postgres, MySQL, Microsoft SQL Server 데이터 소스

그라파나 v8.0은 Postgres, MySQL, Microsoft SQL Server 데이터 소스의 내부 데이터 구조를 data frames로 변경해요. 그 결과 Time series 쿼리 결과가 wide format으로 반환돼요. 시각화가 이전처럼 작동하도록 수동 마이그레이션을 수행해야 할 수도 있어요.

time 열이 시간 범위 필터링에만 필요한 기존 Time series 쿼리를 사용하는 패널/시각화(예: bar gauge 또는 pie chart 패널)의 경우, 대신 Table query를 사용하고 응답에서 time 열을 필드로 제외하는 것을 권장해요. 자세한 지침과 해결 방법은 이 issue 댓글을 참조하세요.

시리즈 이름에 추가되는 접두사

time 값과 숫자 값이 metric이라는 이름이 아닌 문자열 값과 함께 선택되는 쿼리가 있다면, 그래프 패널은 Grafana 8 이전처럼 <hostname>만 표시하는 대신 시리즈 이름을 value <hostname>으로 렌더링해요.

SELECT
  $__timeGroup("createdAt",'10m'),
  avg(value) as "value",
  hostname
FROM grafana_metric
WHERE $__timeFilter("createdAt")
GROUP BY time, hostname
ORDER BY time

이 문제를 해결할 수 있는 두 가지 방법이 있어요.

Grafana v8.0.3에서는 선택한 문자열 열에 metric이라는 별칭을 사용하세요. 예를 들어 hostname as metric처럼요.
Standard field definitions의 표시 이름(display name)을 사용해 별칭을 포맷하세요. 앞선 예제 쿼리에서는 ${__field.labels.hostname} 옵션을 사용하면 돼요.

자세한 내용은 관계형 데이터베이스 문서인 Postgres, MySQL, Microsoft SQL Server를 참조하세요.

더 알아보기

원문 문서