Custom Grafana 인수인계 문서

• 위치:
  • Git: http://10.10.30.238:8980/98_personal/observability-all-in-one/-/tree/main/custom-grafana?ref_type=heads
  • 디렉터리: observability-all-in-one/custom-grafana/

이 문서는 Custom Grafana 이미지가 어떤 역할을 하는지, 어디를 수정해야 하는지, 어떻게 빌드/배포하는지를 새 담당자가 빠르게 파악할 수 있도록 정리한 인수인계용 가이드입니다. 세부 구조 설명은 custom-grafana/README.md 내용을 기반으로 하며, 운영상 자주 쓰는 관점 위주로 재구성했습니다.

1. 이 배포본이 하는 일

1.1 목적

Custom Grafana 배포본은 아래 세 가지를 하나의 Docker 이미지로 묶어서 배포하기 위한 프로젝트입니다.

1. 커스텀 UI (public/)
2. 사전 설치 플러그인 (data/plugins/)
3. 대시보드·데이터소스·알림·권한 등 프로비저닝 리소스 (conf/provisioning/)

운영상 의미는 다음과 같습니다.

• 새 환경(Kubernetes / VM 등)에 배포할 때, **“이미지만 교체하면 동일한 Grafana 구성을 복제”**할 수 있습니다.
• UI·대시보드·알림·플러그인 구성이 Git으로 버전 관리되기 때문에, 변경 이력 추적과 롤백이 용이합니다.
• 오프라인/폐쇄망 환경에서도 필요한 플러그인 및 자산을 이미지 안에 포함해서 바로 사용 가능합니다.

1.2 주요 특징 정리

• 베이스 이미지: grafana/grafana:12.2.0
• 플러그인 설치:
  • Dockerfile 내 GF_INSTALL_PLUGINS 환경 변수를 통해 기본 플러그인 설치
  • 추가/고정 버전이 필요하면 이 값을 수정
• UI 교체:
  • /usr/share/grafana/public 전체를 custom-grafana/public/ 로 교체
  • React/TypeScript 기반 프론트엔드 구조 유지
• 프로비저닝:
  • conf/provisioning/ 이하 YAML을 통해 대시보드, 데이터소스, 알림, 플러그인, 권한 자동 생성
• 데이터 보존:
  • data/ 폴더를 외부 볼륨에 마운트하면 알림 상태·로그·플러그인 캐시 유지 가능

2. 코드/파일 구조

2.1 최상위 구조

custom-grafana/ 디렉터리의 상위 구조는 다음과 같습니다.

custom-grafana/
├── Dockerfile                # 베이스 이미지 + 커스텀 자산 복사
├── docker-compose.yml        # 단일 Grafana 서비스 실행 정의 (로컬 테스트용)
├── build.sh / make-dockerfile.sh
├── conf/                     # Grafana 설정, 프로비저닝 리소스, 백업본
├── data/                     # 실행 시 참조되는 영속 데이터(플러그인, 로그 등)
├── plugins-bundled/          # Grafana 동봉 예제 플러그인 (참고용)
└── public/                   # 커스텀 UI 소스/빌드/에셋 전체

실제 운영/개발 시, 자주 건드리게 될 부분은 아래 네 가지입니다.

1. Grafana 설정/프로비저닝: conf/, 특히 conf/provisioning/
2. 대시보드/알림 JSON/YAML: conf/provisioning/dashboards/json/, conf/provisioning/alerting/
3. 이미지 빌드/배포 스크립트: Dockerfile, build.sh, make-dockerfile.sh

3. 로컬에서 확인하는 방법 (필수 절차)

3.1 요구 사항

• Docker 24.x 이상
• (선택) Docker Compose v2 (docker compose 명령)
• 레지스트리로 push 할 경우, 해당 레지스트리 로그인 정보

3.2 로컬에서 Grafana 띄워보기

1. 리포지토리 클론 후 디렉터리 이동

git clone http://10.10.30.238:8980/98_personal/observability-all-in-one.git
cd observability-all-in-one/custom-grafana

2. Docker 이미지 빌드

docker compose build

3. 컨테이너 실행 (기본 3000 포트 사용)

docker compose up -d

4. 로그 확인

docker compose logs -f grafana

5. 브라우저 접속

   • URL: http://localhost:3000
   • 계정 정보는 공용 운영 정책에 따름 (공유된 관리자 계정 혹은 SSO/LDAP)

3.3 홈 대시보드 및 데이터 경로

• docker-compose.yml 에서 기본 홈 대시보드는 다음 경로로 고정되어 있습니다.
  • GF_PATHS_DEFAULT_HOME_DASHBOARD_PATH=/etc/grafana/provisioning/dashboards/json/통합/00. 모니터링 오버뷰 대시보드.json
• 장기 테스트가 필요하다면 아래처럼 data/ 를 로컬 볼륨에 마운트할 수 있습니다. (기본 compose 파일에서는 이미지에 포함시키는 전략이라 주석 처리되어 있음)

# docker-compose.yml 예시
# volumes:
#   - ./data:/var/lib/grafana

4. 환경별 빌드/배포 절차

4.1 기본 이미지 빌드/태그 (단일 환경용)

간단한 테스트/단일 환경용 이미지는 make-dockerfile.sh 로 빌드합니다.

cd observability-all-in-one/custom-grafana
bash make-dockerfile.sh

• 기본 태그 예시: metabuild-monitoring-dashboard:0.0.1
• 필요 시 스크립트 내부에서 이미지 이름/태그 수정

4.2 다중 타깃(국1/NIPA 등) 빌드/태그/푸시

실제 운영용 배포는 build.sh 를 기준으로 합니다.

• build.sh 내부에 국1 쿠버네티스, NIPA(실시간/이상탐지/통합/관리자) 등 여러 타깃 환경에 맞춘 docker build / docker tag / docker push 명령이 주석 형태로 정리되어 있습니다.
• 새 담당자는 아래 순서로 사용하면 됩니다.

1. build.sh 열기
2. 현재 사용하는 레지스트리 주소, 프로젝트 경로, 태그를 확인
3. 필요한 라인(해당 환경)만 주석 해제
4. 이미지명/태그가 최신 정책에 맞는지 확인 후 스크립트 실행

bash build.sh

운영 정책 변경 시(레지스트리 URL 변경, 네이밍 룰 변경 등) 반드시 이 스크립트를 함께 업데이트해야 합니다.

5. 디렉터리별 상세 설명 (운영상 관점)

5.1 conf/ – Grafana 설정 및 프로비저닝

5.1.1 핵심 설정 파일

5.1.2 대시보드 백업 (conf/backup/)

• G1_Kubernetes, tenant, 모니터링, 실시간, 이상탐지 등 환경/기능별 폴더에 Grafana에서 export 한 JSON 원본이 들어 있습니다.

• 역할:

  • 기존 대시보드가 깨졌을 때 수동 복구용
  • 새로운 프로비저닝 구조로 옮기기 전에 참고용

• 실제 자동 배포에 사용되는 파일은 conf/provisioning/dashboards/json/ 입니다.

5.1.3 conf/provisioning/ 구조

민감정보(비밀번호, 토큰 등)는 아래 방식으로 관리하는 것을 권장합니다.

• YAML 내 secureJsonData 필드 사용
• Docker 시크릿/환경변수에 실제 값을 두고 템플릿 엔진/배포 파이프라인에서 주입

5.2 data/ – 플러그인, 알림 상태, 로그

실운영 환경에서는 일반적으로 data/ 를 별도 Volume/PVC 로 분리하여 컨테이너 재배포 시에도 상태를 유지합니다.

5.3 public/ – 커스텀 UI (건드릴 필요 없습니다.)

• Grafana 12.2.0 기준 /usr/share/grafana/public 폴더와 동일한 구조를 따르며, 여기에 사내 요구사항에 맞게 수정이 적용되어 있습니다.
• 이 경로는 수정할 필요가 없으며, 요구사항에 따라 favicon, logo 등은 아래의 설명에 따라 변경하시면 됩니다.

주요 경로 역할:

• public/app/
  • React/TypeScript 소스 코드.
  • app.ts, AppWrapper.tsx, initApp.ts 등에서 Grafana Core 초기화.
  • core/, features/, plugins/, routes/ 등으로 기능별 분리.
  • UI/기능 수정 시 여기서 개발 → 빌드 결과가 public/build/ 에 생성됩니다.
• public/build/
  • 실제 브라우저에 서빙되는 번들(JS/CSS).
  • 직접 수정은 지양하고, 항상 app/ 수정 후 빌드로 생성합니다.
• public/img/, public/fonts/, fav32.png, meta.svg
  • 로고, 아이콘, 폰트 리소스.
• public/locales/
  • 다국어(i18n) 리소스(ko-KR 포함). 번역 수정 시 사용.

UI 작업 절차는 다음과 같습니다.

1. public/app/ 에서 소스 수정
2. Grafana 프런트엔드 빌드 파이프라인 실행 (yarn build 등, 프로젝트 내 정의된 방식 따름)
3. 빌드 결과(public/build/)가 업데이트 되었는지 확인
4. Docker 이미지 재빌드 (docker compose build 또는 make-dockerfile.sh/build.sh)

5.4 plugins-bundled/

• Grafana가 기본적으로 동봉하는 예제 플러그인 목록입니다.
• 실제 운영용 플러그인은 아래 두 방식으로 관리합니다.
  • data/plugins/ 에 바이너리 포함
  • Dockerfile 의 GF_INSTALL_PLUGINS 환경 변수에 플러그인명@버전 명시

6. 프로비저닝 / 아이콘 변경

6.1 대시보드 추가/수정

1. Grafana UI에서 대시보드 수정
2. JSON으로 export
3. conf/provisioning/dashboards/json/<폴더>/ 에 해당 파일 저장 (예: 통합/00. 모니터링 오버뷰 대시보드.json)
4. conf/provisioning/dashboards/sample.yaml 의 options.path 가 올바른 폴더를 가리키는지 확인
5. Docker 이미지 재빌드 후 재배포
6. 새 컨테이너에서 홈 대시보드가 정상 노출되는지 확인

6.2 데이터소스 추가/수정

1. conf/provisioning/datasources/datasource.yaml 열기
2. 사용하지 않는 예제는 그대로 두고, 실제 필요한 데이터소스 섹션의 주석을 해제
3. url, database, 인증 정보 등 환경에 맞게 수정 (민감정보는 secureJsonData + 시크릿 방식 사용 권장)
4. 이미지 재빌드 후 재배포
5. Grafana UI의 데이터소스 메뉴에서 정상 연결 여부 확인

6.3 알림 설정

1. conf/provisioning/alerting/alert.yaml
   • 알림 조건(SQL, 임계치, 윈도우 등)을 수정
2. conf/provisioning/alerting/contactPoints.yaml, notificationPolicies.yaml
   • 알림 대상/라우팅 정책 조정
3. notifiers/sample.yaml 에서 텔레그램 등 ID 및 봇 토큰 정의 후 적용
4. 재배포 후 Alert Rule 테스트로 실제 알림 동작 확인

7. 운영 팁 및 주의사항

• 플러그인 버전 고정

  • Dockerfile 의 GF_INSTALL_PLUGINS 는 plugin@version 형식을 지원합니다.
  • 운영 중 자동 업데이트로 인한 호환성 문제가 생기지 않도록, 가능하면 명시적 버전 고정을 사용합니다.

• 로그 관리

  • data/log/grafana.log.* 용량이 커지면 로테이션 정책을 설정하거나, 외부 로그 수집 시스템(예: Loki 등)과 연계하여 관리합니다.
  • 필요 시 GF_LOG_MODE=json 으로 변경해 중앙 수집에 유리하게 구성할 수 있습니다.

• 보안 설정

  • LDAP/SSO, 알림 채널, 데이터소스 인증 정보는 Git에 평문으로 남기지 않습니다.
  • 배포 파이프라인(ArgoCD, Jenkins 등)에서 템플릿 + 시크릿 조합으로 주입합니다.

• 문제 발생 시 우선 확인 포인트

  1. docker compose logs -f grafana 또는 K8s kubectl logs 로 Grafana 로그 확인
  2. conf/grafana.ini 의 포트/도메인 설정 확인
  3. conf/provisioning/*.yaml 문법 오류 여부 (잘못된 인덴트나 필드명)
  4. 데이터소스 연결 상태 (네트워크/방화벽/인증 등)

8. 새 담당자가 처음 할 일 체크리스트

1. 상단 Repo 링크로 접속해 custom-grafana/ 구조를 한 번 훑어본다.
2. 로컬 PC에서 docker compose build && docker compose up -d 로 Grafana를 실제로 띄워본다.
3. 브라우저에서 홈 대시보드를 열어, 어떤 대시보드들이 기본 제공되는지 확인한다.
4. conf/provisioning/ 디렉터리를 열어 대시보드/데이터소스/알림/권한이 어떻게 나뉘어 있는지 파악한다.
5. build.sh 를 열어 현재 사용 중인 레지스트리/태그 정책을 확인하고, 운영 환경에서 어떤 태그가 배포되고 있는지 인지한다.
6. 변경 요청(예: “대시보드 추가”, “새 데이터소스 연결”)이 들어올 때, 위 플로우를 기준으로 어디를 수정해야 하는지 감이 잡히면 기본 이해는 완료된 것입니다.

이 문서와 함께 custom-grafana/README.md 를 참고하면, 신규 담당자도 리포지토리 구조와 배포 흐름을 빠르게 이해하고, 안전하게 Custom Grafana 이미지를 유지·확장할 수 있습니다.