AzStackHciHardwareTestSecureBoot

July 6, 2026 ยท View on GitHub

Name AzStackHci_Hardware_Test_Secure_Boot (aggregated as AzStackHci_Hardware_SecureBoot)
Display name Secure Boot (the aggregated name shown in the portal). The per-machine result JSON and event log carry the verbose form Test Secure Boot <machine>; both refer to this same check.
Validator / test Test-SecureBoot (run with Invoke-AzStackHciHardwareValidation)
Component Hardware (Environment Validator / Environment Checker)
Severity Critical: this validator blocks deployment until UEFI Secure Boot is enabled on the machine.
Requirement Each machine must have UEFI Secure Boot enabled in firmware before deployment.
Applicable Scenarios Deployment and Add Node (pre-deployment validation).
Affected Versions Azure Local, version 23H2 and later.

Overview

This validator checks that UEFI Secure Boot is enabled on each Azure Local machine. Secure Boot is part of the Azure Local hardware security baseline: it ensures the machine only loads boot software that is signed by a trusted authority, and it is a prerequisite for the platform's secured-core and attestation features. The check fails when Secure Boot is disabled, or when the machine is not in a state where Secure Boot can be evaluated (for example a machine running in legacy BIOS / CSM mode rather than UEFI).

It runs by calling Confirm-SecureBootUEFI on each machine. A machine with Secure Boot enabled returns True and the check is a SUCCESS; a machine with Secure Boot disabled returns False and the check is a FAILURE. On a machine that is not in UEFI mode at all, Confirm-SecureBootUEFI reports that the platform does not support the cmdlet, which is treated as the machine not meeting the Secure Boot requirement.

While this check is failing, deployment is blocked at the Hardware validation stage and the machine cannot proceed. This is a pre-deployment gate (it runs during Deployment and Add Node validation), so the machine it flags is normally a host being validated to become a cluster node, not a running cluster member. The fix is usually short: check for BitLocker, enable Secure Boot in firmware, and re-validate. Two cautions apply, though: a host being vetted may have been recycled from another project and could already have BitLocker enabled (a Secure Boot change trips it into recovery, so check first), and the cluster-drain precaution is only needed if the machine is already a live, deployed member.

Where this failure appears

You can see this failure in two places, the Azure portal and the machine itself. Both show the same underlying result.

In the Azure portal

This check runs during the deployment validation step. When you deploy Azure Local from the portal (or with a deployment template), the Validation phase runs the environment checks and lists any that fail:

  1. Open the Azure Local deployment for your cluster and go to its Validation results (the deployment surfaces these before it proceeds to apply).
  2. In the list of checks, this one appears under its display name, Secure Boot, with a Critical severity.
  3. Select the failing check to see the per-machine detail, which names the machine whose Secure Boot is off.

On the machine

Two on-box sources carry the result.

Run the single validator (fastest). The Environment Checker module ships on every Azure Local machine, so you can run this one Hardware check directly and read the result in a few seconds. Use -Include Test-SecureBoot to run only this check, so you do not have to run the full Hardware validation suite:

$r = Invoke-AzStackHciHardwareValidation -Include Test-SecureBoot -PassThru
$r | Select-Object Name, Status, Severity
$r.AdditionalData.Detail

You can also read the underlying value directly:

# True = Secure Boot enabled; False = supported but disabled.
# An error ("Cmdlet not supported on this platform") means the machine is not in UEFI mode.
Confirm-SecureBootUEFI

A machine with Secure Boot disabled returns Status of FAILURE and a detail line of the form:

SecureBoot is 'False' on AzL-Node-01. Expected 'True'. Ensure SecureBoot is supported and enabled on AzL-Node-01.

Event log (per machine). The Environment Checker writes every check result to the AzStackHciEnvironmentChecker event log, located at C:\Windows\System32\winevt\Logs\AzStackHciEnvironmentChecker.evtx. Each result is the JSON body of an Event ID 17205 entry. To read this check's most recent result on a machine:

Get-WinEvent -LogName AzStackHciEnvironmentChecker -FilterXPath '*[System[(EventID=17205)]]' -MaxEvents 2000 |
    Where-Object { $_.Message -match 'AzStackHci_Hardware_(Test_Secure_Boot|SecureBoot)' } |
    Select-Object -First 1 -ExpandProperty Message

In both sources the result for this check looks like this:

{
  "Name": "AzStackHci_Hardware_Test_Secure_Boot",
  "DisplayName": "Test Secure Boot AzL-Node-01",
  "Title": "Test Secure Boot",
  "Severity": "Critical",
  "Status": "FAILURE",
  "Description": "Checking Secure Boot is enabled",
  "TargetResourceName": "Machine: AzL-Node-01, SecureBoot",
  "Remediation": "https://aka.ms/hci-envch",
  "AdditionalData": {
    "Detail": "SecureBoot is 'False' on AzL-Node-01. Expected 'True'. Ensure SecureBoot is supported and enabled on AzL-Node-01.",
    "Status": "FAILURE"
  }
}

A note on names across surfaces. The portal shows the aggregated display name Secure Boot, while the per-machine result JSON and the event log carry the verbose form Test Secure Boot <machine>. The underlying Name, AzStackHci_Hardware_Test_Secure_Boot, is the same on both, so if you are matching strings between the portal and the on-box output, expect the two forms.

Before you start: who does this, and confirm it is safe

  • Who owns this. Enabling Secure Boot is a firmware change, so it is done by the server or hardware administrator with firmware / BMC (iDRAC / iLO / XClarity) access. The Windows administrator confirms and suspends BitLocker; the network team can provide BMC access but does not own this change. If you are first-line or temporary staff, do not change firmware without the machine's owner.
  • Confirm all of these before you reboot into firmware (skipping any one is how machines get stranded):

    • The BitLocker recovery key is escrowed and you can retrieve it (see step 1). A Secure Boot change is measured into TPM PCR 7 and can trip an encrypted volume into the recovery screen.

    • The machine boots in UEFI mode with a GPT system disk, not legacy BIOS / MBR. Switching boot mode alone will not boot an OS that was installed in legacy/MBR mode.

      # A GPT boot disk means the OS was installed in UEFI mode.
Get-Disk | Where-Object IsBoot | Select-Object Number, PartitionStyle
# If Confirm-SecureBootUEFI errors with "Cmdlet not supported on this platform",
# the machine is in legacy BIOS / CSM mode, not UEFI.
# Cross-check the boot mode from Windows: a winload.efi boot path means UEFI,
# winload.exe means legacy BIOS. (msinfo32 also reports "BIOS Mode: UEFI" or "Legacy".)
bcdedit /enum '{current}' | Select-String 'path'

    • If this machine is already a deployed cluster member (encrypted or not), the firmware reboot takes a live node down, so drain it first (see If the machine is already a deployed, encrypted cluster member). One node at a time.

How to fix it

This check runs during pre-deployment validation, so the machine it flags is normally a host being prepared to become a cluster node, not a running cluster member: there is usually no cluster to keep in quorum. Do not assume the host is otherwise "clean", though. A host being vetted may have been recycled from another project and could already have BitLocker enabled, and a Secure Boot change is measured into TPM PCR 7, which trips an encrypted volume into recovery, so check for BitLocker before you touch firmware (step 1). The cluster-drain precaution only applies in the uncommon case that the machine is already a live, deployed cluster member.

Secure Boot is a firmware (UEFI/BIOS) setting, so the change is made in the machine's firmware setup, not from Windows.

1. Check for BitLocker, and suspend it if present

Do this even on a fresh pre-deployment host. A host you are vetting may have been recycled from a previous project with BitLocker already enabled, and changing Secure Boot alters the machine's measured-boot state (it is measured into TPM PCR 7). If a protected volume is left armed, the next boot after the change stops at the BitLocker recovery screen and asks for the 48-digit recovery password, which can strand the machine.

# Are any volumes protected? (On a truly clean, never-encrypted host this is empty.)
Get-BitLockerVolume | Select-Object MountPoint, ProtectionStatus, VolumeStatus

If every volume reports ProtectionStatus = Off, there is nothing to suspend; go to step 2. If any volume is protected, confirm its recovery key is escrowed first, then suspend it with -RebootCount 0 so the suspend holds across the firmware change and reboot until you explicitly resume it:

Suspend-BitLocker -MountPoint "C:" -RebootCount 0
# Repeat for any data volume that reports ProtectionStatus = On, for example:
# Suspend-BitLocker -MountPoint "D:" -RebootCount 0

2. Enable Secure Boot in firmware (UEFI/BIOS)

If this machine is already a deployed, encrypted cluster member, do not reboot it into firmware yet. Follow If the machine is already a deployed cluster member first so you take the node down safely.

  1. Reboot the machine and enter firmware setup (the key varies by vendor, commonly F2, F10, Del, or via the BMC / iDRAC / iLO / XClarity remote console).
  2. Make sure the machine is in UEFI boot mode, not legacy BIOS / CSM. Secure Boot only applies in UEFI mode, and the OS disk must be GPT. If the machine was installed in legacy/MBR mode, switching boot mode alone will not boot the existing OS; the machine must be installed in UEFI mode.
  3. Enable Secure Boot. If prompted, make sure the standard Microsoft Secure Boot keys (PK / KEK / db) are provisioned (often shown as "Install default Secure Boot keys" or "Standard" key configuration).
  4. Save and exit, and let the machine boot back into the OS.

The exact menu names are vendor-specific; consult your hardware vendor's documentation for the precise location of the Secure Boot and boot-mode settings. As a starting point, Secure Boot and boot mode usually live here:

Vendor (tool)Where Secure Boot and boot mode usually live
Dell (iDRAC / BIOS Setup)System BIOS > System Security > Secure Boot; boot mode under System BIOS > Boot Settings > Boot Mode
HPE (iLO / UEFI System Utilities)System Configuration > BIOS/Platform Configuration (RBSU) > Server Security > Secure Boot; boot mode under Boot Options
Lenovo (XClarity / UEFI Setup)UEFI Setup > Security > Secure Boot; boot mode under Boot Manager / Startup

These paths vary by model and firmware version, so confirm them against your server's current firmware documentation rather than treating them as exact.

3. Confirm Secure Boot is on

Confirm-SecureBootUEFI

This should now return True.

4. Resume BitLocker (only if you suspended it in step 1)

Resume-BitLocker -MountPoint "C:"
# And any data volume you suspended, for example:
# Resume-BitLocker -MountPoint "D:"

Resuming reseals the BitLocker key to the new (Secure Boot enabled) measurements, and the machine boots normally from then on.

If the machine is already a deployed, encrypted cluster member

Because this is a pre-deployment check, it does not normally fire on a machine that is already a deployed cluster node. But if you are enabling Secure Boot on a machine that is already a live, encrypted cluster member for any reason, add one precaution to the steps above: the firmware reboot takes a running node down, so drain it first and do this one node at a time.

This is a [MEDIUM RISK] change: draining live-migrates VMs off the node, and the node is unavailable until you resume it.

# Confirm the cluster is healthy and can lose this one node before you start.
Get-ClusterNode | Select-Object Name, State          # every other node should be Up
Get-VirtualDisk | Select-Object FriendlyName, HealthStatus, OperationalStatus  # all Healthy / OK
Get-StorageJob                                       # should be empty (no active repair/resync)

# Only when the cluster is healthy, pause and drain this node so its VMs live-migrate off.
Suspend-ClusterNode -Name <node> -Drain
Get-ClusterNode -Name <node> | Select-Object Name, State   # State should be Paused

Then run steps 1 through 4 above (suspend BitLocker, enable Secure Boot, confirm, resume BitLocker). Finally bring the node back and let storage resync before the next one:

Resume-ClusterNode -Name <node>
Get-StorageJob                                       # wait until empty
Get-VirtualDisk | Select-Object FriendlyName, HealthStatus   # back to Healthy

Repeat for each remaining member, one node at a time, so the cluster always keeps quorum and storage resiliency.

Verify the fix

Re-run the single validator:

$r = Invoke-AzStackHciHardwareValidation -Include Test-SecureBoot -PassThru
$r | Select-Object Name, Status, Severity
$r.AdditionalData.Detail

A machine with Secure Boot enabled returns Status of SUCCESS. Once every machine you are deploying reports success, re-run the deployment validation; the Secure Boot check should now pass and deployment can proceed.

When to escalate

Open a support case if any of the following are true:

  • Confirm-SecureBootUEFI returns True, but the Secure Boot check still fails during deployment validation.
  • The firmware has no Secure Boot setting, or Secure Boot cannot be enabled because the platform does not support it. Secure Boot is an Azure Local hardware requirement, so confirm the machine is on the Azure Local supported hardware list.
  • Confirm-SecureBootUEFI reports that the cmdlet is not supported on the platform even after you have set the machine to UEFI boot mode.
  • The machine stops at the BitLocker recovery screen after the change and the recovery key is not available.