Edit

Evaluate the deployment readiness of your environment for Azure Stack HCI, version 23H2

  • Article

Applies to: Azure Stack HCI, version 23H2

This article describes how to use the Azure Stack HCI Environment Checker in a standalone mode to assess how ready your environment is for deploying the Azure Stack HCI solution.

For a smooth deployment of the Azure Stack HCI solution, your IT environment must meet certain requirements for connectivity, hardware, networking, and Active Directory. The Azure Stack HCI Environment Checker is a readiness assessment tool that checks these minimum requirements and helps determine if your IT environment is deployment ready.

About the Environment Checker tool

The Environment Checker tool runs a series of tests on each server in your Azure Stack HCI cluster, reports the result for each test, provides remediation guidance when available, and saves a log file and a detailed report file.

The Environment Checker tool consists of the following validators:

  • Connectivity validator. Checks whether each server in the cluster meets the connectivity requirements. For example, each server in the cluster has internet connection and can connect via HTTPS outbound traffic to well-known Azure endpoints through all firewalls and proxy servers.
  • Hardware validator. Checks whether your hardware meets the system requirements. For example, all the servers in the cluster have the same manufacturer and model.
  • Active Directory validator. Checks whether the Active Directory preparation tool is run prior to running the deployment.
  • Network validator. Validates your network infrastructure for valid IP ranges provided by customers for deployment. For example, it checks there are no active hosts on the network using the reserved IP range.
  • Arc integration validator. Checks if the Azure Stack HCI cluster meets all the prerequisites for successful Arc onboarding.

Why use Environment Checker?

You can run the Environment Checker to:

  • Ensure that your Azure Stack HCI infrastructure is ready before deploying any future updates or upgrades.
  • Identify the issues that could potentially block the deployment, such as not running a pre-deployment Active Directory script.
  • Confirm that the minimum requirements are met.
  • Identify and remediate small issues early and quickly, such as a misconfigured firewall URL or a wrong DNS.
  • Identify and remediate discrepancies on your own and ensure that your current environment configuration complies with the Azure Stack HCI system requirements.
  • Collect diagnostic logs and get remote support to troubleshoot any validation issues.

Environment Checker modes

You can run the Environment Checker in two modes:

  • Integrated tool: The Environment Checker functionality is integrated into the deployment process. By default, all validators are run during deployment to perform pre-deployment readiness checks.

  • Standalone tool: This light-weight PowerShell tool is available for free download from the Windows PowerShell gallery. You can run the standalone tool anytime, outside of the deployment process. For example, you can run it even before receiving the actual hardware to check if all the connectivity requirements are met.

This article describes how to run the Environment Checker in a standalone mode.

Prerequisites

Before you begin, complete the following tasks:

  • Review Azure Stack HCI system requirements.
  • Review Firewall requirements for Azure Stack HCI.
  • Make sure you have access to a client computer that is running on the network where you'll deploy the Azure Stack HCI cluster.
  • Make sure that the client computer used is running PowerShell 5.1 or later.
  • Make sure you have permission to verify the Active Directory preparation tool is run.

Install Environment Checker

The Environment Checker works with PowerShell 5.1, which is built into Windows.

You can install the Environment Checker on a client computer, staging server, or Azure Stack HCI cluster node. However, if installed on an Azure Stack HCI cluster node, make sure to uninstall it before you begin the deployment to avoid any potential conflicts.

To install the Environment Checker, follow these steps:

  1. Run PowerShell as administrator (5.1 or later). If you need to install PowerShell, see Installing PowerShell on Windows.

  2. Enter the following cmdlet to install the latest version of the PowerShellGet module:

    Install-Module PowerShellGet -AllowClobber -Force

  3. After the installation completes, close the PowerShell window and open a new PowerShell session as administrator.

  4. In the new PowerShell session, register PowerShell gallery as a trusted repo:

    Set-PSRepository -Name PSGallery -InstallationPolicy Trusted

  5. Enter the following cmdlet to install the Environment Checker module:

    Install-Module -Name AzStackHci.EnvironmentChecker

  6. If prompted, press Y (Yes) or A (Yes to All) to install the module.

Run readiness checks

Each validator in the Environment Checker tool checks specific settings and requirements. You can run these validators by invoking their respective PowerShell cmdlet on each server in your Azure Stack HCI cluster or from any computer on the network where you'll deploy Azure Stack HCI.

You can run the validators from the following locations:

  • Remotely via PowerShell session.

  • Locally from a workstation or a staging server.

  • Locally from the Azure Stack HCI cluster node. However, make sure to uninstall the Environment Checker before you begin the deployment to avoid any potential conflicts.

Select each of the following tabs to learn more about the corresponding validator.

Use the connectivity validator to check if all the servers in your cluster have internet connectivity and meet the minimum connectivity requirements. For connectivity prerequisites, see Firewall requirements for Azure Stack HCI.

You can use the connectivity validator to:

  • Check the connectivity of your servers before receiving the actual hardware. You can run the connectivity validator from any client computer on the network where you'll deploy the Azure Stack HCI cluster.
  • Check the connectivity of all the servers in your cluster after you've deployed the cluster. You can check the connectivity of each server by running the validator cmdlet locally on each server. Or, you can remotely connect from a staging server to check the connectivity of one or more servers.

Run the connectivity validator

To run the connectivity validator, follow these steps.

  1. Open PowerShell locally on the workstation, staging server, or Azure Stack HCI cluster node.

  2. Run a connectivity validation by entering the following cmdlet:

    Invoke-AzStackHciConnectivityValidation

    Note

    Using the Invoke-AzStackHciConnectivityValidation cmdlet without any parameter checks connectivity for all the service endpoints that are enabled from your device. You can also pass parameters to run readiness checks for specific scenarios. See examples, below.

Here are some examples of running the connectivity validator cmdlet with parameters.

Example 1: Check connectivity of a remote computer

In this example, you remotely connect from your workstation or a staging server to check the connectivity of one or more remote systems.

$session = New-PSSession -ComputerName remotesystem.contoso.com -Credential $credential
Invoke-AzStackHciConnectivityValidation -PsSession $Session

Example 2: Check connectivity for a specific service

You can check connectivity for a specific service endpoint by passing the Service parameter. In the following example, the validator checks connectivity for Azure Arc service endpoints.

Invoke-AzStackHciConnectivityValidation -Service "Arc For Servers"

Example 3: Check connectivity if you're using a proxy

If you're using a proxy server, you can specify the connectivity validator to go through the specified proxy and credentials, as shown in the following example:

Invoke-AzStackHciConnectivityValidation -Proxy http://proxy.contoso.com:8080 -ProxyCredential $proxyCredential

Note

The connectivity validator validates general proxy, it doesn't check if your Azure Stack HCI is configured correctly to use a proxy. For information about how to configure firewalls for Azure Stack HCI, see Firewall requirements for Azure Stack HCI.

Example 4: Check connectivity and create PowerShell output object

You can view the output of the connectivity checker as an object by using the –PassThru parameter:

Invoke-AzStackHciConnectivityValidation –PassThru

Here's a sample screenshot of the output:

Screenshot of a passed connectivity validator report for PassThru parameter.

Connectivity validator attributes

You can filter any of the following attributes and display the connectivity validator result in your desired format:

Attribute name Description
EndPoint The endpoint being validated.
Protocol Protocol used – example https.
Service The service endpoint being validated.
Operation Type Type of operation – deployment, update.
Group Readiness Checks.
System For internal use.
Name Name of the individual service.
Title Service title; user facing name.
Severity Critical, Warning, Informational, Hidden.
Description Description of the service name.
Tags Internal Key-value pairs to group or filter tests.
Status Succeeded, Failed, In Progress.
Remediation URL link to documentation for remediation.
TargetResourceID Unique identifier for the affected resource (node or drive).
TargetResourceName Name of the affected resource.
TargetResourceType Type of the affected resource.
Timestamp The time in which the test was called.
AdditionalData Property bag of key value pairs for additional information.
HealthCheckSource The name of the services called for the health check.

Connectivity validator output

The following samples are the output from successful and unsuccessful runs of the connectivity validator.

To learn more about different sections in the readiness check report, see Understand readiness check report.

Sample output: Successful test

The following sample output is from a successful run of the connectivity validator. The output indicates a healthy connection to all the endpoints, including well-known Azure services and observability services. Under Diagnostics, you can see the validator checks if a DNS server is present and healthy. It collects WinHttp, IE proxy, and environment variable proxy settings for diagnostics and data collection. It also checks if a transparent proxy is used in the outbound path and displays the output.

Screenshot of a passed report after running the connectivity validator.

Sample output: Failed test

If a test fails, the connectivity validator returns information to help you resolve the issue, as shown in the sample output below. The Needs Remediation section displays the issue that caused the failure. The Remediation section lists the relevant article to help remediate the issue.

Screenshot of a failed report after running the connectivity validator.

Potential failure scenario for connectivity validator

The connectivity validator checks for SSL inspection before testing connectivity of any required endpoints. If SSL inspection is turned on in your Azure Stack HCI system, you get the following error:

Screenshot of the error when the connectivity validation fails.

Workaround

Work with your network team to turn off SSL inspection for your Azure Stack HCI system. To confirm your SSL inspection is turned off, you can use the following examples. After SSL inspection is turned off, you can run the tool again to check connectivity to all the endpoints.

If you receive the certificate validation error message, run the following commands individually for each endpoint to manually check the certificate information:

C:\> Import-Module AzStackHci.EnvironmentChecker 
C:\> Get-SigningRootChain -Uri <Endpoint-URI> | ft subject

For example, if you want to verify the certificate information for two endpoints, say https://login.microsoftonline.com and https://portal.azure.com, run the following commands individually for each endpoint:

  • For https://login.microsoftonline.com:

    C:\> Import-Module AzStackHci.EnvironmentChecker 
C:\> Get-SigningRootChain -Uri https://login.microsoftonline.com | ft subject

    Here's a sample output:

    Subject
-------
CN=portal.office.com, O=Microsoft Corporation, L=Redmond, S=WA, C=US
CN=Microsoft Azure TLS Issuing CA 02, O=Microsoft Corporation, C=US
CN=DigiCert Global Root G2, OU=www.digicert.com, O=DigiCert Inc, C=US

  • For https://portal.azure.com:

    C:\> Import-Module AzStackHci.EnvironmentChecker
C:\> Get-SigningRootChain -Uri https://portal.azure.com | ft Subject

    Here's a sample output:

    Subject
-------
CN=portal.azure.com, O=Microsoft Corporation, L=Redmond, S=WA, C=US
CN=Microsoft Azure TLS Issuing CA 01, O=Microsoft Corporation, C=US
CN=DigiCert Global Root G2, OU=www.digicert.com, O=DigiCert Inc, C=US

Understand readiness check report

Each validator generates a readiness check report after completing the check. Make sure to review the report and correct any issues before starting the actual deployment.

The information displayed on each readiness check report varies depending on the checks the validators perform. The following table summarizes the different sections in the readiness check reports for each validator:

Section Description Available in
Services Displays the health status of each service endpoint that the connectivity validator checks. Any service endpoint that fails the check is highlighted with the Needs Remediation tag. Connectivity validator report
Diagnostics Displays the result of the diagnostic tests. For example, the health and availability of a DNS server. It also shows what information the validator collects for diagnostic purposes, such as WinHttp, IE proxy, and environment variable proxy settings. Connectivity validator report
Hardware Displays the health status of all the physical servers and their hardware components. For information on the tests performed on each hardware, see the table under the "Hardware" tab in the Run readiness checks section. Hardware validator report
AD OU Diagnostics Displays the result of the Active Directory organization unit test. Displays if the specified organizational unit exists and contains proper sub-organizational units. Active Directory validator report
Network range test Displays the result of the network range test. If the test fails, it displays the IP addresses that belong to the reserved IP range. Network validator report
Summary Lists the count of successful and failed tests. Failed test results are expanded to show the failure details under Needs Remediation. All reports
Remediation Displays only if a test fails. Provides a link to the article that provides guidance on how to remediate the issue. All reports
Log location (contains PII) Provides the path where the log file is saved. The default path is:

- $HOME\.AzStackHci\AzStackHciEnvironmentChecker.log when you run the Environment Checker in a standalone mode.
- C:\CloudDeployment\Logs when the Environment Checker is run as part of the deployment process.

Each run of the validator overwrites the existing file.		 All reports
Report Location (contains PII) Provides the path where the completed readiness check report is saved in the JSON format. The default path is:

- $HOME\.AzStackHci\AzStackHciEnvironmentReport.json when you run the Environment Checker in a standalone mode.
- C:\CloudDeployment\Logs when the Environment Checker is run as part of the deployment process.

The report provides detailed diagnostics that are collected during each test. This information can be helpful for system integrators or when you need to contact the support team to troubleshoot the issue. Each run of the validator overwrites the existing file.		 All reports
Completion message At the end of the report, displays a message that the validation check is completed. All reports

Environment Checker results

Note

The results reported by the Environment Checker tool reflect the status of your settings only at the time that you ran it. If you make changes later, for example to your Active Directory or network settings, items that passed successfully earlier can become critical issues.

For each test, the validator provides a summary of the unique issues and classifies them into: success, critical issues, warning issues, and informational issues. Critical issues are the blocking issues that you must fix before proceeding with the deployment.

Uninstall environment checker

The environment checker is shipped with Azure Stack HCI, make sure to uninstall it from all Azure Stack HCI cluster nodes before you begin the deployment to avoid any potential conflicts.

Remove-Module AzStackHci.EnvironmentChecker -Force
Get-Module AzStackHci.EnvironmentChecker -ListAvailable | Where-Object {$_.Path -like "*$($_.Version)*"} | Uninstall-Module -force

Troubleshoot environment validation issues

For information about how to get support from Microsoft to troubleshoot any validation issues that may arise during cluster deployment or pre-registration, see Get support for deployment issues.

Next steps