chore(docs): update cloud-init configuration examples (#1830)

* chore(docs): update cloud-init and VM configuration examples

- Added timezone and package installation for qemu-guest-agent in cloud-init configuration.
- Updated VM configuration to include 'started' attribute and clarified agent usage in documentation.

Signed-off-by: Pavel Boldyrev <627562+bpg@users.noreply.github.com>

* not sure why the image checksum has changed

This looks a bit suspicious, but I can ignore this for the test code. In production that would be a red flag requiring investigation

Signed-off-by: Pavel Boldyrev <627562+bpg@users.noreply.github.com>

---------

Signed-off-by: Pavel Boldyrev <627562+bpg@users.noreply.github.com>

docs/guides/clone-vm.md

@@ -20,15 +20,12 @@ resource "proxmox_virtual_environment_vm" "ubuntu_template" {
   node_name = "pve"
 
   template = true
+  started  = false
 
   machine     = "q35"
   bios        = "ovmf"
   description = "Managed by Terraform"
 
-  agent {
-    enabled = true
-  }
-
   cpu {
     cores = 2
   }
@@ -89,6 +86,11 @@ resource "proxmox_virtual_environment_vm" "ubuntu_clone" {
   }
 
   agent {
+    # NOTE: The agent is installed and enabled as part of the cloud-init configuration in the template VM, see cloud-config.tf
+    # The working agent is *required* to retrieve the VM IP addresses.
+    # If you are using a different cloud-init configuration, or a different clone source
+    # that does not have the qemu-guest-agent installed, you may need to disable the `agent` below and remove the `vm_ipv4_address` output.
+    # See https://registry.terraform.io/providers/bpg/proxmox/latest/docs/resources/virtual_environment_vm#qemu-guest-agent for more details.
     enabled = true
   }
 

docs/guides/cloud-init.md

@@ -82,6 +82,7 @@ resource "proxmox_virtual_environment_file" "user_data_cloud_config" {
     data = <<-EOF
     #cloud-config
     hostname: test-ubuntu
+    timezone: America/Toronto
     users:
       - default
       - name: ubuntu
@@ -91,13 +92,15 @@ resource "proxmox_virtual_environment_file" "user_data_cloud_config" {
         ssh_authorized_keys:
           - ${trimspace(data.local_file.ssh_public_key.content)}
         sudo: ALL=(ALL) NOPASSWD:ALL
+    package_update: true
+    packages:
+      - qemu-guest-agent
+      - net-tools
+      - curl
     runcmd:
-        - apt update
+      - systemctl enable qemu-guest-agent
-        - apt install -y qemu-guest-agent net-tools
+      - systemctl start qemu-guest-agent
-        - timedatectl set-timezone America/Toronto
+      - echo "done" > /tmp/cloud-config.done
-        - systemctl enable qemu-guest-agent
-        - systemctl start qemu-guest-agent
-        - echo "done" > /tmp/cloud-config.done
     EOF
 
     file_name = "user-data-cloud-config.yaml"

example/resource_virtual_environment_file.tf

@@ -35,14 +35,14 @@ resource "proxmox_virtual_environment_file" "vendor_config" {
   node_name    = data.proxmox_virtual_environment_datastores.example.node_name
 
   source_raw {
-    data = <<EOF
+    data = <<-EOF
-#cloud-config
+    #cloud-config
-runcmd:
+    runcmd:
-    - apt update
+      - apt update
-    - apt install -y qemu-guest-agent
+      - apt install -y qemu-guest-agent
-    - systemctl enable qemu-guest-agent
+      - systemctl enable qemu-guest-agent
-    - systemctl start qemu-guest-agent
+      - systemctl start qemu-guest-agent
-    - echo "done" > /tmp/vendor-cloud-init-done
+      - echo "done" > /tmp/vendor-cloud-init-done
     EOF
 
     file_name = "terraform-provider-proxmox-example-vendor-config.yaml"
@@ -56,8 +56,8 @@ resource "proxmox_virtual_environment_file" "meta_config" {
   node_name    = data.proxmox_virtual_environment_datastores.example.node_name
 
   source_raw {
-    data = <<EOF
+    data = <<-EOF
-local-hostname: myhost.internal
+    local-hostname: myhost.internal
     EOF
 
     file_name = "meta-config.yaml"

example/variables.tf

@@ -28,5 +28,5 @@ variable "release_20240725_ubuntu_24_noble_lxc_img_url" {
 variable "release_20240725_ubuntu_24_noble_lxc_img_checksum" {
   type        = string
   description = "The checksum for the Ubuntu 24.04 LXC image"
-  default     = "d767d38cb25b2c25d84edc31a80dd1c29a8c922b74188b0e14768b2b2fb6df8e"
+  default     = "10331782a01cd2348b421a261f0e15ba041358bd540f66f2432b162e70b90d28"
 }

examples/guides/clone-vm/clone.tf

@@ -7,6 +7,11 @@ resource "proxmox_virtual_environment_vm" "ubuntu_clone" {
   }
 
   agent {
+    # NOTE: The agent is installed and enabled as part of the cloud-init configuration in the template VM, see cloud-config.tf
+    # The working agent is *required* to retrieve the VM IP addresses.
+    # If you are using a different cloud-init configuration, or a different clone source
+    # that does not have the qemu-guest-agent installed, you may need to disable the `agent` below and remove the `vm_ipv4_address` output.
+    # See https://registry.terraform.io/providers/bpg/proxmox/latest/docs/resources/virtual_environment_vm#qemu-guest-agent for more details.
     enabled = true
   }
 

examples/guides/clone-vm/cloud-config.tf

@@ -11,6 +11,7 @@ resource "proxmox_virtual_environment_file" "user_data_cloud_config" {
     data = <<-EOF
     #cloud-config
     hostname: test-ubuntu
+    timezone: America/Toronto
     users:
       - default
       - name: ubuntu
@@ -20,13 +21,15 @@ resource "proxmox_virtual_environment_file" "user_data_cloud_config" {
         ssh_authorized_keys:
           - ${trimspace(data.local_file.ssh_public_key.content)}
         sudo: ALL=(ALL) NOPASSWD:ALL
+    package_update: true
+    packages:
+      - qemu-guest-agent
+      - net-tools
+      - curl
     runcmd:
-        - apt update
+      - systemctl enable qemu-guest-agent
-        - apt install -y qemu-guest-agent net-tools
+      - systemctl start qemu-guest-agent
-        - timedatectl set-timezone America/Toronto
+      - echo "done" > /tmp/cloud-config.done
-        - systemctl enable qemu-guest-agent
-        - systemctl start qemu-guest-agent
-        - echo "done" > /tmp/cloud-config.done
     EOF
 
     file_name = "user-data-cloud-config.yaml"

examples/guides/clone-vm/template.tf

@@ -3,15 +3,12 @@ resource "proxmox_virtual_environment_vm" "ubuntu_template" {
   node_name = "pve"
 
   template = true
+  started  = false
 
   machine     = "q35"
   bios        = "ovmf"
   description = "Managed by Terraform"
 
-  agent {
-    enabled = true
-  }
-
   cpu {
     cores = 2
   }

examples/guides/cloud-init/custom/cloud-config.tf

@@ -11,6 +11,7 @@ resource "proxmox_virtual_environment_file" "user_data_cloud_config" {
     data = <<-EOF
     #cloud-config
     hostname: test-ubuntu
+    timezone: America/Toronto
     users:
       - default
       - name: ubuntu
@@ -20,13 +21,15 @@ resource "proxmox_virtual_environment_file" "user_data_cloud_config" {
         ssh_authorized_keys:
           - ${trimspace(data.local_file.ssh_public_key.content)}
         sudo: ALL=(ALL) NOPASSWD:ALL
+    package_update: true
+    packages:
+      - qemu-guest-agent
+      - net-tools
+      - curl
     runcmd:
-        - apt update
+      - systemctl enable qemu-guest-agent
-        - apt install -y qemu-guest-agent net-tools
+      - systemctl start qemu-guest-agent
-        - timedatectl set-timezone America/Toronto
+      - echo "done" > /tmp/cloud-config.done
-        - systemctl enable qemu-guest-agent
-        - systemctl start qemu-guest-agent
-        - echo "done" > /tmp/cloud-config.done
     EOF
 
     file_name = "user-data-cloud-config.yaml"

main.go

@@ -32,7 +32,7 @@ import (
 
 // Temporary: while migrating to the TF framework, we need to copy the generated docs to the right place
 // for the resources / data sources that have been migrated.
-// //go:generate cp -R ./build/docs-gen/guides/. ./docs/guides/
+//go:generate cp -R ./build/docs-gen/guides/. ./docs/guides/
 //go:generate cp ./build/docs-gen/data-sources/virtual_environment_acme_account.md ./docs/data-sources/
 //go:generate cp ./build/docs-gen/data-sources/virtual_environment_acme_accounts.md ./docs/data-sources/
 //go:generate cp ./build/docs-gen/data-sources/virtual_environment_acme_plugin.md ./docs/data-sources/