feat(docs): rename howtos -> guides and publish to the Terraform Regi…

…stry (#971)

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

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

howtos/cloud-image/README.md → 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,39 +30,55 @@ 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"
     size         = 20
   }
 }
 
-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.

howtos/cloud-init/README.md → 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]
+}
 ```

howtos/setup-proxmox-for-tests/README.md → 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
 

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

@@ -12,22 +12,18 @@ 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"
     size         = 20
   }
 }
 
-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"
 }

howtos/cloud-init/cutom/provider.tf → 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"
   }
 }

howtos/cloud-image/debian-from-storage/provider.tf → 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"
   }
 }

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

@@ -12,21 +12,18 @@ 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"
     size         = 20
   }
 }
 
-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"
-  }
 }

howtos/cloud-image/ubuntu-img/provider.tf → 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"
   }
 }

howtos/cloud-image/centos-qcow2/provider.tf → 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"
+  }
+}

templates/data-sources.md.tmpl

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