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):

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

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

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

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

### Option 2: Ansible Copy (slower)

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

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

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

Expected output:
```
Available Virtual Switches:
- External-NAT
- Internal-Lab
```

### 4.2 Verify ISO Path

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

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

### 5.2 Custom VM Configuration

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

```powershell
# On Hyper-V host
vmconnect.exe localhost WEB01
```

### Via PowerShell

```bash
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:

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

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

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

## Step 9: Deploy Applications

### Install IIS

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

### Apply Windows Updates

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

## Common Tasks

### List All VMs

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

### Start/Stop VM

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

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

### Check VM State

```bash
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:
   ```powershell
   Get-NetFirewallRule -Name "WINRM-HTTP-In-TCP" | Select-Object Name, Enabled
   ```

2. Check WinRM service:
   ```powershell
   Get-Service WinRM
   winrm enumerate winrm/config/listener
   ```

3. Test from Ansible host:
   ```bash
   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:
   ```bash
   ansible-playbook playbooks/list-hyperv-switches.yml
   ```

2. Update group_vars or pass correct switch:
   ```bash
   -e vm_switch="External-NAT"
   ```

3. Create missing switch on Hyper-V host:
   ```powershell
   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:
   ```bash
   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:
   ```bash
   ansible hyperv -m ansible.windows.win_shell \
     -a "Get-VM WEB01 | Select-Object *"
   ```

2. Verify VHD exists:
   ```bash
   ansible hyperv -m ansible.windows.win_stat \
     -a "path=D:\\VMs\\WEB01\\WEB01.vhdx"
   ```

3. Check Hyper-V event logs:
   ```powershell
   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](https://docs.microsoft.com/en-us/windows-server/virtualization/hyper-v/)
- [Ansible Windows Guide](https://docs.ansible.com/ansible/latest/os_guide/windows_usage.html)
- [WinRM Setup](https://docs.ansible.com/ansible/latest/os_guide/windows_setup.html)
- [Project CLAUDE.md](CLAUDE.md) - Architecture documentation
- [Provisioning Guide](playbooks/README-provision.md) - Detailed VM provisioning