complete example has been redone

Author: ZacksHomeLab

examples/complete/README.md

@@ -1,8 +1,6 @@
 # Complete Virtual Machine Deployment
 
-This example demonstrates how you would deploy a Virtual Machine with multiple network adapters, multiple disks, and using an Ubuntu Cloudinit template.
-
-***NOTE:*** If your Virtual Machine template does ***NOT*** have the Cloudinit drive set to `ide2`, the Terraform provider may fail to provision your Virtual Machine.
+This example demonstrates most of the working configurations you can give to a virtual machine. Within `locals.tf`, there's a long list of variables and what said variable does.
 
 ## Step 1. Configure Terraform environment variables
 
@@ -26,13 +24,9 @@ export PM_PASS="proxmox_account_password"
 
 Rename `terraform.tfvars.example` to `terraform.tfvars`. Once renamed, modify the three variables within the file to match your environment.
 
-The values in `terraform.tfvars` illustrate using more than one storage location for your Virtual Machine. If you do **NOT** have multiple storage locations, just set both the values to the same datastore (e.g., local-pve). 
-
 ## Step 3. Modify Virtual Machine configuration
 
-Once you've populated the required variables in `terraform.tfvars`, you may open `locals.tf` to see all of the settings that you may modify. I've populated the file with three different network adapters, two different disks, and I've started adding Cloudinit settings. 
-
-Feel free to play around with these values to get a feel of how to deploy an out-of-ordinary Virtual Machine. 
+Once you've populated the required variables in `terraform.tfvars`, you may open `locals.tf` to see all of the variables you may modify.
 
 ## Step 4. Deploy Virtual Machine
 
@@ -72,8 +66,7 @@ No resources.
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
 | <a name="input_clone"></a> [clone](#input\_clone) | The base VM from which to clone to create the new VM. Note that clone is mutually exclussive with pxe and iso modes. | `string` | n/a | yes |
-| <a name="input_storage_location_1"></a> [storage\_location\_1](#input\_storage\_location\_1) | The location of where Disk 1 will be located. | `string` | n/a | yes |
-| <a name="input_storage_location_2"></a> [storage\_location\_2](#input\_storage\_location\_2) | The location of where Disk 2 will be located. | `string` | n/a | yes |
+| <a name="input_storage_location"></a> [storage\_location](#input\_storage\_location) | The storage location for the Virtual Machine. | `string` | n/a | yes |
 | <a name="input_target_node"></a> [target\_node](#input\_target\_node) | The name of the Proxmox Node on which to place the VM. | `string` | n/a | yes |
 
 ## Outputs

examples/complete/locals.tf

@@ -1,78 +1,196 @@
 locals {
 
- # Adjust the Virtual Machine's specs here
- memory = 1024
- cores = 1
+ # Automatically reboot the VM when parameter changes require this. If disabled the provider will emit a warning when the VM needs to be rebooted.
+ automatic_reboot = true
 
- # Cloudinit Settings
+ # Override the default cloud-init user's password. Sensitive.
+ cipassword = "my_password"
+
+ # Override the default cloud-init user for provisioning.
  ciuser = "my_username"
- # See the homepage README.md on how to add SSH Keys.
- sshkeys = ""
+
+ # The base VM from which to clone to create the new VM. Note that clone is mutually exclussive with pxe and iso modes.
+ clone = var.clone
+
+ # The number of CPU cores per CPU socket to allocate to the VM.
+ cores = 1
+
+ # The type of CPU to emulate in the Guest. See the docs about CPU Types for more info. ('host' allows you to virtualize on said VM)
+ cpu = "host"
+
+ # Controls if virtual machine should be created.
+ create_vm = true
+
+ # The description of the VM. Shows as the 'Notes' field in the Proxmox GUI.
+ description = "Virtual Machine's description"
 
  /*
- Disk Configurations
-
- Create 2 Disks
- Disk 1 (virtio0): 
- - Set type to 'virtio' 
- - Set storage_location_1 variable in terraform.tfvars
- - Set size to 10G
- Disk 2 (scsi0):
- - Set type to 'scsi'
- - Set storage_location_2 variable in terraform.tfvars
- - Set size to 25G
- - Enable writethrough cache
- */
- # Set the disk locations in terraform.tfvars
- storage_location_1 = var.storage_location_1
- storage_location_2 = var.storage_location_2
+ Disk Configuration
 
+ type - The type of disk device to add. Options: ide, sata, scsi, virtio.
+ storage - The name of the storage pool on which to store the disk.
+ size - The size of the created disk, format must match the regex \d+[GMK], where G, M, and K represent Gigabytes, Megabytes, and Kilobytes respectively.
+ format - The drive’s backing file’s data format.
+ cache - The drive’s cache mode. Options: directsync, none, unsafe, writeback, writethrough
+ backup - Whether the drive should be included when making backups.
+ iothread - Whether to use iothreads for this drive. Only effective with a disk of type virtio, or scsi when the the emulated controller type (scsihw top level block argument) is virtio-scsi-single.
+ replicate - Whether the drive should considered for replication jobs.
+ discard - Controls whether to pass discard/trim requests to the underlying storage. Only effective when the underlying storage supports thin provisioning. 
+ mbps - Maximum r/w speed in megabytes per second. 0 means unlimited.
+ mbps_rd - Maximum read speed in megabytes per second. 0 means unlimited.
+ mbps_rd_max - Maximum read speed in megabytes per second. 0 means unlimited.
+ mbps_wr - Maximum write speed in megabytes per second. 0 means unlimited.
+ mbps_wr_max - Maximum throttled write pool in megabytes per second. 0 means unlimited.
+ media - The drive’s media type. Options: cdrom, disk.
+ iops - Maximum r/w I/O in operations per second.
+ iops_rd - Maximum read I/O in operations per second.
+ iops_rd_max - Maximum unthrottled read I/O pool in operations per second.
+ iops_rd_max_length - Maximum length of read I/O bursts in seconds.
+ iops_wr - Maximum write I/O in operations per second.
+ iops_wr_max - Maximum unthrottled write I/O pool in operations per second.
+ iops_wr_max_length - Maximum length of write I/O bursts in seconds.
+ 
+ */
  disks = [
- # This will create disk virtio0
  {
- type = "virtio"
- storage = local.storage_location_1
- size = "10G"
- },
- # This will create disk scsi0 with writethrough cache enabled
- {
- type = "scsi"
- storage = local.storage_location_2
- size = "25G"
- cache = "writethrough"
+ type = "virtio"
+ storage = var.storage_location
+ size = "10G"
+ format = "raw"
+ cache = "writeback"
+ backup = true
+ iothread = 0
+ replicate = 0
+ discard = 0
+ mbps = 0
+ mbps_rd = 0
+ mbps_rd_max = 0
+ mbps_wr = 0
+ mbps_wr_max = 0
+ media = "disk"
+ iops = 0
+ iops_rd = 0
+ iops_rd_max = 0
+ iops_rd_max_length = 0
+ iops_wr = 0
+ iops_wr_max = 0
+ iops_wr_max_length = 0
  }
  ]
 
+ # If false, and a vm of the same name, on the same node exists, terraform will attempt to reconfigure that VM with these settings. 
+ # Set to true to always create a new VM (note, the name of the VM must still be unique, otherwise an error will be produced.).
+ force_create = false
+ /*
+ If the value of this string changes, the VM will be recreated. Useful for allowing this resource to be recreated when arbitrary attributes change. 
+ An example where this is useful is a cloudinit configuration (as the cicustom attribute points to a file not the content).
+
+ force_recreate_on_change_of = data.template_file.cicustom.rendered
+ */
+ force_recreate_on_change_of = ""
+
+ /*
+ hagroup - The HA group identifier the resource belongs to (requires hastate to be set!).
+ hastate - Requested HA state for the resource. One of 'started', 'stopped', 'enabled', 'disabled', or 'ignored'. See the docs about HA for more info.
+
+ hagroup = "my_resource_group"
+ hastate = enabled
+ */
+ hagroup = ""
+ hastate = ""
+
+ /*
+ Comma delimited list of hotplug features to enable. Options: network, disk, cpu, memory, usb. Set to 0 to disable hotplug.
+
+ To add memory into hotplug, you would set the variable to:
+ hotplug = "cpu,memory,network,disk,usb"
+ */
+ hotplug = "cpu,network,disk,usb"
+
+ # The amount of memory to allocate to the VM in Megabytes.
+ memory = 2048
+
+ # Sets default DNS server for guest.
+ nameserver = "example.com"
 
  /*
- Create 3 Network Adapters
- - All adapters will be assigned model `virtio` and point to network bridge `vmbr0`.
- However, you can adjust these values as needed.
- - Network Adapter 1 (net0) - Set to DHCP
- - Network Adapter 2 (net1) - IP: 192.168.2.58/24 with gateway of 192.168.2.1
- - Network Adapter 3 (net2) - Set to DHCP
+ Network Adapter Configurations
+
+ bridge - Bridge to which the network device should be attached. The Proxmox VE standard bridge is called vmbr0.
+ model - Network Card Model. The virtio model provides the best performance with very low CPU overhead. If your VM does not support it, next best option is e1000
+ gateway - The IPv4 Gateway of the Virtual Machine. Does NOT need to be in CIDR-notation (e.g., this will work: 192.168.1.1)
+ gateway6 - The IPv6 Gateway of the Virtual Machine. Does NOT need to be in CIDR-notation.
+ ip - The IPv4 Address of the Virtual Machine. MUST be in CIDR-notation (e.g., 192.168.1.123/24)
+ ip6 - The IPv6 Address of the Virtual Machine. MUST be in CIDR-notation.
+ dhcp - Set dhcp to true to enable dhcp for IPv4 Addresses. This will override static IP assignments.
+ dhcp6 - Set dhcp6 to true to enable dhcp for IPv6 Addresses. This will override static IP assignments.
+ firewall - Whether to enable the Proxmox firewall on this network device.
+ link_down - Whether this interface should be disconnected (like pulling the plug).
+ macaddr - Override the randomly generated MAC Address for the VM. Requires the MAC Address be Unicast.
+ queues - Number of packet queues to be used on the device. Requires virtio model to have an effect.
+ rate - Network device rate limit in mbps (megabytes per second) as floating point number. Set to 0 to disable rate limiting.
+ vlan_tag - The VLAN tag to apply to packets on this device. -1 disables VLAN tagging.
  */
- # Network Adapter net0 IP Configuration
- network_adapter_1 = {
- dhcp = true
- }
- network_model_1 = "virtio"
- network_bridge_1 = "vmbr0"
-
- # Network Adapter net1 IP Configuration
- network_adapter_2 = {
- # By default, DHCP is set to False if it isn't provided
- ip = "192.168.2.58/24"
- gateway = "192.168.2.1"
- }
- network_model_2 = "virtio"
- network_bridge_2 = "vmbr0"
-
- # Network Adapter net2 IP Configuration
- network_adapter_3 = {
- # By default, DHCP is set to False if it isn't provided
- dhcp = true
- }
- network_model_3 = "virtio"
- network_bridge_3 = "vmbr0"
+ networks = [{
+ bridge = "vmbr0"
+ model = "virtio"
+ gateway = ""
+ gateway6 = ""
+ ip = ""
+ ip6 = ""
+ dhcp = true
+ dhcp6 = false
+ firewall = true
+ link_down = false
+ #macaddr = "" # Commented-out as this will generate an error if you do not provide an address.
+ queues = 1
+ rate = 0
+ vlan_tag = -1
+ }]
+
+ # Whether to enable Non-Uniform Memory Access in the guest. Must have 'memory' in hotplug. 
+ numa = false
+
+ # Whether to have the VM startup after the PVE node starts.
+ onboot = true
+
+ # Whether to have the VM startup after the VM is created.
+ oncreate = true
+
+ # The resource pool to which the VM will be added.
+ pool = ""
+
+ # The SCSI controller to emulate. Options: lsi, lsi53c810, megasas, pvscsi, virtio-scsi-pci, virtio-scsi-single.
+ scsihw = "virtio-scsi-pci"
+
+ # Sets default DNS search domain suffix.
+ searchdomain = "example_domain.com"
+
+ # The number of CPU sockets for the Master Node.
+ sockets = 1
+
+ /*
+ Newline delimited list of SSH public keys to add to authorized keys file for the cloud-init user
+
+ Example (omitted most of the key to save space):
+
+ sshkeys = <<EOF
+ssh-rsa AAAAB3NzaC1yc2YcS+LkeTl9JaW/XzZrzGpb5kQhBNXoSXQ== zackshomelab\zack@ZHLDT01
+EOF
+ */
+ sshkeys = ""
+
+ # Tags of the VM. This is only meta information.
+ tags = ["tag1", "tag2", "tag3"]
+
+
+ # The name of the Proxmox Node on which to place the VM.
+ target_node = var.target_node
+
+ # The virtual machine name.
+ vm_name = "vm-name-example"
+
+ # The ID of the VM in Proxmox. 
+ # The default value of 0 indicates it should use the next available ID in the sequence.
+ vmid = 0
 }

examples/complete/main.tf

@@ -5,49 +5,33 @@ provider "proxmox" {
 module "cloudinit_vm" {
  source = "../../"
 
- vm_name = "ubuntu-complete"
- target_node = var.target_node
- clone = var.clone
-
- onboot = true
-
- # Specs
- cores = local.cores
- memory = local.memory
-
- # Disk(s)
- scsihw = "virtio-scsi-pci"
-
- disks = local.disks
-
- # Network Cards
- networks = [
- # This will create Network Adapter net0
- {
- model = local.network_model_1
- bridge = local.network_bridge_1
- },
-
- # This will create Network Adapter net1
- {
- model = local.network_model_2
- bridge = local.network_bridge_2
- },
-
- # This will create Network Adapter net2
- {
- model = local.network_model_3
- bridge = local.network_bridge_3
- }
- ]
-
- # IP Configuration for net0
- ipconfig0 = local.network_adapter_1
- ipconfig1 = local.network_adapter_2
- ipconfig2 = local.network_adapter_3
-
-
- # Cloudinit settings
- ciuser = local.ciuser
- sshkeys = local.sshkeys != null ? local.sshkeys : null
+ automatic_reboot = local.automatic_reboot
+ cipassword = local.cipassword
+ ciuser = local.ciuser
+ clone = local.clone
+ cores = local.cores
+ cpu = local.cpu
+ create_vm = local.create_vm
+ description = local.description
+ disks = local.disks
+ force_create = local.force_create
+ force_recreate_on_change_of = local.force_recreate_on_change_of
+ hagroup = local.hagroup
+ hastate = local.hastate
+ hotplug = local.hotplug
+ memory = local.memory
+ nameserver = local.nameserver
+ networks = local.networks
+ numa = local.numa
+ onboot = local.onboot
+ oncreate = local.oncreate
+ pool = local.pool
+ scsihw = local.scsihw
+ searchdomain = local.searchdomain
+ sockets = local.sockets
+ sshkeys = local.sshkeys
+ tags = local.tags
+ target_node = local.target_node
+ vm_name = local.vm_name
+ vmid = local.vmid
 }

examples/complete/variables.tf

@@ -1,10 +1,5 @@
-variable "storage_location_1" {
- description = "The location of where Disk 1 will be located."
- type = string
-}
-
-variable "storage_location_2" {
- description = "The location of where Disk 2 will be located."
+variable "storage_location" {
+ description = "The storage location for the Virtual Machine."
  type = string
 }