mirror of https://github.com/bpg/terraform-provider-proxmox.git synced 2025-06-30 10:33:46 +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

2.2 KiB

Raw Blame History

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

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

Required

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

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 VE 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 VE API call, but causes a PCI hardware mapping to be incomplete when not set

Import

Import is supported using the following syntax:

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

2.2 KiB Raw Blame History