ptoal/hyperv-demo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
hyperv-demo/HANDOFF.md
Patrick Toal a096a7eaa0 Handoff
2026-04-29 09:52:02 -04:00

15 KiB
Raw Permalink Blame History

Hyper-V Automation Project - Handoff Document

Date: 2026-04-29
Status: Development - Core provisioning implemented
Next Session: Ready for Hyper-V host setup and VM testing

Project Overview

Enterprise-grade automation for Windows Server VM lifecycle management on Hyper-V using Ansible Automation Platform. Demonstrates GitOps and Infrastructure as Code principles for demo/lab environments.

Primary Use Case: Automated VM provisioning with unattended Windows installation

Target Environment: Demo/Lab (not production-hardened)

Current State

✅ Completed

  1. Project Structure

    • Integrated with toallab standard inventory (/home/ptoal/Dev/inventories/toallab-inventory)
    • Group variables organized (hyperv, windows_servers, web_servers)
    • Host variables configured for hyperv1.lan.toal.ca (192.168.1.182)
    • Collections requirements defined

  2. Hyper-V Host Provisioning ⭐ NEW

    • Playbook: playbooks/provision-hyperv-host.yml
    • Installs Hyper-V role and management tools
    • Creates storage structure (D:\VMs, D:\ISOs, D:\Templates)
    • Configures virtual switches (External-NAT, Internal-Lab)
    • Sets up NAT networking (192.168.100.0/24)
    • Hardens WinRM with HTTPS listener
    • Demo-optimized settings (power, firewall, etc.)

  3. VM Provisioning Workflow

    • Playbook: playbooks/provision-vm.yml
    • Creates VMs with configurable resources (CPU, RAM, disk)
    • Generates autounattend.xml for unattended Windows installation
    • Validates virtual switch availability
    • Supports tags for selective execution (create/install/verify)
    • Idempotent operations
    • AAP-ready with survey support

  4. Templates

    • templates/autounattend.xml.j2 - Complete Windows unattended install
    • Configures: network, WinRM, RDP, computer name, timezone, admin password
    • Static IP or DHCP support
    • First-logon commands for Ansible readiness

  5. Helper Playbooks

    • playbooks/list-hyperv-switches.yml - Discover available switches
    • playbooks/create-autounattend-iso.yml - Helper for ISO creation
    • playbooks/install-iis.yml - IIS deployment demo (existing)
    • playbooks/patch-vms.yml - Windows Update automation (existing)

  6. Documentation

    • QUICKSTART.md - Complete step-by-step guide from scratch
    • playbooks/README-provision.md - Detailed VM provisioning guide
    • CLAUDE.md - Architecture and development guidelines
    • README.md - Project overview

⚠️ Known Issues / Limitations

  1. Virtual Switch Discovery

    • Fixed: Playbook now validates switches before VM creation
    • Default switch changed from "Internal Switch" → "External-NAT"
    • Run list-hyperv-switches.yml to see available switches

  2. AutoUnattend.xml Delivery

    • Currently requires manual intervention or helper playbook
    • Windows Setup needs to find autounattend.xml (second DVD drive, floppy, or custom ISO)
    • Helper playbook provided but requires Windows ADK on host

  3. Circular Variable References

    • Fixed: Moved variable defaults from vars: to set_fact in pre_tasks
    • Variables now compute correctly with extra vars or group_vars fallbacks

  4. WinRM Configuration

    • Currently using NTLM over HTTP (port 5985) for hyperv1.lan.toal.ca
    • Demo-appropriate but not production-ready
    • Host provisioning playbook sets up HTTPS for new hosts

🔄 In Progress

  • Testing: Hyper-V host provisioning playbook not yet tested on actual host
  • VM Provisioning: Ready to test once host is configured
  • AutoUnattend ISO: Helper playbook exists but untested

❌ Not Yet Implemented

  1. Windows Baseline Configuration (future role)

    • Security hardening
    • Monitoring agent installation
    • Compliance scanning

  2. ServiceNow CMDB Integration

    • Playbook exists (sync-cmdb.yml) but needs implementation
    • Requires ServiceNow credentials and table configuration

  3. Custom Execution Environment

    • Currently using aap.toal.ca/ee-demo
    • Could build project-specific EE with all dependencies

  4. Event-Driven Ansible

    • Phase 3 enhancement
    • React to Hyper-V events, ServiceNow incidents, etc.

  5. VM Templates

    • Sysprep and convert base VM to reusable template
    • Faster provisioning than full install

Inventory Configuration

Hypervisor

Host: hyperv1.lan.toal.ca
IP: 192.168.1.182
Connection: WinRM over HTTP (NTLM auth, port 5985)
Group: hyperv

Inventory Location: /home/ptoal/Dev/inventories/toallab-inventory/static.yml

hyperv:
  hosts:
    hyperv1.lan.toal.ca:
      ansible_host: 192.168.1.182

Group Variables

Location: /home/ptoal/Dev/inventories/toallab-inventory/group_vars/

hyperv/vars.yml:

default_vm_cpu_count: 2
default_vm_memory_gb: 4
default_vm_disk_size_gb: 60
default_vm_switch: "External-NAT"  # Changed from "Internal Switch"
vm_storage_path: "D:\\VMs"
iso_storage_path: "D:\\ISOs"
windows_server_iso: "D:\\ISOs\\Windows_Server_2022.iso"

windows_servers/vars.yml:

  • Windows Update categories
  • DNS servers
  • Timezone settings
  • Features to remove

web_servers/vars.yml:

  • IIS features list
  • Application pool settings
  • Website configuration

Host Variables

hyperv1.lan.toal.ca/vars.yml:

ansible_connection: winrm
ansible_winrm_transport: ntlm
ansible_winrm_server_cert_validation: ignore
ansible_port: 5985

Next Steps

Immediate (Next Session)

  1. Configure Hyper-V Host (if fresh install)

    source ~/.venv/ansible/bin/activate
cd /home/ptoal/Dev/Projects/HyperV

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

# Configure host
ansible-playbook playbooks/provision-hyperv-host.yml

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

  2. Upload Windows Server ISO

    • Copy ISO to D:\ISOs\Windows_Server_2022.iso on Hyper-V host
    • Or download directly on host
    • Verify path matches windows_server_iso in group_vars

  3. Test VM Provisioning

    # Provision first test VM
ansible-playbook playbooks/provision-vm.yml \
  -e vm_name=TEST01 \
  -e vm_ip_address=192.168.100.10

# Monitor installation via Hyper-V console
# Wait for WinRM to become available (~20-30 min)

# Test connectivity
ansible TEST01 -i "192.168.100.10," -m ansible.windows.win_ping

  4. Add VM to Inventory

    vi /home/ptoal/Dev/inventories/toallab-inventory/static.yml
# Add under web_servers or appropriate group

  5. Test Application Deployment

    # Deploy IIS
ansible-playbook playbooks/install-iis.yml --limit TEST01

# Verify
curl http://192.168.100.10

Short Term (Next Few Sessions)

  1. Resolve AutoUnattend Delivery

    • Test create-autounattend-iso.yml helper
    • OR: Create custom Windows ISO with embedded autounattend.xml
    • OR: Document manual second-DVD-drive approach
    • Update provisioning playbook with working method

  2. Create Windows Baseline Role

    roles/windows_baseline/
├── tasks/
│   ├── main.yml
│   ├── security.yml
│   ├── monitoring.yml
│   └── compliance.yml
├── templates/
└── defaults/
    • Security hardening (CIS benchmarks subset)
    • Time sync with domain/NTP
    • Windows Update configuration
    • Logging and auditing
    • Monitoring agent (if available)

  3. Implement ServiceNow CMDB Sync

    • Test ServiceNow API connectivity
    • Implement sync-cmdb.yml playbook
    • Create/update CI records
    • Sync on VM create/update/delete

  4. Test Workflow in AAP

    • Create job templates with surveys
    • Test webhook integration
    • Create workflow template (provision → baseline → deploy → CMDB)

Medium Term

  1. VM Template Creation

    • Build golden image VM
    • Sysprep and generalize
    • Convert to template/library
    • Create playbook to clone from template (faster than full install)

  2. Backup and Recovery

    • Hyper-V checkpoint management playbook
    • Export/import VM playbooks
    • Backup scheduling

  3. Network Configuration

    • VLAN tagging playbooks
    • Multiple NIC configuration
    • DNS/DHCP integration

  4. Application Deployment

    • Expand beyond IIS demo
    • SQL Server installation role
    • Custom application deployment patterns

Long Term (Future Phases)

  1. Event-Driven Ansible

    • ServiceNow incident → remediation playbook
    • Hyper-V event monitoring → capacity management
    • Windows Event Log → security response

  2. Multi-Host Hyper-V

    • Cluster configuration
    • Live migration support
    • Shared storage

  3. Advanced Features

    • Nested virtualization
    • Container deployment on Windows VMs
    • Azure Arc integration

Key Files Reference

Playbooks

playbooks/
├── provision-hyperv-host.yml      # Configure Hyper-V host (one-time)
├── provision-vm.yml               # Create Windows VMs
├── list-hyperv-switches.yml       # Discover switches
├── create-autounattend-iso.yml    # AutoUnattend helper
├── install-iis.yml                # IIS deployment
├── patch-vms.yml                  # Windows Updates
└── sync-cmdb.yml                  # ServiceNow (stub)

Configuration

ansible.cfg                        # Points to toallab-inventory
collections/requirements.yml       # Required collections
templates/autounattend.xml.j2      # Windows unattended install

Documentation

README.md                          # Project overview
QUICKSTART.md                      # Step-by-step guide
HANDOFF.md                         # This file
CLAUDE.md                          # Architecture details
playbooks/README-provision.md      # Provisioning deep-dive

Inventory (External)

/home/ptoal/Dev/inventories/toallab-inventory/
├── static.yml                     # Hypervisor and VMs
├── group_vars/
│   ├── hyperv/vars.yml
│   ├── windows_servers/vars.yml
│   └── web_servers/vars.yml
└── host_vars/
    └── hyperv1.lan.toal.ca/vars.yml

Quick Reference Commands

Setup

# Activate environment
source ~/.venv/ansible/bin/activate
cd /home/ptoal/Dev/Projects/HyperV

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

# Configure host (one-time)
ansible-playbook playbooks/provision-hyperv-host.yml

VM Operations

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

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

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

# VM power operations
ansible hyperv -m ansible.windows.win_shell -a "Start-VM -Name WEB01"
ansible hyperv -m ansible.windows.win_shell -a "Stop-VM -Name WEB01 -Force"
ansible hyperv -m ansible.windows.win_shell -a "Remove-VM -Name WEB01 -Force"

Application Deployment

# Deploy IIS
ansible-playbook playbooks/install-iis.yml --limit WEB01

# Patch VMs
ansible-playbook playbooks/patch-vms.yml --limit windows_servers

# Test connectivity to VM
ansible WEB01 -m ansible.windows.win_ping

Troubleshooting

# Verbose output
ansible hyperv -m ansible.windows.win_ping -vvv

# Check WinRM
ansible hyperv -m ansible.windows.win_shell -a "Get-Service WinRM"

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

# Get Hyper-V info
ansible hyperv -m ansible.windows.win_shell -a "Get-VMHost | ConvertTo-Json"

Important Notes

Security Considerations

⚠️ Current configuration is for DEMO/LAB only

Current State:

  • WinRM over HTTP (not HTTPS)
  • NTLM authentication (not Kerberos)
  • Certificate validation disabled
  • Permissive firewall rules
  • No backup/DR
  • No monitoring

For Production:

  • Enable HTTPS for WinRM (port 5986)
  • Use Kerberos authentication
  • Enable certificate validation
  • Implement network segmentation
  • Configure backup and DR
  • Deploy monitoring/alerting
  • Implement change management
  • Regular security patching
  • Compliance scanning

AutoUnattend.xml Gotchas

  1. Delivery Methods (in order of difficulty):

    • Second DVD drive (easiest, use helper playbook)
    • Rebuild ISO with autounattend in root (moderate)
    • Floppy image (legacy, difficult)

  2. Common Issues:

    • File not found → wrong location
    • Interactive prompts → XML syntax error
    • Network not configured → check IP settings in template
    • WinRM not available → first logon commands didn't run

  3. Debugging:

    • Check logs: C:\Windows\Panther\setupact.log
    • Watch VM console during install
    • Verify XML with validator before use

Variable Precedence Reminder

1. Extra vars (-e on command line)          [highest]
2. Task vars (in playbook)
3. Host vars (host_vars/)
4. Group vars (group_vars/)
5. Role defaults
6. Inventory vars                           [lowest]

Testing Checklist

Before declaring completion:

  • Hyper-V host provisioning successful
  • Virtual switches created and accessible
  • VM provisioning creates VM successfully
  • AutoUnattend.xml performs unattended install
  • WinRM available after installation
  • VM pingable from Ansible
  • IIS deployment works
  • Windows Update playbook works
  • AAP job template with survey works
  • Documentation is accurate

Questions for Next Session

  1. Hyper-V Host Status:

    • Is hyperv1.lan.toal.ca a fresh install or already configured?
    • Are virtual switches already created?
    • Is storage already set up?

  2. ISO Availability:

    • Is Windows Server 2022 ISO available?
    • Where is it located?

  3. Network:

    • What network should VMs be on?
    • Static IPs or DHCP?
    • Internet access required?

  4. Scope:

    • How many VMs to provision initially?
    • What applications to deploy?
    • Integration with existing systems needed?

Contact / References

Project Location: /home/ptoal/Dev/Projects/HyperV
Inventory Location: /home/ptoal/Dev/inventories/toallab-inventory
Virtual Environment: ~/.venv/ansible
Execution Environment: aap.toal.ca/ee-demo

Key Technologies:

  • Ansible Core 2.15+
  • Ansible Automation Platform 2.x
  • Microsoft Hyper-V (Windows Server 2019/2022)
  • Windows Server 2019/2022

Collections Used:

  • ansible.windows (>=2.0.0)
  • community.windows (>=2.0.0)
  • servicenow.itsm (>=2.0.0)

Ready for next session: Yes
Blockers: None - ready to test on actual Hyper-V host
Recommended first task: Run provision-hyperv-host.yml to set up the environment