Provisioning Proxmox 8 VMs with Terraform and Telmate

Table of Contents

This post is work in progress and update to the prior Terraform post. The Telmate Proxmox provider is undergoing significant changes in v3, requiring additional permissions and featuring an updated disk schema. As for now, v2.9 is no longer compatible with Proxmox 8 and v3 is still in the testing phase. To use updated disk schema, you will need to build the plugin.

Updated Permissions for PVE 8 #

With the pending release of Telmate v3, you’ll need to grant additional privileges: Pool.Allocate, SDN.Use, Sys.Audit Sys.Console and Sys.Modify. Furthermore, you’ll need to grant access to the root path, /.

We’ll still use the Proxmox CLI to create a new role, group with permissions, and user; then generate an access token for the terraform user, as follows:

# create role
pveum role add TerraformUser -privs "Datastore.AllocateSpace \
  Datastore.Audit Pool.Allocate 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.Migrate VM.Monitor VM.PowerMgmt"

# create group
pveum group add terraform-users

# add root permissions
pveum acl modify / -group terraform-users -role TerraformUser

# create user 'terraform'
pveum useradd terraform@pve -groups terraform-users

# generate a token
pveum user token add terraform@pve token -privsep 0

The last command will output a token value similar to the following:

┌──────────────┬──────────────────────────────────────┐
│ key          │ value                                │
╞══════════════╪══════════════════════════════════════╡
│ full-tokenid │ terraform@pve!token                  │
├──────────────┼──────────────────────────────────────┤
│ info         │ {"privsep":"0"}                      │
├──────────────┼──────────────────────────────────────┤
│ value        │ 782a7700-4010-4802-8f4d-820f1b226850 │
└──────────────┴──────────────────────────────────────┘

Terraform Provider: Telmate Proxmox #

Building the Plugin #

Currently, the revised disk block is only available in the ’new-disk’ branch. So we’ll need to compile it from source. To build the plugin, you will need to have Go and GNU make installed on your machine. After that, you can run the following commands to build and install the plugin:

# clone the repo
git clone https://github.com/Telmate/terraform-provider-proxmox
cd terraform-provider-proxmox
# change the branch
git checkout new-disk

# build the binary
make

This will generate a binary file under bin/terraform-provider-proxmox. To use the binary, we’ll need to move it into the plugins directory, ~/.terraform.d/plugins (Unix) or %APPDATA%\terraform.d\plugins (Windows). For practicality’s sake, we’ll name it 3.0.1, however, note that this is not an official release. The following directions are for linux:

# move the binary into the terraform plugins directory
VERSION='3.0.1'

mkdir -p ~/.terraform.d/plugins/registry.terraform.io/telmate/proxmox/"${VERSION}"/linux_amd64/

cp bin/terraform-provider-proxmox ~/.terraform.d/plugins/registry.terraform.io/telmate/proxmox/"${VERSION}"/linux_amd64/terraform-provider-proxmox_v"${VERSION}"

Update your terraform files to use the new binary:

terraform {
  required_providers {
    proxmox = {
      source  = "Telmate/proxmox"
      version = "3.0.1"
    }
  }
}

This will create a symlink in ~/.terraform.d/plugin-cache/registry.terraform.io/telmate/proxmox

➜ tree ~/.terraform.d/plugin-cache/registry.terraform.io/telmate/proxmox/
/home/$USER/.terraform.d/plugin-cache/registry.terraform.io/telmate/proxmox/
...
├── 3.0.1
│   └── linux_amd64 -> /home/$USER/.terraform.d/plugins/registry.terraform.io/telmate/proxmox/3.0.1/linux_amd64
...

Provisioning Disk in V3 #

With the new version, you can provision disks using either the new disks block or revised disk block. We’ll use the later, as it shares a similar schema to v2.9 and requires minimal modification to the module created in the prior post. Here are the changes to the disk attributes:

# hard-coded example
disk {
  type       = "disk"      # change - value, 'disk' or 'cdrom'
  slot       = "scsi0"     # change - merge of 'type' and 'slot' from v2.9
  storage    = "local-lvm"
  size       = "8G"
  format     = "raw"
  cache      = "writeback"
  backup     = false       # change (v2.9.13) - type, boolean
  iothread   = false       # change - type, boolean
  emulatessd = true        # change - attribute name, formerly 'ssd'
  discard    = true        # change - type, boolean
}

Updated Module #

The updated module is available here (GitHub link). This is a work in progress and will be updated as new release candidates become available. You can use the module by setting the source to github.com/trfore/terraform-telmate-proxmox//modules/vm?ref=v3 in the module block, as follows:

# main.tf
terraform {
  required_providers {
    proxmox = {
      source  = "Telmate/proxmox"
      version = "~> 3.0.0"
    }
  }
}

provider "proxmox" {
  pm_api_url          = var.pve_api_url
  pm_api_token_id     = var.pve_token_id
  pm_api_token_secret = var.pve_token_secret
}

module "vm_minimal_config" {
  source = "github.com/trfore/terraform-telmate-proxmox//modules/vm?ref=v3"

  node             = "pve"
  vm_id            = 100
  vm_name          = "vm-example-minimal"
  template_name    = "ubuntu20"
  ci_ssh_key       = "~/.ssh/id_ed25519.pub"
}

The LXC module works as expected.

module "lxc_minimal_config" {
  source = "github.com/trfore/terraform-telmate-proxmox//modules/lxc?ref=v3"

  node                = "pve"
  lxc_id              = 100
  os_template         = "local:vztmpl/ubuntu-20.04-standard_20.04-1_amd64.tar.gz"
  os_type             = "ubuntu"
  user_ssh_key_public = "~/.ssh/id_ed25519.pub"
}

Current Limitations #

The required permissions are quite broad compared to v2.9.11, this is currently an open issue (#784).
Customizing the cloud-init drive is not supported yet, but is planned (issue #986). Currently, setting cloudinit_cdrom_storage will create a config drive attached to ide3.
Adding pre-enrolled keys for EFI disk is not supported yet (issue #1021).

References #

Companion Repo: Github: trfore/terraform-telmate-proxmox

Terraform:

Terraform Providers / Plugins:

Telmate/Terraform-Provider-Proxmox

Other Resources:

Terraform: Up & Running