매주 한 page, 기술 한 spoon

Proxmox + Terraform으로 Ubuntu 22.04 테스트 VM 자동화하기

회사 내부 테스트 환경에서 VM을 자주 만들어야 하는 경우, 매번 ISO 부팅 → OS 설치 → 계정 설정 과정을 반복하는 것은 비효율적입니다. pu4ro/proxmox-terraform 리포는 이 과정을 완전히 자동화하기 위해 만들었습니다.

이 글에서는 Ubuntu 22.04 템플릿 생성 → Terraform으로 VM 생성·관리를 전부 다룹니다. 또한, 원본 리포의 README에서 제공하는 설치 방법과 예제를 함께 정리해 참고 문서로 활용할 수 있게 했습니다.

1. Proxmox를 선택한 이유

• 가볍고 빠름: 비교적 적은 자원으로도 서버급 하이퍼바이저 구동 가능
• 오픈소스: 핵심 기능 사용에 라이선스 제약 없음
• 자동화 친화적: REST API, CLI, cloud-init 완벽 지원
• 템플릿 기능: 동일 환경의 VM을 반복해서 신속하게 생성 가능
• 다양한 OS 지원: Linux, Windows, BSD까지 가능

테스트 환경에서 특히 유용한 이유는 템플릿 + cloud-init + Terraform 조합으로 반복 가능하고 테스트 가능한 환경을 만들 수 있다는 것 입니다.

2. 리포 개요와 구조

리포 목적
Proxmox 환경에서 Ubuntu 22.04 기반 VM 템플릿을 만들고, Terraform으로 VM을 코드 형태로 생성·관리하기 위해 만들었습니다.

	01-template/ # Ubuntu 22.04 템플릿 생성
	├─ create-template.sh
	├─ user-data
	└─ meta-data
	02-terraform/ # Terraform 설정
	├─ main.tf
	├─ variables.tf
	├─ vm.tf
	├─ outputs.tf
	└─ terraform.tfvars.example
	README.md

view raw gistfile1.txt hosted with ❤ by GitHub

• 템플릿 생성: cloud-init으로 계정, SSH 키, 패스워드, 패키지 설정 자동화, qemu-guest-agent 설치 포함
• Terraform 관리: Proxmox Provider 설정 후 VM 생성, 스펙 변경, 삭제를 코드로 관리

3. 사전 준비 사항

• Proxmox VE 7.x 이상
• Proxmox API 토큰 (Datacenter → Permissions → API Tokens, 적절한 권한 필요)
• Terraform 1.5 이상 및 Proxmox Provider 설치 (Telmate/proxmox)
• VM에서 사용할 브리지 (예: vmbr0) 구성 완료

4. Ubuntu 22.04 템플릿 만들기

01-template/create-template.sh 스크립트를 Proxmox 노드에서 실행하면 템플릿이 자동으로 생성됩니다.

• Ubuntu 22.04 클라우드 이미지 다운로드
• VM 생성 (qm create)
• cloud-init ISO 연결 (qm set --ide2)
• user-data/meta-data 적용
• qemu-guest-agent 설치
• VM을 템플릿으로 변환 (qm template)

	#cloud-config
	users:
	– name: testuser
	sudo: ['ALL=(ALL) NOPASSWD:ALL']
	groups: sudo
	shell: /bin/bash
	ssh_authorized_keys:
	– ssh-rsa AAAAB3Nza…
	chpasswd:
	list: |
	testuser:changeme
	expire: false
	package_update: true
	package_upgrade: true
	packages:
	– qemu-guest-agent

view raw gistfile1.txt hosted with ❤ by GitHub

	instance-id: iid-ubuntu-22
	local-hostname: ubuntu-template

view raw gistfile1.txt hosted with ❤ by GitHub

5. Terraform으로 VM 생성·관리

02-terraform 폴더에는 Proxmox API Provider를 사용하는 Terraform 예제가 있습니다.

	terraform {
	required_providers {
	proxmox = {
	source = "Telmate/proxmox"
	version = ">=2.9.0"
	}
	}
	}
	provider "proxmox" {
	pm_api_url = var.pm_api_url
	pm_api_token_id = var.pm_api_token_id
	pm_api_token_secret = var.pm_api_token_secret
	pm_tls_insecure = true
	}

view raw gistfile1.txt hosted with ❤ by GitHub

	resource "proxmox_vm_qemu" "vm" {
	name = var.vm_name
	target_node = var.target_node
	clone = var.template_name
	full_clone = true
	cores = var.vm_cpu
	memory = var.vm_memory
	agent = 1
	network {
	model = "virtio"
	bridge = var.vm_bridge
	}
	disk {
	size = var.vm_disk_size
	type = "scsi"
	storage = var.vm_storage
	}
	}

view raw gistfile1.txt hosted with ❤ by GitHub

	cd 02-terraform
	cp terraform.tfvars.example terraform.tfvars
	terraform init
	terraform plan
	terraform apply

view raw terraform.sh hosted with ❤ by GitHub

6. 운영 팁 & 트러블슈팅

• 불변 인프라 전략: VM 변경보다는 새로 생성 후 교체
• 네이밍 규칙 적용: 환경-서비스-번호 형식
• 변경 전 terraform plan으로 결과 확인

문제	원인	해결
인증 실패	API 토큰 권한 부족	Proxmox UI에서 Role 확인
VM 이름 충돌	동일 이름 VM 존재	고유 이름 사용
cloud-init 미적용	YAML 오류 또는 중복 설정	문법 확인, 적용 방식 통일
네트워크 불가	브리지 설정 오류	/etc/network/interfaces 점검

7. 마무리

pu4ro/proxmox-terraform는 내부 테스트 VM 배포를 표준화하고 자동화할 수 있는 코드 입니다. 이 코드를 작성한 가장 큰 이유는 사내에서 나오는 제품을 자동화된 프로세스로 직접 test하기 위해서 입니다.

다음 글은 ansible을 통한 배포를 python 코드로 자동화하여 진행하는 방식으로 진행 할게요!

원본 GitHub 리포지토리: https://github.com/pu4ro/proxmox-terraform