Automating ESXi Host Preparation and Commissioning for VCF 9 with PowerShell

Overview

When commissioning ESXi hosts into SDDC Manager as part of a VMware Cloud Foundation 9 deployment, there are a handful of preparation steps that need to be done on every host before it can be added to the inventory. Doing this manually across a dozen or more hosts is tedious and error-prone, so I wrote a pair of PowerShell scripts to handle it automatically — one to prepare the hosts, and one to commission them into SDDC Manager via the REST API.

• HostPrep.ps1 (v4.0.0) — prepares ESXi hosts with DNS validation, NTP configuration, certificate management, vSAN disk wipe, and optional password resets
• Commission-VCFHosts.ps1 (v3.0.1) — commissions prepared hosts into SDDC Manager via REST API with validation reporting

---

HostPrep.ps1 Functionality

The script processes hosts sequentially through these steps:

1. DNS validation — performs forward (A record) and reverse (PTR) lookups before connecting
2. PowerCLI connection — establishes direct connection to each host using root credentials
3. NTP configuration — verifies required servers are configured and ntpd is running
4. Advanced settings — sets Config.HostAgent.ssl.keyStore.allowSelfSigned to true (required by SDDC Manager)
5. Optional advanced settings — applies deployment-specific configurations
6. Storage type detection — identifies primary storage as VMFS_FC, NFS, or vSAN
7. 6b. vSAN disk wipe (optional, -WipeDisk only) — enumerates non-boot disks with existing partitions and wipes them via partedUtil over SSH, preparing disks for clean vSAN commissioning
8. Certificate regeneration — reads the ESXi configured hostname and compares it to the FQDN before attempting regen; regenerates if CN mismatches, reboots, and re-validates after
9. Password reset (optional) — changes root password to VCF 9-compliant value; always runs last

The script generates three outputs: a colorized console summary table, an HTML commissioning report, and a CSV file for Commission-VCFHosts.ps1.

---

vSAN Disk Wipe

When recommissioning ESXi hosts that were previously part of a vSAN cluster, the disks still carry existing partition tables from the old cluster. SDDC Manager will refuse to commission those hosts until the disks are clean. The -WipeDisk switch automates this step.

When specified, the script runs the following on each host after storage type detection:

1. Enumerates all storage devices via esxcli storage core device list
2. Unconditionally excludes the boot disk — identified by the IsBootDrive flag; falls back to a ≤ 8 GB size heuristic if the flag is not set
3. Lists all non-boot disks with existing partition tables and prints them to the console
4. Prompts Y/N per host before making any changes — you always see what will be wiped before confirming
5. Unmounts any VMFS datastores on target disks
6. Wipes partition tables via SSH: partedUtil mklabel <device> gpt
7. Disables SSH again when done

Boot disk is always protected. It is excluded at enumeration time and never passed to partedUtil regardless of the Y/N answer.

The disk wipe only runs for hosts detected as VSAN. It is skipped automatically for VMFS_FC and NFS hosts.

The wipe uses partedUtil over SSH, so Posh-SSH is required. Without it the script prints per-host manual instructions instead of failing.

A DiskWipe column is added to both the console summary table and the HTML commissioning report, showing the per-host result: OK, Skipped (non-VSAN or no disks to wipe), Skipped (DryRun), or Failed.

---

Storage Type Detection

The script automatically identifies storage types:

• VMFS_FC — presence of Fibre Channel HBA
• NFS — mounted NFS datastore
• vSAN — default for all other hosts

Important limitation: vSAN OSA versus ESA cannot be auto-detected on unclaimed disks. Users must manually edit the CSV if ESA or vVols deployment is intended.

---

CN Mismatch Detection

Before v3.7.0, the script would attempt certificate regeneration based solely on the CN in the TLS certificate presented on port 443. It would regenerate, reboot, and only discover after the host came back online that the CN was still wrong — because /sbin/generate-certificates uses the ESXi configured hostname, not the FQDN you provided.

The script now reads the ESXi configured hostname via Get-VMHostNetwork and compares it against the FQDN from the hosts file before attempting any regeneration. If they differ, regen is skipped immediately and the host is flagged as CN mismatch — saving the reboot entirely. After a successful regen and reboot, the CN is re-checked to confirm it now matches. A mismatch at either point marks the host as failed (red) in both the console summary and the HTML report.

This matters because SDDC Manager will not commission a host whose certificate CN does not match its FQDN. Catching this early surfaces the real problem — the ESXi hostname needs fixing — rather than looping through a pointless regeneration cycle.

---

Key Features

• DNS validation with mismatch flagging
• Fully interactive operation requiring no pre-configuration
• VCF 9 password validation before host modification
• CN mismatch detection before and after certificate regeneration
• vSAN disk wipe with boot disk protection and Y/N prompt per host
• Optional Posh-SSH integration for automated certificate generation and disk wipe
• Configurable advanced settings without logic modification
• Dry run and report-only modes via -DryRun and -WhatIfReport switches
• Reboot timeout handling with warnings
• Dark-mode HTML report with copy-to-clipboard certificate thumbprints
• CSV output ready for next-phase commissioning

---

HTML Commissioning Report

The report displays SSL thumbprints in SHA256:<base64> format with one-click copy buttons, certificate expiry highlighted (amber within 90 days, red within 30), DNS status, disk wipe result, and per-step status indicators for each host.

---

Commission-VCFHosts.ps1 Workflow

The commissioning script performs these operations:

1. Reads the CSV from HostPrep.ps1
2. Prompts for SDDC Manager credentials and detects version via API
3. Retrieves available network pools for selection
4. Displays storage types (no prompting; edit CSV if changes needed)
5. Prompts for ESXi root password
6. Saves sanitized JSON payload with masked passwords
7. Validates all hosts via POST /v1/hosts/validations
8. Commissions hosts via POST /v1/hosts and polls for completion
9. Retrieves assigned SDDC Manager host UUIDs
10. Generates HTML report and results CSV

Validation Report Structure

The validation report handles the nested VCF 9 API response structure by:

• Flattening per-host checks from the top-level wrapper
• Excluding wrapper validation from result counts
• Deriving per-host pass/fail status from error messages for accuracy

The report includes stat cards, per-host summary table, full validation checks with color coding, and debug files with sanitized payloads.

Output Files

Commission-VCFHosts.ps1 generates timestamped files:

• Commission_<ts>_Payload.json — sanitized JSON (passwords masked)
• Commission_<ts>_ValidationResponse.json — raw SDDC Manager response
• Commission_<ts>_ValidationReport.html — detailed validation report
• Commission_<ts>_Report.html — commissioning report with host UUIDs
• Commission_<ts>_Results.csv — per-host results including host UUIDs

---

Prerequisites

Before first use:

Set-PowerCLIConfiguration -Scope User -ParticipateInCEIP $false -Confirm:$false

Optional — required for automated certificate regeneration and -WipeDisk:

Install-Module -Name Posh-SSH -Scope CurrentUser

---

Usage Examples

Prepare hosts interactively:

.\HostPrep.ps1

Wipe vSAN disks during prep (prompts Y/N per host before wiping):

.\HostPrep.ps1 -WipeDisk

Dry run — shows which disks would be wiped, no changes made:

.\HostPrep.ps1 -WipeDisk -DryRun

Generate report without modifications:

.\HostPrep.ps1 -WhatIfReport

Commission hosts from CSV:

.\Commission-VCFHosts.ps1

Validate only without commissioning:

.\Commission-VCFHosts.ps1 -ValidateOnly

Pass arguments to skip prompts:

.\Commission-VCFHosts.ps1 -CsvPath "C:\VCF\HostPrep_20260320_Commissioning.csv" -SddcManager sddc-manager.vcf.lab

---

Download

Both scripts are available on GitHub: github.com/pauldiee/VCFHostPreparation