Handoff

2026-04-29 09:52:02 -04:00
parent fe11468547
commit a096a7eaa0
4 changed files with 1333 additions and 0 deletions
--- a/HANDOFF.md
+++ b/HANDOFF.md
@@ -0,0 +1,509 @@
+# 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