Add `list` resource support for `terraform query` (Terraform 1.14)

[CloudbrokerAz]

Code of Conduct

• I have read and agree to the project's Code of Conduct.

Description

Terraform 1.14 introduced list resources, the provider primitive backing the terraform query command, .tfquery.hcl files, and -generate-config-out. The vSphere provider does not yet implement list resources (verified through v2.16.0, 2026-05-12).

This request is to add list resource support to the provider, starting with list.vsphere_virtual_machine, to enable native discovery of existing inventory objects and configuration-driven import workflows.

Environment

• Terraform: 1.14+
• Provider: vmware/vsphere (verified absent through v2.16.0)
• vCenter: 7.0+ / 8.0+

Use Case(s)

Bulk import of pre-existing vSphere resources into Terraform state currently requires out-of-band enumeration (PowerCLI, govc, vCenter API) followed by hand-authored or templated import blocks. A list.vsphere_virtual_machine resource would let users express discovery declaratively in a .tfquery.hcl file and produce import blocks plus skeleton resource configuration via terraform query -generate-config-out.

Representative scenarios:

• Onboarding existing VMs to Terraform management without per-VM manual enumeration and import block authoring.
• Producing a complete inventory of VMs matching tag/folder/state predicates for governance and reconciliation workflows.
• Driving the HCP Terraform "Search & Import" workspace UI against vSphere inventory, which currently has no provider-native discovery path.

Potential Configuration

Minimum scope: list.vsphere_virtual_machine

Filter inputs

• datacenter (string, required)
• folder (string, optional; recursive)
• name_pattern (string, optional; glob)
• power_state (list(string), optional)
• guest_id (list(string), optional)
• template (bool, optional; default false)
• tag_present / tag_absent (list(string), category:value form, optional)
• custom_attribute (map(string), optional)

Per-result attributes

At minimum the attributes required to construct a usable import block and a meaningful generated resource "vsphere_virtual_machine" block:

• inventory_path — required as the import.id (/<dc>/vm/<folder>/<name>)
• uuid, moid, name
• datacenter_id, folder
• resource_pool_id, host_system_id
• datastore_id (primary) and per-disk datastore where divergent
• num_cpus, num_cores_per_socket, memory
• guest_id, firmware, hardware_version
• power_state
• network_interface[] — network_id, mac_address, adapter_type, unit_number
• disk[] — label, size, unit_number, controller_type, datastore_id, thin_provisioned, eagerly_scrub
• scsi_controller[] — bus_number, type, sharing
• tags[], custom_attributes (map)

Example query

# discover.tfquery.hcl
list "vsphere_virtual_machine" "unmanaged" {
  provider = vsphere

  config {
    datacenter = "dc-east"
    folder     = "/Production"

    filter = {
      power_state = ["poweredOn"]
      template    = false
      tag_absent  = ["lifecycle:terraform_managed"]
    }
  }
}

$ terraform query -generate-config-out=imports.tf

…producing import blocks plus skeleton resource "vsphere_virtual_machine" blocks keyed by inventory path.

Implementation notes

• List resources require terraform-plugin-framework. The provider is currently on terraform-plugin-sdk/v2 (v2.40.1 as of v2.16.0). Provider muxing is the lowest-disruption path: existing resources remain on SDKv2 while new framework-based list resources are served from a muxed framework provider.
• All required vCenter primitives are already used by the provider via vmware/govmomi:
  • view.ContainerView for scalable inventory traversal (inventories of 10k+ VMs are common; results should stream rather than materialize).
  • property.Collector for batched property retrieval (necessary to avoid N+1 calls when populating disk/NIC details).
  • tags.Manager (vSphere Automation SDK) for tag and category lookups used by the filter predicates.
  • find.Finder for inventory-path resolution.
• Disk handling is the most error-prone surface of the existing manual-import path and should be addressed deliberately in the generator:
  • Emit disk blocks in canonical SCSI order with Hard Disk 0..N labels, indexed by (controller bus, unit_number).
  • Emit scsi_controller_count (or per-controller blocks) reflecting contiguous controllers from bus 0; non-contiguous controllers in the source VM should surface as a validation diagnostic, not silently render an unappliable plan.
  • Set keep_on_remove = true on imported disks (current behavior on terraform import of vsphere_virtual_machine) and document this in the generated config so users can opt back to false deliberately.
  • Surface per-disk datastore_id where it diverges from the VM's primary datastore.
• The generator should not emit clone {} or customize {} blocks — those describe creation, not steady state. This matches the existing manual-import guidance in the vsphere_virtual_machine docs.
• Provider-level vCenter session and any datacenter scoping should apply; per-list overrides should be supported.

Follow-up list resources (not blocking)

Useful but out of scope for an initial implementation:

• list.vsphere_folder
• list.vsphere_tag, list.vsphere_tag_category
• list.vsphere_resource_pool, list.vsphere_compute_cluster, list.vsphere_host
• list.vsphere_datastore, list.vsphere_datastore_cluster
• list.vsphere_virtual_disk (detached / shared VMDK discovery)
• list.vsphere_network, list.vsphere_distributed_port_group, list.vsphere_distributed_virtual_switch
• list.vsphere_custom_attribute

References

• Terraform 1.14 — Search & Import announcement
• Plugin Framework — List Resources
• Plugin Framework — Implementing list resources
• AWS provider — list resource contributor guide (reference implementation pattern)
• Provider muxing
• vmware/govmomi