feat(cluster): Implement initial support for "hardware mappings"

Right now it is alredy possible to use a mapped resource [1], but there
is no dedicated `proxmox_virtual_environment_cluster_hardware_mapping`
resource but this step must still be done manually (or automated through
other ways that interact with the Proxmox API).

This commit implements support for "hardware mapping" resources and data
sources for the, currently, available bus types PCI and USB, based on
the Proxmox VE API documentations [2].

There are some "specialities" in these resources and data sources:

1. The Proxmox VE API attribute, but this implementations names it
   "comment" since this naming is generally across the Proxmox VE web UI
   and API documentations. This still follows the Terraform
   "best practices" [3] as it improves the user experience by matching
   the field name to the naming used in the human-facing interfaces.

2. Like in point 1, the name of the attribute of "node checks
   diagnostics" for USB hardware mappings is "errors" in the Proxmox VE
   API while it is "checks" for hardware mappings of type PCI.
   The second naming pattern is also generally used across the
   Proxmox VE web UI and API documentations, including the "check_node"
   attribute that is also implemented in the
   "proxmox_virtual_environment_hardware_mappings" data source.
   Therefore, this implementation named both attributes "checks" which
   still follows the Terraform "best practices" [3] as it improves the
   user experience by matching the field name to the naming used in the
   human-facing interfaces.
3. This implmenetation comes with the "unique" feature of allowing
   comments (named "descriptions" by the Proxmox VE API) for an entry in
   a device map which is not possible through the web UI at all but only
   adding a comment for the whole mapping entry instead.

Note that this implementation also adds another point in the
"Known Issues" documentation since it is only possible to map a
PCI/USB device using the `root` PAM account, but this is still better
than having to manually configure it through the web UI or by
interacting with the Proxmox VE API on other ways.

[1]: bpg#500
[2]: https://pve.proxmox.com/pve-docs/api-viewer/#/cluster/mapping/pci
[3]: https://developer.hashicorp.com/terraform/plugin/best-practices/hashicorp-provider-design-principles#resource-and-attribute-schema-should-closely-match-the-underlying-api

Signed-off-by: Sven Greb <development@svengreb.de>

Closes bpgGH-886

Signed-off-by: Sven Greb <development@svengreb.de>

.golangci.yml

@@ -26,6 +26,10 @@ issues:
     - path: fwprovider/tests/.*\.go
       linters:
         - paralleltest
+    # Exclude `lll` issues for long lines with URLs.
+    - linters:
+        - lll
+      source: "^.*https?://.*$"
 linters-settings:
   exhaustive:
     default-signifies-exhaustive: true

docs/data-sources/virtual_environment_hardware_mapping_pci.md

@@ -0,0 +1,50 @@
+---
+layout: page
+title: proxmox_virtual_environment_hardware_mapping_pci
+parent: Data Sources
+subcategory: Virtual Environment
+description: |-
+  Retrieves a PCI hardware mapping from a Proxmox VE cluster.
+---
+
+# Data Source: proxmox_virtual_environment_hardware_mapping_pci
+
+Retrieves a PCI hardware mapping from a Proxmox VE cluster.
+
+## Example Usage
+
+```terraform
+data "proxmox_virtual_environment_hardware_mapping_pci" "example" {
+  name = "example"
+}
+
+output "data_proxmox_virtual_environment_hardware_mapping_pci" {
+  value = data.proxmox_virtual_environment_hardware_mapping_pci.example
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `name` (String) The name of this PCI hardware mapping.
+
+### Read-Only
+
+- `comment` (String) The comment of this PCI hardware mapping.
+- `id` (String) The unique identifier of this PCI hardware mapping data source.
+- `map` (Attributes Set) The actual map of devices for the hardware mapping. (see [below for nested schema](#nestedatt--map))
+- `mediated_devices` (Boolean) Indicates whether to use with mediated devices.
+
+<a id="nestedatt--map"></a>
+### Nested Schema for `map`
+
+Read-Only:
+
+- `comment` (String) The comment of the mapped PCI device.
+- `id` (String) The ID attribute of the map.
+- `iommu_group` (Number) The IOMMU group attribute of the map.
+- `node` (String) The node name attribute of the map.
+- `path` (String) The path attribute of the map.
+- `subsystem_id` (String) The subsystem ID attribute of the map.Not mandatory for the Proxmox API call, but causes a PCI hardware mapping to be incomplete when not set.

docs/data-sources/virtual_environment_hardware_mapping_usb.md

@@ -0,0 +1,47 @@
+---
+layout: page
+title: proxmox_virtual_environment_hardware_mapping_usb
+parent: Data Sources
+subcategory: Virtual Environment
+description: |-
+  Retrieves a USB hardware mapping from a Proxmox VE cluster.
+---
+
+# Data Source: proxmox_virtual_environment_hardware_mapping_usb
+
+Retrieves a USB hardware mapping from a Proxmox VE cluster.
+
+## Example Usage
+
+```terraform
+data "proxmox_virtual_environment_hardware_mapping_usb" "example" {
+  name = "example"
+}
+
+output "data_proxmox_virtual_environment_hardware_mapping_usb" {
+  value = data.proxmox_virtual_environment_hardware_mapping_usb.example
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `name` (String) The name of this USB hardware mapping.
+
+### Read-Only
+
+- `comment` (String) The comment of this USB hardware mapping.
+- `id` (String) The unique identifier of this USB hardware mapping data source.
+- `map` (Attributes Set) The actual map of devices for the hardware mapping. (see [below for nested schema](#nestedatt--map))
+
+<a id="nestedatt--map"></a>
+### Nested Schema for `map`
+
+Read-Only:
+
+- `comment` (String) The comment of the mapped USB device.
+- `id` (String) The ID attribute of the map.
+- `node` (String) The node name attribute of the map.
+- `path` (String) The path attribute of the map.

docs/data-sources/virtual_environment_hardware_mappings.md

@@ -0,0 +1,60 @@
+---
+layout: page
+title: proxmox_virtual_environment_hardware_mappings
+parent: Data Sources
+subcategory: Virtual Environment
+description: |-
+  Retrieves a list of hardware mapping resources.
+---
+
+# Data Source: proxmox_virtual_environment_hardware_mappings
+
+Retrieves a list of hardware mapping resources.
+
+## Example Usage
+
+```terraform
+data "proxmox_virtual_environment_hardware_mappings" "example-pci" {
+  check_node = "pve"
+  type       = "pci"
+}
+
+data "proxmox_virtual_environment_hardware_mappings" "example-usb" {
+  check_node = "pve"
+  type       = "usb"
+}
+
+output "data_proxmox_virtual_environment_hardware_mappings_pci" {
+  value = data.proxmox_virtual_environment_hardware_mappings.example-pci
+}
+
+output "data_proxmox_virtual_environment_hardware_mappings_usb" {
+  value = data.proxmox_virtual_environment_hardware_mappings.example-usb
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `type` (String) The type of the hardware mappings.
+
+### Optional
+
+- `check_node` (String) The name of the node whose configurations should be checked for correctness.
+
+### Read-Only
+
+- `checks` (Attributes List) Might contain relevant diagnostics about incorrect configurations. (see [below for nested schema](#nestedatt--checks))
+- `id` (String) The unique identifier of this hardware mappings data source.
+- `ids` (Set of String) The identifiers of the hardware mappings.
+
+<a id="nestedatt--checks"></a>
+### Nested Schema for `checks`
+
+Read-Only:
+
+- `mapping_id` (String) The corresponding hardware mapping ID of the node check diagnostic entry.
+- `message` (String) The message of the node check diagnostic entry.
+- `severity` (String) The severity of the node check diagnostic entry.

docs/resources/virtual_environment_hardware_mapping_pci.md

@@ -0,0 +1,77 @@
+---
+layout: page
+title: proxmox_virtual_environment_hardware_mapping_pci
+parent: Resources
+subcategory: Virtual Environment
+description: |-
+  Manages a PCI hardware mapping in a Proxmox VE cluster.
+---
+
+# Resource: proxmox_virtual_environment_hardware_mapping_pci
+
+Manages a PCI hardware mapping in a Proxmox VE cluster.
+
+## Example Usage
+
+```terraform
+resource "proxmox_virtual_environment_hardware_mapping_pci" "example" {
+  comment = "This is a comment"
+  name    = "example"
+  # The actual map of devices.
+  map = [
+    {
+      comment = "This is a device specific comment"
+      id      = "8086:5916"
+      # This is an optional attribute, but causes a mapping to be incomplete when not defined.
+      iommu_group = 0
+      node        = "pve"
+      path        = "0000:00:02.0"
+      # This is an optional attribute, but causes a mapping to be incomplete when not defined.
+      subsystem_id = "8086:2068"
+    },
+  ]
+  mediated_devices = true
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `map` (Attributes Set) The actual map of devices for the PCI hardware mapping. (see [below for nested schema](#nestedatt--map))
+- `name` (String) The name of this PCI hardware mapping.
+
+### Optional
+
+- `comment` (String) The comment of this PCI hardware mapping.
+- `mediated_devices` (Boolean) Indicates whether to enable mediated devices.
+
+### Read-Only
+
+- `id` (String) The unique identifier of this PCI hardware mapping resource.
+
+<a id="nestedatt--map"></a>
+### Nested Schema for `map`
+
+Required:
+
+- `id` (String) The ID of the map.
+- `node` (String) The node name of the map.
+- `path` (String) The path of the map.
+
+Optional:
+
+- `comment` (String) The comment of the mapped PCI device.
+- `iommu_group` (Number) The IOMMU group of the map. Not mandatory for the Proxmox API call, but causes a PCI hardware mapping to be incomplete when not set
+- `subsystem_id` (String) The subsystem ID group of the map. Not mandatory for the Proxmox API call, but causes a PCI hardware mapping to be incomplete when not set
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+#!/usr/bin/env sh
+# A PCI hardware mapping can be imported using their name, e.g.:
+terraform import proxmox_virtual_environment_hardware_mapping_pci.example example
+```

docs/resources/virtual_environment_hardware_mapping_usb.md

@@ -0,0 +1,70 @@
+---
+layout: page
+title: proxmox_virtual_environment_hardware_mapping_usb
+parent: Resources
+subcategory: Virtual Environment
+description: |-
+  Manages a USB hardware mapping in a Proxmox VE cluster.
+---
+
+# Resource: proxmox_virtual_environment_hardware_mapping_usb
+
+Manages a USB hardware mapping in a Proxmox VE cluster.
+
+## Example Usage
+
+```terraform
+resource "proxmox_virtual_environment_hardware_mapping_usb" "example" {
+  comment = "This is a comment"
+  name    = "example"
+  # The actual map of devices.
+  map = [
+    {
+      comment = "This is a device specific comment"
+      id      = "8087:0a2b"
+      node    = "pve"
+      # This attribute is optional, but can be used to map the device based on its port instead of only the device ID.
+      path = "1-8.2"
+    },
+  ]
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `map` (Attributes Set) The actual map of devices for the hardware mapping. (see [below for nested schema](#nestedatt--map))
+- `name` (String) The name of this hardware mapping.
+
+### Optional
+
+- `comment` (String) The comment of this USB hardware mapping.
+
+### Read-Only
+
+- `id` (String) The unique identifier of this USB hardware mapping resource.
+
+<a id="nestedatt--map"></a>
+### Nested Schema for `map`
+
+Required:
+
+- `id` (String) The ID of the map.
+- `node` (String) The node name of the map.
+
+Optional:
+
+- `comment` (String) The comment of the mapped USB device.
+- `path` (String) The path of the map. For hardware mappings of type USB the path is optional and indicates that the device is mapped through the device ID instead of ports.
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+#!/usr/bin/env sh
+# A USB hardware mapping can be imported using their name, e.g.:
+terraform import proxmox_virtual_environment_hardware_mapping_usb.example example
+```

examples/data-sources/proxmox_virtual_environment_hardware_mapping_pci/data-source.tf

@@ -0,0 +1,7 @@
+data "proxmox_virtual_environment_hardware_mapping_pci" "example" {
+  name = "example"
+}
+
+output "data_proxmox_virtual_environment_hardware_mapping_pci" {
+  value = data.proxmox_virtual_environment_hardware_mapping_pci.example
+}

examples/data-sources/proxmox_virtual_environment_hardware_mapping_usb/data-source.tf

@@ -0,0 +1,7 @@
+data "proxmox_virtual_environment_hardware_mapping_usb" "example" {
+  name = "example"
+}
+
+output "data_proxmox_virtual_environment_hardware_mapping_usb" {
+  value = data.proxmox_virtual_environment_hardware_mapping_usb.example
+}

examples/data-sources/proxmox_virtual_environment_hardware_mappings/data-source.tf

@@ -0,0 +1,17 @@
+data "proxmox_virtual_environment_hardware_mappings" "example-pci" {
+  check_node = "pve"
+  type       = "pci"
+}
+
+data "proxmox_virtual_environment_hardware_mappings" "example-usb" {
+  check_node = "pve"
+  type       = "usb"
+}
+
+output "data_proxmox_virtual_environment_hardware_mappings_pci" {
+  value = data.proxmox_virtual_environment_hardware_mappings.example-pci
+}
+
+output "data_proxmox_virtual_environment_hardware_mappings_usb" {
+  value = data.proxmox_virtual_environment_hardware_mappings.example-usb
+}

examples/resources/proxmox_virtual_environment_hardware_mapping_pci/import.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+# A PCI hardware mapping can be imported using their name, e.g.:
+terraform import proxmox_virtual_environment_hardware_mapping_pci.example example

examples/resources/proxmox_virtual_environment_hardware_mapping_pci/resource.tf

@@ -0,0 +1,18 @@
+resource "proxmox_virtual_environment_hardware_mapping_pci" "example" {
+  comment = "This is a comment"
+  name    = "example"
+  # The actual map of devices.
+  map = [
+    {
+      comment = "This is a device specific comment"
+      id      = "8086:5916"
+      # This is an optional attribute, but causes a mapping to be incomplete when not defined.
+      iommu_group = 0
+      node        = "pve"
+      path        = "0000:00:02.0"
+      # This is an optional attribute, but causes a mapping to be incomplete when not defined.
+      subsystem_id = "8086:2068"
+    },
+  ]
+  mediated_devices = true
+}

examples/resources/proxmox_virtual_environment_hardware_mapping_usb/import.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+# A USB hardware mapping can be imported using their name, e.g.:
+terraform import proxmox_virtual_environment_hardware_mapping_usb.example example

examples/resources/proxmox_virtual_environment_hardware_mapping_usb/resource.tf

@@ -0,0 +1,14 @@
+resource "proxmox_virtual_environment_hardware_mapping_usb" "example" {
+  comment = "This is a comment"
+  name    = "example"
+  # The actual map of devices.
+  map = [
+    {
+      comment = "This is a device specific comment"
+      id      = "8087:0a2b"
+      node    = "pve"
+      # This attribute is optional, but can be used to map the device based on its port instead of only the device ID.
+      path = "1-8.2"
+    },
+  ]
+}