Writing a Blueprint for Windows VM Automation

Last updated: March 4, 2026

---

Table of Contents

1. Why Windows VMs in a Blueprint?

2. CE Prerequisites for Windows Blueprints

3. Preparing the Windows Image

4. Sysprep and Cloud-Init (Cloudbase-Init) Primer

5. Blueprint Structure for a Windows VM

6. Writing the Blueprint – Step by Step

7. Credentials and WinRM Configuration

8. Install Tasks via PowerShell

9. Day 2 Actions for Windows VMs

10. Using calm-dsl to Define the Blueprint as Code

11. Publishing to the Marketplace

12. Troubleshooting Common Windows Blueprint Issues

---

Why Windows VMs in a Blueprint?

When I started using NCM Self-Service on my CE cluster, most examples I found were Linux-focused: cloud-init, bash scripts, and SSH. But in my home lab I run several Windows workloads — a Windows Server 2022 domain controller, a SQL Server 2022 instance, and a Windows 10 test desktop for application testing.

Provisioning those by hand every time was painful. Windows has its own unattended setup mechanism (Sysprep + Autounattend.xml), its own remote execution protocol (WinRM), and its own scripting language (PowerShell). Getting a Blueprint to fully automate a Windows VM end-to-end took me longer than I expected, mostly because of Cloudbase-Init quirks. This article documents what actually works.

---

CE Prerequisites

Before writing a Windows Blueprint, confirm your CE environment has:

• Prism Central deployed and registered to your cluster

• NCM Self-Service enabled in Prism Central (Settings → Enable App Management)

• A Windows Server 2022 image uploaded to Prism Central Image Service (sysprepped, see below)

• VirtIO drivers installed in the image (required for AHV disk and NIC recognition)

• Cloudbase-Init installed in the image (the Windows equivalent of cloud-init)

• A network with reachable DNS (WinRM requires name resolution to work reliably)

Enable NCM Self-Service on CE

Prism Central → Settings → Enable App Management
Toggle: Enable App Management → On
(Takes 3–5 minutes to initialize services)

Once enabled, the Services menu in Prism Central shows Calm (the NCM Self-Service icon).

---

Preparing the Windows Image

The Nutanix AHV hypervisor uses VirtIO for paravirtualized disk and NIC drivers. A standard Windows ISO does not include these — you must inject them before or during installation.

Step 1 – Download VirtIO ISO

Download the Nutanix-validated VirtIO ISO from:

Nutanix Portal → Downloads → Tools & Firmware → VirtIO
File: Nutanix-VirtIO-1.2.x.iso

Step 2 – Install Windows with VirtIO

During Windows Server 2022 installation:

1. Attach both the Windows Server ISO and the VirtIO ISO as CD-ROMs in AHV

2. When the installer asks "Where do you want to install Windows?" and shows no disks, click Load Driver

3. Browse to the VirtIO CD → viostor\2k22\amd64 → load the SCSI driver

4. Disk appears; proceed with installation

5. After Windows boots, install remaining VirtIO drivers by running the VirtIO installer from the CD:

   D:\virtio-win-gt-x64.msi

Step 3 – Install Cloudbase-Init

Cloudbase-Init reads metadata from the AHV hypervisor (via a config drive or HTTP metadata endpoint) and runs setup tasks on first boot.

# Download and install Cloudbase-Init
$url = "https://cloudbase.it/downloads/CloudbaseInitSetup_Stable_x64.msi"
Invoke-WebRequest -Uri $url -OutFile C:\CloudbaseInitSetup.msi
msiexec /i C:\CloudbaseInitSetup.msi /qn

# During the MSI installation wizard (if running interactively):
# Serial port: COM1
# Run Cloudbase-Init as: LocalSystem
# CHECK: "Run Sysprep" at the end

Step 4 – Configure Cloudbase-Init

Edit C:\Program Files\Cloudbase Solutions\Cloudbase-Init\conf\cloudbase-init.conf:

[DEFAULT]
username=Administrator
groups=Administrators
inject_user_password=true
config_drive_raw_hhd=true
config_drive_cdrom=true
config_drive_vfat=true
bsdtar_path=C:\Program Files\Cloudbase Solutions\Cloudbase-Init\bin\bsdtar.exe
mtools_path=C:\Program Files\Cloudbase Solutions\Cloudbase-Init\bin\
verbose=true
debug=true
logdir=C:\Program Files\Cloudbase Solutions\Cloudbase-Init\log\
logfile=cloudbase-init.log
default_log_levels=comtypes=INFO,suds=INFO,iso8601=WARN,requests=WARN
logging_serial_port_settings=COM1,115200,N,8
mtu_use_dhcp_config=true
ntp_use_dhcp_config=true
local_scripts_path=C:\Program Files\Cloudbase Solutions\Cloudbase-Init\LocalScripts\
metadata_services=cloudbaseinit.metadata.services.configdrive.ConfigDriveService,
    cloudbaseinit.metadata.services.httpservice.HttpService
plugins=cloudbaseinit.plugins.common.mtu.MTUPlugin,
    cloudbaseinit.plugins.common.sethostname.SetHostNamePlugin,
    cloudbaseinit.plugins.windows.createuser.CreateUserPlugin,
    cloudbaseinit.plugins.common.setuserpassword.SetUserPasswordPlugin,
    cloudbaseinit.plugins.windows.extendvolumes.ExtendVolumesPlugin,
    cloudbaseinit.plugins.common.userdata.UserDataPlugin,
    cloudbaseinit.plugins.common.localscripts.LocalScriptsPlugin

Step 5 – Sysprep and Shutdown

Run Sysprep to generalize the image so new VMs get unique SIDs and machine names:

C:\Windows\System32\Sysprep\sysprep.exe /generalize /oobe /shutdown /unattend:C:\unattend.xml

Minimal unattend.xml to skip OOBE prompts:

<?xml version="1.0" encoding="utf-8"?>
<unattend xmlns="urn:schemas-microsoft-com:unattend">
  <settings pass="oobeSystem">
    <component name="Microsoft-Windows-Shell-Setup"
               processorArchitecture="amd64"
               publicKeyToken="31bf3856ad364e35"
               language="neutral" versionScope="nonSxS">
      <OOBE>
        <HideEULAPage>true</HideEULAPage>
        <HideLocalAccountScreen>true</HideLocalAccountScreen>
        <HideOEMRegistrationScreen>true</HideOEMRegistrationScreen>
        <HideOnlineAccountScreens>true</HideOnlineAccountScreens>
        <HideWirelessSetupInOOBE>true</HideWirelessSetupInOOBE>
        <ProtectYourPC>1</ProtectYourPC>
      </OOBE>
    </component>
  </settings>
</unattend>

After Sysprep shuts down the VM, take a Nutanix VM snapshot from Prism Element. Then use that snapshot as the basis for an AHV disk image uploaded to the Image Service via acli:

nutanix@cvm:~$ acli image.create win2022-cloudbase-init-template \
  image_type=kDisk \
  source_url=nfs://127.0.0.1/default-container/windows-template.qcow2

Or upload directly via Prism Central → Image Service → Add Image → From URL.

---

Sysprep and Cloudbase-Init Primer

When AHV creates a VM from a sysprepped image, the boot sequence is:

1. AHV creates a config drive (ISO attached as CD-ROM) with:
   - meta-data  (instance-id, hostname)
   - user-data  (cloud-init / Cloudbase-Init script)
   - network-data (optional)

2. Windows boots → Sysprep OOBE runs → Cloudbase-Init starts

3. Cloudbase-Init reads config drive:
   - Sets hostname from meta-data
   - Sets Administrator password from user-data
   - Runs PowerShell scripts from user-data

4. Cloudbase-Init signals completion → VM is ready

The Blueprint create action runs its Tasks after Cloudbase-Init completes, so by the time your shell scripts run, the VM is fully initialized with the hostname and credentials you specified.

---

Blueprint Structure for a Windows VM

A Windows single-VM Blueprint consists of:

Blueprint: windows-server-2022
├── Credentials
│   └── win-admin (username: Administrator, password: ••••••••)
├── Services
│   └── Windows-VM
│       ├── Substrate (AHV VM spec)
│       │   ├── Image: win2022-cloudbase-init-template
│       │   ├── vCPU: @@{vcpu}@@
│       │   ├── RAM: @@{ram_gb}@@ GB
│       │   ├── Disk: @@{disk_gb}@@ GB
│       │   └── NIC: vm-prod-vlan20
│       ├── Variables (guest customization injected via Cloudbase-Init)
│       │   ├── hostname → @@{calm_application_name}@@
│       │   └── admin_password → (hidden, runtime)
│       └── Actions
│           ├── Create  → [Waitfor WinRM] → [Configure OS] → [Install IIS]
│           ├── Delete  → [Cleanup]
│           ├── Day2: Patch → [Run Windows Update]
│           └── Day2: JoinDomain → [Add to AD]
└── Application Profiles
    └── Default
        └── Variables: vcpu (default 4), ram_gb (default 8), disk_gb (default 80)

---

Writing the Blueprint – Step by Step

Navigate to NCM Self-Service

Prism Central → Services → Calm → Blueprints → + Create Blueprint → Multi VM / Pod Blueprint

Define the Service

1. Click + Service on the canvas → name it WindowsVM

2. In the Service panel (right side):

   • Service Name: WindowsVM

   • Variable Name: WindowsVM (used in macros as @@{WindowsVM.address}@@)

Configure the Substrate

Under the Service → VM tab:

Cloud: Nutanix
OS: Windows

VM Name: @@{calm_application_name}@@-@@{calm_array_index}@@

vCPU: @@{vcpu}@@
Cores per vCPU: 1
Memory (GiB): @@{ram_gb}@@

Disks:
  Disk 1:
    Type: DISK
    Bus: SCSI
    Image: win2022-cloudbase-init-template
    Size: @@{disk_gb}@@ GiB
    Bootable: Yes

NICs:
  NIC 1:
    Network: vm-prod-vlan20
    Private IP: Dynamic

Guest Customization:
  Type: Sysprep
  Customization Script: (see below)
  Check In Script: (leave empty)

Guest Customization Script (Sysprep XML injected via config drive)

In the Customization Script field, paste the unattend.xml with password macro:

<?xml version="1.0" encoding="utf-8"?>
<unattend xmlns="urn:schemas-microsoft-com:unattend">
  <settings pass="specialize">
    <component name="Microsoft-Windows-Shell-Setup"
               processorArchitecture="amd64"
               publicKeyToken="31bf3856ad364e35"
               language="neutral" versionScope="nonSxS">
      <ComputerName>@@{calm_application_name}@@</ComputerName>
    </component>
  </settings>
  <settings pass="oobeSystem">
    <component name="Microsoft-Windows-Shell-Setup"
               processorArchitecture="amd64"
               publicKeyToken="31bf3856ad364e35"
               language="neutral" versionScope="nonSxS">
      <UserAccounts>
        <AdministratorPassword>
          <Value>@@{admin_password}@@</Value>
          <PlainText>true</PlainText>
        </AdministratorPassword>
      </UserAccounts>
      <OOBE>
        <HideEULAPage>true</HideEULAPage>
        <HideLocalAccountScreen>true</HideLocalAccountScreen>
        <HideOEMRegistrationScreen>true</HideOEMRegistrationScreen>
        <HideOnlineAccountScreens>true</HideOnlineAccountScreens>
        <HideWirelessSetupInOOBE>true</HideWirelessSetupInOOBE>
        <ProtectYourPC>1</ProtectYourPC>
      </OOBE>
    </component>
  </settings>
</unattend>

@@{admin_password}@@ is a Blueprint variable marked as Secret / Hidden. The value is injected at deploy time.

---

Credentials and WinRM Configuration

Define Credentials

Blueprint → Credentials → + Add Credential
Name: win-admin
Username: Administrator
Type: Password
Password: ••••••• (mark as Secret)

Enable WinRM in the Create Action

WinRM is not enabled by default on Windows Server. Your Blueprint's Create action must enable it before any subsequent Tasks can connect.

Add the first Task in the Create action as a Shell (Execute) task run locally (on the Blueprint engine, not via WinRM) — this task polls until WinRM is responsive:

Task: Wait for WinRM

# Task Type: Set Variable (or Execute)
# Script Type: EScript (Python)
import requests
import time

ip = "@@{WindowsVM.address}@@"
url = f"http://{ip}:5985/wsman"
timeout = 600  # 10 minutes
elapsed = 0

while elapsed < timeout:
    try:
        r = requests.get(url, timeout=5)
        if r.status_code in [200, 401, 403]:
            print(f"WinRM reachable at {ip}")
            exit(0)
    except Exception:
        pass
    time.sleep(15)
    elapsed += 15

print("Timeout waiting for WinRM")
exit(1)

Task: Enable WinRM (via Run Script Execute on VM)

Wait — before WinRM is up, how do I run a script on the VM? The answer is the AHV Guest Script mechanism. In Prism Central, you can inject a first-boot PowerShell script via user-data in the config drive. Add this to the Cloudbase-Init user-data section:

In Substrate → Guest Customization → User Data (separate from Sysprep):

#ps1_sysnative
# Enable WinRM for remote management
winrm quickconfig -q
winrm set winrm/config/service '@{AllowUnencrypted="true"}'
winrm set winrm/config/service/auth '@{Basic="true"}'
netsh advfirewall firewall add rule name="WinRM HTTP" protocol=TCP dir=in localport=5985 action=allow
Set-Item WSMan:\localhost\Service\Auth\Basic $true
Set-Item WSMan:\localhost\Service\AllowUnencrypted $true
Restart-Service winrm

This runs automatically on first boot via Cloudbase-Init before your Blueprint Tasks fire.

---

Install Tasks via PowerShell

Once WinRM is reachable, subsequent Tasks run over WinRM using the win-admin credential.

Task: Install IIS

Task Type: Execute
Script Type: PowerShell
Credential: win-admin
Target: WindowsVM

Script:
Install-WindowsFeature -Name Web-Server -IncludeManagementTools
Install-WindowsFeature -Name Web-Asp-Net45

# Verify
$status = Get-WindowsFeature -Name Web-Server
if ($status.Installed) {
    Write-Output "IIS installed successfully"
} else {
    Write-Error "IIS installation failed"
    exit 1
}

Task: Configure IIS Site

# Task Type: Execute / PowerShell / win-admin credential

$siteName   = "@@{app_name}@@"
$sitePath   = "C:\inetpub\$$siteName"
$port       = @@{app_port}@@

New-Item -ItemType Directory -Path $sitePath -Force

Import-Module WebAdministration
New-WebSite -Name $siteName -Port $port -PhysicalPath $sitePath -Force

# Write index page
Set-Content -Path "$sitePath\index.html" -Value "<h1>@@{calm_application_name}@@ - Deployed via Nutanix Blueprint</h1>"

Write-Output "Site $siteName configured on port $port"

Task: Set VM Output Variables

Set the VM's IP as an application output for downstream use:

Task Type: Set Variable
Script Type: PowerShell
Credential: win-admin

Script:
$ip = (Get-NetIPAddress -AddressFamily IPv4 | Where-Object { $_.PrefixOrigin -eq "Dhcp" }).IPAddress
Write-Output "vm_ip=$ip"

Mark vm_ip as an output variable in the Task configuration. It becomes available in the Application summary after deployment.

---

Day 2 Actions for Windows VMs

Action: Windows Update

Action Name: Patch
Task: Run Windows Update

Script Type: PowerShell
Credential: win-admin

Script:
$updateSession = New-Object -ComObject Microsoft.Update.Session
$updateSearcher = $updateSession.CreateUpdateSearcher()
Write-Output "Searching for updates..."
$updates = $updateSearcher.Search("IsInstalled=0 and Type='Software'")
Write-Output "Found $($updates.Updates.Count) updates"

if ($updates.Updates.Count -gt 0) {
    $updatesToDownload = New-Object -ComObject Microsoft.Update.UpdateColl
    foreach ($update in $updates.Updates) { $updatesToDownload.Add($update) | Out-Null }
    $downloader = $updateSession.CreateUpdateDownloader()
    $downloader.Updates = $updatesToDownload
    $downloader.Download()
    $installer = $updateSession.CreateUpdateInstaller()
    $installer.Updates = $updatesToDownload
    $result = $installer.Install()
    Write-Output "Installation result: $($result.ResultCode)"
} else {
    Write-Output "No updates available"
}

Action: Join Domain

Action Name: JoinDomain

Variables (Action-scoped):
  domain_name: (runtime input, e.g. lab.local)
  domain_admin: (runtime input)
  domain_admin_password: (hidden, runtime)

Task Script (PowerShell):
$secPassword = ConvertTo-SecureString "@@{domain_admin_password}@@" -AsPlainText -Force
$credential  = New-Object System.Management.Automation.PSCredential("@@{domain_admin}@@", $secPassword)

Add-Computer -DomainName "@@{domain_name}@@" -Credential $credential -Restart -Force
Write-Output "Joined domain @@{domain_name}@@, restarting..."

Action: Snapshot Before Patch

Action Name: SnapshotVM

Task Type: HTTP (calls Prism Central API)
URL: https://@@{pc_ip}@@:9440/api/nutanix/v3/vm_snapshots
Method: POST
Authorization: Basic @@{pc_user}@@:@@{pc_password}@@
Content-Type: application/json

Body:
{
  "spec": {
    "resources": {
      "entity_uuid": "@@{WindowsVM.uuid}@@"
    },
    "name": "pre-patch-@@{calm_time}@@"
  },
  "api_version": "3.1",
  "metadata": {
    "kind": "vm_snapshot"
  }
}

---

Using calm-dsl to Define the Blueprint as Code

The GUI is fine for initial design, but I version-control all my Blueprints using calm-dsl.

Install calm-dsl

pip install calm-dsl==3.9.0
calm init dsl
# Configure: PC IP, username, password, project

Windows VM Blueprint in Python

# windows_server_blueprint.py
from calm.dsl.builtins import *


# ---------- Credentials ----------
ADMIN_CRED = basic_cred(
    "Administrator",
    name="win-admin",
    type="PASSWORD",
    password=os.environ.get("WIN_ADMIN_PASSWORD", "Nutanix/4u"),
    default=True,
)


# ---------- Substrate ----------
class WinVMSubstrate(AhvVmDisk):
    image = "win2022-cloudbase-init-template"
    bootable = True


class WinVMSpec(AhvVm):
    name = "@@{calm_application_name}@@"
    num_sockets = 4
    memory = 8
    disks = [AhvVmDisk(image="win2022-cloudbase-init-template", bootable=True, disk_size=80)]
    nics = [AhvVmNic("vm-prod-vlan20")]
    guest_customization = AhvVmGC.Sysprep(
        filename="sysprep_unattend.xml",
        is_domain=False,
    )


class WinVMResources(AhvVmResources):
    vm_spec = WinVMSpec


class WinVMSubstrateSpec(Substrate):
    provider_type = "AHV_VM"
    provider_spec = WinVMResources
    os_type = "Windows"
    readiness_probe = {
        "connection_type": "POWERSHELL",
        "connection_port": 5985,
        "disabled": False,
        "login_credential_local_reference": ref(ADMIN_CRED),
    }


# ---------- Package ----------
@action
def __install__():
    CalmTask.Exec.powershell(
        name="Enable WinRM",
        script="""
winrm quickconfig -q
winrm set winrm/config/service '@{AllowUnencrypted="true"}'
Set-Item WSMan:\\localhost\\Service\\Auth\\Basic $true
netsh advfirewall firewall add rule name="WinRM HTTP" protocol=TCP dir=in localport=5985 action=allow
Restart-Service winrm
""",
        cred=ref(ADMIN_CRED),
        target=ref(WinVMService),
    )

    CalmTask.Exec.powershell(
        name="Install IIS",
        script="""
Install-WindowsFeature -Name Web-Server -IncludeManagementTools
""",
        cred=ref(ADMIN_CRED),
        target=ref(WinVMService),
    )


class WinVMPackage(Package):
    services = [ref(WinVMService)]

    @action
    def __install__():
        CalmTask.Exec.powershell(
            name="Install IIS",
            script="Install-WindowsFeature -Name Web-Server -IncludeManagementTools",
            cred=ref(ADMIN_CRED),
            target=ref(WinVMService),
        )


# ---------- Service ----------
class WinVMService(Service):
    dependencies = []


# ---------- Deployment ----------
class WinVMDeployment(Deployment):
    packages = [ref(WinVMPackage)]
    substrate = ref(WinVMSubstrateSpec)


# ---------- Profile ----------
class DefaultProfile(Profile):
    deployments = [WinVMDeployment]

    vcpu = CalmVariable.Simple("4", label="vCPU Count", runtime=True)
    ram_gb = CalmVariable.Simple("8", label="RAM (GB)", runtime=True)
    disk_gb = CalmVariable.Simple("80", label="Disk (GB)", runtime=True)
    admin_password = CalmVariable.Simple.Secret(
        "", label="Administrator Password", runtime=True
    )


# ---------- Blueprint ----------
class WindowsServerBlueprint(Blueprint):
    """Windows Server 2022 self-service blueprint for Nutanix CE"""

    credentials = [ADMIN_CRED]
    services = [WinVMService]
    packages = [WinVMPackage]
    substrates = [WinVMSubstrateSpec]
    profiles = [DefaultProfile]

Push Blueprint to Prism Central

calm create bp --file windows_server_blueprint.py --name "Windows-Server-2022"
# Blueprint created: Windows-Server-2022 (uuid: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

---

Publishing to the Marketplace

Once the Blueprint is tested, publish it so other users can launch Windows VMs without needing Blueprint edit permissions.

Prism Central → Calm → Blueprints → Windows-Server-2022 → Publish
  Name: Windows Server 2022
  Version: 1.0.0
  Description: Self-service Windows Server 2022 deployment with IIS
  Icon: (upload a Windows icon PNG)
  Categories: Infrastructure

→ Approve (Admin role required)
→ Now visible in: Calm → Marketplace

Users with the Consumer role can now launch a Windows Server VM from the Marketplace without touching the Blueprint itself.

---

Troubleshooting Common Windows Blueprint Issues

Symptom	Likely Cause	Fix
VM boots but Cloudbase-Init never runs	Sysprep not run before image creation, or Cloudbase-Init service disabled	Verify cloudbase-init service is set to Automatic in the template
WinRM connection refused	WinRM not enabled in user-data, or Windows Firewall blocking port 5985	Check user-data script executed; add firewall rule manually and test winrm id -remote:http://IP:5985
Blueprint Task fails: "Auth failed"	Password macro not resolving or wrong credential bound	Verify @@{admin_password}@@ variable is Secret, runtime=True, and mapped correctly
Hostname not set from macro	Cloudbase-Init SetHostNamePlugin not in plugin list	Add SetHostNamePlugin to cloudbase-init.conf plugins list
Sysprep error 0x800f0906	.NET Framework install failed during Sysprep generalize	Install all Windows Updates before Sysprep; avoid Sysprep while .NET is pending reboot
VM IP is 169.254.x.x (APIPA)	DHCP not assigned; VLAN misconfigured	Verify VM NIC is on correct VLAN, DHCP scope has available IPs
calm-dsl readiness probe times out	WinRM takes > 300 seconds to become ready	Increase connection_timeout in readiness probe spec, or add a longer Wait task

---

Next Steps

• Blueprint Syntax and Best Practices

• GitLab CI/CD Integration with Nutanix Blueprint

• Automating Nutanix Backup with Ansible

---

Tags: Nutanix, Blueprint, NCM Self-Service, Windows Server, calm-dsl, Cloudbase-Init, Sysprep, WinRM, PowerShell, Community Edition