terraform-provider-hyperv

Terraform Provider for Hyper-V

Manage the lifecycle of Microsoft Hyper-V virtual machines, switches, disks, and images from Terraform — with a provider binary that runs on Linux, macOS, or Windows and talks to Hyper-V hosts over local PowerShell, SSH, or WinRM.

[!IMPORTANT] This provider is pre-1.0. Schema, attribute names, and behavior may change between minor versions until v1.0.0 ships. Pin to an exact version in production.

Highlights

• Pluggable execution backends. local (provider already on the host), ssh (key- or password-auth into the host's OpenSSH), or winrm (HTTP/HTTPS, NTLM/Basic/Kerberos). The provider binary itself runs on Linux, macOS, or Windows.
• Built on terraform-plugin-framework. Strict typed schemas, plan modifiers, validators, custom semantic-equality types, and Terraform protocol v6.
• Embedded PowerShell with a JSON contract. Each operation ships an embedded .ps1 through the chosen transport and round-trips JSON via stdin/stdout. Scripts are independently testable with Pester.

Requirements

The connecting identity needs the privilege appropriate to each resource. The matrix below was verified empirically on Windows Server 2022 (build 10.0.20348).

• Hyper-V Administrators is sufficient for: hyperv_vm, hyperv_vhd, hyperv_image_file; data sources hyperv_host, hyperv_vm_state, hyperv_virtual_switch; and hyperv_virtual_switch with switch_type = "Private" or "Internal". Per Microsoft, members of this group have complete and unrestricted access to all the features in Hyper-V.
• Local Administrators is required for: hyperv_nat_static_mapping (Add-NetNatStaticMapping and New-NetFirewallRule return "Access denied" for Hyper-V Administrators alone); and hyperv_virtual_switch with switch_type = "NAT" (the underlying New-NetNat returns the same). switch_type = "External" was not directly tested — Local Administrators is the recommended floor.
• No host-side requirement for the hyperv_iso_volume data source — runs on the Terraform runner.

WinRM-backend transport. Opening a WinRM/PSSession needs membership in Administrators or Remote Management Users in addition to the per-resource privilege above. Administrators implies this; a delegated identity in only Hyper-V Administrators does not. For least-privilege delegation, configure a JEA endpoint and point the WinRM backend at it. The provider does not (and should not) set JEA up for you — that's host fabric configuration owned by DSC, GPO, or Intune.

Supported resources and data sources

Inline attachments, not sub-resources

hyperv_vm ships with inline blocks for NICs, hard disks, DVDs, boot order, and power state — not separate hyperv_vm_* resources. Reconciliation is keyed on slot tuples (HDDs / DVDs) or display name (NICs); see the hyperv_vm documentation for the full attribute set.

Out of scope / not yet implemented

The following are either deferred to post-1.0 or under active design — track an issue if you need one:

• Image creation — use Packer or DISM to build golden images and reference them via hyperv_image_file.
• Checkpoints (hyperv_vm_checkpoint).
• Hyper-V integration services map (per-service enable/disable on hyperv_vm).
• VM automatic start/stop actions (AutomaticStartAction / AutomaticStopAction).
• Generation 1 BIOS startup order (Set-VMBios -StartupOrder).
• Trunk and isolation VLAN modes on inline NICs (access-mode VLANs are supported via vlan_id; static MAC addresses via mac_address).
• Replication, live migration, SR-IOV, GPU partitioning, shielded VMs.
• Additional hyperv_image_file source modes beyond the four shipped — e.g. a templated-content mode or a native answer-file synthesizer. The current literal_bytes mode paired with hyperv_iso_volume covers most cloud-init NoCloud / autounattend use cases without a new mode.

Requirements

Runtime

• Terraform >= 1.5
• A Hyper-V host running Windows Server 2019+ or Windows 10/11 Pro/Enterprise with the Hyper-V role enabled.
• Windows PowerShell 5.1 on the host (ships with Windows). PowerShell 7.4+ is supported and tested but not required.
• One reachable transport to the host: a local PowerShell installation, OpenSSH, or WinRM (HTTPS recommended).

Development

• Go matching the toolchain in go.mod (currently 1.25+).
• Task for the build, lint, test, and docs targets.
• aqua to provision pinned versions of terraform, goreleaser, gosec, etc. (see aqua.yaml).
• PowerShell 7+ to run the Pester script-level tests.
• A reachable Hyper-V host for acceptance tests (task test:acc); unit tests run anywhere.

Quickstart

terraform {
  required_providers {
    hyperv = {
      source  = "windsorcli/hyperv"
      version = "~> 0.3"
    }
  }
}

# Configuration is environment-driven by default; see "Configuration" below.
provider "hyperv" {}

resource "hyperv_virtual_switch" "lab" {
  name        = "lab-internal"
  switch_type = "Internal"
}

resource "hyperv_image_file" "ubuntu" {
  destination_path = "C:/hyperv/images/ubuntu-22.04.vhdx"
  url = {
    url      = "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.vhdx"
    checksum = "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  }
}

resource "hyperv_vhd" "vm01_root" {
  path        = "C:/hyperv/vhds/vm01-root.vhdx"
  vhd_type    = "differencing"
  parent_path = hyperv_image_file.ubuntu.destination_path
}

More examples — including the complete hyperv_vm resource with inline NICs, disks, DVDs, boot order, and dynamic memory — live under examples/ and on the Terraform Registry.

Configuration

Every provider attribute has a corresponding HYPERV_* environment variable. Precedence: provider attribute > env var > zero/error. Omitting the provider block entirely makes env vars the sole source — useful for shared modules where each user supplies their own host.

Local backend (provider runs on the Hyper-V host)

provider "hyperv" {
  backend = "local"
}

SSH backend

provider "hyperv" {
  backend  = "ssh"
  host     = "hv01.lab"
  username = "Administrator"
  ssh = {
    private_key_path = "~/.ssh/id_ed25519"
  }
}

The host needs OpenSSH Server enabled with PowerShell as the default shell.

WinRM backend

provider "hyperv" {
  backend  = "winrm"
  host     = "hv01.lab"
  username = "Administrator"
  password = var.hv_password
  winrm = {
    use_https = true
    auth      = "ntlm"
  }
}

WinRM HTTPS with NTLM is the recommended configuration for workgroup hosts; Kerberos is supported in domain environments. The host needs WSMan/WinRM enabled with an HTTPS listener.

Environment variables

A complete .env.example is committed at the repository root.

Documentation

• Registry: registry.terraform.io/providers/windsorcli/hyperv/latest/docs (canonical, generated)
• Repo: docs/ — same content; useful when reading the source on a branch.
• Examples: examples/ — copy-paste-ready HCL for each resource and data source.

Building from source

git clone https://github.com/windsorcli/terraform-provider-hyperv.git
cd terraform-provider-hyperv
task tools          # install pinned dev tools
task                # default: lint + unit tests
task build          # build the provider binary for the current platform
task install        # install to ~/.terraform.d/plugins/ for local Terraform use

To use a locally built provider in a Terraform configuration without publishing, add a dev_overrides block to ~/.terraformrc:

provider_installation {
  dev_overrides {
    "windsorcli/hyperv" = "/Users/<you>/go/bin"
  }
  direct {}
}

task install writes the binary to ~/.terraform.d/plugins/registry.terraform.io/windsorcli/hyperv/0.0.0-dev/<os>_<arch>/; with the override above pointing at $GOPATH/bin, run go install to drop the binary there directly.

Testing

The provider is exercised in three tiers, each runnable independently:

task test:unit      # Go unit tests, no Hyper-V required (fakes the PS runner)
task test:pester    # Pester tests for the embedded .ps1 scripts (PowerShell 7+)
task test:acc       # acceptance tests against a real Hyper-V host

[!CAUTION] task test:acc creates real Hyper-V resources — virtual switches, VMs, disks. Run only against a host you own. Sweepers (task sweep) clean up orphaned resources prefixed with the test name. Tests are gated on TF_ACC=1.

Acceptance test configuration lives in .env.local (gitignored); copy .env.example and fill in HYPERV_* values for the backend you want to exercise.

Debugging

• TF_LOG=DEBUG — standard Terraform log level; surfaces provider-level messages.
• TF_LOG_PROVIDER=DEBUG — provider-only logs; quieter than TF_LOG.
• TF_LOG_PROVIDER=TRACE — full PS stdin/stdout/stderr per call. Sensitive values are masked, but enable only when debugging.

To attach a debugger, build with task build and run the provider with -debug; Terraform will print a TF_REATTACH_PROVIDERS env var to set in the shell that runs terraform plan or terraform apply.

Known limitations

• No image creation. Use Packer or DISM to build golden images and reference them via hyperv_image_file.
• PowerShell startup latency. Each operation pays the cost of a pwsh/powershell.exe invocation, dominated by module load. Terraform's default 10-way parallelism absorbs this for typical fleets; persistent-runspace mode is a stretch-goal for >100-resource deployments.
• Cancel-mid-cmdlet may leave partial state. A New-VM interrupted after disk creation but before VM registration will require either a re-apply or a manual cleanup.
• Differencing parent paths surface errors at apply time, not plan time. New-VHD validates the parent path; the provider maps the cmdlet error to an attribute-level diagnostic.
• WinRM + Kerberos: ccache mode only. Password-mode (auth = "kerberos" with password) is blocked upstream — masterzen/winrm passes client.AssumePreAuthentication(true) to gokrb5, which makes the AS-REQ skip the PA-ETYPE-INFO2 probe and use a default salt that doesn't match what AD has registered for the account. The result is KDC_ERR_PREAUTH_FAILED on what would otherwise be a valid credential. Use ccache mode (kerberos.ccache_path / HYPERV_KRB5_CCACHE_PATH) pointing at a kinit-obtained TGT instead. See docs/contributing/kerberos.md for the diagnostic and upstream-issue tracking.

Contributing

Contributions are welcome. For non-trivial changes — new resources, schema changes, new backends — please open an issue first to align on design before writing code. Bug fixes and documentation improvements can go straight to a PR.

The repository follows strict TDD: PowerShell scripts get Pester tests first to lock the JSON contract, then Go unit tests with a fake runner, then resource schema tests, then acceptance tests, then implementation.

PRs require:

• A release-drafter label (feature, fix, chore, documentation, dependencies, breaking, etc.) — enforced in CI.
• All task lint, task test:unit, task validate:examples, task docs:check, and task docs:validate jobs green.
• Acceptance tests passing on at least one backend (the acc-test label gates the self-hosted runner pool).

License

This provider is distributed under the Mozilla Public License 2.0.