17. ProxmoxVE와 연동하기

Zabbix로 Proxmox VE 모니터링하기

Zabbix로 Proxmox VE를 모니터링할 수 있습니다. 가장 일반적인 방식은 Zabbix Server 또는 Proxy가 Proxmox VE REST API에 HTTPS로 접근하는 agentless API monitoring입니다.

Zabbix Server / Proxy
        │
        │ HTTPS TCP 8006
        │ Read-only API Token
        ▼
Proxmox VE Cluster
├── PVE Node
├── VM
├── LXC Container
├── Storage
├── Cluster / Quorum
└── HA Resource

Zabbix 공식 Proxmox VE by HTTP 템플릿은 Proxmox API를 통해 node, VM, LXC container, storage 등의 상태를 수집할 수 있습니다.

권장 구조

운영 환경에서는 Zabbix Server 또는 Zabbix Proxy를 Proxmox 관리망에 배치하는 구성이 좋습니다.

Management Network
├── Zabbix Server / Proxy
├── Proxmox VE Node
├── Proxmox Backup Server
├── Ceph / Shared Storage
└── Bastion Host

권장 원칙은 다음과 같습니다.

Proxmox API TCP 8006은 Zabbix Server 또는 Proxy에만 제한적으로 허용
root@pam 대신 monitoring 전용 사용자와 API Token 사용
Token에는 PVEAuditor 같은 읽기 전용 권한만 부여
Token privilege separation 활성화
사설 CA 또는 조직 CA를 Zabbix Server·Proxy trust store에 배포
TLS 검증 비활성화나 curl -k는 최종 운영 설정에 사용하지 않음

Proxmox API는 HTTPS TCP 8006에서 제공되며, API Token은 stateless REST API 접근을 지원합니다.

API Token 생성

Monitoring 사용자 생성

pveum user add zabbix-monitor@pve \
  --comment "Zabbix Proxmox VE API monitoring"

읽기 전용 Token 생성

pveum user token add \
  zabbix-monitor@pve \
  zabbix-api \
  --privsep 1 \
  --comment "Read-only token for Zabbix"

Token ID는 다음과 같은 형식입니다.

zabbix-monitor@pve!zabbix-api

Token Secret은 생성 시점에만 확인할 수 있으므로, 즉시 Zabbix Secret Macro 또는 조직의 Secret Manager에 보관합니다.

읽기 전용 권한 부여

Datacenter 전체 조회가 필요하다면 / 경로에 PVEAuditor 권한을 부여할 수 있습니다.

pveum acl modify / \
  --token 'zabbix-monitor@pve!zabbix-api' \
  --role PVEAuditor

권한을 확인합니다.

pveum user token permissions \
  zabbix-monitor@pve \
  zabbix-api

API Token은 사용자 권한과 Token ACL의 교집합으로 권한이 결정됩니다. monitoring 계정과 Token 모두 최소 권한으로 관리하는 것이 좋습니다.

API 연결 테스트

Zabbix 설정 전, Zabbix Server 또는 Proxy에서 API 호출을 먼저 확인합니다.

export PVE_TOKEN_ID='zabbix-monitor@pve!zabbix-api'
export PVE_TOKEN_SECRET='발급받은-Token-Secret'

curl --fail --silent --show-error \
  -H "Authorization: PVEAPIToken=${PVE_TOKEN_ID}=${PVE_TOKEN_SECRET}" \
  [https://pve-01.example.internal:8006/api2/json/version](https://pve-01.example.internal:8006/api2/json/version)

클러스터 상태도 확인할 수 있습니다.

curl --fail --silent --show-error \
  -H "Authorization: PVEAPIToken=${PVE_TOKEN_ID}=${PVE_TOKEN_SECRET}" \
  [https://pve-01.example.internal:8006/api2/json/cluster/status](https://pve-01.example.internal:8006/api2/json/cluster/status)

사설 CA 환경에서는 Zabbix Server 또는 Proxy에 PVE Cluster CA나 조직 Root CA를 등록한 뒤, 인증서 검증을 유지한 상태에서 호출해야 합니다.

curl --fail --silent --show-error \
  --cacert /etc/pki/ca-trust/source/anchors/internal-root-ca.crt \
  -H "Authorization: PVEAPIToken=${PVE_TOKEN_ID}=${PVE_TOKEN_SECRET}" \
  [https://pve-01.example.internal:8006/api2/json/version](https://pve-01.example.internal:8006/api2/json/version)

curl -k는 TLS 검증을 우회하므로 초기 장애 분리 외에는 사용하지 않습니다.

Zabbix 템플릿 설정

Zabbix에서 공식 Proxmox VE by HTTP 템플릿을 Host에 연결하고, API endpoint와 Token 정보를 Host Macro로 설정합니다.

Macro	예시	설명
`{$PVE.URL.HOST}`	`pve-01.example.internal`	Proxmox API FQDN 또는 IP
`{$PVE.URL.PORT}`	`8006`	HTTPS API 포트
`{$PVE.TOKEN.ID}`	`zabbix-monitor@pve!zabbix-api`	API Token ID
`{$PVE.TOKEN.SECRET}`	Secret Macro	API Token Secret

Token Secret은 일반 Macro보다 Zabbix Secret Text Macro 또는 별도 Secret 관리 시스템을 사용하는 것이 좋습니다.

모니터링 범위

공식 HTTP 템플릿으로는 Proxmox API 기반 상태를 수집할 수 있습니다.

영역	주요 수집 항목
PVE Node	CPU, memory, swap, uptime, rootfs
VM	실행 상태, CPU, memory, resource 상태
LXC	container 상태와 resource 상태
Storage	active 상태, 사용량, 여유 공간
Cluster	node discovery, cluster resource
API	PVE API endpoint 접근 상태

다만 API 템플릿만으로는 운영에 충분하지 않을 수 있습니다.

Zabbix Monitoring Layers
├── Proxmox API
│   ├── Node / VM / CT
│   ├── Storage
│   ├── Cluster / HA
│   └── Backup Overview
│
├── PVE Host OS Agent
│   ├── CPU / Memory / Filesystem
│   ├── ZFS / SMART
│   ├── systemd / Journal
│   └── Network / Corosync
│
├── Guest OS Agent
│   ├── Linux / Windows Health
│   ├── Application Process
│   ├── DB / Filesystem
│   └── Kubernetes Node
│
└── Custom Checks
    ├── Ceph Health
    ├── PBS Verify / Sync
    ├── Backup Failure
    └── TLS Certificate Expiry

VM이 Proxmox API에서 running 상태여도, VM 내부의 PostgreSQL, GitLab, Harbor, kubelet, containerd가 정상이라는 뜻은 아닙니다. Hypervisor, Guest OS, Application 계층을 분리해 모니터링해야 합니다.

추가 권장 항목

영역	권장 방식	주요 항목
PVE Host OS	Zabbix Agent 2	CPU, load, memory, filesystem, systemd, kernel log
ZFS	UserParameter 또는 script	pool health, checksum error, scrub, DEGRADED
SMART	Agent + `smartctl`	disk health, media error, temperature
Corosync	custom script 또는 log check	quorum, membership, link failure
Ceph	exporter·API·script	`HEALTH_WARN`, OSD down, PG degraded
PBS	PBS API 또는 custom script	datastore capacity, verify, sync, prune·GC
TLS	certificate check	PVE 8006, PBS 8007, internal repository
Backup	task/API monitoring	backup failure, duration, storage capacity
VM Guest	Zabbix Agent	application, database, filesystem, service health

알림 우선순위 예시

이벤트	권장 심각도
Cluster quorum loss	Disaster
Ceph `HEALTH_ERR`	Disaster
Proxmox node down	High
Corosync membership 또는 link failure	High
HA failover 실패	High
PBS datastore full 임박	High
Backup job 실패	High
ZFS pool DEGRADED	High
VM·CT unexpected down	Average~High
Root filesystem 85% 이상	Warning
TLS certificate 30일 이내 만료	Warning
Snapshot 장기 유지	Warning

권장 구성

Zabbix Server
        │
Zabbix Proxy on Management Network
        │
├── Proxmox VE by HTTP Template
│   └── Read-only API Token
│
├── Zabbix Agent on PVE Nodes
│   └── Host OS, ZFS, SMART, systemd, Corosync
│
├── Zabbix Agent on Critical VM
│   └── DB, GitLab, Harbor, Kubernetes Node
│
└── Custom Monitoring
    ├── Ceph Health
    ├── PBS Verify / Sync
    ├── Backup Job
    └── Certificate Expiry

핵심 정리

Zabbix는 Proxmox VE REST API를 통해 agentless monitoring을 할 수 있습니다.
공식 Proxmox VE by HTTP 템플릿과 읽기 전용 API Token 조합을 우선 검토합니다.
monitoring 용도에는 root@pam 대신 전용 사용자, privilege-separated Token, PVEAuditor 권한을 사용합니다.
Zabbix Server 또는 Proxy는 Proxmox 관리망에서 HTTPS TCP 8006으로 접근하도록 구성합니다.
사설 CA 환경에서는 Zabbix Server·Proxy에도 CA trust를 배포하고 TLS 검증을 유지합니다.
API monitoring만으로는 부족하므로 PVE Host, ZFS, SMART, Corosync, Ceph, PBS, Guest OS, Application monitoring을 함께 구성합니다.
VM이 running 상태여도 application 정상성을 보장하지 않으므로 Guest OS와 service monitoring이 필요합니다.
quorum loss, Ceph error, backup failure, PBS capacity, ZFS degraded, certificate expiry를 핵심 alert로 관리합니다.