iac-homelab/docs/proxmox-setup.md

Proxmox Setup for Terraform

Configuration guide for the bpg/proxmox Terraform provider on Proxmox VE 9.1.

Related issue: #1 - Proxmox 9.1 upgrade: Terraform API user disabled

Overview

Instead of using the Administrator role, we create a dedicated TerraformRole with minimal required privileges.

Required Privileges (Proxmox 9.1)

Category	Privileges
Datastore	Allocate, AllocateSpace, AllocateTemplate, Audit
System	Audit, Console, Modify
VM	Allocate, Audit, Clone, Config.*, Console, Migrate, PowerMgmt, Snapshot, Snapshot.Rollback,GuestAgent.Audit, GuestAgent.FileRead
Pool	Allocate, Audit
SDN	Use

⚠️ VM.Monitor was deprecated in Proxmox 9 — do not include it.

---

Option A: Web Interface

1. Create Role

Datacenter → Permissions → Roles → Create

• Name: TerraformRole
• Privileges: Select all from the table above

2. Create User

Datacenter → Permissions → Users → Add

Field	Value
User name	terraform
Realm	Proxmox VE authentication server
Password	(set a strong password)
Enabled	☑️
Expire	never

3. Create API Token

Datacenter → Permissions → API Tokens → Add

Field	Value
User	terraform@pve
Token ID	terraform_token
Privilege Separation	☐ (unchecked)
Expire	never

📋 Save the token secret — it won't be shown again!

4. Assign Permissions

Datacenter → Permissions → Add → User Permission

Field	Value
Path	/
User	terraform@pve
Role	TerraformRole
Propagate	☑️

---

Option B: CLI

# 1. Create role
pveum role add TerraformRole -privs "Datastore.Allocate,Datastore.AllocateSpace,Datastore.AllocateTemplate,Datastore.Audit,Pool.Allocate,Pool.Audit,SDN.Use,Sys.Audit,Sys.Console,Sys.Modify,VM.Allocate,VM.Audit,VM.Clone,VM.Config.CDROM,VM.Config.Cloudinit,VM.Config.CPU,VM.Config.Disk,VM.Config.HWType,VM.Config.Memory,VM.Config.Network,VM.Config.Options,VM.Console,VM.Migrate,VM.PowerMgmt,VM.Snapshot,VM.Snapshot.Rollback,VM.GuestAgent.Audit,VM.GuestAgent.FileRead"

# 2. Create user
pveum user add terraform@pve --comment "Terraform automation"

# 3. Create API token (save the output!)
pveum user token add terraform@pve terraform_token --privsep 0

# 4. Assign permissions
pveum acl modify / --user terraform@pve --role TerraformRole

---

SSH Access (Required)

The bpg/proxmox provider uses SSH to upload cloud-init files.

# Create system user
useradd -m -s /bin/bash terraform

# Configure passwordless sudo
echo 'terraform ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/terraform
chmod 440 /etc/sudoers.d/terraform

# Setup SSH key
mkdir -p /home/terraform/.ssh
echo "YOUR_PUBLIC_KEY" > /home/terraform/.ssh/authorized_keys
chmod 700 /home/terraform/.ssh
chmod 600 /home/terraform/.ssh/authorized_keys
chown -R terraform:terraform /home/terraform/.ssh

---

Terraform Configuration

provider "proxmox" {
  endpoint  = "https://pve01.example.com:8006"
  api_token = "terraform@pve!terraform_token=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  insecure  = true
  
  ssh {
    agent    = true
    username = "terraform"
  }
}

Or use environment variables:

export PROXMOX_VE_ENDPOINT="https://pve01.example.com:8006"
export PROXMOX_VE_API_TOKEN="terraform@pve!terraform_token=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

---

Verification

# Test API token
curl -k -H "Authorization: PVEAPIToken=terraform@pve!terraform_token=YOUR_SECRET" \
  https://pve01.example.com:8006/api2/json/version

# Test Terraform
terraform init && terraform plan

---

References

• bpg/proxmox provider
• Proxmox User Management
• Proxmox API