[인프라] Proxmox API Grafana 연동으로 자원 사용량 모니터링과 자동화 사례

홈랩이나 소규모 가상화 환경을 굴리다 보면, 처음에는 Proxmox VE(프록스목스 가상화 환경) 웹 UI만 봐도 충분하다고 느끼실 수 있습니다. 저도 그랬거든요. 그런데 VM이 몇 대만 넘어가도 CPU, Memory(메모리), Storage(스토리지) 사용량이 순간적으로 튀는 구간이 보이고, 그때마다 사람이 직접 들어가 확인하는 방식은 금방 한계가 오더라고요. 그래서 이번 글에서는 Proxmox API Grafana 조합으로 자원 사용량을 한눈에 보고, 특정 조건에서는 자동화까지 연결한 실제 운영 패턴을 정리해보겠습니다. Proxmox 모니터링과 API 자동화, Grafana 연동이 왜 같이 가야 하는지, 제가 직접 해보면서 느낀 삽질 포인트까지 솔직하게 적어보겠습니다.

특히 이런 분들께 잘 맞습니다. VM 수가 늘면서 자원 사용량을 장기적으로 보고 싶으신 분, 장애 직전의 징후를 미리 잡고 싶으신 분, 그리고 반복 확인 작업을 자동화하고 싶으신 분이요. 여기서 중요한 포인트! 단순히 대시보드만 예쁘게 만드는 게 목적이 아니라, 운영 판단 속도를 올리는 것이 핵심입니다.

Proxmox API Grafana 연동 전체 흐름을 보여주는 아키텍처 예시입니다. Proxmox 노드, 메트릭 수집 스크립트, 시각화 계층의 관계를 한눈에 볼 수 있게 배치하면 이해가 훨씬 쉬워집니다.

왜 Proxmox API Grafana 구성이 중요한가

쉽게 말해 Proxmox API는 현재 상태를 꺼내오는 창구이고, Grafana는 그 상태를 사람이 판단하기 좋은 형태로 보여주는 대시보드입니다. 둘을 따로 보면 평범한데, 같이 묶으면 운영 품질이 꽤 달라집니다.

예를 들어 웹 UI에서는 지금 CPU가 높은지 낮은지 바로 볼 수는 있어도, 지난 일주일 동안 특정 VM이 언제부터 메모리를 먹기 시작했는지, 백업 시간대와 I/O 부하가 겹쳤는지 같은 맥락은 금방 흐려집니다. 실제로 써보니까, 이 부분이 사람이 체감하는 운영 난이도를 크게 갈라놓더라고요.

• Proxmox API: 노드, VM, 컨테이너(CT), 스토리지 상태를 JSON 형태로 조회
• Grafana: 시계열 그래프, 표, 상태 패널로 이상 징후 시각화
• 자동화: 임계치 초과 시 알림 또는 후속 작업 실행

저는 초반에 “그냥 필요한 순간에 UI 들어가서 보면 되지 않을까?”라고 생각했었는데요. 막상 밤에 부하가 튀고, 다음 날 와서 원인을 보려니 이미 지나간 데이터는 감으로만 추적하게 되더라고요. 그때부터 API 기반 수집을 붙였습니다. 드디어 됐다 싶은 순간이 있었던 게, 장애가 나기 전에 패턴이 보이기 시작했다는 점이었습니다.

핵심 개념 정리: API 자동화와 Proxmox 모니터링

Proxmox API는 무엇을 주는가

Proxmox VE는 REST API(레스트 API, HTTP 기반 관리 인터페이스)를 제공합니다. 이 API로 노드 목록, VM 상태, CPU 사용량, 메모리 점유, 디스크 상태 같은 정보를 조회할 수 있습니다. 인증은 보통 API Token(토큰 인증)이나 세션 기반으로 처리합니다.

여기서 주의하실 점은, API가 만능은 아니라는 겁니다. 현재값(current) 조회에는 아주 편하지만, 장기 보관과 비교 분석은 별도 저장 계층이 있어야 합니다. 그래서 Grafana를 붙일 때도 대개는 중간에 메트릭 저장소나 수집 스크립트를 둡니다.

Grafana는 어디서 빛나는가

Grafana는 단순 그래프 툴이 아니라, 운영자가 “그래서 지금 뭘 해야 하지?”를 판단하게 해주는 시각화 도구에 가깝습니다. CPU 평균, 메모리 사용률, VM별 트렌드, 노드별 비교, 이상치 탐지에 강하거든요.

혹시 이런 경험 있으신가요? 숫자는 많은데, 막상 어떤 VM이 문제인지 바로 안 보이는 상황이요. 저는 딱 그랬습니다. 그래서 패널을 예쁘게 만드는 것보다, 노드 단위와 VM 단위를 분리해서 보는 구조가 더 중요하다는 걸 뒤늦게 배웠습니다.

실전 구현 1: Proxmox API 토큰과 수집 흐름 만들기

제가 실제로 안정적으로 썼던 방식은 이렇습니다. Proxmox API에서 값을 읽고, Python(파이썬) 스크립트로 필요한 필드만 정리한 뒤, Prometheus exporter(프로메테우스 익스포터, 메트릭 노출기) 형태로 내보내고, Grafana에서 이를 시각화하는 구조입니다. Grafana가 직접 API를 두드리는 방식도 가능은 하지만, 운영해보니 중간 계층을 두는 편이 훨씬 관리가 편하더라고요.

1. Proxmox에서 읽기 전용 API Token 생성
2. 수집 대상 노드와 VM 범위 정의
3. Python 스크립트로 API 호출 및 메트릭 변환
4. Prometheus가 주기적으로 수집
5. Grafana 대시보드와 알림 정책 구성

1. API 토큰 준비

실서비스든 홈랩이든, 자동화에는 계정 분리가 기본입니다. 관리자 계정을 그대로 물리는 건 추천드리지 않습니다. 최소 권한 원칙(Principle of Least Privilege, 최소 권한 원칙)으로 읽기 전용 토큰을 따로 만드시는 게 좋습니다.

export PVE_HOST="https://proxmox.example.local:8006"
export PVE_TOKEN_ID="monitor@pve!grafana"
export PVE_TOKEN_SECRET="YOUR_TOKEN_SECRET"

환경 변수로 분리해두면 스크립트 수정 없이 운영하기 편합니다. 저는 처음에 토큰 문자열을 코드 안에 박아뒀다가, 나중에 회전(rotation)할 때 꽤 귀찮았거든요.

2. API 확인

먼저 가장 단순한 조회부터 붙여보면 감이 옵니다.

curl -k -H "Authorization: PVEAPIToken=${PVE_TOKEN_ID}=${PVE_TOKEN_SECRET}" \
  "${PVE_HOST}/api2/json/nodes"

응답은 JSON 형태로 오고, 여기서 노드 이름을 먼저 확인할 수 있습니다. 그다음 특정 노드의 상태를 조회합니다.

NODE="pve01"
curl -k -H "Authorization: PVEAPIToken=${PVE_TOKEN_ID}=${PVE_TOKEN_SECRET}" \
  "${PVE_HOST}/api2/json/nodes/${NODE}/status"

이 단계에서 API 응답 구조를 손으로 한 번 읽어보시는 걸 추천드립니다. 제가 직접 해보니, 어떤 필드를 지표로 쓸지 이때 정리해두면 이후 Grafana 패널 설계가 훨씬 빨라집니다.

API 응답 JSON에서 CPU, 메모리, 디스크 필드를 골라 메트릭으로 바꾸는 과정을 표현한 이미지 자리입니다. 중간 수집 계층의 역할을 보여주면 실전 흐름 이해에 도움이 됩니다.

실전 구현 2: Python으로 메트릭 변환하고 Grafana 연동하기

여기서는 예시로 간단한 Python 스크립트를 사용하겠습니다. 핵심은 Proxmox API 응답을 가져와서 Prometheus가 읽기 좋은 텍스트 포맷으로 내보내는 겁니다.

import os
import requests
from flask import Flask, Response

app = Flask(__name__)

PVE_HOST = os.environ["PVE_HOST"]
PVE_TOKEN_ID = os.environ["PVE_TOKEN_ID"]
PVE_TOKEN_SECRET = os.environ["PVE_TOKEN_SECRET"]
VERIFY_TLS = False


def pve_get(path: str):
    headers = {
        "Authorization": f"PVEAPIToken={PVE_TOKEN_ID}={PVE_TOKEN_SECRET}"
    }
    r = requests.get(f"{PVE_HOST}{path}", headers=headers, verify=VERIFY_TLS, timeout=10)
    r.raise_for_status()
    return r.json()["data"]


@app.route("/metrics")
def metrics():
    lines = []
    nodes = pve_get("/api2/json/nodes")

    for node in nodes:
        node_name = node["node"]
        status = pve_get(f"/api2/json/nodes/{node_name}/status")

        cpu = status.get("cpu", 0)
        maxmem = status.get("memory", {}).get("total", 0) if isinstance(status.get("memory"), dict) else 0
        usedmem = status.get("memory", {}).get("used", 0) if isinstance(status.get("memory"), dict) else 0

        lines.append(f'proxmox_node_cpu_ratio{{node="{node_name}"}} {cpu}')
        lines.append(f'proxmox_node_memory_used_bytes{{node="{node_name}"}} {usedmem}')
        lines.append(f'proxmox_node_memory_total_bytes{{node="{node_name}"}} {maxmem}')

    body = "\n".join(lines) + "\n"
    return Response(body, mimetype="text/plain; version=0.0.4")


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=9108)

여기서 한 가지 말씀드리면, 실제 API 응답 필드 구조는 환경에 따라 확인이 필요합니다. 그래서 처음부터 모든 리소스를 다 넣기보다, CPU와 메모리처럼 운영 판단에 바로 쓰이는 값부터 시작하는 편이 좋습니다. 저도 처음엔 욕심내서 디스크, 네트워크, VM 상태, 백업 작업까지 한 번에 넣으려다가 오히려 디버깅 시간이 길어졌습니다.

Prometheus 스크랩 설정

scrape_configs:
  - job_name: "proxmox-api-exporter"
    metrics_path: /metrics
    static_configs:
      - targets:
          - "proxmox-exporter.local:9108"

이제 Grafana에서는 Prometheus 데이터 소스를 연결하고 패널을 만듭니다. 예를 들면 이런 쿼리들이 기본 뼈대가 됩니다.

proxmox_node_cpu_ratio * 100

(proxmox_node_memory_used_bytes / proxmox_node_memory_total_bytes) * 100

Grafana 연동에서 중요한 건 패널 개수보다 뷰의 목적입니다. 저는 보통 아래처럼 나눕니다.

• 상단: 노드별 CPU, 메모리 전체 상태
• 중단: VM별 Top N 사용량
• 하단: 지난 24시간 변화량과 이상 구간

이 구성이 생각보다 편합니다. 문제를 위에서 아래로 좁혀 들어가기 좋거든요.

실전 구현 3: API 자동화로 반복 작업 줄이기

이제 대시보드가 보이기 시작하면, 다음 단계는 자동화입니다. 저는 처음에 알림만 붙였다가, 나중에는 특정 조건에서 후속 작업을 자동으로 실행하는 구조까지 확장했습니다. 여기서 말하는 자동화는 무조건 VM을 강제로 끄는 위험한 방식이 아니라, 안전한 선에서 운영자 개입을 줄이는 보조 자동화입니다.

예를 들면 이런 식입니다.

1. 특정 노드 메모리 사용률이 일정 시간 이상 높게 유지됨
2. Grafana Alerting(알림) 또는 별도 스크립트가 Webhook(웹훅)을 호출
3. Webhook 수신 스크립트가 Slack, 메일, 또는 내부 운영 채널로 통보
4. 필요 시 사전 정의된 Ansible(앤서블, 자동화 도구) 작업 실행

저는 여기서 “자동 복구”라는 말을 쉽게 쓰지 않습니다. 자동화는 편하지만, 잘못 걸면 장애를 키우거든요. 대신 알림 + 안전한 후속 조치 구조가 현실적이었습니다.

import requests

THRESHOLD = 0.90


def notify_if_high(node_name, memory_ratio):
    if memory_ratio >= THRESHOLD:
        requests.post(
            "https://hooks.example.local/proxmox-alert",
            json={
                "node": node_name,
                "metric": "memory",
                "ratio": memory_ratio,
                "message": f"{node_name} memory usage is high"
            },
            timeout=5,
        )

작게 시작하시는 걸 추천드립니다. 예를 들면 “임계치 초과 시 알림”까지만 먼저 붙여도 운영 피로도가 꽤 줄어듭니다. 그다음에 스냅샷 정리, 백업 전 상태 점검, 테스트 VM 정리 같은 보조 자동화를 단계적으로 넣는 게 안전합니다.

노드 CPU, 메모리 추이 그래프와 임계치 초과 알림 흐름을 함께 보여주는 이미지 자리입니다. 결과가 머릿속에 바로 그려지게 만드는 용도로 좋습니다.

⚠️ 제가 겪었던 문제들: 인증, TLS, 지표 해석

여기 구간은 정말 중요합니다. 문서만 보면 금방 될 것 같았는데, 실제로는 여기서 삽질을 좀 했습니다 ㅎㅎ

1. API 인증은 되는데 일부 엔드포인트가 비어 보이는 문제

원인은 대부분 권한 범위였습니다. 토큰이 살아 있어도 읽기 권한이 필요한 경로에 충분히 부여되지 않으면 응답이 제한적으로 보일 수 있습니다. 관리자 토큰으로 대충 해결하기보다, 어떤 리소스를 읽어야 하는지 먼저 정리하고 권한을 맞추시는 게 좋습니다.

2. 사설 인증서(Private CA) 때문에 요청 실패

홈랩에서는 TLS(전송 계층 보안) 인증서를 자체 서명으로 쓰는 경우가 많죠. 저도 처음엔 요청마다 인증서 검증 오류가 났습니다. 개발 단계에서만 검증을 끄고, 운영 단계에서는 신뢰할 수 있는 CA를 배포하는 쪽이 맞습니다. 검증 비활성화는 임시 조치라고 생각하셔야 합니다.

3. CPU 비율과 메모리 절대값을 한 패널에 섞어놓은 실수

이거 진짜 헷갈리더라고요. 초반엔 한 패널에 다 넣었다가 그래프 해석이 너무 어려웠습니다. 비율(%)과 절대값(Bytes)은 분리해서 보는 게 맞습니다. 운영자는 예쁜 그래프보다 빠른 판단이 중요하거든요.

4. 스크랩 주기를 너무 짧게 잡은 문제

수집 주기를 과하게 짧게 잡으면 API 요청 수만 늘고, 얻는 실익은 크지 않을 수 있습니다. 특히 홈랩처럼 자원이 넉넉하지 않은 환경에서는 더 그렇습니다. 저는 처음엔 촘촘하게 잡아야 정확할 줄 알았는데, 실제로는 운영 목적에 맞는 간격이 더 중요했습니다.

• 실시간 장애 대응이 목적이면 짧은 주기
• 용량 계획(capacity planning, 용량 계획)이 목적이면 중간 주기
• 장기 추세 분석이 목적이면 보존 정책이 더 중요

검증: 대시보드에서 무엇이 보이면 성공인가

모니터링은 붙였다고 끝이 아닙니다. 검증 기준이 있어야 합니다. 제가 보는 기준은 아래와 같습니다.

1. 노드별 CPU, 메모리 사용률이 시간 흐름으로 안정적으로 보이는가
2. 특정 VM의 급격한 사용량 증가가 구분되는가
3. 백업, 배치 작업, 업데이트 시간대와 부하 상관관계가 보이는가
4. 임계치 초과 시 알림이 중복 없이 적절히 오는가

이 정도만 확보돼도 Proxmox 모니터링 체계가 운영에 실제 도움이 되기 시작합니다. 숫자를 모으는 것과 운영에 쓰는 건 다르거든요. 저는 Grafana에서 하루 뷰, 7일 뷰, 30일 뷰를 나눠두니 체감이 확 달랐습니다. 하루 뷰는 장애 분석용, 7일 뷰는 패턴 확인용, 30일 뷰는 증설 판단용으로 쓰기 좋았습니다.

그리고 의외로 유용했던 게 표(Table) 패널입니다. Top N VM 목록을 표로 뽑아두면, 그래프보다 바로 눈에 들어오는 경우가 많습니다. 특히 야간에 급한 상황에서는요.

Grafana에서 CPU, 메모리 추이를 시각화하고 VM별 Top N 표를 함께 보여주는 결과 예시 이미지 자리입니다. 모니터링 완성 상태를 전달하기 좋습니다.

정리: 제가 다시 구성한다면 이렇게 하겠습니다

지금 다시 처음부터 구성한다면, 저는 이렇게 갑니다.

• 1단계: Proxmox API로 노드/VM 기본 지표만 수집
• 2단계: Prometheus에 저장하고 Grafana에서 노드/VM 대시보드 분리
• 3단계: 알림 추가
• 4단계: 안전한 범위의 API 자동화 연결

중요한 건 처음부터 모든 걸 다 하려 하지 않는 겁니다. 저도 처음엔 “이왕 하는 김에 완벽하게” 갔다가 시간이 꽤 들었어요. 그런데 운영은 결국 지속 가능해야 하더라고요. 작게 시작해서 점진적으로 확장하는 쪽이 훨씬 오래 갑니다.

이번 글의 핵심을 짧게 정리하면 이렇습니다. Proxmox API Grafana 조합은 단순 시각화 도구가 아니라, 운영 판단 체계를 만드는 기반입니다. API 자동화는 반복 작업을 줄여주고, Grafana 연동은 문제를 더 빨리 보게 해줍니다. 둘이 합쳐질 때 가치가 커집니다.

다음 글에서는 Proxmox 백업 작업과 알림 흐름을 더 세밀하게 묶는 방법, 그리고 장기 보존 지표를 기준으로 증설 시점을 판단하는 방법도 다뤄볼 예정입니다. 이전 글에서 홈랩 네트워크 분리와 스토리지 구성 이야기를 보셨다면, 이번 구성과 같이 연결해서 보시면 훨씬 이해가 잘 되실 겁니다.

구성 요소, 장점, 주의사항, 자동화 확장 단계를 한 장으로 요약하는 인포그래픽 자리입니다. 글 마무리 직전에 넣으면 복습용으로 좋습니다.

자주 묻는 질문

Grafana가 Proxmox API를 직접 읽어야 하나요?

반드시 그럴 필요는 없습니다. 제가 운영해보니 중간 수집 계층을 두는 편이 안정적이었습니다. API 응답을 바로 시각화하는 것보다 메트릭 구조를 정리한 뒤 보여주는 쪽이 관리가 쉽습니다.

API 자동화는 어디까지 붙이는 게 좋을까요?

처음에는 알림과 로그 수집 정도가 적당합니다. 운영 흐름이 충분히 검증된 뒤에 후속 작업 자동화를 넣는 게 안전합니다.

Proxmox 모니터링에서 가장 먼저 볼 지표는 무엇인가요?

노드 CPU, 메모리 사용률, 그리고 VM별 상위 사용량 목록부터 시작하시면 됩니다. 이 세 가지가 문제 파악 속도를 가장 많이 올려줍니다.