Helm으로 Kubernetes에 Grafana 배포하기
Grafana Helm 차트를 설치하고 PVC 영구 저장, Prometheus 데이터 소스와 대시보드 프로비저닝, Ingress TLS를 설정하는 방법을 설명합니다.
Grafana Pod를 교체한 뒤 대시보드가 사라졌는데도 Prometheus에는 시계열이 그대로 남아 있을 수 있습니다. 두 시스템이 저장하는 데이터가 다르기 때문입니다. Prometheus는 메트릭을 보관하고, Grafana는 화면에서 만든 대시보드와 사용자 설정을 자체 데이터베이스에 저장합니다. 영구 볼륨은 이 데이터베이스를 유지합니다. 프로비저닝을 쓰면 버전 관리 중인 파일에서 데이터 소스와 대시보드를 다시 만들 수 있습니다.
이 글에서는 Helm으로 Kubernetes에 Grafana를 배포하고 Prometheus에 연결합니다. 화면은 열리는데 패널이 비어 있을 때도 살펴봅니다. 예제는 Grafana 13.3.0을 포함한 커뮤니티 차트 14.4.0을 사용합니다. Kubernetes 1.25 이상의 1.x 버전이 필요합니다. 예제 매니페스트는 로컬 Helm으로 렌더링해 확인했습니다.
Grafana를 설치하고 로컬에서 접속하기
임시 확인용이라면 Grafana 커뮤니티 차트의 기본값으로 시작할 수 있습니다. 여기서 만든 대시보드를 보존하려면 다음 절의 영구 저장 설정을 처음부터 적용하세요.
helm repo add grafana-community https://grafana-community.github.io/helm-charts
helm repo update grafana-community
helm upgrade --install grafana grafana-community/grafana \
--version 14.4.0 --namespace monitoring --create-namespace
생성된 초기 관리자 비밀번호를 조회하고 Grafana Service로 로컬 포트를 포워딩합니다. 기본 Service는 80번 포트로 받은 요청을 컨테이너의 3000번 포트에 전달합니다.
kubectl -n monitoring get secret grafana \
-o jsonpath='{.data.admin-password}' | base64 -d; printf '\n'
kubectl -n monitoring port-forward svc/grafana 3000:80
브라우저에서 http://localhost:3000을 열어 admin으로 로그인합니다. Secret에 저장된 값은 초기 인증 정보입니다. Grafana에서 이미 비밀번호를 변경했다면 현재 비밀번호는 이 값과 다릅니다.
Grafana 데이터베이스를 PVC에 보관하기
기본 SQLite를 사용하는 단일 복제본이라면 데이터 디렉터리에 영구 볼륨을 마운트합니다. 클러스터에서 요청한 스토리지를 제공할 수 있는지 먼저 확인하세요. 이 예제는 Deployment 전략을 Recreate로 설정합니다. 기존 Pod를 중지한 뒤 새 Pod를 띄우므로 업그레이드 중 잠시 접속이 끊깁니다.
monitoring 네임스페이스에 grafana-bootstrap이라는 Secret을 준비하고 admin-user와 admin-password 키를 설정합니다. 아래 내용을 values.yaml로 저장합니다. 비밀번호는 values 파일에 넣지 않습니다.
replicas: 1
deploymentStrategy:
type: Recreate
persistence:
enabled: true
size: 10Gi
admin:
existingSecret: grafana-bootstrap
userKey: admin-user
passwordKey: admin-password
datasources:
datasources.yaml:
apiVersion: 1
datasources:
- name: Prometheus
uid: prometheus
type: prometheus
access: proxy
url: http://prometheus-server.monitoring.svc:80
isDefault: true
dashboardProviders:
dashboardproviders.yaml:
apiVersion: 1
providers:
- name: default
orgId: 1
type: file
options:
path: /var/lib/grafana/dashboards/default
dashboards:
default:
node-exporter:
gnetId: 1860
revision: 46
curlOptions: "-sSLf"
예제 URL은 monitoring 네임스페이스에 릴리스 이름 prometheus로 설치한 독립형 Prometheus 차트의 Service를 가리킵니다. 이 주소에 접속하는 쪽은 Grafana 서버입니다. 이름이나 설치 방식이 다르다면 kubectl -n monitoring get svc로 실제 Service와 포트를 확인하세요.
대시보드가 조회할 데이터를 확인하기
차트는 Pod 초기화 단계에서 Node Exporter Full의 리비전 46을 내려받습니다. 프로바이더는 차트가 JSON을 두는 디렉터리를 읽습니다. 다운로드 주소에 접근할 수 없는 환경이라면 gnetId 다운로드 항목을 제거하고 검토한 JSON을 ConfigMap으로 마운트합니다.
설정을 적용한 다음 PVC 상태를 확인합니다.
helm upgrade --install grafana grafana-community/grafana \
--version 14.4.0 --namespace monitoring --create-namespace \
-f values.yaml
kubectl -n monitoring get pvc,svc
PVC가 Bound가 되면 Grafana Explore에서 Prometheus를 선택해 up을 실행합니다. 다른 타깃이 조회된다고 해서 Node Exporter의 메트릭까지 수집되고 있는 것은 아닙니다. node_uname_info를 조회하고, 대시보드에서도 해당 Prometheus 데이터 소스를 선택하세요. 그래도 빈 패널이 있다면 시간 범위와 필터부터 확인합니다.
Kubernetes 메트릭을 Guance에도 보내려면 DataKit의 KubernetesPrometheus 수집기(영어)에서 어노테이션 기반 검색을 활성화하고 수집할 Pod 또는 Service에 어노테이션을 추가합니다. Prometheus와 DataKit은 각각 수집 대상을 선택하며 Grafana는 계속 Prometheus Service에 쿼리를 보냅니다.
Ingress로 Grafana에 접속하기
아래 예제를 ingress.yaml로 저장하고 Helm 명령에서 -f values.yaml 뒤에 -f ingress.yaml을 추가합니다. private-web은 사용하는 컨트롤러의 IngressClass로 바꿉니다. DNS가 해당 컨트롤러를 가리키도록 설정하고, 같은 네임스페이스에 호스트 이름과 일치하는 TLS Secret을 준비합니다. root_url은 사용자가 브라우저에서 여는 HTTPS 주소로 지정합니다.
ingress:
enabled: true
ingressClassName: private-web
hosts: [grafana.example.com]
tls:
- secretName: grafana-tls
hosts: [grafana.example.com]
grafana.ini:
server:
root_url: https://grafana.example.com/
사용자에게 주소를 공유하기 전에 인증과 접근 제어를 설정하세요. 조회 가능한 데이터 범위는 Grafana와 데이터 소스의 권한 설정에 따릅니다. 포트 포워딩은 로컬에서 문제를 확인할 때 쓸 수 있습니다.
kube-prometheus-stack으로 Grafana를 관리하는 경우
스택의 values에서 grafana.enabled를 확인합니다. 이미 활성화돼 있다면 기존 릴리스의 grafana: 항목을 수정합니다. 함께 설치되는 차트 버전은 스택의 의존성에 따라 결정되므로 해당 버전의 values를 확인하세요.
grafana:
enabled: true
deploymentStrategy:
type: Recreate
persistence:
enabled: true
admin:
existingSecret: grafana-bootstrap
userKey: admin-user
passwordKey: admin-password
이 구성도 SQLite를 쓰는 단일 복제본입니다. Grafana 복제본을 여러 개 운영하려면 공유 PostgreSQL 또는 MySQL이 필요합니다. Grafana Alerting의 고가용성은 별도로 설정합니다.
배포 후 자주 나오는 질문
Pod를 교체한 뒤 대시보드가 사라졌습니다.
영구 저장을 켜지 않으면 Grafana는 데이터 디렉터리에 Pod의 임시 볼륨을 사용합니다. 해당 데이터베이스에만 저장한 대시보드는 사라질 수 있습니다. 프로비저닝 파일이 남아 있으면 파일에 정의된 대시보드는 다시 불러올 수 있습니다. 기존 설치에 PVC를 붙이기 전에 필요한 데이터를 내보내거나 백업하세요. 새 볼륨은 기존 볼륨의 데이터를 자동으로 옮기지 않습니다.
관리자 비밀번호를 어떻게 재설정하나요?
로그인할 수 있다면 Grafana에서 변경하세요. 복구할 때는 grafana cli admin reset-admin-password를 사용합니다. 실행 중인 Grafana와 같은 구성과 데이터 디렉터리를 지정해야 실제 데이터베이스에 반영됩니다. Kubernetes Secret을 수정하면 초기 인증 정보가 바뀝니다. 기존 Grafana 사용자의 비밀번호는 Grafana에서 재설정해야 합니다.
대시보드를 Git으로 관리할 수 있나요?
JSON을 Git에 보관하고 ConfigMap으로 프로비저닝할 수 있습니다. GitOps 컨트롤러가 지정한 레이블로 ConfigMap을 만들고, sidecar.dashboards.enabled로 켠 사이드카가 이를 감시하게 할 수도 있습니다. 원본 파일이 바뀌면 화면에서 저장한 변경 사항이 덮어써질 수 있습니다. Grafana 대시보드 프로비저닝
함께 읽기 · Grafana로 Prometheus 메트릭 시각화하기
