mirror of https://github.com/bpg/terraform-provider-proxmox.git synced 2025-06-30 18:42:58 +00:00

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

* 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]: https://github.com/bpg/terraform-provider-proxmox/pull/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>

* fix linter

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

---------

Signed-off-by: Sven Greb <development@svengreb.de>
Signed-off-by: Pavel Boldyrev <627562+bpg@users.noreply.github.com>
Co-authored-by: Pavel Boldyrev <627562+bpg@users.noreply.github.com>

2024-04-18 16:00:51 -04:00

1.8 KiB

Raw Blame History

layout	title	parent	subcategory	description
page	proxmox_virtual_environment_hardware_mapping_usb	Resources	Virtual Environment	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

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

Required

map (Attributes Set) The actual map of devices for the hardware mapping. (see below for nested schema)
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.

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:

#!/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

1.8 KiB Raw Blame History