# 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](https://gitea.arnodo.fr/Damien/iac-homelab/issues/1)

## 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` |
| 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

```bash
# 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"

# 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.

```bash
# 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

```hcl
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:

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

---

## Verification

```bash
# 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](https://github.com/bpg/terraform-provider-proxmox)
- [Proxmox User Management](https://pve.proxmox.com/wiki/User_Management)
- [Proxmox API](https://pve.proxmox.com/wiki/Proxmox_VE_API)