51bcd79e05
This commit updates the documentation and Terraform variables to reflect recent changes in the Proxmox environment setup.
- `docs/proxmox-setup.md`: Added `VM.GuestAgent.Audit` and `VM.GuestAgent.FileRead` to the required privileges list and the CLI command example. This ensures Terraform can properly interact with the QEMU Guest Agent.
- `terraform/prod/variables.tf`: Set a default value ("damien") for the `username` variable in the `virtual_machines` object to simplify configuration for the primary user.
154 lines
5.1 KiB
Markdown
154 lines
5.1 KiB
Markdown
# 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`,`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
|
|
|
|
```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,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.
|
|
|
|
```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)
|