hyperv-demo/HANDOFF.md

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

```yaml
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**:
```yaml
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**:
```yaml
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)
   ```bash
   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**
   ```bash
   # 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**
   ```bash
   vi /home/ptoal/Dev/inventories/toallab-inventory/static.yml
   # Add under web_servers or appropriate group
   ```

5. **Test Application Deployment**
   ```bash
   # 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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