terraform-provider-libvirt

When configuring disk mirroring within a libvirt_domain resource, you must specify a source for the backing_store. This source defines where the data for the mirror is located. The source block is a polymorphic configuration that accepts different types of storage backends.

Common source types include:

• block: For physical block devices (requires dev).
• file: For local files (requires file).
• dir: For directory-based storage (requires dir).
• data_store: For data store formats (requires type and format).
• network: For network-based storage.
• volume: For storage volumes.
• vhost_user or vhost_vdpa: For specialized high-performance interfaces.

The provider offers two SSH transport options depending on your requirements:

qemu+ssh:// (Go SSH Library)

Use this if:

• You want a pure Go solution without external dependencies.
• You have simple, straightforward SSH authentication.
• You need maximum portability.

Note: It does not respect ~/.ssh/config and lacks support for ProxyJump.

qemu+sshcmd:// (Native SSH Command)

Use this if:

• You have complex SSH configurations (bastion hosts, proxy jumps).
• You need to respect existing SSH config files.
• You use SSH agent forwarding or advanced SSH features.

Note: Requires the ssh binary to be installed and nc (netcat) or virt-ssh-helper on the remote system.

Some resources allow you to control provider-level operations via nested create and destroy attributes. These attributes control API calls related to the resource lifecycle (such as build, start, or delete operations) rather than modifying the XML configuration itself.

Note: Lifecycle operation controls are considered experimental and may change between provider releases. They follow the standard nested-attribute style:

• create = { ... }
• destroy = { ... }

Some resources allow controlling post-define and pre-undefine API operations (like build, start, or delete behavior) via nested create and destroy objects. These are provider-specific controls and are not direct libvirt XML fields. Note that these controls are currently experimental.

Example for libvirt_pool:

resource "libvirt_pool" "data" {
  name = "data-pool"
  type = "dir"
  target = {
    path = "/var/lib/libvirt/data"
  }

  create = {
    build     = true
    start     = true
    autostart = true
  }

  destroy = {
    delete = false
  }
}

The generator uses a multi-stage pipeline to transform libvirtxml reflection and documentation into Terraform provider code:

1. Inputs: It consumes libvirtxml reflection data and a documentation registry (YAML files located in internal/codegen/docs/).
2. IR Builder: Normalizes struct metadata, tracks optionality, and carries docstrings into an Intermediate Representation (IR).
3. Field Policy Layer: Applies Terraform-specific semantics (like Computed, Required, or RequiresReplace) to the reflected fields.
4. Generators: Templates render the IR into Go files (models, schemas, and converters) located in internal/generated/*.gen.go.
5. Orchestration: The main.go entry point manages the workflow and runs gofmt on the output.

The generator follows a strict contract for optional nested objects to prevent Terraform Provider produced inconsistent result after apply errors. This is critical for fields like alias, where libvirt might not round-trip the XML exactly as provided.

When converting XML back to a model, the generator distinguishes between three states:

1. Plan field is null: The user did not configure the object; the state remains null.
2. Plan field is non-null AND XML field is present: The XML is converted back into the state.
3. Plan field is non-null AND XML field is absent: The generator preserves the planned value instead of collapsing it to null. This ensures that if a user explicitly configures an object that libvirt happens to omit during readback, Terraform doesn't try to delete it.

When using devices.smartcards.passthrough, you must specify one of the following source types to define how the smartcard backend connects:

• dev: Uses a device file. Requires path (String) and optional sec_label.
• file: Uses a file source. Requires path (String) and optional append and sec_label.
• nmdm: Uses a null modem device. Requires master (String) and slave (String).
• pipe: Uses a pipe. Requires path (String) and optional sec_label.
• pty: Uses a pseudo-terminal. Requires path (String) and optional sec_label.
• dbus: Uses a DBus source. Requires channel (String).
• null: Configures a null source.

Other available backend settings include qemuvd_agent, spice_port, spice_vmc, std_io, tcp, udp, unix, and vc (virtual console connection).