Handoff
This commit is contained in:
394
QUICKSTART.md
Normal file
394
QUICKSTART.md
Normal file
@@ -0,0 +1,394 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user