feat(docs): rename howtos -> guides and publish to the Terraform Registry (#971)

feat(docs): rename howtos -> guides and publish on the registry page

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

docs/guides/cloud-image.md

@@ -1,10 +1,13 @@
-# HOW-TO Create a VM from a Cloud Image
+---
+layout: page
+title: Create a VM from a Cloud Image
+parent: Guides
+subcategory: Virtual Environment
+description: |-
+    This guide explains how to create a VM from a cloud image.
+---
 
-> [!NOTE]
-> Examples below use the following defaults:
->
-> - a single Proxmox node named `pve`
-> - local storages named `local` and `local-lvm`
+# Create a VM from a Cloud Image
 
 ## Download a public cloud image from URL
 
@@ -27,7 +30,7 @@ resource "proxmox_virtual_environment_vm" "centos_vm" {
 
   disk {
     datastore_id = "local-lvm"
-    file_id      = proxmox_virtual_environment_file.centos_cloud_image.id
+    file_id      = proxmox_virtual_environment_download_file.centos_cloud_image.id
     interface    = "virtio0"
     iothread     = true
     discard      = "on"
@@ -35,31 +38,47 @@ resource "proxmox_virtual_environment_vm" "centos_vm" {
   }
 }
 
-resource "proxmox_virtual_environment_file" "centos_cloud_image" {
+resource "proxmox_virtual_environment_download_file" "centos_cloud_image" {
   content_type = "iso"
   datastore_id = "local"
   node_name    = "pve"
-
-  source_file {
-    # you may download this image locally on your workstation and then use the local path instead of the remote URL
-    path      = "https://cloud.centos.org/centos/8-stream/x86_64/images/CentOS-Stream-GenericCloud-8-20231113.0.x86_64.qcow2"
-    file_name = "centos8.img"
-
-    # you may also use the SHA256 checksum of the image to verify its integrity
-    checksum = "b9ba602de681e493b020825db0ee30602a46ef92"
-  }
+  url          = "https://cloud.centos.org/centos/8-stream/x86_64/images/CentOS-Stream-GenericCloud-8-20231113.0.x86_64.qcow2"
+  file_name    = "centos8.img"
 }
 ```
 
 Ubuntu cloud images are available at [cloud-images.ubuntu.com](https://cloud-images.ubuntu.com/). Ubuntu cloud images are in `qcow2` format as well, but stored with `.img` extension, so they can be directly uploaded to Proxmox without renaming.
 
-Just update the `source_file` block in the example above to use the Ubuntu image URL:
-
 ```terraform
- source_file {
-    path     = "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"
-    ...
+resource "proxmox_virtual_environment_vm" "ubuntu_vm" {
+  name      = "test-ubuntu"
+  node_name = "pve"
+
+  initialization {
+    user_account {
+      # do not use this in production, configure your own ssh key instead!
+      username = "user"
+      password = "password"
+    }
   }
+
+  disk {
+    datastore_id = "local-lvm"
+    file_id      = proxmox_virtual_environment_download_file.ubuntu_cloud_image.id
+    interface    = "virtio0"
+    iothread     = true
+    discard      = "on"
+    size         = 20
+  }
+}
+
+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"
+
+}
 ```
 
 For [large images](https://registry.terraform.io/providers/bpg/proxmox/latest/docs/resources/virtual_environment_file#important-notes), you may want to use a dedicated temporary directory [configured](https://registry.terraform.io/providers/bpg/proxmox/latest/docs#tmp_dir) for provider via `tmp_dir` attribute, instead of system's default temporary directory. This is especially useful if you are deploying from a container with limited disk space.

docs/guides/cloud-init.md

@@ -1,16 +1,23 @@
-# HOW-TO Configure a VM with Cloud-Init
+---
+layout: page
+title: Configure a VM with Cloud-Init
+parent: Guides
+subcategory: Virtual Environment
+description: |-
+    This guide explains how to use the Proxmox provider to create and manage virtual machines using cloud-init.
+---
 
-> [!NOTE]
-> Examples below use the following defaults:
->
-> - a single Proxmox node named `pve`
-> - local storages named `local` and `local-lvm`
+# Configure a VM with Cloud-Init
 
 ## Native Proxmox Cloud-Init support
 
 Proxmox supports Cloud-Init natively, so you can use the `initialization` block to configure your VM:
 
 ```terraform
+data "local_file" "ssh_public_key" {
+  filename = "./id_rsa.pub"
+}
+
 resource "proxmox_virtual_environment_vm" "ubuntu_vm" {
   name      = "test-ubuntu"
   node_name = "pve"
@@ -43,6 +50,14 @@ resource "proxmox_virtual_environment_vm" "ubuntu_vm" {
     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"
+}
 ```
 
 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.
@@ -54,6 +69,10 @@ Because of several limitations of the native Proxmox cloud-init support, you may
 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
+data "local_file" "ssh_public_key" {
+  filename = "./id_rsa.pub"
+}
+
 resource "proxmox_virtual_environment_file" "cloud_config" {
   content_type = "snippets"
   datastore_id = "local"
@@ -126,4 +145,16 @@ resource "proxmox_virtual_environment_vm" "ubuntu_vm" {
   }
 
 }
+
+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]
+}
 ```

docs/guides/setup-proxmox-for-tests.md

@@ -1,4 +1,13 @@
-# Setup VM with proxmox to run examples and acceptance tests
+---
+layout: page
+title: Setup a VM with Proxmox
+parent: Guides
+subcategory: Virtual Environment
+description: |-
+  This guide will help you setup a proxmox node in VM using virt-manager for a job.
+---
+
+# Setup VM with Proxmox to run examples and acceptance tests
 
 ## Who
 
@@ -8,7 +17,7 @@ Contributors
 
 To test changes, it's best to try it on real proxmox cluster. There is dedicated `make example` command that will try to apply changes defined in `example` directory. Most resources have its examples declarations there. For example, if you add new resource, you could add new file with example resource there (ideally after adding tests). If nothing breaks, apply works fine, new resource is created and all other resources are fine, then likely change is safe.
 
-But – proxmox node setup can be tricky task for some contributors.
+But, proxmox node setup can be tricky task for some contributors.
 
 ## Preconditions
 

examples/guides/cloud-image/centos-qcow2/main.tf

@@ -12,7 +12,7 @@ resource "proxmox_virtual_environment_vm" "centos_vm" {
 
   disk {
     datastore_id = "local-lvm"
-    file_id      = proxmox_virtual_environment_file.centos_cloud_image.id
+    file_id      = proxmox_virtual_environment_download_file.centos_cloud_image.id
     interface    = "virtio0"
     iothread     = true
     discard      = "on"
@@ -20,14 +20,10 @@ resource "proxmox_virtual_environment_vm" "centos_vm" {
   }
 }
 
-resource "proxmox_virtual_environment_file" "centos_cloud_image" {
+resource "proxmox_virtual_environment_download_file" "centos_cloud_image" {
   content_type = "iso"
   datastore_id = "local"
   node_name    = "pve"
-
-  source_file {
-    # you may download this image locally on your workstation and then use the local path instead of the remote URL
-    path      = "https://cloud.centos.org/centos/8-stream/x86_64/images/CentOS-Stream-GenericCloud-8-20231113.0.x86_64.qcow2"
-    file_name = "centos8.img"
-  }
+  url          = "https://cloud.centos.org/centos/8-stream/x86_64/images/CentOS-Stream-GenericCloud-8-20231113.0.x86_64.qcow2"
+  file_name    = "centos8.img"
 }

examples/guides/cloud-image/centos-qcow2/provider.tf

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

examples/guides/cloud-image/debian-from-storage/provider.tf

@@ -2,7 +2,7 @@ terraform {
   required_providers {
     proxmox = {
       source  = "bpg/proxmox"
-      version = "0.45.1"# x-release-please-version
+      version = "0.45.1" # x-release-please-version
     }
   }
 }
@@ -11,7 +11,7 @@ provider "proxmox" {
   endpoint  = var.virtual_environment_endpoint
   api_token = var.virtual_environment_token
   ssh {
-    agent = true
-    username = "root"
+    agent    = true
+    username = "terraform"
   }
 }

examples/guides/cloud-image/ubuntu-img/main.tf

@@ -12,7 +12,7 @@ resource "proxmox_virtual_environment_vm" "ubuntu_vm" {
 
   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"
@@ -20,13 +20,10 @@ resource "proxmox_virtual_environment_vm" "ubuntu_vm" {
   }
 }
 
-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"
+  url          = "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"
 
-  source_file {
-    # you may download this image locally on your workstation and then use the local path instead of the remote URL
-    path      = "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"
-  }
 }

examples/guides/cloud-image/ubuntu-img/provider.tf

@@ -2,7 +2,7 @@ terraform {
   required_providers {
     proxmox = {
       source  = "bpg/proxmox"
-      version = "0.45.1"# x-release-please-version
+      version = "0.45.1" # x-release-please-version
     }
   }
 }
@@ -11,7 +11,7 @@ provider "proxmox" {
   endpoint  = var.virtual_environment_endpoint
   api_token = var.virtual_environment_token
   ssh {
-    agent = true
-    username = "root"
+    agent    = true
+    username = "terraform"
   }
 }

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

@@ -2,7 +2,7 @@ terraform {
   required_providers {
     proxmox = {
       source  = "bpg/proxmox"
-      version = "0.45.1"# x-release-please-version
+      version = "0.45.1" # x-release-please-version
     }
   }
 }
@@ -11,7 +11,7 @@ provider "proxmox" {
   endpoint  = var.virtual_environment_endpoint
   api_token = var.virtual_environment_token
   ssh {
-    agent = true
-    username = "root"
+    agent    = true
+    username = "terraform"
   }
 }

examples/guides/cloud-init/native/provider.tf

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

howtos/README.md

@@ -1,12 +0,0 @@
-# HOW-TOs
-
-A collection of HOW-TOs for common tasks.
-
-## Virtual Machines
-
-- [Create a VM from a Cloud Image](./cloud-image/README.md)
-- [Configure a VM with Cloud-Init](./cloud-init/README.md)
-
-## Contributors
-
-- [Setup VM with proxmox to run examples and acceptance tests](./setup-proxmox-for-tests/README.md)

howtos/cloud-init/native/provider.tf

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

templates/data-sources.md.tmpl

@@ -14,7 +14,7 @@ description: |-
 {{ if .HasExample -}}
 ## Example Usage
 
-{{ printf "{{tffile %q}}" .ExampleFile }}
+{{ codefile "terraform" .ExampleFile }}
 {{- end }}
 
 {{ .SchemaMarkdown | trimspace }}

templates/guides/cloud-image.md.tmpl

@@ -0,0 +1,30 @@
+---
+layout: page
+title: Create a VM from a Cloud Image
+parent: Guides
+subcategory: Virtual Environment
+description: |-
+    This guide explains how to create a VM from a cloud image.
+---
+
+# Create a VM from a Cloud Image
+
+## Download a public cloud image from URL
+
+Proxmox does not natively support QCOW2 images, but provider can do the conversion for you.
+
+Example of how to create a CentOS 8 VM from a "generic cloud" `qcow2` image. CentOS 8 images are available at [cloud.centos.org](https://cloud.centos.org/centos/8-stream/x86_64/images/):
+
+{{ codefile "terraform" "examples/guides/cloud-image/centos-qcow2/main.tf" }}
+
+Ubuntu cloud images are available at [cloud-images.ubuntu.com](https://cloud-images.ubuntu.com/). Ubuntu cloud images are in `qcow2` format as well, but stored with `.img` extension, so they can be directly uploaded to Proxmox without renaming.
+
+{{ codefile "terraform" "examples/guides/cloud-image/ubuntu-img/main.tf" }}
+
+For [large images](https://registry.terraform.io/providers/bpg/proxmox/latest/docs/resources/virtual_environment_file#important-notes), you may want to use a dedicated temporary directory [configured](https://registry.terraform.io/providers/bpg/proxmox/latest/docs#tmp_dir) for provider via `tmp_dir` attribute, instead of system's default temporary directory. This is especially useful if you are deploying from a container with limited disk space.
+
+## Create a VM from an exiting image on Proxmox
+
+If you already have a cloud image on Proxmox, you can use it to create a VM:
+
+{{ codefile "terraform" "examples/guides/cloud-image/debian-from-storage/main.tf" }}

templates/guides/cloud-init.md.tmpl

@@ -0,0 +1,28 @@
+---
+layout: page
+title: Configure a VM with Cloud-Init
+parent: Guides
+subcategory: Virtual Environment
+description: |-
+    This guide explains how to use the Proxmox provider to create and manage virtual machines using cloud-init.
+---
+
+# Configure a VM with Cloud-Init
+
+## Native Proxmox Cloud-Init support
+
+Proxmox supports Cloud-Init natively, so you can use the `initialization` block to configure your VM:
+
+{{ codefile "terraform" "examples/guides/cloud-init/native/main.tf" }}
+
+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.
+
+{{ codefile "terraform" "examples/guides/cloud-init/custom/cloud-config.tf" }}
+
+{{ codefile "terraform" "examples/guides/cloud-init/custom/main.tf" }}

templates/guides/setup-proxmox-for-tests.md.tmpl

@@ -0,0 +1,96 @@
+---
+layout: page
+title: Setup a VM with Proxmox
+parent: Guides
+subcategory: Virtual Environment
+description: |-
+  This guide will help you setup a proxmox node in VM using virt-manager for a job.
+---
+
+# Setup VM with Proxmox to run examples and acceptance tests
+
+## Who
+
+Contributors
+
+## Motivation
+
+To test changes, it's best to try it on real proxmox cluster. There is dedicated `make example` command that will try to apply changes defined in `example` directory. Most resources have its examples declarations there. For example, if you add new resource, you could add new file with example resource there (ideally after adding tests). If nothing breaks, apply works fine, new resource is created and all other resources are fine, then likely change is safe.
+
+But, proxmox node setup can be tricky task for some contributors.
+
+## Preconditions
+
+Be sure to install `go` and `terraform` on your system first.
+
+## Linux (Debian/Ubuntu) with virt-manager
+
+Goal is to have a proxmox node in VM using <https://virt-manager.org/> for a job. This text assumes some linux knowledge. Tested on Debian 12 bookworm and proxmox VE 8.1. For other distros, with any luck steps should be similar.
+
+1. `sudo apt-get install virt-manager`.
+
+2. Download some proxmox image from <http://download.proxmox.com/iso/>, currently latest is `proxmox-ve_8.1-1.iso`.
+
+3. Run `virt-manager` and "create a new virtual machine", use a file you just downloaded, choose debian as a operating system, leave default network settings.
+
+4. Give it enough RAM and disk size (required minimum is unknown for make example though I used 4GB on my 8GB laptop and 30GB disk size with success).
+
+5. Proceed forward with installation, choose whatever you want for timezone, country, password, domain, email. Don't change other default settings.
+
+6. After installation, log in using password from previous step and `root` username (it's proxmox default). Run: `ip a` to get assigned ip (this also appears during installation). In my case it is `192.168.122.43`.
+
+   It may look like this:
+
+   ```txt
+   root@proxmox:~# ip a
+   1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
+       link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
+       inet 127.0.0.1/8 scope host lo
+       valid_lft forever preferred_lft forever
+       inet6 ::1/128 scope host noprefixroute
+       valid_lft forever preferred_lft forever
+   2: enp1s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master vmbr0 state UP group default qlen 1000
+       link/ether 52:54:00:b3:22:f5 brd ff:ff:ff:ff:ff:ff
+   3: vmbr0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
+       link/ether 52:54:00:b3:22:f5 brd ff:ff:ff:ff:ff:ff
+       inet 192.168.122.43/24 scope global vmbr0
+       valid_lft forever preferred_lft forever
+       inet6 fe80::5054:ff:feb3:22f5/64 scope link
+       valid_lft forever preferred_lft forever
+   ```
+
+7. (Optional) On **your** computer, there should be new interface created mapped to that one you see on proxmox. Again `ip a`:
+
+   ```txt
+   ...
+
+   8: virbr0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
+       link/ether 52:54:00:ca:65:49 brd ff:ff:ff:ff:ff:ff
+       inet 192.168.122.1/24 brd 192.168.122.255 scope global virbr0
+       valid_lft forever preferred_lft forever
+
+   ...
+
+   ```
+
+8. (Optional) You can SSH into proxmox node:
+
+   ```bash
+   ssh root@192.168.122.43
+   ```
+
+   You can also use browser and visit console at <https://192.168.122.43:8006>.
+
+9. Create `terraform.tfvars` file (it will be git ignored file) in `example` folder with credentials for you new proxmox node.
+
+   ```txt
+   # example/terraform.tfvars
+   virtual_environment_username = "root@pam"
+   virtual_environment_endpoint = "https://192.168.122.43:8006/"
+   virtual_environment_password = "your password from step 5"
+
+   ```
+
+10. Now you can run `make example`.
+
+11. If you see error with proxmox_virtual_environment_file: the datastore "local" does not support content type "snippets"; supported content types are: [backup iso vztmpl], you need to enable them, see <https://registry.terraform.io/providers/bpg/proxmox/latest/docs/resources/virtual_environment_file#snippets>.

templates/resources.md.tmpl

@@ -14,7 +14,7 @@ description: |-
 {{ if .HasExample -}}
 ## Example Usage
 
-{{ printf "{{tffile %q}}" .ExampleFile }}
+{{ codefile "terraform" .ExampleFile }}
 {{- end }}
 
 {{ .SchemaMarkdown | trimspace }}
@@ -24,5 +24,5 @@ description: |-
 
 Import is supported using the following syntax:
 
-{{ printf "{{codefile \"shell\" %q}}" .ImportFile }}
+{{ codefile "shell" .ImportFile }}
 {{- end }}

tools/tools.go

@@ -28,6 +28,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 ../build/docs-gen/data-sources/virtual_environment_version.md ../docs/data-sources/
 //go:generate cp ../build/docs-gen/data-sources/virtual_environment_hagroup.md ../docs/data-sources/
 //go:generate cp ../build/docs-gen/data-sources/virtual_environment_hagroups.md ../docs/data-sources/