taliesins/terraform-provider-hyperv のフォークです。 WinRM 経由で Hyper-V の VM・ネットワーク・ストレージを Terraform で管理します。
| リソース | 概要 |
|---|---|
hyperv_cloudinit_iso |
Cloud-Init NoCloud 互換 ISO をホスト上で直接生成 |
hyperv_vm_checkpoint |
VM チェックポイントの作成・復元・削除(restore_on_destroy 対応) |
| リソース | 追加属性 | 概要 |
|---|---|---|
hyperv_machine_instance |
automatic_checkpoints_enabled |
自動チェックポイントの有効/無効 |
hyperv_machine_instance |
gpu_adapters ブロック |
GPU-P (GPU Partitioning) サポート |
- Gen 2 VM: IDE コントローラ使用時の plan 段階バリデーション追加
- Gen 2 VM: DVD/HDD BootOrder 判定を .NET 型チェックに変更(日本語ロケール対応)
- VM Notes: Base64 エンコードで Unicode 文字列を安全に WinRM 転送
- HardDisk/DVD ドライブの Update/Delete をインデックスベースに統一
- MAC アドレス
00-00-00-00-00-00生成防止(dynamic_mac_address=true時) - Go 1.26 対応、golang.org/x/net HTTP/2 脆弱性修正
- GitHub Actions を最新バージョンに更新
- govulncheck によるセキュリティスキャン追加
- goreleaser v2 対応
このフォークは、PowerShell 経由での Hyper-V 操作を go-wsman(Go ネイティブの WS-Man/CIM クライアント)へ 段階的に置き換えている。移行中のため既定は従来どおり PowerShell 経路で、 切り替えは環境変数で行う。
| 環境変数 | 有効時の挙動 | 既定 |
|---|---|---|
HYPERV_USE_WSMAN=1 |
CIM 経路に切り替える。未移行の操作は PowerShell へ自動的に落ちる | 無効 |
HYPERV_WSMAN_STRICT=1 |
PowerShell へのフォールバックをエラーにする(PS 不使用の検証用) | 無効 |
HYPERV_WSMAN_STRICT は HYPERV_USE_WSMAN が有効なときだけ意味を持つ。
| リソース | CIM 経路 |
|---|---|
hyperv_vhd |
✅ 対応(source / source_vm 指定時と削除は PowerShell) |
hyperv_machine_instance |
|
hyperv_network_switch |
❌ PowerShell のみ |
hyperv_iso_image |
❌ PowerShell のみ |
hyperv_cloudinit_iso |
❌ PowerShell のみ |
hyperv_vm_checkpoint |
✅ 対応 |
挙動が 3 種類あり、利用者から見た結果が大きく違う。
| 挙動 | 気付けるか | |
|---|---|---|
| A | 自動で PowerShell に落ちる | 気付かなくてよい(正しく反映される) |
| B | エラーで停止する | すぐ気付く |
| C | 黙って捨てられ恒常 diff になる | 気付きにくい。apply のたびに VM が停止する |
| 条件 | 備考 |
|---|---|
| OS インストール済み Gen2 VM の firmware read | 最も頻繁に踏む。Windows Boot Manager の boot entry を CIM 側が解釈できないため。plan / refresh のたびに発生する |
wait_for_ips = true |
|
| 非ゼロ → 0 / false へのダウングレード | CIM はゼロ値を送れず黙殺されるため、意図的に委譲する。VM レベル設定 / vm_processor / vm_firmware の 3 箇所にガードがある |
secure_boot_template が未知の GUID / 名前 |
既知の対応表に無いもの |
gpu_adapters が非空 |
割り当ての CIM 実装が未着手 |
automatic_checkpoints_enabled を true → false |
false は CIM で送れないため(checkpoint_type は CIM で変更できる) |
hyperv_vhd の source / source_vm 指定 |
ファイルコピー / VM ディスクキャプチャは CIM の範囲外 |
hyperv_vhd の削除(terraform destroy) |
ファイル削除は CIM の範囲外。移行状況表では ✅ だが削除だけは PowerShell が走る |
| 稼働中 VM のチェックポイント復元 | CIM の ApplySnapshot は種別に関係なく稼働中 VM を受け付けない(ReturnValue=32775)。PowerShell はスナップショット時点の状態へ戻せるため委譲する |
こちらは apply が失敗する。 黙って PowerShell に落ちることはしない (気付かないまま設定が反映されない事故を避けるため)。
⚠️ ただし C の経路はこの原則から漏れている。「気付かないまま設定が反映されない」 事故が別の形で起きているので、下記 C も併せて確認すること。
| 条件 | 備考 |
|---|---|
| NIC の高度なオプション | QoS / IOV / MAC spoofing / 各種 guard / VLAN / 帯域 / チーミング / PacketDirect |
| ハードディスクの高度なオプション | QoS / パススルー / カスタムプール / キャッシュ属性 / 永続予約 |
| 同名のチェックポイントが複数存在する | Hyper-V の既定名は秒精度のため同一秒に作ると重複しうる。誤ったチェックポイントを削除/復元しないよう名前で一意に特定できない場合は停止する |
| 同一 VM のチェックポイントを別プロセスから並列作成する | 作成したものを一覧の差分で特定するため、同時作成があると特定できない。同一プロセス内は直列化する |
⚠️ 同一 VM 内で NIC 名を重複させた構成は CIM 経路では非対応。 CIM には NIC の 作成順を表す決定的なキーが無く、read 結果を config の並びへ寄せる際に名前で突き合わせる ため、同名 NIC は位置が入れ替わりうる。switch や MAC が異なる同名 NIC を作ると 恒常 diff になる。NIC 名は VM 内で一意にすること。
A でも B でもない第 3 の挙動が残っている。 CIM に値が送られないまま成功が返り、
read は実値を返すため差分が消えない。これらのフィールドは
hasChangesThatRequireVmToBeOff に含まれるので、apply のたびに VM が停止して
何も変わらないループになる。
| 条件 | 追跡 |
|---|---|
automatic_start_delay を指定する |
#133。read も常に 0 のため一度もエラーにならない |
automatic_critical_error_action_timeout を既定 (30) 以外にする |
#133 / go-wsman #119。read は実値を返すため恒常 diff になる |
static_memory = true で 新規作成 する |
#143。動的メモリの VM ができる。次の apply で PowerShell へ委譲されて修正される |
根本原因は go-wsman がゼロ値を明示的に送れないこと (go-wsman #135)。 update 経路は上記 A 表のガードで委譲するが、create 経路にはガードが無い。
| 項目 | PowerShell | CIM |
|---|---|---|
hyperv_vm_checkpoint の creation_time |
ローカル時刻 + オフセット(2026-09-10T01:20:31.4447620+09:00) |
UTC(2026-09-09T16:20:31.444762Z) |
| 稼働中 VM の復元後の状態 | スナップショット時点の状態(Standard なら Running のまま) | 同左(PowerShell へ委譲するため) |
integration_services の state のキー |
Get-VMIntegrationService の Name をそのまま使うためホスト OS 言語にローカライズされる |
常に英語の 6 種(#98) |
| NIC の同一性 | Rename-VMNetworkAdapter / Connect-VMNetworkAdapter で in-place 更新するため MAC は変わらない |
(名前, スイッチ, MAC)が変わると NIC を作り直す(#153) |
動的 MAC の NIC の static_mac_address |
現在の MAC が state に入る | 空のまま(CIM の read は静的 MAC のときしか値を返さない) |
同じ瞬間を指すが文字列表現が異なる。creation_time は Computed なので plan の差分にはならないが、
PowerShell 時代の state を HYPERV_USE_WSMAN=1 で refresh すると state 上の値が書き換わる。
output で参照している場合は表示が変わる。
VLAN を使う構成などはここに該当する。 HYPERV_USE_WSMAN=1 のままでは apply が通らない。
integration_services のキーは、非英語ホストで PS 経路と CIM 経路の state が食い違う。
CIM 経路の書き込みは英語名しか受理しない(hyperv.IntegrationServiceComponent の固定 6 種)。
一方 PS の Enable-VMIntegrationService -Name はローカライズ名で照合すると思われる
(この挙動は本リポジトリの実機では未確認)。
日本語ホストで PS 経路を使い、config のキーも日本語で書いていた場合、
HYPERV_USE_WSMAN=1 に切り替えると config のキーを英語に書き換える必要がある
(state は refresh で英語に入れ替わるが、config 側は入れ替わらない)。
NIC を作り直す件は、MAC で識別している構成(Talos の machine.network.interfaces の MAC マッチ、
DHCP 予約、MAC に紐づくライセンスやクラスタ membership)を壊す。CIM 経路は NIC を
(名前, スイッチ, MAC)で同一視し、キーが変わる NIC を detach + attach で置き換えるため、
dynamic_mac_address = true の NIC には新しい MAC が割り当てられる。
作り直しの引き金になるのは name / switch_name の変更のほか、
dynamic_mac_address の切り替えと(dynamic_mac_address = false のときの)static_mac_address の変更。
VLAN や帯域(vlan_access / vlan_id / maximum_bandwidth 等)は CIM 経路が未対応で
そもそも apply が通らない(上の A 表の側の話になる)。
⚠️ 新しい MAC が割り当てられること自体は実機で未確認(コードが detach + attach で あることと、MAC を送るのが静的指定時だけであることまでを確認した段階)。
回避策: dynamic_mac_address = false と static_mac_address を両方書く。
network_adaptors {
name = "eth0"
switch_name = hyperv_network_switch.example.name
dynamic_mac_address = false # これが無いと plan でエラーになる
static_mac_address = "00155d000101"
}dynamic_mac_address の既定は true なので、static_mac_address だけを書くと
どちらの経路でも恒常 diff になる(#160)。
壊れ方が違うだけで、PS 経路に戻しても直りません。
| 経路 | 静的 MAC | read が返すもの | 恒常 diff が出る場所 |
|---|---|---|---|
| CIM | 黙って捨てられる | static_mac_address = 空 |
static_mac_address |
| PS | 適用される | dynamic_mac_address = false |
dynamic_mac_address |
そのため この組み合わせは経路を問わず terraform plan でエラーになります。
dynamic_mac_address = false を併記してください。
2026-09-27 実機確認:
Set-VMNetworkAdapter -StaticMacAddress実行後にDynamicMacAddressEnabledがTrue→Falseへ変わることを cmdlet 直叩きで確認した (provider を PS 経路で通した確認は未実施)。
HYPERV_USE_WSMAN=1 を有効にしても PowerShell が不要になるわけではない。
フルライフサイクルが PowerShell 0 件で通ることは実機で確認しているが、 成立する構成は狭く、次をすべて満たす場合に限られる。
- Gen2 VM で、OS を入れていないこと(入れると firmware read が PowerShell に落ちる)
- NIC がスイッチに接続されていないこと(go-wsman #114 の既知バグ)
wait_for_ips = falsehigh_memory_mapped_io_space/low_memory_mapped_io_spaceが非ゼロであること (0は「ゼロ値への変更要求」ではなく無効値。schema 既定の 512MB / 128MB なら問題ない)- プロセッサとファームウェアが既定値のまま
以前ここに並んでいた次の制約は解消した(go-wsman のポインタフィールド #135 / #149 と datetime タグ #119 による)。
| 以前の制約 | 現在 |
|---|---|
automatic_checkpoints_enabled はホスト既定と一致が必要 |
✅ false を明示的に送れる |
static_memory = false (動的メモリ) のみ |
✅ static_memory = true で作れる |
automatic_critical_error_action_timeout は 30 分固定 |
✅ 任意の値を書ける |
automatic_start_delay は 0 固定 |
✅ 任意の値を書ける |
実機の strict テストは static_memory = true / automatic_checkpoints_enabled = false /
timeout = 45 / delay = 90(いずれもホスト既定と異なる)で PowerShell 0 件を確認している。
残る「非ゼロ→0」「true→false」の要求のうち CIM のペイロードに乗らないものは、 create の時点で PowerShell に委譲して正しい VM を作る(黙って別物を作らない)。
移行の方式と判断の経緯は docs/adr/ を参照。
検証済み環境: Windows 11 Pro (Hyper-V)
upstream では Windows 10 / Windows Server 2016 以降に対応とされていますが、本フォークでは Windows 11 でのみ検証しています。
本フォークは Terraform Registry に公開していないため、ローカルビルドで使用します。
# ビルド
go build -o dist/ .
# ~/.terraformrc に dev_overrides を設定
cat <<'EOF' > ~/.terraformrc
provider_installation {
dev_overrides {
"taliesins/hyperv" = "/path/to/terraform-provider-hyperv/dist"
}
direct {}
}
EOF# Hyper-V 有効化
Enable-WindowsOptionalFeature -Online -FeatureName:Microsoft-Hyper-V -All
# WinRM 有効化
Enable-PSRemoting -SkipNetworkProfileCheck -Force
Set-WSManInstance WinRM/Config/WinRS -ValueSet @{MaxMemoryPerShellMB = 1024}
Set-WSManInstance WinRM/Config -ValueSet @{MaxTimeoutms = 1800000}
Set-WSManInstance WinRM/Config/Client -ValueSet @{TrustedHosts = "*"}
Set-WSManInstance WinRM/Config/Service/Auth -ValueSet @{Negotiate = $true}自己署名証明書を使用する場合:
# ホスト証明書作成
$hostName = [System.Net.Dns]::GetHostName()
$dnsNames = @($hostName, "localhost", "127.0.0.1") + [System.Net.Dns]::GetHostByName($env:computerName).AddressList.IpAddressToString
$cert = New-SelfSignedCertificate -DnsName $dnsNames -CertStoreLocation Cert:\LocalMachine\My
# HTTPS リスナー作成
Get-ChildItem wsman:\localhost\Listener\ | Where-Object -Property Keys -eq 'Transport=HTTPS' | Remove-Item -Recurse
New-Item -Path WSMan:\localhost\Listener -Transport HTTPS -Address * -CertificateThumbPrint $cert.Thumbprint -Force
Restart-Service WinRM
# ファイアウォールルール
New-NetFirewallRule -DisplayName "WinRM HTTPS" -Name "WinRMHTTPSIn" -Profile Any -LocalPort 5986 -Protocol TCP$cred = Get-Credential
$soptions = New-PSSessionOption -SkipCACheck -SkipCNCheck
Enter-PSSession -ComputerName $hostName -Port 5986 -Credential $cred -SessionOption $soptions -UseSSLvariable "hyperv_user" {
type = string
}
variable "hyperv_password" {
type = string
sensitive = true
}
variable "hyperv_host" {
type = string
}
provider "hyperv" {
user = var.hyperv_user
password = var.hyperv_password
host = var.hyperv_host
port = 5986
https = true
insecure = true
use_ntlm = true
timeout = "300s"
}resource "hyperv_cloudinit_iso" "ubuntu" {
destination_iso_file_path = "D:\\Hyper-V\\cloud-init\\ubuntu-01.iso"
user_data = <<-EOF
#cloud-config
hostname: ubuntu-01
users:
- name: admin
sudo: ALL=(ALL) NOPASSWD:ALL
ssh_authorized_keys:
- ${var.ssh_public_key}
EOF
meta_data = <<-EOF
instance-id: ubuntu-01
local-hostname: ubuntu-01
EOF
}
resource "hyperv_machine_instance" "ubuntu" {
name = "ubuntu-01"
generation = 2
processor_count = 2
static_memory = true
memory_startup_bytes = 4294967296 # 4GB
automatic_checkpoints_enabled = false
checkpoint_type = "Disabled"
# ...
}resource "hyperv_vm_checkpoint" "pre_chaos" {
vm_name = "worker-01"
checkpoint_name = "pre-chaos-experiment"
restore_on_destroy = true
}# Terraform ログ
export TF_LOG=DEBUG
# WinRM デバッグ
export WINRMCP_DEBUG=1