fix(docs): update HOW-TOs for cloud-init (#955)

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

.gitignore

@@ -32,6 +32,7 @@ modules-dev/
 *.tfstate.lock.info
 *.tfvars
 *.env
+id_rsa.pub
 
 .*.swp
 .DS_Store

howtos/cloud-init/README.md

@@ -1,6 +1,129 @@
 # HOW-TO Configure a VM with Cloud-Init
 
+> [!NOTE]
+> Examples below use the following defaults:
+>
+> - a single Proxmox node named `pve`
+> - local storages named `local` and `local-lvm`
+
 ## Native Proxmox Cloud-Init support
 
-TODO
+Proxmox supports Cloud-Init natively, so you can use the `initialization` block to configure your VM:
 
+```terraform
+resource "proxmox_virtual_environment_vm" "ubuntu_vm" {
+  name      = "test-ubuntu"
+  node_name = "pve"
+
+  initialization {
+
+    ip_config {
+      ipv4 {
+        address = "192.168.3.233/24"
+        gateway = "192.168.3.1"
+      }
+    }
+
+    user_account {
+      username = "ubuntu"
+      keys     = [trimspace(data.local_file.ssh_public_key.content)]
+    }
+  }
+
+  disk {
+    datastore_id = "local-lvm"
+    file_id      = proxmox_virtual_environment_download_file.ubuntu_cloud_image.id
+    interface    = "virtio0"
+    iothread     = true
+    discard      = "on"
+    size         = 20
+  }
+
+  network_device {
+    bridge = "vmbr0"
+  }
+}
+```
+
+Note that many cloud images do not have `qemu-guest-agent` installed by default, so you won't be able to retrieve the dynamic IP address of the VM from Proxmox, as this is agent's responsibility. You can use the `ip_config` block to configure a static IP address instead.
+
+## Custom Cloud-Init configuration
+
+Because of several limitations of the native Proxmox cloud-init support, you may want to use a custom Cloud-Init configuration instead. This would allow you to adjust the VM configuration to your needs, and also install the `qemu-guest-agent` and additional packages.
+
+In order to use a custom cloud-init configuration, you need to create a `cloud-config` snippet file and pass it to the VM as a `user_data_file_id` parameter. You can use the `proxmox_virtual_environment_file` resource to create the file. Make sure the "Snippets" content type is enabled on the target datastore in Proxmox before applying the configuration below.
+
+```terraform
+resource "proxmox_virtual_environment_file" "cloud_config" {
+  content_type = "snippets"
+  datastore_id = "local"
+  node_name    = "pve"
+
+  source_raw {
+    data = <<EOF
+#cloud-config
+users:
+  - default
+  - name: ubuntu
+    groups:
+      - sudo
+    shell: /bin/bash
+    ssh_authorized_keys:
+      - ${trimspace(data.local_file.ssh_public_key.content)}
+    sudo: ALL=(ALL) NOPASSWD:ALL
+runcmd:
+    - apt update
+    - apt install -y qemu-guest-agent net-tools
+    - timedatectl set-timezone America/Toronto
+    - systemctl enable qemu-guest-agent
+    - systemctl start qemu-guest-agent
+    - echo "done" > /tmp/cloud-config.done
+    EOF
+
+    file_name = "cloud-config.yaml"
+  }
+}
+```
+
+```terraform
+resource "proxmox_virtual_environment_vm" "ubuntu_vm" {
+  name      = "test-ubuntu"
+  node_name = "pve"
+
+  agent {
+    enabled = true
+  }
+
+  cpu {
+    cores = 2
+  }
+
+  memory {
+    dedicated = 2048
+  }
+
+  disk {
+    datastore_id = "local-lvm"
+    file_id      = proxmox_virtual_environment_download_file.ubuntu_cloud_image.id
+    interface    = "virtio0"
+    iothread     = true
+    discard      = "on"
+    size         = 20
+  }
+
+  initialization {
+    ip_config {
+      ipv4 {
+        address = "dhcp"
+      }
+    }
+
+    user_data_file_id = proxmox_virtual_environment_file.cloud_config.id
+  }
+
+  network_device {
+    bridge = "vmbr0"
+  }
+
+}
+```

howtos/cloud-init/cutom/cloud-config.tf

@@ -0,0 +1,33 @@
+data "local_file" "ssh_public_key" {
+  filename = "./id_rsa.pub"
+}
+
+resource "proxmox_virtual_environment_file" "cloud_config" {
+  content_type = "snippets"
+  datastore_id = "local"
+  node_name    = "pve"
+
+  source_raw {
+    data = <<EOF
+#cloud-config
+users:
+  - default
+  - name: ubuntu
+    groups:
+      - sudo
+    shell: /bin/bash
+    ssh_authorized_keys:
+      - ${trimspace(data.local_file.ssh_public_key.content)}
+    sudo: ALL=(ALL) NOPASSWD:ALL
+runcmd:
+    - apt update
+    - apt install -y qemu-guest-agent net-tools
+    - timedatectl set-timezone America/Toronto
+    - systemctl enable qemu-guest-agent
+    - systemctl start qemu-guest-agent
+    - echo "done" > /tmp/cloud-config.done
+    EOF
+
+    file_name = "cloud-config.yaml"
+  }
+}

howtos/cloud-init/cutom/main.tf

@@ -0,0 +1,52 @@
+resource "proxmox_virtual_environment_vm" "ubuntu_vm" {
+  name      = "test-ubuntu"
+  node_name = "pve"
+
+  agent {
+    enabled = true
+  }
+
+  cpu {
+    cores = 2
+  }
+
+  memory {
+    dedicated = 2048
+  }
+
+  disk {
+    datastore_id = "local-lvm"
+    file_id      = proxmox_virtual_environment_download_file.ubuntu_cloud_image.id
+    interface    = "virtio0"
+    iothread     = true
+    discard      = "on"
+    size         = 20
+  }
+
+  initialization {
+    ip_config {
+      ipv4 {
+        address = "dhcp"
+      }
+    }
+
+    user_data_file_id = proxmox_virtual_environment_file.cloud_config.id
+  }
+
+  network_device {
+    bridge = "vmbr0"
+  }
+
+}
+
+resource "proxmox_virtual_environment_download_file" "ubuntu_cloud_image" {
+  content_type = "iso"
+  datastore_id = "local"
+  node_name    = "pve"
+
+  url = "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"
+}
+
+output "vm_ipv4_address" {
+  value = proxmox_virtual_environment_vm.ubuntu_vm.ipv4_addresses[1][0]
+}

howtos/cloud-init/cutom/provider.tf

@@ -0,0 +1,17 @@
+terraform {
+  required_providers {
+    proxmox = {
+      source  = "bpg/proxmox"
+      version = "0.45.0"# x-release-please-version
+    }
+  }
+}
+
+provider "proxmox" {
+  endpoint  = var.virtual_environment_endpoint
+  api_token = var.virtual_environment_token
+  ssh {
+    agent = true
+    username = "root"
+  }
+}

howtos/cloud-init/cutom/variables.tf

@@ -0,0 +1,9 @@
+variable "virtual_environment_endpoint" {
+  type        = string
+  description = "The endpoint for the Proxmox Virtual Environment API (example: https://host:port)"
+}
+
+variable "virtual_environment_token" {
+  type        = string
+  description = "The token for the Proxmox Virtual Environment API"
+}

howtos/cloud-init/native/main.tf

@@ -1,32 +1,44 @@
-resource "proxmox_virtual_environment_vm" "centos_vm" {
+data "local_file" "ssh_public_key" {
+  filename = "./id_rsa.pub"
+}
+
+resource "proxmox_virtual_environment_vm" "ubuntu_vm" {
   name      = "test-ubuntu"
   node_name = "pve"
 
   initialization {
-    user_account {
-      keys     = [trimspace(tls_private_key.ubuntu_vm_key.public_key_openssh)]
 
-      # do not use this in production, cofigure your own ssh key instead!
+    ip_config {
+      ipv4 {
+        address = "192.168.3.233/24"
+        gateway = "192.168.3.1"
+      }
+    }
+
+    user_account {
       username = "ubuntu"
+      keys     = [trimspace(data.local_file.ssh_public_key.content)]
     }
   }
 
   disk {
     datastore_id = "local-lvm"
-    file_id      = proxmox_virtual_environment_file.ubuntu_cloud_image.id
+    file_id      = proxmox_virtual_environment_download_file.ubuntu_cloud_image.id
     interface    = "virtio0"
     iothread     = true
     discard      = "on"
     size         = 20
   }
+
+  network_device {
+    bridge = "vmbr0"
+  }
 }
 
-resource "proxmox_virtual_environment_file" "ubuntu_cloud_image" {
+resource "proxmox_virtual_environment_download_file" "ubuntu_cloud_image" {
   content_type = "iso"
   datastore_id = "local"
   node_name    = "pve"
 
-  source_file {
+  url = "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"
-    path      = "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"
-  }
 }