hyperv-demo/QUICKSTART.md

Hyper-V Automation - Quick Start Guide

This guide walks through setting up a Hyper-V host and provisioning Windows VMs using Ansible.

Prerequisites

• Fresh Windows Server 2019/2022 installation
• Network connectivity from Ansible control node
• Windows Server ISO image

Step 1: Initial Hyper-V Host Setup

1.1 Configure WinRM on Hyper-V Host

On the Windows Server (as Administrator):

# Enable PowerShell remoting
Enable-PSRemoting -Force

# Configure WinRM for Ansible
winrm quickconfig -transport:http
Set-Item WSMan:\localhost\Service\Auth\Basic -Value $true
Set-Item WSMan:\localhost\Service\Auth\NTLM -Value $true

# Allow unencrypted traffic for initial setup (demo only!)
Set-Item WSMan:\localhost\Service\AllowUnencrypted -Value $true

# Configure firewall
Enable-NetFirewallRule -Name "WINRM-HTTP-In-TCP"

1.2 Test Ansible Connectivity

# Activate virtual environment
source ~/.venv/ansible/bin/activate

# Test connection
ansible hyperv -m ansible.windows.win_ping

# If successful, you should see:
# hyperv1.lan.toal.ca | SUCCESS => {
#     "changed": false,
#     "ping": "pong"
# }

Step 2: Provision Hyper-V Host

This playbook configures the Hyper-V host with:

• Hyper-V role and management tools
• Storage directories for VMs and ISOs
• Virtual switches (External-NAT and Internal-Lab)
• NAT networking for VM internet access
• WinRM security hardening
• Demo-appropriate settings

# Run the provisioning playbook
ansible-playbook playbooks/provision-hyperv-host.yml

# This takes 5-10 minutes and may reboot the host

What Gets Created

D:\
├── VMs\              # VM storage
├── ISOs\             # ISO images
└── Templates\        # VHD templates (future)

Virtual Switches:
├── External-NAT      # For internet access via NAT
└── Internal-Lab      # Isolated internal network

NAT Network: 192.168.100.0/24
Gateway: 192.168.100.1

Step 3: Upload Windows ISO

Option 1: Manual Upload

# On Hyper-V host or via RDP
# Copy ISO to D:\ISOs\Windows_Server_2022.iso

Option 2: Ansible Copy (slower)

# From Ansible control node
ansible hyperv -m ansible.windows.win_copy \
  -a "src=/path/to/Windows_Server_2022.iso dest=D:\\ISOs\\Windows_Server_2022.iso"

Option 3: Direct Download (if internet available)

ansible hyperv -m ansible.windows.win_get_url \
  -a "url=https://your-iso-source/Windows_Server_2022.iso dest=D:\\ISOs\\Windows_Server_2022.iso"

Step 4: Verify Configuration

4.1 List Available Virtual Switches

ansible-playbook playbooks/list-hyperv-switches.yml

Expected output:

Available Virtual Switches:
- External-NAT
- Internal-Lab

4.2 Verify ISO Path

ansible hyperv -m ansible.windows.win_stat \
  -a "path=D:\\ISOs\\Windows_Server_2022.iso"

Step 5: Provision Your First VM

5.1 Basic VM Provisioning

ansible-playbook playbooks/provision-vm.yml \
  -e vm_name=WEB01 \
  -e vm_ip_address=192.168.100.10

5.2 Custom VM Configuration

ansible-playbook playbooks/provision-vm.yml \
  -e vm_name=APP01 \
  -e vm_ip_address=192.168.100.20 \
  -e vm_cpu_count=4 \
  -e vm_memory_gb=8 \
  -e vm_disk_size_gb=100

5.3 What Happens

1. ✓ Creates VM with specified resources
2. ✓ Generates autounattend.xml for unattended installation
3. ✓ Attaches Windows Server ISO
4. ✓ Starts VM
5. ⏸ Waits for you to verify installation (15-30 min)
6. ✓ Verifies WinRM connectivity

Step 6: Monitor Installation

Via Hyper-V Manager

# On Hyper-V host
vmconnect.exe localhost WEB01

Via PowerShell

ansible hyperv -m ansible.windows.win_shell \
  -a "Get-VM WEB01 | Select-Object Name, State, CPUUsage, Uptime"

Installation Progress

• 0-5 min: Windows Setup boots from ISO
• 5-20 min: Windows installation (with autounattend.xml)
• 20-25 min: First boot and configuration
• 25-30 min: WinRM configuration completes

Step 7: Add VM to Inventory

Once installation completes:

# Edit inventory
vi /home/ptoal/Dev/inventories/toallab-inventory/static.yml

# Add under web_servers:
    web_servers:
      hosts:
        WEB01:
          ansible_host: 192.168.100.10

Step 8: Verify VM Connectivity

# Test WinRM
ansible WEB01 -m ansible.windows.win_ping

# Gather facts
ansible WEB01 -m ansible.windows.setup

Step 9: Deploy Applications

Install IIS

ansible-playbook playbooks/install-iis.yml --limit WEB01

Apply Windows Updates

ansible-playbook playbooks/patch-vms.yml --limit WEB01

Common Tasks

List All VMs

ansible hyperv -m ansible.windows.win_shell \
  -a "Get-VM | Select-Object Name, State, CPUUsage | Format-Table"

Start/Stop VM

# Start
ansible hyperv -m ansible.windows.win_shell -a "Start-VM -Name WEB01"

# Stop
ansible hyperv -m ansible.windows.win_shell -a "Stop-VM -Name WEB01"

# Shutdown gracefully
ansible hyperv -m ansible.windows.win_shell -a "Stop-VM -Name WEB01 -Force"

Delete VM

ansible hyperv -m ansible.windows.win_shell -a "Remove-VM -Name WEB01 -Force"

Check VM State

ansible hyperv -m ansible.windows.win_shell \
  -a "Get-VM WEB01 | ConvertTo-Json"

Troubleshooting

WinRM Connection Failed

Problem: unreachable or connection timeout

Solutions:

1. Verify firewall allows WinRM:

   Get-NetFirewallRule -Name "WINRM-HTTP-In-TCP" | Select-Object Name, Enabled
   

2. Check WinRM service:

   Get-Service WinRM
   winrm enumerate winrm/config/listener
   

3. Test from Ansible host:

   ansible hyperv -m ansible.windows.win_ping -vvv
   

Virtual Switch Not Found

Problem: Hyper-V was unable to find a virtual switch

Solutions:

1. List available switches:

   ansible-playbook playbooks/list-hyperv-switches.yml
   

2. Update group_vars or pass correct switch:

   -e vm_switch="External-NAT"
   

3. Create missing switch on Hyper-V host:

   New-VMSwitch -Name "External-NAT" -SwitchType External -NetAdapterName "Ethernet"
   

AutoUnattend Not Working

Problem: Windows installation shows interactive prompts

Solutions:

1. Verify autounattend.xml was created:

   ansible hyperv -m ansible.windows.win_stat \
     -a "path=D:\\VMs\\WEB01\\autounattend.xml"
   

2. Check XML syntax in file

3. Mount as second DVD drive (requires manual step or helper playbook)

4. Review Windows Setup logs on VM:

   C:\Windows\Panther\setupact.log
   

VM Won't Start

Problem: failed to start or invalid configuration

Solutions:

1. Check VM configuration:

   ansible hyperv -m ansible.windows.win_shell \
     -a "Get-VM WEB01 | Select-Object *"
   

2. Verify VHD exists:

   ansible hyperv -m ansible.windows.win_stat \
     -a "path=D:\\VMs\\WEB01\\WEB01.vhdx"
   

3. Check Hyper-V event logs:

   Get-EventLog -LogName "Microsoft-Windows-Hyper-V-*" -Newest 20
   

Directory Structure

/home/ptoal/Dev/Projects/HyperV/
├── playbooks/
│   ├── provision-hyperv-host.yml    # Configure Hyper-V host
│   ├── provision-vm.yml             # Create VMs
│   ├── list-hyperv-switches.yml     # List available switches
│   ├── install-iis.yml              # Deploy IIS
│   └── patch-vms.yml                # Windows Updates
├── templates/
│   └── autounattend.xml.j2          # Unattended install template
└── ansible.cfg                      # Project config

/home/ptoal/Dev/inventories/toallab-inventory/
├── static.yml                       # Static inventory
├── group_vars/
│   ├── hyperv/vars.yml              # Hyper-V defaults
│   └── windows_servers/vars.yml     # Windows defaults
└── host_vars/
    └── hyperv1.lan.toal.ca/vars.yml # Host-specific config

Next Steps

1. Create VM templates - Sysprep a base VM and convert to template
2. Implement backups - Use Hyper-V checkpoints or backup playbooks
3. Configure monitoring - Integrate with Grafana/Prometheus
4. Domain join - Add VMs to Active Directory
5. Application deployment - Deploy real applications beyond IIS demo
6. CMDB sync - Implement ServiceNow integration
7. Event-Driven Ansible - React to Hyper-V events automatically

Production Considerations

⚠️ This is a demo configuration. For production:

• Enable HTTPS for WinRM (not HTTP)
• Use Kerberos authentication (not NTLM/Basic)
• Configure storage on SAN/redundant storage
• Implement Hyper-V clustering for HA
• Network segmentation and VLANs
• Security hardening (CIS benchmarks)
• Backup and disaster recovery
• Monitoring and alerting
• Change management and approvals
• Documentation and runbooks

Resources

• Hyper-V Documentation
• Ansible Windows Guide
• WinRM Setup
• Project CLAUDE.md - Architecture documentation
• Provisioning Guide - Detailed VM provisioning