Grafana Docker 이미지 구성

Grafana Docker 이미지 구성 (Configure a Grafana Docker image)

이 문서는 복잡한 환경에서 Docker로 Grafana를 실행하는 방법을 설명해요. 이 문서의 예시는 Grafana Enterprise Docker 이미지를 사용합니다. Grafana 오픈소스 에디션을 사용하려면 이미지를 grafana/grafana로 바꾸면 돼요.

출처: 문서

본문

주의: Grafana 12.4.0 릴리스부터 grafana/grafana-oss Docker Hub 저장소는 더 이상 업데이트되지 않아요. 대신 grafana/grafana Docker Hub 저장소를 사용하는 것을 권장합니다. 두 저장소는 같은 Grafana OSS 도커 이미지를 갖고 있어요.

지원되는 Docker 이미지 변형

앞서 말한 공식 Docker 이미지로 Grafana를 설치·실행할 수 있어요. 각 에디션은 Alpine, Ubuntu, Distroless 기반 이미지로 제공되며, 각 기반 이미지에는 slim 변형도 있어요. 이미지 태그의 Grafana 버전 뒤에 변형 접미사를 붙이세요.

기반 이미지	표준 태그	Slim 태그
Alpine	<version>	<version>-slim
Ubuntu	<version>-ubuntu	<version>-ubuntu-slim
Distroless	<version>-distroless	<version>-distroless-slim

Alpine 이미지 (권장)

Alpine Linux는 상업적 주체에 속하지 않는 Linux 배포판으로, 보안·효율·사용 편의성을 중시하는 사용자를 위한 범용 운영체제예요. 다른 배포판 기반 이미지보다 훨씬 작아서 더 슬림하고 안전한 이미지를 만들 수 있어요. 기본적으로 이미지는 널리 사용되는 Alpine Linux 프로젝트 기반 이미지로 빌드돼요. 보안을 중시하고 이미지 크기를 최소화하고 싶다면 Alpine 변형을 권장해요. 다만 Alpine 변형은 glibc 대신 musl libc를 사용하므로, libc 요구 사항에 따라 일부 소프트웨어에 문제가 생길 수 있어요. 대부분의 소프트웨어는 문제없이 동작해 일반적으로 안정적이에요.

Ubuntu 이미지

Ubuntu 기반 Grafana Enterprise 및 OSS 이미지는 Ubuntu 기반 이미지로 빌드돼요. Ubuntu 기반 이미지를 선호하거나 Alpine에 없는 특정 도구가 필요할 때 좋은 선택이에요.

Distroless 이미지

Distroless 기반 이미지는 Alpine·Ubuntu 이미지보다 운영체제 패키지가 적어요. 셸, 패키지 관리자, 기타 범용 OS 유틸리티를 포함하지 않아 더 작은 풋프린트를 만들어요.

Slim 이미지

Slim 이미지는 표준 이미지에 Grafana가 번들로 포함하는 플러그인을 포함하지 않아요. 컨테이너 시작 시 GF_PLUGINS_PREINSTALL 환경 변수를 설정해 플러그인을 설치할 수 있어요. slim 이미지를 쓰려면 <version>-slim(Alpine), <version>-ubuntu-slim(Ubuntu), <version>-distroless-slim(Distroless)처럼 기반 접미사에 -slim을 추가하세요.

특정 Grafana 버전 실행

특정 버전의 Grafana나 grafana/grafana GitHub 저장소의 메인 브랜치 기반 베타 버전을 실행할 수도 있어요.

참고: Debian이나 Ubuntu 같은 Linux OS에서 Docker 명령 실행 시 권한 오류가 나면 명령 앞에 sudo를 붙이거나 사용자를 docker 그룹에 추가하세요.

특정 버전을 실행하려면 명령 부분에 버전을 추가하세요:

docker run -d -p 3000:3000 --name grafana grafana/grafana-enterprise:<version number>

예시 — 9.4.7 버전을 지정해 Grafana Enterprise 컨테이너 실행:

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

최근 Grafana 릴리스의 경우 grafana/grafana와 grafana/grafana-enterprise 도커 저장소에 마이너 버전 태그도 있어요. 예를 들어 항상 최신 12.1 버전을 쓰려면 grafana/grafana-enterprise:12.1 또는 grafana/grafana-enterprise:12.1-ubuntu를 사용하면 돼요.

Grafana 메인 브랜치 실행

메인 브랜치의 빌드가 성공할 때마다 grafana/grafana:main과 grafana/grafana:main-ubuntu 두 태그가 업데이트되고, grafana/grafana-dev:<version>과 grafana/grafana-dev:<version>-ubuntu 두 새 태그가 만들어져요. 여기서 version은 Grafana의 사전 릴리스 버전(예: GitHub Run ID가 1234면 12.2.0-1234)이에요. 이 태그들은 가장 최근 Grafana main 빌드에 접근하게 해줘요. 프로덕션 환경에서 main 브랜치를 실행할 때는 안정성과 일관성을 위해 grafana/grafana-dev:<version> 태그를 강력히 권장해요.

기본 경로 (Default paths)

Grafana에는 OS나 환경과 무관하게 버전 간 동일한 기본 구성 파라미터가 있어요. Docker 컨테이너 시작 시 다음 구성이 기본으로 설정돼요. Docker에서 실행할 때는 conf/grafana.ini 파일을 편집해 구성을 변경할 수 없고, 환경 변수로 수정해야 해요.

설정	기본값
GF_PATHS_CONFIG	/etc/grafana/grafana.ini
GF_PATHS_DATA	/var/lib/grafana
GF_PATHS_HOME	/usr/share/grafana
GF_PATHS_LOGS	/var/log/grafana
GF_PATHS_PLUGINS	/var/lib/grafana/plugins
GF_PATHS_PROVISIONING	/etc/grafana/provisioning

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

공개 플러그인과 조직 내부에서만 사용하는 프라이빗 플러그인을 설치할 수 있어요. 다른 소스에서 플러그인을 설치하려면 GF_PLUGINS_PREINSTALL 환경 변수에서 플러그인 이름 바로 앞에 커스텀 URL을 지정하세요: GF_PLUGINS_PREINSTALL=<plugin ID>@[<plugin version>]@<url to plugin zip>.

예시 — 커스텀 플러그인을 설치하며 Grafana Enterprise 실행:

docker run -d -p 3000:3000 --name=grafana \
  -e "GF_PLUGINS_PREINSTALL=custom-plugin@@http://plugin-domain.com/my-custom-plugin.zip,grafana-clock-panel" \
  grafana/grafana-enterprise

커스텀 Grafana Docker 이미지 빌드

Grafana GitHub 저장소의 packaging/docker/custom/ 폴더에는 커스텀 Grafana 이미지를 빌드하는 데 쓸 수 있는 Dockerfile이 있어요. 이 Dockerfile은 GRAFANA_VERSION과 GF_INSTALL_PLUGINS를 빌드 인자로 받아요. 기본적으로 Grafana는 Alpine 기반 이미지를 빌드하며, Ubuntu 기반 이미지를 빌드하려면 GRAFANA_VERSION 빌드 인자에 -ubuntu를 추가하세요.

최신 공식 Ubuntu 기반 이미지를 기반으로 커스텀 이미지를 빌드·실행하는 예시:

# go to the custom directory
cd packaging/docker/custom

# run the docker build command to build the image
docker build \
  --build-arg "GRAFANA_VERSION=latest-ubuntu" \
  -t grafana-custom .

# run the custom grafana container using docker run command
docker run -d -p 3000:3000 --name=grafana grafana-custom

사전 설치된 플러그인이 있는 이미지 빌드

여러 Grafana 설치에서 같은 플러그인을 쓰면, Grafana 플러그인 다운로드 페이지의 플러그인을 포함한 커스텀 이미지를 빌드해 시작 시 플러그인 설치를 생략할 수 있어요. 플러그인 버전을 지정하려면 GF_INSTALL_PLUGINS 빌드 인자에 버전 번호를 추가하세요. 버전을 지정하지 않으면 최신 버전이 사용돼요.

# go to the custom directory
cd packaging/docker/custom

# running the build command
# include the plugins you want e.g. clock planel etc
docker build \
  --build-arg "GRAFANA_VERSION=latest" \
  --build-arg "GF_INSTALL_PLUGINS=grafana-clock-panel,yesoreyeram-infinity-datasource" \
  -t grafana-custom .

# running the custom Grafana container using the docker run command
docker run -d -p 3000:3000 --name=grafana grafana-custom

다른 소스에서 사전 설치된 플러그인이 있는 이미지 빌드

조직 전용 플러그인을 포함한 Docker 이미지를 만들 수 있어요. GF_INSTALL_PLUGINS 빌드 인자에 플러그인 URL과 설치 폴더 이름을 지정하세요: GF_INSTALL_PLUGINS=<url to plugin zip>;<plugin install folder name>.

# go to the folder
cd packaging/docker/custom

# running the build command
docker build \
  --build-arg "GRAFANA_VERSION=latest" \
  --build-arg "GF_INSTALL_PLUGINS=http://plugin-domain.com/my-custom-plugin.zip;my-custom-plugin,grafana-clock-panel,yesoreyeram-infinity-datasource" \
  -t grafana-custom .

# running the docker run command
docker run -d -p 3000:3000 --name=grafana grafana-custom

로깅 (Logging)

기본적으로 Docker 컨테이너 로그는 Docker 커뮤니티의 일반적 관행대로 STDOUT으로 전달돼요. console, file, syslog 같은 다른 로그 모드를 설정해 변경할 수 있어요. 기본적으로 console과 file 모드가 모두 활성화돼요.

예시 — GF_LOG_MODE 환경 변수에 console file 로그 모드를 설정:

# Run Grafana while logging to both standard out
# and /var/log/grafana/grafana.log

docker run -p 3000:3000 -e "GF_LOG_MODE=console file" grafana/grafana-enterprise

Docker Secrets로 Grafana 구성

로그인 자격 증명과 시크릿 같은 기밀 데이터를 구성 파일로 Grafana에 입력할 수 있어요. 이 방법은 Docker Secrets와 잘 동작하며, 시크릿이 컨테이너 내 /run/secrets/ 위치에 자동으로 매핑돼요. conf/grafana.ini의 어떤 구성 옵션에도 GF_<SectionName>_<KeyName>__FILE을 시크릿 정보를 담은 파일 경로로 설정해 이 기법을 적용할 수 있어요.

AWS CloudWatch용 Docker secrets 자격 증명 구성

Grafana는 Amazon CloudWatch 데이터 소스를 내장 지원해요. 데이터 소스를 구성하려면 AWS ID-Key, 시크릿 액세스 키, 지역 같은 정보를 제공해야 해요. Docker secrets로 이 정보를 제공할 수 있어요.

AWS_default_ACCESS_KEY_ID=aws01us02
AWS_default_SECRET_ACCESS_KEY=topsecret9b78c6
AWS_default_REGION=us-east-1

여러 프로파일을 GF_AWS_PROFILES에 지정할 수도 있어요(예: GF_AWS_PROFILES=default another).

Docker 배포 문제 해결

기본 Grafana 로그 레벨은 INFO지만, 문제를 재현할 때 DEBUG 모드로 로그 레벨을 높일 수 있어요.

Docker run(CLI) 명령으로 로그 레벨 높이기

GF_LOG_LEVEL 환경 변수를 명령줄에 추가하세요:

docker run -d -p 3000:3000 --name=grafana \
  -e "GF_LOG_LEVEL=debug" \
  grafana/grafana-enterprise

Docker Compose로 로그 레벨 높이기

GF_LOG_LEVEL 환경 변수를 docker-compose.yaml 파일에 추가하세요:

version: '3.8'
services:
  grafana:
    image: grafana/grafana-enterprise
    container_name: grafana
    restart: unless-stopped
    environment:
      # increases the log level from info to debug
      - GF_LOG_LEVEL=debug
    ports:
      - '3000:3000'
    volumes:
      - 'grafana_storage:/var/lib/grafana'
volumes:
  grafana_storage: {}

Docker Compose YAML 파일 검증

파일이 복잡해질수록 YAML 파일에 구문 오류가 생길 가능성이 높아져요. 다음 명령으로 구문 오류를 검사할 수 있어요:

# go to your docker-compose.yaml directory
cd /path-to/docker-compose/file

# run the validation command
docker compose config

YAML 파일에 오류가 있으면 명령 출력이 오류가 있는 줄을 강조하고, 오류가 없으면 docker-compose.yaml 파일의 내용을 상세 YAML 형식으로 출력해요.

더 알아보기 (Learn more)

• Grafana 구성
• Docker에서 Grafana 설치
• 환경 변수 (Configure Grafana)
• Grafana 로깅
• grafana/grafana Docker Hub