Deploying Windows with Eikon¶

This page explains how a Windows image deploy moves through the universal-image-deploy workflow when Eikon is the deploy engine. It covers where each stage runs, where to add your own tasks, and how the unattend.xml and cloudbase-init first-boot paths differ.

It uses the universal application profile method, which works on DRP v4.16 and later. For image formats and capture, see Eikon Image Deploy. For moving existing Curtin Windows deploys, see Migrating Windows Deployments from Curtin to Eikon.

Prerequisites¶

DRP v4.16 or later with the eikon, universal, image-deploy and flexiflow content installed.
A generalized (sysprepped with /generalize /oobe) Windows image, with the target's drivers installed. Windows ignores the answer file on an image that is not generalized.
cloudbase-init installed in the image, only if you use the cloudbase-init path.
UEFI boot. Secure Boot can stay on: the image boots its own Microsoft-signed boot manager. Getting into Sledgehammer with Secure Boot on needs the secure boot license entitlement and the DRP DHCP server; see Secure Boot Support and External DHCP.
The image uploaded to the DRP file server. Use the HTTP port (8091) in eikon/image-url, or set eikon/tls-ca-cert when you use HTTPS. An HTTPS URL fails against the default self-signed certificate.

Configure the Machine¶

Add the universal-application-eikon-image-deploy profile and set the workflow to universal-image-deploy. In the UX this is Pipeline eikon-image-deploy with Workflow universal-image-deploy.

Warning

Do not use the stand-alone eikon-image-deploy workflow for Windows. It never reaches the Windows stages, so the image is written to disk with no unattend.xml and no DRP agent.

A minimal Windows profile, based on example-windows-noplan:

YAML

Name: my-windows-2025
Params:
  eikon/image-type: dd-zst
  eikon/image-url: "{{.ProvisionerURL}}/files/images/eikon/win2025.raw.zst"
  eikon/install-dev: /dev/sda
  eikon/win-unattend-password: "<password>"
  image-deploy/use-cloud-init: false

Bash

drpcli profiles create my-windows-2025.yaml
drpcli machines addprofile <machine-uuid> universal-application-eikon-image-deploy
drpcli machines addprofile <machine-uuid> my-windows-2025
drpcli machines workflow <machine-uuid> universal-image-deploy

eikon/install-dev writes a whole-disk image. Use eikon/plan only for a custom layout.
eikon/win-unattend-password is a Secure param. Without it the password is Password123. The password must meet Windows complexity rules or setup drops it; see Configure Windows first-boot (Administrator password + agent).
image-deploy/use-cloud-init selects the first-boot path. It defaults to true (cloudbase-init).

How the Deploy Progresses¶

Everything up to the reboot runs in Sledgehammer. Windows has no chroot phase: after the image is written, Eikon mounts the Windows volume at /mnt and edits it from Sledgehammer. After the reboot, the rest of the workflow runs as PowerShell tasks through the DRP agent on Windows.

Stage	Runs in	What happens
`discover`, start callback, pre-classification	Sledgehammer	Normal discovery.
`universal-image-deploy-pre-flexiflow`	Sledgehammer	Empty by default. Hook for your tasks.
`universal-image-deploy-image-deploy-flexiflow`	Sledgehammer	Sets the bootenv, erases disks, cleans UEFI boot entries, writes the image, mounts it and runs `eikon-evaluate-target`. No Linux `os-release` is found, so Eikon adds the `eikon-mount-probe-flexiflow` profile.
`universal-image-deploy-mount-probe-flexiflow`	Sledgehammer	`eikon-mount-probe` finds the `Windows` directory, removes the probe profile and adds `eikon-set-win-cbi-flexiflow` or `eikon-set-win-unattend-flexiflow`, based on `image-deploy/use-cloud-init`.
`universal-image-deploy-win-prep-flexiflow`	Sledgehammer, C: at `/mnt`	`eikon-win-prep` copies `drpcli.exe` and writes `Windows\Panther\unattend.xml` and `Windows\Setup\Scripts\SetupComplete.cmd`. The cloudbase-init path also runs `eikon-cloudbase-init-config`.
`...-set-chroot-flexiflow`, `...-chroot-flexiflow`, `...-chroot-finalize-flexiflow`	Sledgehammer, C: at `/mnt`	Empty for Windows. Eikon adds chroot tasks only for Linux images. `chroot-flexiflow` is a hook for your tasks.
`universal-image-deploy-unmount-flexiflow`, `reorder-uefi-bootorder`	Sledgehammer	Stops the deploy agent, sets the boot order, writes the NoCloud seed and unmounts. kexec applies only to Linux.
`universal-image-deploy-pre-reboot-flexiflow`	Sledgehammer, then Windows	`bootenv:local` reboots the machine to disk. Windows runs the specialize and oobeSystem passes from `unattend.xml`, then `SetupComplete.cmd` runs `C:\eikon-win-agent.bat`, which downloads and runs `join-up.ps1`. `eikon-win-joinup` then runs on the new agent.
`image-deploy-cloud-init`, `inventory-os`	Windows	`image-deploy-cleanup` removes the join-up scripts and `C:\curtin`.
`universal-image-deploy-post-flexiflow`	Windows	Empty by default. Hook for your tasks.
classification, post-validation, complete callback, `universal-chain-workflow`, `complete`	Windows	Normal end of the workflow.

Adding Your Own Tasks¶

Each stage reads its task list from a param. Put your tasks in your own profile; flexiflow merges the lists from all profiles when the stage starts. See Adding Tasks to a Workflow.

Param	Runs in	Use it for
`universal/image-deploy-pre-flexiflow`	Sledgehammer, before the disks are erased	BIOS, RAID and firmware settings; checks that should stop the deploy
`universal/image-deploy-chroot-flexiflow`	Sledgehammer (bash), C: mounted at `/mnt`	Offline changes to the image: copy files onto C:, replace `unattend.xml` with a per-machine version, add lines to `SetupComplete.cmd`
`universal/image-deploy-post-flexiflow`	Windows (PowerShell, through the agent)	Domain join, roles and features, and other OS configuration

For work after the deploy, such as a runbook, chain to another workflow with universal-chain-workflow.

Example profile that adds one offline task and one post-boot task:

YAML

Name: my-windows-customize
Params:
  universal/image-deploy-chroot-flexiflow:
    - my-win-offline-files
  universal/image-deploy-post-flexiflow:
    - my-win-domain-join

Warning

SetupComplete.cmd starts the DRP agent. From an offline task, append to it; do not replace it.

Avoid these params:

universal/image-deploy-image-deploy-flexiflow is set with flexiflow/no-compose, so a value in your profile replaces the whole Eikon list instead of adding to it. Set it only when you mean to replace that list, for example to change how disks are erased.
universal/image-deploy-win-prep-flexiflow and universal/image-deploy-pre-reboot-flexiflow already hold Eikon tasks, and the order of merged lists is not guaranteed. A task in win-prep can run before C: is mounted, and a task in pre-reboot can run before or after the reboot.

Choosing unattend.xml or cloudbase-init¶

Both paths write unattend.xml and SetupComplete.cmd, and SetupComplete.cmd starts the DRP agent on both. image-deploy/use-cloud-init only decides whether Eikon also configures cloudbase-init.

unattend.xml only¶

Set image-deploy/use-cloud-init to false. cloudbase-init is not needed in the image.

The built-in template sets the local administrator name, password and locale, and skips the OOBE screens. See Windows Unattend.xml.
eikon/win-unattend-xml replaces the whole file. It is written as-is without template expansion, so it cannot carry per-machine values such as ComputerName. For per-machine values, write your own file over /mnt/Windows/Panther/unattend.xml from a task in universal/image-deploy-chroot-flexiflow.
If your answer file stops SetupComplete.cmd from running, for example by using FirstLogonCommands, call C:\eikon-win-agent.bat from it.

cloudbase-init¶

Leave image-deploy/use-cloud-init at true. cloudbase-init must be installed in the image.

Eikon installs the RackN metadata service plugin into cloudbase-init and points cloudbase-init.conf and cloudbase-init-unattend.conf at it.
With image-deploy/cloud-init-base-url at its file:///curtin/ default, Eikon writes meta-data and user-data to C:\curtin. cloudbase-init applies the hostname, SSH keys, certificates and cloud-init/user-data on first boot. See The curtin Directory on Windows for how that directory is handled.
The default user-data runs C:\eikon-win-agent.ps1. If you set your own cloud-init/user-data, keep that runcmd entry as described in Cloud-Init Agent Startup.
Set the administrator password with eikon/win-unattend-password. Do not set image-deploy/admin-username or image-deploy/admin-password on this path: cloudbase-init takes over the Administrator account and you are locked out. See Configure Windows first-boot (Administrator password + agent).

Validation¶

The machine reaches BootEnv: local and reboots into Windows.
The agent reconnects and the machine runs eikon-win-joinup and the remaining stages.
The workflow reaches complete and you can log in with the configured administrator account.

Bash

drpcli machines show <machine-uuid> --slim params | jq '{Stage, BootEnv, Runnable, Profiles}'

Troubleshooting¶

Image written, but no agent and no unattend.xml — the machine ran the stand-alone eikon-image-deploy workflow. Switch to universal-image-deploy.
Image download fails — the image URL uses HTTPS with the default certificate. Use the HTTP port or set eikon/tls-ca-cert.
Both Windows task lists run after changing image-deploy/use-cloud-init — the eikon-set-win-cbi-flexiflow or eikon-set-win-unattend-flexiflow profile from the last deploy stays on the machine. Remove it before you redeploy.
Agent never joins — Windows does not run SetupComplete.cmd on images activated with some OEM product keys. Volume and KMS keys work.
cloudbase-init specialize steps do not run — sysprep caches its answer file to C:\Windows\Panther\unattend.xml, and Eikon replaces that file. The cloudbase-init service still runs at boot. Put any specialize-pass steps you need in eikon/win-unattend-xml.
Cannot log in — see Troubleshooting (Windows).

References¶

operator howto image-deploy universal flexiflow