Skip to content

About

HyperV provider for Terraform

Resources

Code of conduct

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

Terraform Provider for Hyper-V

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 脆弱性修正

CI/CD

  • GitHub Actions を最新バージョンに更新
  • govulncheck によるセキュリティスキャン追加
  • goreleaser v2 対応

PowerShell 非依存化(移行中)

このフォークは、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 ✅ 対応

CIM 経路で扱えない入力の 3 通りの挙動

挙動が 3 種類あり、利用者から見た結果が大きく違う。

挙動 気付けるか
A 自動で PowerShell に落ちる 気付かなくてよい(正しく反映される)
B エラーで停止する すぐ気付く
C 黙って捨てられ恒常 diff になる 気付きにくい。apply のたびに VM が停止する

A. 自動で PowerShell に落ちる(何もしなくても動く)

条件 備考
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 はスナップショット時点の状態へ戻せるため委譲する

B. エラーで停止する(HYPERV_USE_WSMAN を外す必要がある)

こちらは 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 内で一意にすること。

C. 黙って捨てられる(恒常 diff になる)

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 経路との既知の差分

項目 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 経路で通した確認は未実施)。

PowerShell 0 件で通る条件

HYPERV_USE_WSMAN=1 を有効にしても PowerShell が不要になるわけではない。

フルライフサイクルが PowerShell 0 件で通ることは実機で確認しているが、 成立する構成は狭く、次をすべて満たす場合に限られる。

  • Gen2 VM で、OS を入れていないこと(入れると firmware read が PowerShell に落ちる)
  • NIC がスイッチに接続されていないこと(go-wsman #114 の既知バグ)
  • wait_for_ips = false
  • high_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/ を参照。

動作環境

  • Terraform >= 1.13.0
  • Go 1.26(ビルドする場合)
  • Hyper-V が有効な Windows ホスト + WinRM 設定済み

検証済み環境: 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 ホストの WinRM 設定

基本設定

# 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}

HTTPS リスナー設定

自己署名証明書を使用する場合:

# ホスト証明書作成
$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 -UseSSL

Provider 設定例

variable "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"
}

使用例

Cloud-Init ISO + Ubuntu VM

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"

  # ...
}

VM Checkpoint(Chaos Engineering 向け)

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

関連リンク

About

HyperV provider for Terraform

Resources

Code of conduct

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages