terraform-proxmox-provisioning

Terraform-based provisioning templates for creating Linux virtual machines on Proxmox VE using the bpg/proxmox provider.
Each OS distribution is maintained in its own branch for isolation, reproducibility, and OS-specific customization.

---

Repository Structure

Each branch represents a specific Linux distribution template:

Branch	Description
base	Common baseline for creating new distro branches
alpine	Alpine Linux minimal VM provisioning
ubuntu-jammy	Ubuntu 22.04 (Jammy) provisioning
opensuse	openSUSE Leap / Tumbleweed setup
fedora	Fedora Linux Provisioning

---

Requirements

Core

• Terraform >= 1.13.0 (tested with v1.13.4)
• Proxmox VE >= 8.x (tested with 8.4.14)
• Proxmox API access (token or user/password)
• Cloud-Init enabled workflow/templates
• SSH key for VM access (recommended)

---

Terraform Provider

terraform {
  required_providers {
    proxmox = {
      source  = "bpg/proxmox"
      version = ">= 0.46.0"
    }
  }
}

---

Usage

1. Clone Repository

git clone https://github.com/marcuwynu23/terraform-proxmox-provisioning.git
cd terraform-proxmox-provisioning

2. Select Distribution Branch

git checkout <distro-branch>
# example:
# git checkout ubuntu-jammy

3. Initialize Terraform

terraform init

4. Configure Variables

Create terraform.tfvars (do not commit):

proxmox_api_url        = "https://<proxmox-host>:8006/"
proxmox_api_username   = "root@pam"
proxmox_api_password   = "REPLACE_ME"

virtual_environment_node_name = "pve"

datastore_iso = "local"
datastore_vm  = "data"

cloud_init_username = "<distro>"
cloud_init_password = "<secure-password>"
cloud_init_ssh_keys = [
  "ssh-ed25519 AAAA... user@host"
]

5. Plan & Apply

terraform plan
terraform apply

---

Destroy

terraform destroy

---

Provisioning Flow

All branches follow a common pattern:

1. Download cloud image (QCOW2)
2. Import disk into Proxmox datastore
3. Create Cloud-Init enabled template VM
4. Clone VM from template
5. Apply Cloud-Init configuration:
   • user
   • password / SSH keys
   • hostname
   • networking

---

Branch Customization

Each distribution branch may define:

• Cloud image source URL
• Default user (ubuntu, alpine, opensuse, etc.)
• Package manager:
  • Alpine → apk
  • Ubuntu/Debian → apt
  • openSUSE → zypper
• Cloud-Init templates (.tftpl)
• Bootstrap scripts (runcmd, packages)

---

Typical Structure

.
├── main.tf
├── variables.tf
├── outputs.tf
├── provider.tf
├── terraform.tfvars.example
├── cloud-init.user-data.yaml.tftpl
└── scripts/

---

Debugging

Enable Terraform debug logs:

export TF_LOG=DEBUG

Check Proxmox tasks:

cat /var/log/pve/tasks/*

---

Notes

• Cloud-Init runs only on first boot of cloned VM
• Recreate VM if Cloud-Init changes are not applied:

  terraform destroy && terraform apply

• Ensure storage supports:
  • Disk image (for downloads/imports)
  • Snippets (if using custom Cloud-Init)
• VM IDs must be unique per cluster
• Avoid parallel provisioning conflicts on the same node

---

Security

• Do not commit:
  • terraform.tfvars
  • API credentials
• Prefer:
  • API tokens over password authentication
  • SSH keys over password login
• Use secret management (Vault, CI/CD variables, etc.)

---

Adding a New Distribution

git checkout base
git checkout -b <new-distro>

Update:

• Cloud image source
• Cloud-Init template
• Default variables
• OS-specific provisioning logic

Push:

git push origin <new-distro>

---

📜 License

MIT