Ansible on Hyper-V on Windows Server 2025 Automation Complete Guide

Hyper-V on Windows Server 2025 is Microsoft's flagship Type-1 hypervisor, with deep integration into Active Directory, Failover Clustering, and Storage Spaces Direct (S2D). Ansible automates Hyper-V hosts via WinRM/SSH using ansible.windows and community.windows, plus PowerShell Hyper-V module cmdlets through ansible.windows.win_powershell. This is the master Ansible guide for Hyper-V on WS2025.

Hyper-V WS2025 release facts

| Item | Value | |---|---| | Host OS | Windows Server 2025 | | Hypervisor | Hyper-V (Hyper-V role) | | Mainstream Support | until 2029-10-09 | | Extended Support | until 2034-10-10 | | New | GPU partitioning improvements, Azure Arc-enabled by default, S2D enhancements |

See also: Ansible Windows Server 2025 Automation: WinRM, PSRP, Active Directory, IIS, Hyper-V Complete Guide

Ansible-core compatibility

Use ansible-core 2.18 LTS with ansible.windows >= 3.0, community.windows >= 3.0. WinRM 5985/5986 or SSH for Windows.

Inventory

[hyperv_hosts]
hv01 ansible_host=10.0.0.21
hv02 ansible_host=10.0.0.22
[hyperv_hosts:vars]
ansible_connection=ansible.windows.winrm
ansible_user=DOMAIN\\svc_ansible
ansible_password='{{ vault_winrm_password }}'
ansible_winrm_transport=kerberos
ansible_winrm_server_cert_validation=ignore

See also: Ansible on Windows Server 2022 Automation: WinRM, Active Directory, IIS, Hyper-V Complete Guide

Install Hyper-V role

- name: Install Hyper-V role
  hosts: hyperv_hosts
  gather_facts: false
  tasks:
    - name: Hyper-V + tools + cluster
      ansible.windows.win_feature:
        name:
          - Hyper-V
          - Hyper-V-PowerShell
          - Failover-Clustering
          - RSAT-Clustering-PowerShell
        state: present
        include_management_tools: true
      register: hv
- name: Reboot if required
      ansible.windows.win_reboot:
      when: hv.reboot_required

Create a virtual switch

- name: Configure external vSwitch
  hosts: hyperv_hosts
  gather_facts: false
  tasks:
    - name: External vSwitch on team
      ansible.windows.win_powershell:
        script: |
          if (-not (Get-VMSwitch -Name 'External' -ErrorAction SilentlyContinue)) {
            New-VMSwitch -Name 'External' -NetAdapterName 'TEAM0' -AllowManagementOS $true
            $Ansible.Changed = $true
          } else { $Ansible.Changed = $false }

See also: microsoft.hyperv 1.0.0 — First Certified Ansible Collection for Hyper-V

Create a VM

- name: Create Gen2 VM
  hosts: hv01
  gather_facts: false
  tasks:
    - name: Create VM
      ansible.windows.win_powershell:
        parameters:
          Name: app-01
          Memory: 8GB
          VHDPath: C:\VMs\app-01\app-01.vhdx
          SwitchName: External
        script: |
          param($Name,$Memory,$VHDPath,$SwitchName)
          if (-not (Get-VM -Name $Name -ErrorAction SilentlyContinue)) {
            New-VHD -Path $VHDPath -SizeBytes 80GB -Dynamic | Out-Null
            New-VM -Name $Name -Generation 2 -MemoryStartupBytes $Memory -VHDPath $VHDPath -SwitchName $SwitchName | Out-Null
            Set-VM -Name $Name -ProcessorCount 4 -DynamicMemory
            $Ansible.Changed = $true
          } else { $Ansible.Changed = $false }

Checkpoints

- name: Create checkpoint before patching
  hosts: hv01
  gather_facts: false
  tasks:
    - name: Checkpoint
      ansible.windows.win_powershell:
        script: |
          Checkpoint-VM -Name 'app-01' -SnapshotName "pre-patch-$(Get-Date -Format yyyyMMddHHmm)"
          $Ansible.Changed = $true

Failover cluster bootstrap

- name: Create Hyper-V failover cluster
  hosts: hv01
  gather_facts: false
  tasks:
    - name: Test then create cluster
      ansible.windows.win_powershell:
        script: |
          Test-Cluster -Node hv01,hv02 -Include "Storage Spaces Direct","Inventory","Network","System Configuration" | Out-Null
          if (-not (Get-Cluster -Name HVCL01 -ErrorAction SilentlyContinue)) {
            New-Cluster -Name HVCL01 -Node hv01,hv02 -StaticAddress 10.0.0.30 -NoStorage
            $Ansible.Changed = $true
          } else { $Ansible.Changed = $false }

Best practices

• Drive all PowerShell snippets through ansible.windows.win_powershell with explicit $Ansible.Changed for idempotency. • Use Group Managed Service Accounts (gMSA) for the Ansible Hyper-V service account. • Enable Credential Guard + Virtualization-based Security (VBS) on hosts; test playbook compatibility. • Combine Hyper-V + Failover Clustering for HA; use Live Migration for patching workflows.

Conclusion

Hyper-V on Windows Server 2025 + Ansible delivers a fully scriptable Microsoft hypervisor stack. Use ansible.windows, PowerShell-via-Ansible, and gMSA service accounts to automate VM lifecycle, virtual switches, checkpoints, and clusters declaratively.