Proxmox API 자동화

Proxmox를 클릭 운영에서 선언적/자동화 운영으로 옮기기 위한 기준.

Proxmox를 클릭 운영에서 선언적/자동화 운영으로 옮기기 위한 기준.

자동화 대상

반복되는 작업은 자동화 후보가 된다.

VM 템플릿 생성
VM clone
Cloud-Init 설정
백업 job 확인
리소스 사용량 조회
사용자/API token 관리
Terraform으로 VM 선언
Ansible로 VM 내부 설정

자동화 도구별 역할

도구	역할
qm/pct	단일 노드 CLI 작업
pvesh	Proxmox API 직접 호출
Terraform	VM/LXC 인프라 선언
Ansible	guest OS 설정 관리
Packer	VM template 이미지 빌드
API Token	비밀번호 없는 자동화 인증

API Token

자동화에는 개인 비밀번호보다 API token을 쓴다.

원칙:

용도별 token 분리
최소 권한 부여
만료/회전 정책
토큰 값은 vault나 환경변수에 저장
Git에 커밋 금지

웹 UI 경로:

Datacenter > Permissions > API Tokens

pvesh

pvesh는 Proxmox API를 CLI에서 호출하는 도구다.

# 노드 목록
pvesh get /nodes

# 특정 노드의 VM 목록
pvesh get /nodes/<node>/qemu

# 작업 목록
pvesh get /cluster/tasks

API 경로를 익히면 웹 UI가 내부에서 어떤 작업을 하는지 이해하기 좋다.

qm/pct 자동화

VM:

qm clone 9000 101 --name app-01 --full
qm set 101 --memory 4096 --cores 2
qm set 101 --ipconfig0 ip=192.168.20.101/24,gw=192.168.20.1
qm start 101

LXC:

pct create 201 local:vztmpl/debian-template.tar.zst \
  --hostname svc-01 \
  --storage local-zfs \
  --rootfs local-zfs:8 \
  --memory 512 \
  --cores 1 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp

반복 스크립트는 idempotent하게 만들기 어렵다. 그래서 장기적으로는 Terraform/Ansible이 더 낫다.

Terraform

Terraform은 “VM이 어떤 상태여야 하는지”를 코드로 적는 데 좋다.

관리 대상:

VM clone
CPU/Memory/Disk
Network
Cloud-Init
tags/description

주의:

provider 버전 관리
state 파일 보호
VM 수동 변경과 drift
API token 권한
destroy 명령 위험

[!warning] Terraform 주의 Proxmox VM을 Terraform으로 관리할 때 destroy는 실제 VM 삭제로 이어질 수 있다. state와 plan을 반드시 확인한다.

Ansible

Ansible은 VM 생성 후 OS 내부 설정에 적합하다.

예:

패키지 설치
사용자 생성
SSH 설정
Docker/containerd 설치
kubeadm 준비
모니터링 agent 설치

Proxmox API로 VM을 만들고, Ansible로 내부를 설정하는 조합이 자연스럽다.

자동화 흐름 예시

flowchart LR
    A["Cloud image"] --> B["Proxmox Template"]
    B --> C["Terraform Clone"]
    C --> D["Cloud-Init"]
    D --> E["Ansible Configure"]
    E --> F["Service Ready"]

운영 기준

수동으로 만든 VM과 자동화 VM을 구분
VMID 규칙 정하기
이름 규칙 정하기
Terraform state 백업
API token 최소 권한
자동화 변경은 Git으로 리뷰
삭제 작업은 별도 확인 절차

VMID 예시:

100-199: 인프라 VM
200-299: LXC 서비스
300-399: Kubernetes 노드
9000-9099: 템플릿