Pada artikel sebelumnya saya membahas gambaran otomatisasi homelab Proxmox menggunakan Terraform dan Ansible.

Kali ini saya mulai mempraktikkannya di homelab, dimulai dari Terraform terlebih dahulu. Targetnya adalah menyiapkan Terraform Controller yang nantinya dapat membuat 3 VM Ubuntu secara otomatis di Proxmox.

Pada bagian ini proses hanya sampai terraform plan, sehingga belum ada perubahan yang diterapkan ke Proxmox.

Rancangan Homelab

Seluruh server menggunakan network 192.168.14.0/24.

Hostname	Fungsi	IP Address
terraform-controller	Terraform Controller	192.168.14.80
ubuntu-tf-01	VM Target	192.168.14.81
ubuntu-tf-02	VM Target	192.168.14.82
ubuntu-tf-03	VM Target	192.168.14.83

Konfigurasi Proxmox:

Parameter	Nilai
Node	pverafi1
API	https://192.168.14.31:8006/
Gateway	192.168.14.31
Bridge	vmbr0
Image Storage	local
VM Storage	local-lvm

Alur yang akan dibuat:

Terraform Controller
192.168.14.80
        │
        │ Proxmox API
        ▼
     Proxmox VE
        │
        ├── ubuntu-tf-01 → 192.168.14.81
        ├── ubuntu-tf-02 → 192.168.14.82
        └── ubuntu-tf-03 → 192.168.14.83

1. Menyiapkan Terraform Controller

Saya membuat satu VM Ubuntu Server 24.04 secara manual di Proxmox dengan spesifikasi:

Resource	Konfigurasi
CPU	2 Core
RAM	2 GB
Disk	20 GB
Network	vmbr0
IP	192.168.14.80/24

VM ini hanya digunakan sebagai controller untuk menjalankan Terraform.

Setelah Ubuntu selesai diinstal, pastikan controller dapat berkomunikasi dengan Proxmox:

ping -c 3 192.168.14.31

2. Install Terraform

Install dependency:

sudo apt update
sudo apt install -y gnupg software-properties-common wget curl

Tambahkan GPG key HashiCorp:

wget -O- https://apt.releases.hashicorp.com/gpg |
gpg --dearmor |
sudo tee /usr/share/keyrings/hashicorp-archive-keyring.gpg > /dev/null

Tambahkan repository:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(grep -oP '(?<=UBUNTU_CODENAME=).*' /etc/os-release || lsb_release -cs) main" |
sudo tee /etc/apt/sources.list.d/hashicorp.list

Kemudian install Terraform:

sudo apt update
sudo apt install -y terraform

Verifikasi instalasi:

root@terraform:~/terraform-proxmox# terraform version
Terraform v1.15.8
on linux_amd64

3. Mengaktifkan Import Storage Proxmox

Terraform nantinya akan mengunduh Ubuntu Cloud Image dan memasukkannya ke storage Proxmox.

Buka:

Datacenter
└── Storage
    └── local
        └── Edit

Pada bagian Content, aktifkan:

Import

Ini dibutuhkan agar Terraform dapat menggunakan Ubuntu Cloud Image sebagai sumber disk VM.

4. Membuat User Terraform

Sebaiknya Terraform menggunakan user khusus, bukan akun administrator utama Proxmox.

Buka:

Datacenter
└── Permissions
    └── Users
        └── Add

Buat:

terraform@pve

Untuk percobaan homelab ini saya memberikan role:

Administrator

pada path:

/

Untuk lingkungan production, permission sebaiknya dibatasi sesuai kebutuhan.

Membuat API Token

Buka:

Datacenter
└── Permissions
    └── API Tokens
        └── Add

Gunakan:

Parameter	Nilai
User	terraform@pve
Token ID	provider
Privilege Separation	Nonaktif

Setelah dibuat, simpan:

Token secret hanya ditampilkan satu kali.

5. Test Proxmox API

Dari Terraform Controller:

curl -k https://192.168.14.31:8006/api2/json/version

Kemudian masukkan API token sebagai environment variable:

read -rsp "API token: " PROXMOX_VE_API_TOKEN
export PROXMOX_VE_API_TOKEN
echo ${#PROXMOX_VE_API_TOKEN}  -> output harus > 0

Formatnya:

terraform@pve!provider=TOKEN_SECRET

Test autentikasi:

curl -k -H \ "Authorization:PVEAPIToken=${PROXMOX_VE_API_TOKEN}" \
https://192.168.14.31:8006/api2/json/version

Jika berhasil, Proxmox akan mengembalikan informasi versi dalam format JSON.

6. Membuat SSH Key

SSH key nantinya akan dimasukkan ke setiap VM melalui Cloud-init.

ssh-keygen -t ed25519 -C "terraform-controller"

Gunakan lokasi default:

~/.ssh/id_ed25519

7. Membuat Project Terraform

Buat directory:

mkdir -p ~/terraform-proxmox
cd ~/terraform-proxmox

Struktur project:

terraform-proxmox/
├── versions.tf
├── variables.tf
├── main.tf
├── terraform.tfvars
└── outputs.tf

8. Konfigurasi Provider

Buat versions.tf:

terraform {
  required_version = ">= 1.5.0"

  required_providers {
    proxmox = {
      source  = "bpg/proxmox"
      version = "~> 0.111.0"
    }
  }
}

provider "proxmox" {
  endpoint = var.proxmox_endpoint
  insecure = true
}

Saya menggunakan provider bpg/proxmox.

insecure = true digunakan karena Proxmox homelab masih menggunakan sertifikat self-signed.

9. Membuat Variable

Buat variables.tf:

variable "proxmox_endpoint" {
  type = string
}

variable "proxmox_node" {
  type = string
}

variable "image_datastore" {
  type    = string
  default = "local"
}

variable "vm_datastore" {
  type    = string
  default = "local-lvm"
}

variable "bridge" {
  type    = string
  default = "vmbr0"
}

variable "gateway" {
  type = string
}

variable "dns_servers" {
  type    = list(string)
  default = ["8.8.8.8", "1.1.1.1"]
}

variable "ssh_public_key_file" {
  type    = string
  default = "~/.ssh/id_ed25519.pub"
}

10. Mendefinisikan 3 VM Ubuntu

Konfigurasi utama berada pada main.tf.

Pertama, tentukan VM yang ingin dibuat:

locals {
  ubuntu_vms = {
    "ubuntu-tf-01" = {
      vm_id = 181
      ip    = "192.168.14.81/24"
    }

    "ubuntu-tf-02" = {
      vm_id = 182
      ip    = "192.168.14.82/24"
    }

    "ubuntu-tf-03" = {
      vm_id = 183
      ip    = "192.168.14.83/24"
    }
  }
}

Kemudian definisikan Ubuntu Cloud Image:

resource "proxmox_download_file" "ubuntu_cloud_image" {
  content_type = "import"
  datastore_id = var.image_datastore
  node_name    = var.proxmox_node

  url       = "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
  file_name = "noble-server-cloudimg-amd64.qcow2"

  overwrite = false
}

Selanjutnya resource VM:

resource "proxmox_virtual_environment_vm" "ubuntu_vm" {
  for_each = local.ubuntu_vms

  name        = each.key
  description = "Ubuntu 24.04 deployed by Terraform"
  tags        = ["terraform", "ubuntu"]

  node_name = var.proxmox_node
  vm_id     = each.value.vm_id

  started = true
  on_boot = true

  boot_order    = ["scsi0"]
  scsi_hardware = "virtio-scsi-single"

  cpu {
    cores = 2
    type  = "x86-64-v2-AES"
  }

  memory {
    dedicated = 2048
  }

  disk {
    datastore_id = var.vm_datastore
    import_from  = proxmox_download_file.ubuntu_cloud_image.id
    interface    = "scsi0"
    size         = 20
    discard      = "on"
    iothread     = true
  }

  initialization {
    datastore_id = var.vm_datastore

    dns {
      servers = var.dns_servers
    }

    ip_config {
      ipv4 {
        address = each.value.ip
        gateway = var.gateway
      }
    }

    user_account {
      username = "ubuntu"

      keys = [
        trimspace(
          file(
            pathexpand(var.ssh_public_key_file)
          )
        )
      ]
    }
  }

  network_device {
    bridge = var.bridge
    model  = "virtio"
  }

  operating_system {
    type = "l26"
  }

  serial_device {}
}

Dengan looping for_each, satu resource dapat digunakan untuk mendefinisikan tiga VM sekaligus.

Target konfigurasinya:

VM	VM ID	IP	CPU	RAM	Disk
ubuntu-tf-01	181	192.168.14.81	2 Core	2 GB	20 GB
ubuntu-tf-02	182	192.168.14.82	2 Core	2 GB	20 GB
ubuntu-tf-03	183	192.168.14.83	2 Core	2 GB	20 GB

11. Konfigurasi Environment Homelab

Buat terraform.tfvars:

proxmox_endpoint = "https://192.168.14.31:8006/"
proxmox_node     = "pverafi1"

image_datastore = "local"
vm_datastore    = "local-lvm"

bridge  = "vmbr0"
gateway = "192.168.14.31"

dns_servers = [
  "8.8.8.8",
  "1.1.1.1"
]

ssh_public_key_file = "~/.ssh/id_ed25519.pub"

Nama node dapat diperiksa pada Proxmox:

hostname

Sedangkan storage:

pvesm status

12. Membuat Output

Buat outputs.tf:

output "deployed_vms" {
  value = {
    for name, vm in local.ubuntu_vms : name => {
      vm_id = vm.vm_id
      ip     = split("/", vm.ip)[0]
      ssh    = "ssh ubuntu@${split("/", vm.ip)[0]}"
    }
  }
}

Output ini nantinya menampilkan informasi VM setelah deployment dilakukan.

13. Inisialisasi dan Validasi Terraform

Rapikan konfigurasi:

terraform fmt

Download dan inisialisasi provider:

terraform init

Kemudian lakukan validasi:

terraform validate

Jika konfigurasi benar:

Success! The configuration is valid.

Sampai tahap ini Terraform sudah siap berkomunikasi dengan Proxmox dan konfigurasi VM sudah berhasil divalidasi.

14. Melihat Terraform Plan

Sebelum benar-benar membuat VM, periksa terlebih dahulu perubahan yang akan dilakukan Terraform.

Pastikan API token masih tersedia:

echo "${PROXMOX_VE_API_TOKEN:+API token sudah tersedia}"

Kemudian:

terraform plan

Targetnya Terraform menampilkan:

Plan: 4 to add, 0 to change, 0 to destroy.

Empat resource tersebut adalah:

Resource	Jumlah
Ubuntu Cloud Image	1
Ubuntu VM	3
Total	4

Plan juga dapat disimpan:

terraform plan -out=tfplan

File tfplan inilah yang nantinya dapat diterapkan menggunakan terraform apply.

Referensi

• HashiCorp Terraform Documentation
• bpg/proxmox Terraform Provider
• Proxmox VE Documentation
• Ubuntu Cloud Images