Grafana 구성하기 — 설정 파일과 환경변수로 인스턴스 조정하기
Grafana 구성하기 — 설정 파일과 환경변수로 인스턴스 조정하기
Grafana 인스턴스가 어떻게 동작할지는 기본값 설정 파일과 커스텀 설정 파일, 그리고 환경변수로 결정돼요. 대부분의 운영 파라미터 — 듣는 포트, 로그 레벨, 보안, 외부 연동, 기능 토글까지 — 를 여기서 다룰 수 있어요. 이번 장에서는 설정 파일을 어디서 찾는지, 어떻게 주석을 풀고 바꾸는지, 환경변수로 어떻게 덮어쓰는지를 차근차근 살펴볼게요.
본문
설정 파일 위치. Grafana 인스턴스의 기본 설정은 <WORKING DIRECTORY>/conf/defaults.ini 파일에 저장돼요. 이 파일은 절대 건드리면 안 돼요. 커스텀 설정 파일은 운영체제에 따라 <WORKING DIRECTORY>/conf/custom.ini 또는 /usr/local/etc/grafana/grafana.ini이고, --config 옵션으로 커스텀 경로를 지정할 수도 있어요.
- Linux: deb나 RPM 패키지로 설치했다면
/etc/grafana/grafana.ini에 있고 별도custom.ini는 쓰지 않아요. 이 경로는 Grafana init.d 스크립트의--config옵션으로 지정돼요. - Docker: 환경변수·영구 저장소·커스텀 이미지 빌드는 Docker 이미지 구성 문서를 참고해요.
- Windows:
sample.ini가defaults.ini와 같은 디렉터리에 있고, 모든 설정이 주석 처리된 채 들어 있어요.sample.ini를 복사해서custom.ini로 이름을 바꿔 쓰면 돼요. - macOS: 기본적으로
/opt/homebrew/etc/grafana/grafana.ini또는/usr/local/etc/grafana/grafana.ini에 있어요. Homebrew로 설치했다면grafana.ini를 직접 편집하고, 아니면conf디렉터리에custom.ini를 두고defaults.ini에 정의된 설정을 덮어써요. - Grafana Cloud: 로컬 설정 파일이 없지만, 많은 설정을 여전히 변경할 수 있어요. 설정이 필요한 항목은 지원 티켓으로 요청해야 해요.
주석 풀기. Grafana는 INI 파일에서 줄을 주석 처리할 때 세미콜론(;)을 써요. 주석 처리를 풀려면 줄 맨 앞의 세미콜론(;)을 지우면 돼요. 세미콜론으로 시작하는 모든 설정 줄은 Grafana가 무시해요. 예를 들면:
;http_port = 3000
환경변수로 덮어쓰기. 환경변수는 새 설정을 추가하는 용도가 아니라 기존 옵션을 덮어쓰는 용도로 써요. 옵션을 덮어쓰려면 다음 규칙을 따릅니다.
GF_<SECTION NAME>_<KEY>
여기서 <SECTION NAME>은 설정 파일에서 대괄호([ ]) 안에 들어 있는 텍스트예요. 모든 글자는 대문자여야 하고, 점(.)과 대시(-)는 밑줄(_)로 바꿔요. 예를 들어 이런 설정이 있다면:
# default section
instance_name = ${HOSTNAME}
[security]
admin_user = admin
[auth.google]
client_secret = 0ldS3cretKey
[plugin.grafana-image-renderer]
rendering_ignore_https_errors = true
[feature_toggles]
newNavigation = true
Linux 머신에서 다음과 같이 덮어쓸 수 있어요.
export GF_DEFAULT_INSTANCE_NAME=my-instance
export GF_SECURITY_ADMIN_USER=owner
export GF_AUTH_GOOGLE_CLIENT_SECRET=newS3cretKey
export GF_PLUGIN_GRAFANA_IMAGE_RENDERER_RENDERING_IGNORE_HTTPS_ERRORS=true
export GF_FEATURE_TOGGLES_newNavigation=true
변수 확장(Variable expansion). 옵션 값에 $__<PROVIDER>{<ARGUMENT>}나 ${<ENVIRONMENT VARIABLE>} 표현이 들어 있으면 Grafana가 이를 평가해요. 평가는 제공자(provider)에 인자를 넘겨 최종 값을 얻는 방식으로 진행돼요. env, file, vault 세 가지 제공자가 있어요.
env 제공자는 환경변수를 확장해요. 옵션을 $__env{PORT}로 설정하면 PORT 환경변수의 값으로 바뀌고, 환경변수에는 ${PORT} 축약 문법도 쓸 수 있어요. 다음 예시는 로그 디렉터리를 LOGDIR 환경변수의 경로로 설정해요:
[paths]
logs = $__env{LOGDIR}/grafana
file 제공자는 파일시스템에서 파일을 읽어요. 파일 앞뒤의 공백은 잘라내요. 다음 예시는 데이터베이스 비밀번호를 /etc/secrets/gf_sql_password 파일의 내용으로 설정해요:
[database]
password = $__file{/etc/secrets/gf_sql_password}
vault 제공자는 Hashicorp Vault로 시크릿을 관리해요. 참고로 vault 제공자는 Grafana Enterprise에서만 사용할 수 있어요.
주요 구성 옵션 훑어보기. instance_name은 Grafana 서버 인스턴스의 이름으로 로깅·내부 메트릭·클러스터 정보에 쓰이고 기본값은 ${HOSTNAME}이에요. [server] 섹션에는 http_addr(바인딩할 네트워크 인터페이스), http_port(기본 3000), domain, enforce_domain(DNS 리바인딩 방지), root_url(브라우저에서 접근하는 전체 URL — OAuth 콜백에 중요), serve_from_sub_path, enable_gzip(HTTP 압축) 등이 있어요. [paths] 섹션에는 data, logs, plugins, provisioning 경로를 설정해요.
구성 관리 도구로 프로비저닝하기. Grafana 커뮤니티는 Puppet, Ansible, Chef, NixOS 등 널리 쓰이는 구성 관리 도구용 라이브러리를 유지하고 있어요. IaC(GitOps)로 Grafana를 코드처럼 다루고 싶다면 프로비저닝 문서와 함께 살펴보면 좋아요.