Assess your environment for deployment readiness (preview)
Applies to: Azure Stack HCI, Supplemental Package
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.
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.
- Work with the support team more effectively in troubleshooting any advanced issues.
Environment Checker modes
You can run the Environment Checker in two modes:
As a built-in tool: The Environment Checker functionality comes built-in with the Azure Stack HCI Deployment Tool. By default, the Deployment Tool runs all the validators to perform the pre-deployment readiness checks.
As a standalone tool: It's a light-weight PowerShell tool that you can download for free from the Windows PowerShell gallery. You can run the standalone tool anytime, independent of the Deployment Tool. For example, you can run it even before receiving the actual hardware to check if all the connectivity requirements are met. You can also run it from any Windows server or client on the network where you'll deploy Azure Stack HCI.
This article describes how to run the Environment Checker in a standalone mode.
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.
To install the Environment Checker on the client computer, follow these steps:
Run PowerShell as administrator (5.1 or later). If you need to install PowerShell, see Installing PowerShell on Windows.
Enter the following cmdlet to install the latest version of the PowerShellGet module:
Install-Module PowerShellGet -AllowClobber -Force
After the installation completes, close the PowerShell window and open a new PowerShell session as administrator.
In the new PowerShell session, register PowerShell gallery as a trusted repo:
Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
Enter the following cmdlet to install the Environment Checker module:
Install-Module -Name AzStackHci.EnvironmentChecker -AllowPrerelease
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:
Locally from the Azure Stack HCI server node
Remotely via PowerShell session
Locally from a workstation or a staging server
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 using the Deployment Tool. 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.
You can use the connectivity validator with Azure Stack HCI, version 21H2 installations also.
Run the connectivity validator
To run the connectivity validator, follow these steps.
Open PowerShell locally on the Azure Stack HCI server, workstation, or a staging server.
Run a connectivity validation by entering the following cmdlet:
Invoke-AzStackHciConnectivityValidationcmdlet 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
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
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
Here's a sample screenshot of the output:
Connectivity validator attributes
You can filter any of the following attributes and display the connectivity validator result in your desired format:
|EndPoint||The endpoint being validated.|
|Protocol||Protocol used – example https.|
|Service||The service endpoint being validated.|
|Operation Type||Type of operation – deployment, update.|
|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.
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.
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:
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://portal.azure.com, run the following commands individually for each endpoint:
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
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:
|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:
Each run of the validator overwrites the existing file.
|Report Location (contains PII)||Provides the path where the completed readiness check report is saved in the JSON format. The default path is:
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.
|Completion message||At the end of the report, displays a message that the validation check is completed.||All reports|
Environment Checker results
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.
Submit and view feedback for