Grafana Docker 이미지 실행

Grafana Docker 이미지 실행 (Run Grafana Docker image)

이 문서는 공식 Docker 이미지로 Grafana를 설치하는 방법을 안내해요. 특히 Docker CLI와 docker-compose를 통한 Grafana 실행을 다룹니다. Grafana Docker 이미지에는 두 에디션이 있어요: Grafana Enterprise(grafana/grafana-enterprise)와 Grafana Open Source(grafana/grafana).

출처: 문서

본문

Caution: Grafana 12.4.0 릴리스부터 grafana/grafana-oss Docker Hub 저장소가 더 이상 업데이트되지 않아요. 대신 grafana/grafana 저장소 사용을 권장하며, 두 저장소는 동일한 Grafana OSS Docker 이미지를 가져요.

Note: 권장되고 기본적인 Grafana 에디션은 Grafana Enterprise예요. 무료이며 OSS 에디션의 모든 기능을 포함해요. 또한 Enterprise 플러그인 지원을 포함한 전체 Enterprise 기능 세트로 업그레이드할 수 있어요.

기본 이미지는 Alpine Linux 프로젝트로 만들어졌으며 Alpine 공식 이미지에서 찾을 수 있어요. Grafana Docker 이미지 구성 방법은 "Configure a Grafana Docker image"를 참고하세요.

Note: Linux 시스템(Debian이나 Ubuntu)이라면 명령 앞에 sudo를 붙이거나 사용자를 docker 그룹에 추가해야 할 수 있어요. 자세한 내용은 Docker Engine의 Linux post-installation steps를 참고하세요.

Docker CLI로 Grafana 실행

최신 안정 버전을 실행하려면:

docker run -d -p 3000:3000 --name=grafana grafana/grafana-enterprise

여기서:

  • docker run은 이미지에서 새 컨테이너를 실행하는 Docker CLI 명령
  • -d(--detach)는 컨테이너를 백그라운드로 실행
  • -p <host-port>:<container-port>(--publish)는 컨테이너 포트를 호스트에 게시해 호스트 포트로 도달하게 함. 여기서는 호스트 포트 3000으로 컨테이너 포트 3000에 도달
  • --name은 컨테이너에 논리적 이름(예: grafana)을 지정해 ID 대신 이름으로 참조하게 함
  • grafana/grafana-enterprise는 실행할 이미지

Grafana 컨테이너 중지

# `docker ps` 명령은 Docker에서 실행 중인 프로세스를 보여줌
docker ps

# 이렇게 하면 다음과 같은 목록이 표시됨:
CONTAINER ID   IMAGE  COMMAND   CREATED  STATUS   PORTS    NAMES
cd48d3994968   grafana/grafana-enterprise   "/run.sh"   8 seconds ago   Up 7 seconds   0.0.0.0:3000->3000/tcp   grafana

# grafana 컨테이너를 중지하려면
# docker stop CONTAINER-ID 또는
# docker stop NAME(위에서 정의한 `grafana`)을 사용
docker stop grafana

Grafana 데이터 저장

기본적으로 Grafana는 임베디드 SQLite 3 데이터베이스로 설정·사용자·대시보드·기타 데이터를 저장해요. Docker 이미지를 컨테이너로 실행하면 이 Grafana 데이터의 변경 사항이 컨테이너 내 파일시스템에 기록되는데, 컨테이너가 존재하는 동안만 유지돼요. 컨테이너를 중지하고 제거하면 파일시스템 변경(즉 Grafana 데이터)이 버려져요. 데이터 손실을 피하려면 Docker 볼륨이나 bind mounts로 영구 스토리지를 설정하세요.

Note: 두 방법은 비슷하지만 약간의 차이가 있어요. 스토리지를 Docker가 완전히 관리하고 Docker 컨테이너와 Docker CLI로만 접근하려면 영구 스토리지(persistent storage)를 선택하세요. 스토리지를 완전히 제어하고 Docker 외의 다른 프로세스가 접근·수정하게 하려면 bind mounts가 적합해요.

Docker 볼륨 사용 (권장):

  1. Grafana 컨테이너가 쓸 Docker 볼륨을 설명적인 이름(예: grafana-storage)으로 만들어요:
# 데이터용 영구 볼륨 생성
docker volume create grafana-storage

# 볼륨이 올바르게 생성됐는지 확인
# JSON 출력이 보여야 함
docker volume inspect grafana-storage
  1. 다음 명령으로 Grafana 컨테이너를 시작해요:
# grafana 시작
docker run -d -p 3000:3000 --name=grafana \
  --volume grafana-storage:/var/lib/grafana \
  grafana/grafana-enterprise

Bind mounts 사용:

Docker에서 Grafana를 실행할 때 데이터베이스나 구성을 위해 호스트 디렉터리를 쓰려면, 매핑한 디렉터리에 접근·쓰기 권한이 있는 사용자로 컨테이너를 시작해야 해요.

# 데이터용 디렉터리 생성
mkdir data

# 사용자 ID와 data 디렉터리로 grafana 시작
docker run -d -p 3000:3000 --name=grafana \
  --user "$(id -u)" \
  --volume "$PWD/data:/var/lib/grafana" \
  grafana/grafana-enterprise

환경 변수로 Grafana 구성

Grafana는 환경 변수로 커스텀 구성 설정을 지정하는 것을 지원해요.

# debug 로그 활성화
docker run -d -p 3000:3000 --name=grafana \
  -e "GF_LOG_LEVEL=debug" \
  grafana/grafana-enterprise

Docker 컨테이너에 플러그인 설치

공식·커뮤니티 플러그인 페이지나 커스텀 URL로 비공개 플러그인을 설치해 Grafana에 플러그인을 추가할 수 있어요. 이 플러그인들은 새 시각화 유형·데이터 소스·애플리케이션을 추가해 데이터를 더 잘 시각화하게 해줘요. Grafana는 패널·데이터 소스·앱 세 가지 플러그인 유형을 지원해요 (Plugin Management 참고).

  1. 설치할 플러그인을 GF_PLUGINS_PREINSTALL 환경 변수에 쉼표로 구분된 목록으로 Docker에 전달해요. 이는 Grafana 서버가 시작되는 동안 플러그인 목록을 설치하는 백그라운드 프로세스를 시작해요. 예:
docker run -d -p 3000:3000 --name=grafana \
  -e "GF_PLUGINS_PREINSTALL=grafana-clock-panel, yesoreyeram-infinity-datasource" \
  grafana/grafana-enterprise
  1. 플러그인 버전을 지정하려면 GF_PLUGINS_PREINSTALL 환경 변수에 버전 번호를 추가해요:
docker run -d -p 3000:3000 --name=grafana \
  -e "[email protected]" \
  grafana/grafana-enterprise

Note: 버전 번호를 지정하지 않으면 최신 버전이 사용돼요.

  1. 커스텀 URL에서 플러그인을 설치하려면 다음 규칙으로 URL을 지정해요: <plugin ID>@[<plugin version>]@<url to plugin zip>.
docker run -d -p 3000:3000 --name=grafana \
  -e "GF_PLUGINS_PREINSTALL=custom-plugin@@https://github.com/VolkovLabs/custom-plugin.zip" \
  grafana/grafana-enterprise

예제

다음 예제는 최신 안정 버전의 Grafana를 포트 3000에서 실행하고, 컨테이너 이름은 grafana, grafana-storage Docker 볼륨에 영구 스토리지를 두고, 서버 루트 URL을 설정하고, 공식 clock panel 플러그인을 설치해요.

# 데이터용 영구 볼륨 생성
docker volume create grafana-storage

# 위 영구 스토리지를 사용하고 환경 변수를 정의해 grafana 시작
docker run -d -p 3000:3000 --name=grafana \
  --volume grafana-storage:/var/lib/grafana \
  -e "GF_SERVER_ROOT_URL=http://my.grafana.server/" \
  -e "GF_PLUGINS_PREINSTALL=grafana-clock-panel" \
  grafana/grafana-enterprise

Docker Compose로 Grafana 실행

Docker Compose는 여러 컨테이너로 구성된 애플리케이션을 정의·공유하기 쉽게 해주는 도구예요. 보통 docker-compose.yaml이라 부르는 YAML 파일로 애플리케이션을 구성하는 모든 서비스를 나열해요. 단일 명령으로 올바른 순서로 컨테이너를 시작하고, 다른 명령으로 종료할 수 있어요.

시작하기 전에: compose 도구를 설치해야 해요. 사용 가능한지 확인:

docker compose version

Compose 도구를 사용할 수 없으면 Install Docker Compose를 참고하세요. 예제는 Compose 버전 3을 사용해요.

최신 안정 버전 실행:

  1. docker-compose.yaml 파일을 만들어요:
# docker-compose.yaml 파일을 만든 디렉터리로 이동
cd /path/to/docker-compose-directory

# docker-compose.yaml 파일 생성
touch docker-compose.yaml
  1. docker-compose.yaml 파일에 다음 코드를 추가해요:
services:
  grafana:
    image: grafana/grafana-enterprise
    container_name: grafana
    restart: unless-stopped
    ports:
      - '3000:3000'
  1. 실행:
# grafana 컨테이너 시작
docker compose up -d

여기서 -d는 분리 모드, up은 컨테이너를 올리고 실행하는 것. Grafana가 실행 중인지 확인하려면 브라우저를 열고 IP_ADDRESS:3000을 입력하면 로그인 화면이 나타나요.

컨테이너 중지:

docker compose down

Grafana 데이터 저장 (Docker 볼륨):

  1. docker-compose.yaml 파일을 만들어요.
  2. 다음 코드를 추가해요:
services:
  grafana:
    image: grafana/grafana-enterprise
    container_name: grafana
    restart: unless-stopped
    ports:
      - '3000:3000'
    volumes:
      - grafana-storage:/var/lib/grafana
volumes:
  grafana-storage: {}
  1. 저장하고 실행:
docker compose up -d

(Bind mounts):

  1. docker-compose.yaml 파일을 만들어요.
  2. 데이터를 마운트할 디렉터리(여기서는 /data)를 현재 작업 디렉터리에 만들어요:
mkdir $PWD/data
  1. 다음 코드를 추가해요:
services:
  grafana:
    image: grafana/grafana-enterprise
    container_name: grafana
    restart: unless-stopped
    # root로 실행 중이면 0으로 설정
    # 아니면 id -u 명령으로 적절한 id 찾기
    user: '0'
    ports:
      - '3000:3000'
    # 앞서 만든 마운트 볼륨 지점 추가
    volumes:
      - '$PWD/data:/var/lib/grafana'
  1. 저장하고 실행:
docker compose up -d

Compose 예제: 최신 안정 버전, 포트 3000, 컨테이너 이름 grafana, grafana-storage 볼륨의 영구 스토리지, 서버 루트 URL 설정, 공식 clock panel 플러그인 설치:

services:
  grafana:
    image: grafana/grafana-enterprise
    container_name: grafana
    restart: unless-stopped
    environment:
      - GF_SERVER_ROOT_URL=http://my.grafana.server/
      - GF_PLUGINS_PREINSTALL=grafana-clock-panel
    ports:
      - '3000:3000'
    volumes:
      - 'grafana_storage:/var/lib/grafana'
volumes:
  grafana_storage: {}

Note: 플러그인 버전을 지정하려면 GF_PLUGINS_PREINSTALL 환경 변수에 버전 번호를 추가하세요. 예: -e "[email protected],[email protected]". 버전 번호를 지정하지 않으면 최신 버전이 사용돼요.

다음 단계

로그인, 데이터 소스 설정 등은 Getting Started 가이드를 참고하세요. Docker 이미지 사용자 지정 옵션(환경, 로깅, 데이터베이스 등)은 "Configure a Grafana Docker image" 페이지를, Grafana 일반 구성은 Configuration 페이지를 참고하세요.

더 알아보기 (Learn more)