feat(docs): add initial mini-howtos for VM (#730)

* chore(docs): minor fixes and linting

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

* chore(docs): add VM mini-howtos with examples

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

* address peer-review feedback

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

* vscode settings

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

---------

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

.markdownlint.json

@@ -0,0 +1,4 @@
+{
+    "MD013": false,
+    "MD025": false
+}

.vscode/launch.json

@@ -0,0 +1,13 @@
+{
+    "version": "0.2.0",
+    "configurations": [      
+        {
+            "name": "Debug provider",
+            "type": "go",
+            "request": "launch",
+            "mode": "auto",
+            "program": "./",
+            "args": ["-debug"]
+        }
+    ]
+}

.vscode/settings.json

@@ -1,3 +1,8 @@
 {
-    "git.alwaysSignOff": true
+    "git.alwaysSignOff": true,
+    "cSpell.words": [
+        "iothread",
+        "qcow",
+        "virtio"
+    ]
 }

CONTRIBUTING.md

@@ -50,7 +50,7 @@ Please use lowercase for the description and do not end it with a period.
 
 For example:
 
-```
+```commit
 feat(vm): add support for the `clone` operation
 ```
 
@@ -61,7 +61,7 @@ it [here](https://developercertificate.org).
 Accepting is accomplished by signing off on your commits, you can do this by
 adding a `Signed-off-by` line to your commit message, like here:
 
-```
+```commit
 feat(vm): add support for the `clone` operation
 
 Signed-off-by: Random Developer <random@developer.example.org>
@@ -69,7 +69,7 @@ Signed-off-by: Random Developer <random@developer.example.org>
 
 Git has a built-in flag to append this line automatically:
 
-```
+```shell
 > git commit -s -m 'feat(vm): add a cool new feature'
 ```
 
@@ -89,7 +89,7 @@ well.
 ## Releasing
 
 We use automated release management orchestrated
-by https://github.com/googleapis/release-please GitHub Action. The action
+by [release-please](https://github.com/googleapis/release-please) GitHub Action. The action
 creates a new release PR with the changelog and bumps the version based on the
 commit messages. The release PR is merged by the maintainers.
 

docs/index.md

@@ -155,18 +155,9 @@ provider "proxmox" {
 }
 ```
 
-> Note1: The `username` field in the `ssh` block is required when using API
+-> **Note:** The `username` field in the `ssh` block is required when using API Token authentication. This is because the provider needs to know which user to use for the SSH connection.
-> Token authentication. This is because the provider needs to know which user to
-> use for the SSH connection.
 
-> Note2: Not all Proxmox API operations are supported via API Token. You may see
+-> **Note:** Not all Proxmox API operations are supported via API Token. You may see errors like `error creating container: received an HTTP 403 response - Reason: Permission check failed (changing feature flags for privileged container is only allowed for root@pam)` or `error creating VM: received an HTTP 500 response - Reason: only root can set 'arch' config` when using API Token authentication, even when `Administrator` role or the `root@pam` user is used with the token.
-> errors like
-`error creating container: received an HTTP 403 response - Reason: Permission check
-failed (changing feature flags for privileged container is only allowed for root@pam)`
-> or
-`error creating VM: received an HTTP 500 response - Reason: only root can set 'arch' config`
-> when using API Token authentication, even when `Administrator` role or
-> the `root@pam` user is used with the token.
 
 ### Temporary directory
 

docs/resources/virtual_environment_cluster_firewall.md

@@ -53,5 +53,5 @@ Be careful not to use this resource multiple times for the same node.
 Instances can be imported without an ID, but you still need to pass one, e.g.,
 
 ```bash
-$ terraform import proxmox_virtual_environment_cluster_firewall.example example
+terraform import proxmox_virtual_environment_cluster_firewall.example example
 ```

docs/resources/virtual_environment_cluster_firewall_security_group.md

@@ -66,7 +66,7 @@ resource "proxmox_virtual_environment_cluster_firewall_security_group" "webserve
   - `log` - (Optional) Log level for this rule (`emerg`, `alert`, `crit`,
       `err`, `warning`, `notice`, `info`, `debug`, `nolog`).
   - `macro`- (Optional) Macro name. Use predefined standard macro
-      from https://pve.proxmox.com/pve-docs/pve-admin-guide.html#_firewall_macro_definitions
+      from <https://pve.proxmox.com/pve-docs/pve-admin-guide.html#_firewall_macro_definitions>
   - `proto` - (Optional) Restrict packet protocol. You can use protocol names
       as defined in '/etc/protocols'.
   - `source` - (Optional) Restrict packet source address. This can refer
@@ -92,5 +92,5 @@ There are no attribute references available for this resource.
 Instances can be imported using the `name`, e.g.,
 
 ```bash
-$ terraform import proxmox_virtual_environment_cluster_firewall_security_group.webserver webserver
+terraform import proxmox_virtual_environment_cluster_firewall_security_group.webserver webserver
 ```

docs/resources/virtual_environment_container.md

@@ -215,5 +215,5 @@ There are no additional attributes available for this resource.
 Instances can be imported using the `node_name` and the `vm_id`, e.g.,
 
 ```bash
-$ terraform import proxmox_virtual_environment_container.ubuntu_container first-node/1234
+terraform import proxmox_virtual_environment_container.ubuntu_container first-node/1234
 ```

docs/resources/virtual_environment_dns.md

@@ -48,5 +48,5 @@ Be careful not to use this resource multiple times for the same node.
 Instances can be imported using the `node_name`, e.g.,
 
 ```bash
-$ terraform import proxmox_virtual_environment_dns.first_node first-node
+terraform import proxmox_virtual_environment_dns.first_node first-node
 ```

docs/resources/virtual_environment_file.md

@@ -94,7 +94,6 @@ resource "proxmox_virtual_environment_file" "ubuntu_container_template" {
 }
 ```
 
-
 ## Argument Reference
 
 - `content_type` - (Optional) The content type. If not specified, the content type will be inferred from the file
@@ -158,5 +157,5 @@ node_name:datastore_id/content_type/file_name
 Example:
 
 ```bash
-$ terraform import proxmox_virtual_environment_file.cloud_config pve/local:snippets/example.cloud-config.yaml
+terraform import proxmox_virtual_environment_file.cloud_config pve/local:snippets/example.cloud-config.yaml
 ```

docs/resources/virtual_environment_firewall_options.md

@@ -41,7 +41,7 @@ resource "proxmox_virtual_environment_firewall_options" "example" {
 - `dhcp` - (Optional)Enable DHCP.
 - `enabled` - (Optional) Enable or disable the firewall.
 - `ipfilter` - (Optional) Enable default IP filters. This is equivalent to
-  adding an empty ipfilter-net<id> ipset for every interface. Such ipsets
+  adding an empty `ipfilter-net<id>` ipset for every interface. Such ipsets
   implicitly contain sane default restrictions such as restricting IPv6 link
   local addresses to the one derived from the interface's MAC address. For
   containers the configured IP addresses will be implicitly added.

docs/resources/virtual_environment_firewall_rules.md

@@ -84,7 +84,7 @@ resource "proxmox_virtual_environment_firewall_rules" "inbound" {
     - `log` - (Optional) Log level for this rule (`emerg`, `alert`, `crit`,
           `err`, `warning`, `notice`, `info`, `debug`, `nolog`).
     - `macro`- (Optional) Macro name. Use predefined standard macro
-          from https://pve.proxmox.com/pve-docs/pve-admin-guide.html#_firewall_macro_definitions
+          from <https://pve.proxmox.com/pve-docs/pve-admin-guide.html#_firewall_macro_definitions>
     - `proto` - (Optional) Restrict packet protocol. You can use protocol
           names as defined in '/etc/protocols'.
     - `source` - (Optional) Restrict packet source address. This can refer

docs/resources/virtual_environment_group.md

@@ -38,5 +38,5 @@ resource "proxmox_virtual_environment_group" "operations_team" {
 Instances can be imported using the `group_id`, e.g.,
 
 ```bash
-$ terraform import proxmox_virtual_environment_group.operations_team operations-team
+terraform import proxmox_virtual_environment_group.operations_team operations-team
 ```

docs/resources/virtual_environment_hosts.md

@@ -52,5 +52,5 @@ Be careful not to use this resource multiple times for the same node.
 Instances can be imported using the `node_name`, e.g.,
 
 ```bash
-$ terraform import proxmox_virtual_environment_hosts.first_node_host_entries first-node
+terraform import proxmox_virtual_environment_hosts.first_node_host_entries first-node
 ```

docs/resources/virtual_environment_network_linux_bridge.md

@@ -54,7 +54,7 @@ resource "proxmox_virtual_environment_network_linux_bridge" "vmbr99" {
 
 ### Read-Only
 
-- `id` (String) A unique identifier with format '<node name>:<iface>'
+- `id` (String) A unique identifier with format `<node name>:<iface>`
 
 ## Import
 

docs/resources/virtual_environment_network_linux_vlan.md

@@ -55,7 +55,7 @@ resource "proxmox_virtual_environment_network_linux_vlan" "vlan98" {
 
 ### Read-Only
 
-- `id` (String) A unique identifier with format '<node name>:<iface>'.
+- `id` (String) A unique identifier with format `<node name>:<iface>`.
 
 ## Import
 

docs/resources/virtual_environment_pool.md

@@ -39,5 +39,5 @@ resource "proxmox_virtual_environment_pool" "operations_pool" {
 Instances can be imported using the `pool_id`, e.g.,
 
 ```bash
-$ terraform import proxmox_virtual_environment_pool.operations_pool operations-pool
+terraform import proxmox_virtual_environment_pool.operations_pool operations-pool
 ```

docs/resources/virtual_environment_role.md

@@ -37,5 +37,5 @@ There are no additional attributes available for this resource.
 Instances can be imported using the `role_id`, e.g.,
 
 ```bash
-$ terraform import proxmox_virtual_environment_role.operations_monitoring operations-monitoring
+terraform import proxmox_virtual_environment_role.operations_monitoring operations-monitoring
 ```

docs/resources/virtual_environment_time.md

@@ -35,5 +35,5 @@ resource "proxmox_virtual_environment_time" "first_node_time" {
 Instances can be imported using the `node_name`, e.g.,
 
 ```bash
-$ terraform import proxmox_virtual_environment_dns.first_node first-node
+terraform import proxmox_virtual_environment_dns.first_node first-node
 ```

docs/resources/virtual_environment_user.md

@@ -61,5 +61,5 @@ There are no additional attributes available for this resource.
 Instances can be imported using the `user_id`, e.g.,
 
 ```bash
-$ terraform import proxmox_virtual_environment_user.operations_automation operations-automation@pve
+terraform import proxmox_virtual_environment_user.operations_automation operations-automation@pve
 ```

docs/resources/virtual_environment_vm.md

@@ -227,7 +227,7 @@ output "ubuntu_vm_public_key" {
     - `qemu32`/`qemu64` - QEMU Virtual CPU version 2.5+ (32 & 64 bit
           variants).
     - `x86-64-v2`/`x86-64-v2-AES`/`x86-64-v3`/`x86-64-v4`
-          See https://en.wikipedia.org/wiki/X86-64#Microarchitecture_levels
+          See <https://en.wikipedia.org/wiki/X86-64#Microarchitecture_levels>
     - `custom-<model>` - Custom CPU model. All `custom-<model>` values
           should be defined in `/etc/pve/virtual-guest/cpu-models.conf` file.
   - `units` - (Optional) The CPU units (defaults to `1024`).
@@ -645,5 +645,5 @@ resource "proxmox_virtual_environment_vm" "data_user_vm" {
 Instances can be imported using the `node_name` and the `vm_id`, e.g.,
 
 ```bash
-$ terraform import proxmox_virtual_environment_vm.ubuntu_vm first-node/4321
+terraform import proxmox_virtual_environment_vm.ubuntu_vm first-node/4321
 ```

fwprovider/resource_linux_bridge.go

@@ -172,7 +172,7 @@ func (r *linuxBridgeResource) Schema(
 		Description: "Manages a Linux Bridge network interface in a Proxmox VE node.",
 		Attributes: map[string]schema.Attribute{
 			// Base attributes
-			"id": structure.IDAttribute("A unique identifier with format '<node name>:<iface>'"),
+			"id": structure.IDAttribute("A unique identifier with format `<node name>:<iface>`"),
 			"node_name": schema.StringAttribute{
 				Description: "The name of the node.",
 				Required:    true,

fwprovider/resource_linux_vlan.go

@@ -146,7 +146,7 @@ func (r *linuxVLANResource) Schema(
 		Description: "Manages a Linux VLAN network interface in a Proxmox VE node.",
 		Attributes: map[string]schema.Attribute{
 			// Base attributes
-			"id": structure.IDAttribute("A unique identifier with format '<node name>:<iface>'."),
+			"id": structure.IDAttribute("A unique identifier with format `<node name>:<iface>`."),
 			"node_name": schema.StringAttribute{
 				Description: "The name of the node.",
 				Required:    true,

howtos/README.md

@@ -0,0 +1,8 @@
+# HOW-TOs
+
+A collection of HOW-TOs for common tasks.
+
+## Virtual Machines
+
+- [Create a VM from a Cloud Image](howtos/cloud-image/README.md)
+- [Configure a VM with Cloud-Init](howtos/cloud-init/README.md)

howtos/cloud-image/README.md

@@ -0,0 +1,93 @@
+# 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`
+
+## 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/):
+
+```terraform
+resource "proxmox_virtual_environment_vm" "centos_vm" {
+  name      = "test-centos"
+  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_file.centos_cloud_image.id
+    interface    = "virtio0"
+    iothread     = true
+    discard      = "on"
+    size         = 20
+  }
+}
+
+resource "proxmox_virtual_environment_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"
+  }
+}
+```
+
+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"
+    ...
+  }
+```
+
+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:
+
+```terraform
+resource "proxmox_virtual_environment_vm" "debian_vm" {
+  name      = "test-debian"
+  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      = "local:iso/debian-12-genericcloud-amd64.img"
+    interface    = "virtio0"
+    iothread     = true
+    discard      = "on"
+    size         = 20
+  }
+}
+```

howtos/cloud-image/centos-qcow2/main.tf

@@ -0,0 +1,33 @@
+resource "proxmox_virtual_environment_vm" "centos_vm" {
+  name      = "test-centos"
+  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_file.centos_cloud_image.id
+    interface    = "virtio0"
+    iothread     = true
+    discard      = "on"
+    size         = 20
+  }
+}
+
+resource "proxmox_virtual_environment_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"
+  }
+}

howtos/cloud-image/centos-qcow2/provider.tf

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

howtos/cloud-image/centos-qcow2/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-image/debian-from-storage/main.tf

@@ -0,0 +1,22 @@
+resource "proxmox_virtual_environment_vm" "debian_vm" {
+  name      = "test-debian"
+  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      = "local:iso/debian-12-genericcloud-amd64.img"
+    interface    = "virtio0"
+    iothread     = true
+    discard      = "on"
+    size         = 20
+  }
+}
+

howtos/cloud-image/debian-from-storage/provider.tf

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

howtos/cloud-image/debian-from-storage/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-image/ubuntu-img/main.tf

@@ -0,0 +1,32 @@
+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_file.ubuntu_cloud_image.id
+    interface    = "virtio0"
+    iothread     = true
+    discard      = "on"
+    size         = 20
+  }
+}
+
+resource "proxmox_virtual_environment_file" "ubuntu_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-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"
+  }
+}

howtos/cloud-image/ubuntu-img/provider.tf

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

howtos/cloud-image/ubuntu-img/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/README.md

@@ -0,0 +1,6 @@
+# HOW-TO Configure a VM with Cloud-Init
+
+## Native Proxmox Cloud-Init support
+
+TODO
+

howtos/cloud-init/native/main.tf

@@ -0,0 +1,32 @@
+resource "proxmox_virtual_environment_vm" "centos_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!
+      username = "ubuntu"
+    }
+  }
+
+  disk {
+    datastore_id = "local-lvm"
+    file_id      = proxmox_virtual_environment_file.ubuntu_cloud_image.id
+    interface    = "virtio0"
+    iothread     = true
+    discard      = "on"
+    size         = 20
+  }
+}
+
+resource "proxmox_virtual_environment_file" "ubuntu_cloud_image" {
+  content_type = "iso"
+  datastore_id = "local"
+  node_name    = "pve"
+
+  source_file {
+    path      = "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"
+  }
+}

howtos/cloud-init/native/provider.tf

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

howtos/cloud-init/native/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"
+}