machine module

This Terraform module is designed to clone the Proxmox template generated by the Packer Alpine repository.

It results in a VM ready for configuration with Ansible.

Variables

  • proxmox_api_url - Proxmox VE API server URL. Required.
  • proxmox_target_node - Proxmox node to create the VM on. Required.
  • proxmox_template - Proxmox template to clone. Required.
  • id - ID of the created VM in Proxmox. Uses next available ID when not specified.
  • full_clone - Create a linked clone when false, full clone when true. Default is false.
  • name - Name of the created VM. Required.
  • description - Description of the created VM. Required.
  • on_boot - Start the machine on boot when true. Required.
  • memory - Memory size in MB. Required.
  • cores - CPU core count. Required.
  • disk_pool - Proxmox storage pool to use for the VM’s disk. Required.
  • disk_size - Size of the VM’s disk. For example 25G. Required.
  • mac_address - Use a specific MAC address for the network interface. Auto generated when not specified.
  • cloud_init_public_keys - SSH public keys to add to the VM with Cloud Init.

Make sure to set full_clone to true when cloning VMs to a different disk_pool than the Template’s disk.

When creating multiple machines at the same time, it is recommended to explicitly set their ids to avoid multiple VMs trying to use the same id and failing to clone.

cloud_init_public_keys is a string of public keys in OpenSSH format. To generate a new key, see the SSH keys how-to guide. An example value is shown below.

Outputs

  • id - Proxmox virtual machine ID.
  • ip - IP of the cloned VM.
  • user - Generated user for the VM.
  • password - Password of the generated user.

The outputs are designed for use with terraform_http and terraform_local Ansible inventory plugins to dynamically populate Ansible inventory with Terraform provisioned VMs.

You may manually SSH to provisioned VMs using values from the outputs:

ssh <user>@<ip> -p 2222

Proxmox Authentication

This module requires you to set PM_API_TOKEN_ID and PM_API_TOKEN_SECRET environment variables with your Proxmox credentials.

PM_API_TOKEN_ID must be of the form user@realm!token. For example root@pam!terraform.

See Proxmox API Tokens how-to guide for instructions on creating a Proxmox role with correct privileges and an API token of said role.

It is recommended to use a .env file to store your credentials. Make sure Git ignores it.

# Inside .env
export PM_API_TOKEN_ID='user@pve!token'
export PM_API_TOKEN_SECRET='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

Example

For a full module example see the machine example in Terraform Proxmox repository. It is recommend to create a Terraform module with the machines being provisioned. Use variables to allow customization of your module, and outputs to output SSH connection details to later use with an Ansible inventory plugin.

This example is focused on configuring the machine module. See the full module example for additional files you will need such as outputs.tf, variables.tf and terraform.tfvars.

Follow the instructions above for setting up credentials for Proxmox authentication.

# Inside main.tf
module "example_machine" {
  source = "github.com/LKummer/terraform-proxmox//modules/machine?ref=1.0.0"

  proxmox_api_url     = "https://192.168.0.100:8006/api2/json"
  proxmox_target_node = "example"
  proxmox_template    = "alpine-3.17.0-1"

  name                   = "example-machine"
  description            = "Example machine."
  on_boot                = true
  memory                 = 2048
  cores                  = 2
  disk_pool              = "local-lvm"
  disk_size              = "10G"
  cloud_init_public_keys = <<EOF
ssh-ed25519 REDACTED user@host
EOF
}