# clayshek/ans-pve-win-templ architecture

> Architecture diagram of the GitHub repository clayshek/ans-pve-win-templ, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/clayshek/ans-pve-win-templ
- Repository: https://github.com/clayshek/ans-pve-win-templ

## Overview

##### Project type and purpose
- This is an Ansible-based automation/orchestration tool that builds a Windows Server 2019 template for Proxmox VE.
- It stitches together: a base Microsoft ISO, VirtIO drivers, an AutoUnattend.xml template, PowerShell scripts, and Proxmox’s `qm` CLI via Ansible.

##### File structure
- Top-level:
- README.md – project summary and usage
- provision-template.yml – main Ansible playbook
- inventory.yml – Proxmox node definitions
- vars.yml – custom variables (ISO path, VM specs, credentials)
- autounattend.xml.tpl – Windows unattended install template
- iso-files/
– drivers/virtio/... – all VirtIO driver INF/SYS/MSI files
– scripts/*.ps1 – PowerShell scripts: AnsiblePrep.ps1, Windows-updates passes
- No separate “frontend”/“backend” folders – this is infrastructure code.
- Key config: Ansible playbook, variables, Jinja2 template for AutoUnattend.xml, driver ISO build context.

##### README for additional insights
- Uses Proxmox `qm` command via Ansible’s command module rather than the proxmox_kvm module.
- Installs latest Windows Updates (two passes with reboots).
- Syspreps and marks the VM as a template.
- Requires genisoimage on Proxmox to build the drivers+scripts ISO.

a. Main components
- Ansible Control Host (your local machine or central automation server)
- Proxmox VE Host(s) (target nodes defined in inventory.yml)
- Storage subsystem on Proxmox (holds Windows ISO, driver ISO, VM disk)
- Windows VM (in provisioning lifecycle)
- External source: Microsoft Windows Server ISO
b. Relationships & interactions
1. Ansible Control → SSH → Proxmox VE
- Runs `provision-template.yml`
2. Proxmox VE → `qm` CLI → QEMU/KVM Hypervisor
- Creates VM, disks, network
- Attaches two ISOs:
- Official Windows ISO (os_iso_location)
- Custom VirtIO+Scripts ISO (built from iso-files/)
3. Windows VM boots → reads AutoUnattend.xml from first ISO
- Applies VirtIO drivers from second ISO during setup
- Runs embedded PowerShell scripts (AnsiblePrep.ps1, Windows-updates-pass1.ps1, pass2)
4. Windows VM finalizes setup → Sysprep → VM shutdown
5. Proxmox VE → marks VM as template
c. Architectural patterns/design principles
- Infrastructure as Code (Ansible playbook + templates)
- Idempotent provisioning steps
- Separation of concerns:
- Inventory & credentials (inventory.yml, vault)
- Parameterization (vars.yml)
- Build logic (provision-template.yml)
- Platform artifacts (iso-files/)
- Hybrid orchestration: combining Ansible modules & raw CLI (`qm`)
d. Key technologies/frameworks
- Ansible v2.8+ (playbooks, Jinja2 templates)
- Proxmox VE QM command
- QEMU/KVM virtualization
- Windows unattended setup (AutoUnattend.xml)
- VirtIO drivers for KVM guest performance
- PowerShell scripting inside WinPE/Windows

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External source
    ExternalISO["Microsoft Windows Server ISO"]:::external

    %% Storage subsystem
    Storage["Proxmox Storage\n(ISOs & VM Disk)"]:::storage

    %% Ansible Control Host
    subgraph "Ansible Control Host"
        direction TB
        README["README.md"]:::docs
        provision["provision-template.yml"]:::config
        inventory["inventory.yml"]:::config
        vars["vars.yml"]:::config
    end

    %% ISO Files Build Context
    subgraph "ISO Build Context on Proxmox"
        direction TB
        drivers["VirtIO Drivers Repo\n(amd64)"]:::iso
        scriptsPrep["AnsiblePrep.ps1"]:::iso
        scriptsPass1["win-updates-pass1.ps1"]:::iso
        scriptsPass2["win-updates-pass2.ps1"]:::iso
        autounattend["autounattend.xml.tpl"]:::template
    end

    %% Proxmox VE Host
    Proxmox["Proxmox VE Host"]:::compute

    %% Windows VM in provisioning
    VM["Windows VM (Provisioning)"]:::vm

    %% Final Template
    Template["Windows VM Template"]:::vm

    %% Relationships
    provisioning[/"1. Run playbook via SSH"/]:::note
    provisioning --> Proxmox
    provision -->|"\u2192 SSH / Run"| Proxmox
    inventory -->|"\u2192 Targets"| Proxmox
    vars -->|"\u2192 Parameters"| Proxmox

    %% Build driver ISO step
    Proxmox -->|"\u2192 Build driver ISO\n(genisoimage)"| drivers
    Proxmox -->|"\u2192 Include Scripts & AutoUnattend"| scriptsPrep
    Proxmox -->|"\u2192 Include Scripts & AutoUnattend"| scriptsPass1
    Proxmox -->|"\u2192 Include Scripts & AutoUnattend"| scriptsPass2
    Proxmox -->|"\u2192 Include AutoUnattend Template"| autounattend

    %% Storage attachments
    Storage -->|"\u2192 Store Windows ISO"| ExternalISO
    Storage -->|"\u2192 Store Driver ISO"| drivers
    Storage -->|"\u2192 Attach ISOs"| VM

    %% VM provisioning lifecycle
    VM -->|"\u2192 Boot from Windows ISO\n+ AutoUnattend.xml"| autounattend
    VM -->|"\u2192 Load VirtIO Drivers"| drivers
    VM -->|"\u2192 Execute AnsiblePrep"| scriptsPrep
    VM -->|"\u2192 Windows Updates Pass1"| scriptsPass1
    VM -->|"\u2192 Reboot"| VM
    VM -->|"\u2192 Windows Updates Pass2"| scriptsPass2
    VM -->|"\u2192 Sysprep & Shutdown"| VM
    VM -->|"\u2192 Mark as Template"| Template

    %% Click Events
    click README "https://github.com/clayshek/ans-pve-win-templ/blob/master/README.md"
    click provision "https://github.com/clayshek/ans-pve-win-templ/blob/master/provision-template.yml"
    click inventory "https://github.com/clayshek/ans-pve-win-templ/blob/master/inventory.yml"
    click vars "https://github.com/clayshek/ans-pve-win-templ/blob/master/vars.yml"
    click autounattend "https://github.com/clayshek/ans-pve-win-templ/blob/master/autounattend.xml.tpl"
    click drivers "https://github.com/clayshek/ans-pve-win-templ/tree/master/iso-files/drivers/virtio/amd64/"
    click scriptsPrep "https://github.com/clayshek/ans-pve-win-templ/blob/master/iso-files/scripts/AnsiblePrep.ps1"
    click scriptsPass1 "https://github.com/clayshek/ans-pve-win-templ/blob/master/iso-files/scripts/win-updates-pass1.ps1"
    click scriptsPass2 "https://github.com/clayshek/ans-pve-win-templ/blob/master/iso-files/scripts/win-updates-pass2.ps1"

    %% Styles
    classDef compute fill:#D0E6FF,stroke:#1E70BF,stroke-width:2px
    classDef storage fill:#DFFFE0,stroke:#2F8F00,stroke-width:2px
    classDef vm fill:#FFE5B4,stroke:#BF7300,stroke-width:2px
    classDef external fill:#E0E0E0,stroke:#888888,stroke-width:2px
    classDef config fill:#F0E0FF,stroke:#8F00BF,stroke-width:2px
    classDef docs fill:#FFF5D0,stroke:#BFA000,stroke-width:2px
    classDef iso fill:#FFF0D0,stroke:#BF7F00,stroke-width:2px
    classDef template fill:#E0F0FF,stroke:#007FBF,stroke-width:2px
    classDef note fill:none,stroke:none,stroke-width:0px;font-style:italic;color:#555
    class provisioning note
```
