Validate Azure Stack system state

Applies to: Azure Stack integrated systems and Azure Stack Development Kit

As an Azure Stack operator, having the ability to know the health and status of your system on-demand is essential. The Azure Stack validation tool (Test-AzureStack) is a PowerShell cmdlet that lets you run a series of tests on your system to identify failures if present. You will typically be asked to run this tool through the privileged end point (PEP) when you contact Microsoft Customer Services Support (CSS) with an issue. With the system-wide health and status information at hand, CSS can collect and analyze detailed logs, focus on the area where the error occurred, and work with you to resolve the issue.

Running the validation tool and accessing results

As stated previously, the validation tool is run via the PEP. Each test returns a PASS/FAIL status in the PowerShell window. Additionally, a detailed HTML report is created which can later be accessed during log collection. Here is an outline of the end-to-end validation testing process:

  1. Access the privileged endpoint (PEP). Run the following commands to establish a PEP session:

    Enter-PSSession -ComputerName "<ERCS VM-name/IP address>" -ConfigurationName PrivilegedEndpoint -Credential $localcred 
    

    Tip

    To access the PEP on an ASDK host computer, use AzS-ERCS01 for -ComputerName.

  2. Once you are in the PEP, run:

    Test-AzureStack
    

    Refer to the Parameter considerations and Use case examples sections for more information.

  3. If any tests report FAIL, run:

    Get-AzureStackLog -FilterByRole SeedRing -OutputSharePath "<path>" -OutputShareCredential $cred
    

    The cmdlet gathers logs generated by Test-AzureStack. For more information about diagnostic logs, see Azure Stack diagnostics tools. You should not collect logs or contact CSS if tests report WARN.

  4. If you were instructed to run the validation tool by the CSS, the CSS representative will request the logs you collected to continue troubleshooting your issue.

Tests available

The validation tool lets you run a series of system-level tests and basic cloud scenarios that provide you an insight to the current state and ascertain issues in your system.

Cloud infrastructure tests

These low impact tests work on an infrastructure level and provide you with information on various system components and functions. Currently, tests are grouped into the following categories:

Test Category Argument for -Include and -Ignore
Azure Stack Alert Summary AzsAlertSummary
Azure Stack Backup Share Accessibility Summary AzsBackupShareAccessibility
Azure Stack Control Plane Summary AzsControlPlane
Azure Stack Defender Summary AzsDefenderSummary
Azure Stack Hosting Infrastructure Firmware Summary AzsHostingInfraFWSummary
Azure Stack Cloud Hosting Infrastructure Summary AzsHostingInfraSummary
Azure Stack Cloud Hosting Infrastructure Utilization AzsHostingInfraUtilization
Azure Stack Infrastructure Capacity AzsInfraCapacity
Azure Stack Infrastructure Performance AzsInfraPerformance
Azure Stack Infrastructure Role Summary AzsInfraRoleSummary
Azure Stack Update Summary AzsInfraUpdateSummary
Azure Stack Portal and API Summary AzsPortalAPISummary
Azure Stack Scale Unit VM Events AzsScaleUnitEvents
Azure Stack Scale Unit VM Resources AzsScaleUnitResources
Azure Stack SDN Validation Summary AzsSDNValidation
Azure Stack Service Fabric Role Summary AzsSFRoleSummary
Azure Stack BMC Summary AzsStampBMCSummary
Azure Stack Storage Services Summary AzsStorageSvcsSummary
Azure Stack SQL Store Summary AzsStoreSummary
Azure Stack VM Placement Summary AzsVmPlacement

Cloud scenario tests

In addition to the infrastructure tests above, you also have the ability to run cloud scenario tests to check functionality across infrastructure components. Cloud administrator credentials are required to run these tests as they involve resource deployment.

Note

Currently you cannot run cloud scenario tests using Active Directory Federated Services (AD FS) credentials.

The following cloud scenarios are tested by the validation tool:

  • Resource group creation
  • Plan creation
  • Offer creation
  • Storage account creation
  • Virtual machine creation
  • Blob storage operation
  • Queue storage operation
  • Table storage operation

Parameter considerations

  • The parameter List can be used to display all available test categories.

  • The parameters Include and Ignore can be used to include or exclude test categories. See the Tests available section for more information on shorthand to be used with these arguments.

    Test-AzureStack -Include AzsSFRoleSummary, AzsInfraCapacity
    
    Test-AzureStack -Ignore AzsInfraPerformance
    
  • A tenant VM is deployed as part of one the cloud scenario tests. You can use DoNotDeployTenantVm to disable this.

  • You need to supply the ServiceAdminCredential parameter to run cloud scenario tests as described in the Use case examples section.

  • BackupSharePath and BackupShareCredential are used when testing infrastructure backup settings as shown in the Use case examples section.

  • The validation tool also supports common PowerShell parameters: Verbose, Debug, ErrorAction, ErrorVariable, WarningAction, WarningVariable, OutBuffer, PipelineVariable, and OutVariable. For more information, see About Common Parameters.

Use case examples

Run validation without cloud scenarios

Run the validation tool without the ServiceAdminCredential parameter to skip running cloud scenario tests:

New-PSSession -ComputerName "<ERCS VM-name/IP address>" -ConfigurationName PrivilegedEndpoint -Credential $localcred
Test-AzureStack

Run validation with cloud scenarios

Supplying the validation tool with the ServiceAdminCredentials parameter runs the cloud scenario tests by default:

Enter-PSSession -ComputerName "<ERCS VM-name/IP address>" -ConfigurationName PrivilegedEndpoint -Credential $localcred 
Test-AzureStack -ServiceAdminCredential "<Cloud administrator user name>" 

If you wish to run ONLY cloud scenarios without running the rest of the tests, you can use the Include parameter to do so:

Enter-PSSession -ComputerName "<ERCS VM-name/IP address>" -ConfigurationName PrivilegedEndpoint -Credential $localcred 
Test-AzureStack -ServiceAdminCredential "<Cloud administrator user name>" -Include AzsScenarios   

The cloud administrator user name must be typed in the UPN format: serviceadmin@contoso.onmicrosoft.com (Azure AD). When prompted, type the password to the cloud administrator account.

Run validation tool to test system readiness before installing update or hotfix

Before you start installation of an update or hotfix, you should run the validation tool to check the status of your Azure Stack:

New-PSSession -ComputerName "<ERCS VM-name/IP address>" -ConfigurationName PrivilegedEndpoint -Credential $localcred 
Test-AzureStack -Include AzsControlPlane, AzsDefenderSummary, AzsHostingInfraSummary, AzsHostingInfraUtilization, AzsInfraCapacity, AzsInfraRoleSummary, AzsPortalAPISummary, AzsSFRoleSummary, AzsStampBMCSummary

Run validation tool to test infrastructure backup settings

Before configuring infrastructure backup, you can test the backup share path and credential using the AzsBackupShareAccessibility test:

New-PSSession -ComputerName "<ERCS VM-name/IP address>" -ConfigurationName PrivilegedEndpoint -Credential $localcred 
Test-AzureStack -Include AzsBackupShareAccessibility -BackupSharePath "\\<fileserver>\<fileshare>" -BackupShareCredential <PSCredentials-for-backup-share>

After configuring backup, you can run AzsBackupShareAccessibility to validate the share is accessible from the ERCS:

Enter-PSSession -ComputerName "<ERCS VM-name/IP address>" -ConfigurationName PrivilegedEndpoint -Credential $localcred 
Test-AzureStack -Include AzsBackupShareAccessibility

To test new credentials with the configured backup share, run:

Enter-PSSession -ComputerName "<ERCS VM-name/IP address>" -ConfigurationName PrivilegedEndpoint -Credential $localcred 
Test-AzureStack -Include AzsBackupShareAccessibility -BackupShareCredential "<PSCredential for backup share>"

Next steps

To learn more about Azure Stack diagnostics tools and issue logging, see Azure Stack diagnostics tools.

To learn more about troubleshooting, see Microsoft Azure Stack troubleshooting.