Helm Charts로 Grafana 배포

Helm Charts로 Grafana 배포 (Deploy Grafana using Helm Charts)

이 문서는 Helm Charts를 사용해 Kubernetes에 Grafana를 설치하고 실행하는 방법을 안내해요. Helm은 Kubernetes 애플리케이션 관리용 오픈소스 CLI 도구이며 CNCF Landscape의 graduate 프로젝트예요. Grafana 오픈소스 커뮤니티가 Kubernetes 실행용 Helm Charts를 제공하며, 코드는 보증 없이 제공되므로 문제가 있으면 커뮤니티 유지 GitHub 저장소에 보고할 수 있어요.

출처: 문서

본문

시작하기 전에

머신에 Kubernetes 서버를 설치해요. Install Kubernetes 참고.
최신 안정 버전의 Helm을 설치해요. Install Helm 참고.

Helm으로 Grafana 설치

다음 작업을 수행해요:

Grafana Helm 저장소 설정 — Grafana를 설치할 공간을 제공.
Helm으로 Grafana 배포 — Grafana를 네임스페이스에 설치.
Grafana 접근 — 로그인 단계.

Grafana Helm 저장소 설정

Grafana 저장소를 추가하려면 다음 문법을 사용해요:

helm repo add <DESIRED-NAME> <HELM-REPO-URL>

예제:

helm repo add grafana-community https://grafana-community.github.io/helm-charts

다음 명령으로 저장소가 추가됐는지 확인해요:

helm repo list

다음 명령으로 저장소를 업데이트해 최신 Grafana Helm Charts를 다운로드해요:

helm repo update

Grafana Helm Charts 배포

Grafana Helm 차트를 배포할 때 기본 네임스페이스에 의존하지 말고 별도 네임스페이스를 사용하세요. 기본 네임스페이스에는 다른 애플리케이션이 이미 실행 중일 수 있고, 이는 충돌과 잠재적 문제를 일으킬 수 있어요.

네임스페이스를 만들려면:

kubectl create namespace monitoring

공식 저장소를 검색해요:

helm search repo grafana-community/grafana

네임스페이스 안에 Grafana Helm Chart를 배포해요:

helm install my-grafana grafana-community/grafana --namespace monitoring

여기서 helm install은 차트를 클러스터에 배포하고, my-grafana는 차트의 논리적 이름, grafana-community/grafana는 설치할 저장소·패키지 이름, --namespace는 차트를 배포할 Kubernetes 네임스페이스(예: monitoring)예요. 4. 배포 상태를 확인해요:

helm list -n monitoring

STATUS 컬럼에 deployed가 표시되는지 확인해요. 5. 네임스페이스의 모든 객체 전체 상태를 확인해요:

kubectl get all -n monitoring

Grafana 접근

다음 명령으로 차트 노트를 얻어요:

helm get notes my-grafana -n monitoring

이 명령은 Grafana admin 계정 로그인 비밀번호를 디코딩하는 방법과 Grafana 서비스에 접근하는 방법에 대한 완전한 지침을 담은 NOTES 출력을 제공해요. 2. Grafana admin 비밀번호를 얻으려면:

kubectl get secret --namespace monitoring my-grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo

디코딩한 비밀번호를 머신의 파일에 저장해요.
웹 브라우저에서 Grafana 서비스에 접근하려면:

export POD_NAME=$(kubectl get pods --namespace monitoring -l "app.kubernetes.io/name=grafana,app.kubernetes.io/instance=my-grafana" -o jsonpath="{.items[0].metadata.name}")

Grafana pod가 포트 3000을 듣도록 포트 포워딩을 실행해요:

kubectl --namespace monitoring port-forward $POD_NAME 3000

브라우저에서 127.0.0.1:3000으로 이동해요.
로그인 화면에서 username에 admin, password로 앞서 저장한 값을 붙여넣어요.

Grafana 기본 구성 커스터마이즈

values.yaml 파일은 이미지 버전, 리소스 제한, 서비스 구성 같은 다양한 파라미터의 값을 지정해 차트 구성을 커스터마이즈하게 해줘요. helm install 또는 upgrade 명령으로 values.yaml의 값을 수정해 배포를 요구사항에 맞출 수 있어요.

values.yaml 파일 다운로드

구성 변경을 위해 Grafana Helm Charts 저장소에서 values.yaml을 다운로드해요: https://github.com/grafana-community/helm-charts/blob/main/charts/grafana/values.yaml

Note: 사용 사례에 따라 구성 변경을 담은 단일 YAML 파일 또는 여러 YAML 파일을 사용할 수 있어요.

영구 스토리지 활성화 (권장)

기본적으로 영구 스토리지는 비활성화되어 있어 Grafana가 임시(ephemeral) 스토리지를 사용하고 모든 데이터가 컨테이너 파일시스템에 저장돼요. 이 데이터는 컨테이너가 중지·재시작·크래시되면 손실돼요. 컨테이너 재시작이나 실패 시 데이터가 보존되도록 Grafana Helm Charts에서 영구 스토리지를 활성화하는 것을 강력히 권장해요.

편집기에서 values.yaml을 열어요.
persistence 섹션 아래에서 enabled 플래그를 false에서 true로 변경해요:

persistence:
  type: pvc
  enabled: true
  # storageClassName: default

변경 사항을 적용하려면 다음 helm upgrade 명령을 실행해요:

helm upgrade my-grafana grafana-community/grafana -f values.yaml -n monitoring

이제 PVC가 대시보드·데이터 소스 등 모든 데이터를 저장해요.

플러그인 설치 (예: Zabbix app, Clock panel)

편집기에서 values.yaml을 열어요.
plugins: 줄을 찾아 그 아래에 설치할 플러그인을 정의해요:

plugins:
- alexanderzobnin-zabbix-app
- grafana-clock-panel

변경 사항을 저장하고 helm upgrade로 플러그인을 설치해요:

helm upgrade my-grafana grafana-community/grafana -f values.yaml -n monitoring

브라우저에서 127.0.0.1:3000으로 이동하고 로그인한 뒤 UI -> Administration -> Plugins에서 설치된 플러그인을 확인해요.

Private CA (인증 기관) 구성

많은 엔터프라이즈 네트워크에서 TLS 인증서는 비공개 인증 기관이 발급하며 기본적으로 신뢰되지 않아요. Grafana 인스턴스가 이 비공개 CA가 발급한 인증서를 노출하는 서비스와 상호작용해야 한다면 Grafana가 루트 인증서를 신뢰하도록 해야 해요. 다음 경우에 구성이 필요할 수 있어요: GEM/GEL/GET 플러그인 같은 클러스터가 비공개 인증서를 쓰는 경우, 비공개 인증서로 HTTPS를 듣는 데이터 소스에 연결하려는 경우, 전송 중 암호화에 비공개 인증서를 쓰는 백엔드 DB나 캐싱 사용 시. 인스턴스 전체(플러그인·데이터 소스·백엔드 연결)에 적용되는 간단한 해결책은 자신의 서명 CA 인증서를 Kubernetes 배포에 추가하는 것이에요.

인증서를 담은 ConfigMap을 만들고 클러스터에 배포해요:

# grafana-ca-configmap.yaml
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: grafana-ca-cert
data:
  ca.pem: |
    -----BEGIN CERTIFICATE-----
    (rest of the CA cert)
    -----END CERTIFICATE-----

kubectl apply --filename grafana-ca-configmap.yaml --namespace monitoring

Helm values.yaml을 열고 extraConfigmapMounts: 줄을 찾아 마운트할 ConfigMap을 지정해요:

extraConfigmapMounts:
   - name: ca-certs-configmap
     mountPath: /etc/ssl/certs/ca.pem
     subPath: ca.pem
     configMap: grafana-ca-cert
     readOnly: true

변경 사항을 저장하고 helm upgrade로 새 ConfigMap을 마운트해요:

helm upgrade my-grafana grafana-community/grafana --values values.yaml --namespace monitoring

문제 해결

로그 수집: 문제 해결 시 Grafana 서버 로그를 보는 것이 중요해요.

kubectl logs --namespace=monitoring deploy/my-grafana

여러 컨테이너가 있으면:

kubectl logs --namespace=monitoring deploy/grafana -c my-grafana

로그 레벨 증가: 기본적으로 Grafana 로그 레벨은 info지만 디버그 모드로 올려 문제 진단 정보를 얻을 수 있어요.

values.yaml에서 grafana.ini 문자열을 검색해 로그 모드 섹션을 찾아요.
mode: console 줄 바로 아래에 level: debug를 추가해요:

grafana.ini:
  ...
  mode: console
  level: debug

helm upgrade로 적용하고 Server Admin > Settings에서 log를 검색해 debug 레벨을 확인해요.

Grafana admin 시크릿(로그인 자격 증명) 초기화: 기본적으로 슈퍼 admin 계정의 로그인 자격 증명은 시크릿으로 생성돼요.

values.yaml에서 adminPassword를 검색해 새 비밀번호를 정의해요:

adminUser: admin
adminPassword: admin

helm upgrade 명령을 실행해요:

helm upgrade my-grafana grafana-community/grafana -f values.yaml -n monitoring

username과 password 모두 admin으로 로그인해 슈퍼 admin으로 로그인할 수 있는지 확인해요.

Grafana 배포 제거

배포를 제거하려면:

helm uninstall my-grafana -n monitoring

네임스페이스 monitoring도 삭제하려면:

kubectl delete namespace monitoring

Helm Charts로 Grafana 배포