Zabbix로 Kubernetes를 모니터링할 때 일반적으로는 각 노드마다 Zabbix Agent2 pod(또는 DaemonSet)를 올려 호스트 리소스를 수집하고, Zabbix Proxy pod는 cluster 상태를 수집해 Server로 전달한다. 그러나 이미 노드 OS에 zabbix‑agent2가 설치되어 있거나, 관리 정책상 cluster 내부에는 Proxy만 두고 싶은 경우 proxy pod만 배포하고 host‑agent2로 노드 메트릭을 커버하는 방식이 적합하다.
이러한 전제하에서 taint 걸린 워크 노드에 zabbix proxy를 배포하고자 한다.

관련 글 링크 :

Zabbix로 Kubernetes 모니터링 구축

검증 환경

• Kubernetes: Ubuntu 24.04
• Zabbix Helm Chart: 7.4
• host OS에 zabbix-agent2 직접 설치 (pod 사용 X)
• cluster 내부에는 **Zabbix Proxy + kube-state-metrics(KSM)**만 배포
• Helm chart에서 Zabbix agent DaemonSet은 비활성화 (zabbixAgent.enabled: false)

---

0. 전체 구조 개념

• Zabbix Server는 cluster 외부
• Server는 cluster node CIDR 접근 가능해야 한다
• kubelet / node / API server 템플릿은 Proxy 없이 사용 가능
• 단, “Kubernetes cluster state by HTTP” 템플릿은 Proxy 필수
  (KSM → Proxy → Server 구조)

---

1. Helm values.yaml 준비

# helm show values . > $HOME/zabbix_values.yaml

이제 $HOME/zabbix_values.yaml 기준으로 작업한다.

1.1 Zabbix agent pod 비활성화 설정 (중요)

이번 구성에서는 각 노드에 이미 host zabbix-agent2가 설치되어 있다는 전제이기 때문에,
Helm chart가 추가로 agent pod(DaemonSet)를 깔지 않도록 해야 한다.

values.yaml에서 zabbixAgent 섹션을 찾아 다음과 같이 설정한다.

이렇게 하면:

• Kubernetes 안에는 agent pod가 전혀 올라가지 않고,
• 노드 모니터링은 host에 설치된 zabbix-agent2가 담당하게 된다.

그 외 Proxy / KSM 관련 설정만 유지하면 된다.

---

2. 기본 proxy nodeSelector/tolerations
비활성화

values.yaml 하단에 있는 아래 항목들은 충돌을 피하기 위해 전부 주석 처리한다.

---

3. zabbixProxy 섹션에 nodeSelector + tolerations 추가

values.yaml에서 아래 블록을 찾는다.

zabbixProxy:
  enabled: true

여기에 우리가 사용할 nodeSelector / tolerations를 직접 작성한다.

---

📌 (중요) Proxy 배포할 노드 hostname & taint
값 확인 가이드

(이 섹션을 반드시 참고해야 toleration이 정확하게 들어맞음)

✔ 1) 노드 hostname(label) 확인

# kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{" = "}{.metadata.labels.kubernetes\.io/hostname}{"\n"}{end}'

출력 예시:

worker-01 = worker-01

→ <example-system-1> 여기에 들어갈 값은
명령어로 확인한 노드라벨의 값만 그대로 넣으면 된다.

Tip. 대부분의 Kubernetes에서는 hostname 라벨의 value가 노드 이름과 동일하다

---

✔ 2) 해당 노드에 걸린 taint 확인하기

이 값이 toleration에 그대로 들어가야 스케줄링이 성립된다.

방법 A (가장 직관적)

# kubectl describe node <노드명> | grep -A3 Taints

출력 예:

Taints:  Service=system:NoSchedule

방법 B (jsonpath)

# kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{" -> "}{.spec.taints}{"\n"}{end}'

출력 예:

worker-01 -> [{"effect":"NoSchedule","key":"Service","value":"system"}]

---

✔ 3) toleration에 넣을 때의 형태

노드 taint가 다음과 같다면:

Service=system:NoSchedule

values.yaml에는 반드시 이렇게 들어가야 한다:

tolerations:
  - key: Service
    operator: Equal
    value: system
    effect: NoSchedule

⚠ 주의

• key, value, effect는 글자 하나라도 달라지면 절대 매칭되지 않는다
• 대소문자(Service/system)도 반드시 동일해야 한다

---

4. helm install

# helm install zabbix . \
  -n monitoring \
  --dependency-update \
  -f $HOME/zabbix_values.yaml

Proxy pod가 지정한 노드에서 Running인지 확인:

# kubectl get pods -n monitoring -o wide

---

5. kube-state-metrics(KSM)이 Pending될 때 해결

(values.yaml만으로는 반영이 누락될 수 있어 patch 사용이 가장 확실한 우회 방법)

Ubuntu 24.04 + Zabbix Helm 7.4 환경에서는
values.yaml의 tolerations가 KSM Deployment에는 정상 반영되지 않는 경우가 있다.

즉:

• “values.yaml로 절대 적용 안 된다”가 아니라
• “특정 환경에서는 적용이 누락될 수 있고,
  patch 방식이 가장 안정적으로 동작한다”가 정확한 표현이다.

5.1 우회 해결 방법: kubectl patch

kubectl patch deploy zabbix-kube-state-metrics -n monitoring --type=merge -p '
spec:
  template:
    spec:
      nodeSelector:
        kubernetes.io/hostname: <배포할-노드-hostname>
      tolerations:
        - key: <taint-key>
          operator: "Equal"
          value: "<taint-value>"
          effect: "NoSchedule"
'

적용 후:

# kubectl get pods -n monitoring

→ zabbix-kube-state-metrics가 Running이면 정상

---

6. 개념 가이드: Taint / Toleration 이해하기

✔ taint란?

• 노드에 조건을 걸어 pod 스케줄링을 제한하는 기능
• 예: kubectl taint nodes <node> key=value:NoSchedule
• 이 노드에는 이 taint를 toleration 하는 pod만 들어올 수 있다.

---

✔ toleration이란?

• pod가 특정 taint를 허용한다는 선언
• 형식: tolerations: - key: "key" operator: "Equal" value: "value" effect: "NoSchedule"

---

✔ 매칭 규칙 요약

taint	toleration	결과
key=value:NoSchedule	key=value + NoSchedule	OK
key=value:NoSchedule	key만 있고 value 없음	value mismatch → X
NoExecute	tolerationSeconds	제한적 허용

---

7. 요약

• host zabbix-agent2로 node 모니터링
• Helm chart에서는 zabbixAgent.enabled: false로 agent pod(DaemonSet) 배포를 막는다
• cluster 내부에는 Proxy + KSM만 배포
• Proxy toleration은 zabbixProxy 섹션에 직접 작성
• KSM toleration은 values.yaml 반영 실패 사례가 있어 patch가 안정적인 대안
• taint key/value/effect는 노드 값과 100% 일치해야 한

🛠 마지막 수정일: 2025.11.21