Zabbix로 Kubernetes 모니터링 구축

버전 주의(중요): Zabbix는 7.4/7.2/7.0(LTS) 등 버전별로 Helm Repo URL/차트 브랜치가 다름.
아래 예시는 7.4 기준이며, 운영 중인 Zabbix 서버/템플릿 버전에 맞춰 <ZBX_VER>만 변경.
Repo 패턴:
https://cdn.zabbix.com/zabbix/integrations/kubernetes-helm/<ZBX_VER>/

0) 사전 준비

• Kubernetes 1.23+ (권장 1.24+) / kubectl, helm 사용 가능
• Zabbix Server 또는 Proxy에서 TCP 10050/10051 경로 허용
• 적용하고자 하는 버전으로 Zabbix agent2 설치
• 설치 네임스페이스(예시): monitoring

1) Repo 등록(버전 선택)

- 사용할 Zabbix 버전 지정 (7.4 / 7.2 / 7.0 중 하나)
# export ZBX_VER=7.4

- 네임스페이스 생성
# kubectl create namespace monitoring 2>/dev/null || true

- 버전별 Helm Repo 추가/업데이트
# helm repo add zabbix-chart-${ZBX_VER} https://cdn.zabbix.com/zabbix/integrations/kubernetes-helm/${ZBX_VER}/

# helm repo update

2) 기본 values 덤프 → 파일 한 장만 편집

- 차트 기본값을 로컬 파일로 저장
# helm show values zabbix-chart-${ZBX_VER}/zabbix-helm-chrt > zabbix_values.yaml

아래 항목을 같은 파일(zabbix_values.yaml) 에서 찾아 환경에 맞게 수정
버전별로 다를수 있음 . 아래는 7.4 기준임

1. kube-state-metrics 특정 노드에 배치

## kubeStateMetrics.enabled 
 deploys the kube-state-metrics deployment: K8s 오브젝트 상태(Deployment/Pod/노드 컨디션 등)를 실질적으로 제공
: kubeStateMetrics 블록 안에 nodeSelector 추가: taint 걸린 노드   
  라면 tolerations 필요함
values 블록 이름이 kubeStateMetrics 로 되어 있다면
=> 아래와 같이 kube-state-metrics 로 수정

kube-state-metrics:
  enabled: true
  nodeSelector:
    kubernetes.io/hostname: example-node1   - 배포할 노드

2. Zabbix Proxy 특정 노드에 배포

zabbixProxy:
  enabled: true
  nodeSelector:
    kubernetes.io/hostname: example-node1
  tolerations: []   # 필요 시 taint에 맞춰 추가
  affinity: {}      # (선택) 더 정교한 제어 시 사용

 ## Zabbix proxy hostname
    - name: ZBX_HOSTNAME
      value: example-proxy      => 추후 프록시명 설정시   
                                   사용할 이름

 ## Note that since version 6.0 the variable ZBX_SERVER_PORT is not supported anymore. Instead, add a colon (:) followed by the port number to the end of ZBX_SERVER_HOST value.
    - name: ZBX_SERVER_HOST
      value: "zabbix 서버 IP"

 

3. Zabbix Agent를 특정 노드로 제한(Agent는 DaemonSet)
: false로 할경우 아래 3)번 작업 호스트 agent2 중지 작업은 
   필요 없음.여기서는  true로 설정하도록 한다.

zabbixAgent:
  enabled: true
  nodeSelector:
    kubernetes.io/hostname: emample-node1
  # 기본적으로 DaemonSet이므로, 이 조건에 맞는 노드(example-node1)에만 1개 배포됩니다

## Node selector for Agent. Only supports Linux. 
   #반드시 아래 설정 주석 처리
  #nodeSelector:
  #  kubernetes.io/os: linux
  
4. Zabbix Java Gateway 특정 노드로 배포
   : 여기서는 일단 false로 한다. true로 할경우
     아래처럼 적용

zabbixJavaGateway:
  enabled: true  # 안 쓰는 경우 false
  nodeSelector:
    kubernetes.io/hostname: example-node1

5. zabbix server ip 변경
  ## Zabbix server host
    - name: ZBX_SERVER_HOST
      value: 실제 서버 IP


=> 기본적으로 이 정도 컨피그만 수정해도 사용하는데          
   큰 무리는없으나, 
   상황에 맞게 컨피그를 수정할 수도 있다.

필요 시 같은 파일에서 resources, tolerations, hostNetwork 등도 함께 조정.
핵심은 한 파일만 수정하여 그대로 설치한다는 점.

zabbix web ui 에서 관리 -> 프록시 ->
프록시 생성 -> 프록시명 설정 후 추가

zabbix template 적용시 Prod K8S Cluster
에 프록시 추가

• 템플릿 중 kubernetes cluster state by http는 k8s cluster 외부에 zabbix 서버가 있을
  경우 데이터 수집이 불가함으로
  zabbix proxy가 반드시 필요하다

3) 배포 대상 호스트 agent2 중지

# 호스트 zabbix-agent2 중지/비활성화
sudo systemctl stop zabbix-agent2
sudo systemctl disable zabbix-agent2

• pod로 배포되지 않은 노드는 기존 호스트 agent2 계속 사용 → 중복/충돌 없음
• pod로 배포된 노드는 Pod만 사용(호스트 agent2 중지) → 포트/중복 수집 방지

4) Helm 설치

#helm install zabbix zabbix-chart-${ZBX_VER}/zabbix-helm-chrt \
  -n monitoring \
  --dependency-update \
  -f zabbix_values.yaml

- 확인
# kubectl -n monitoring get pods -o wide

- zabbix helm 설치후 values.yaml 수정시 배포 
# helm upgrade --install zabbix zabbix-chart-${ZBX_VER}/zabbix-helm-chrt   -n monitoring   -f zabbix_values.yaml

5) ServiceAccount 토큰 발급(K8s 1.24+ 권장)

# 즉시 토큰 출력(권장)
kubectl -n monitoring create token zabbix-service-account

# (구버전 호환) Secret에서 추출하는 방식
kubectl -n monitoring get secret | grep zabbix-service-account
kubectl -n monitoring get secret zabbix-service-account -o jsonpath='{.data.token}' | base64 -d; echo

6) Zabbix 템플릿 적용(충돌 회피 원칙)

• Host K8S Cluster : Kubenetes cluster state by HTTP 등 나머지 템플릿 연결
• Host K8S NODE : Kubernetes Kubelet by HTTP / Kubernetes nodes by HTTP 연결

공통 매크로

• {$KUBE.API.TOKEN} = (위에서 발급한 SA 토큰)
• {$KUBE.KUBELET.URL} = https://<노드IP>:10250
• {$KUBE.API.URL} = https://<apiserver ip>:6443
• 상황에 따라서 추가 : {$KUBE.API.SERVER.URL} = https://<apiaerver ip>:6443/metrics
• kube.kubelet.url 의 주소를 마스터 노드의 ip로 지정해도 무방

7) Zabbix UI 입력 예시

• 예시 호스트명: Prod K8S Cluster / Prod K8S NODE
• 예시 IP: API IP – 198.168.190.24 (master node) / Kubelet IP – 198.168.190.25 (zabbix pod 배포된 node ip)
  
  1. 클러스터 호스트 템플릿 – cluster state / api server / controller manager / scheduler

2. 클러스터 호스트 – 매크로 입력

3. 노드 호스트 – node/kubelet 템플릿

4. 노드 호스트 – 매크로 입력

8) 체크리스트

• 배포된 노드의 호스트 agent2 완전 중지
• Server ↔ Agent2(10050/10051) 통신 허용
• {$KUBE.API.TOKEN} 유효, 필요 권한(get/list/watch) 확인
• {$KUBE.KUBELET.URL}(노드IP:10250) 접근 가능
• 템플릿 Host A/B 분리 유지(새 템플릿 추가 시에도 동일 원칙 적용)
• Repo/차트/템플릿 버전이 서버 버전과 일치

9) FAQ 요약

• zabbix 서버를 왜 외부에 설치 하는지?
  -> 온프레미스 상황에서는 모니터링 서버인 zabbix를 k8s 외부에
  두어야 하는게 필수적인 상황은 아니지만. k8s cluster의 상태도
  모니터링 해야 하니..외부에 두는걸 권장

🛠 마지막 수정일: 2025.10.28