Integrate ACM Pack in your cluster deployment
The PowerShell HPC.ACM module is for performing a basic MPI ping-pong test for a cluster of virtual machines or virtual machine scale sets on Azure. This module adds the cluster to a deployed Azure Cluster Management (ACM) service before the test. You can use it to do basic validation after you deploy a cluster on Azure.
Prerequisites
To use the module, get PowerShell and install the Azure PowerShell module Az first. You must have deployed a ACM service.
PowerShell
Either PowerShell Core 6.1 or Windows PowerShell 5.1 is OK. Older versions of PowerShell Core (>=6.0) and Windows PowerShell (>= 5.0) might not work.
PowerShell Core is available on Linux, Mac, and Windows. While Windows PowerShell is only on Windows. For installation instructions, see Install PowerShell on Windows, Linux, and macOS.
Az
Az is the module for managing your resource on Azure. To install it, run the following command in PowerShell:
Install-Module -Name Az -Scope CurrentUser
Installation
To install HPC.ACM, run the following command in PowerShell:
Install-Module -Name HPC.ACM -Scope CurrentUser
Usage
You can use the exported PowerShell function Add-AcmCluster to add your cluster to ACM, and then test your cluster later, or you can use New-AcmTest to add and test your cluster in one simple step.
Note
You will be prompted to authenticate to Azure for the first time by accessing a given URL with a given code. After the authentication, your session data is saved locally and you won't be prompted again even if you exit the PowerShell and enter one again on the same computer. So to run an automation script in PowerShell, you can first sign in to Azure (by Login-AzAccount from module Az) on the same computer to avoid being prompted in the future.
Add cluster to ACM only
To add an Azure cluster to ACM, run the following command in PowerShell:
Add-AcmCluster -SubscriptionId "YourSubscriptionId" -ResourceGroup "YourResourceGroupNameOfVmCluster" -AcmResourceGroup "YourResourceGroupNameOfAcmCluster" 2>error_log 6>info_log
Replace the arguments for your own values. The command records errors in error_log file and information output in info_log file, both under the current working directory.
The previous command creates output result like the following, with comments beginning with a number sign (#):
###########################################################################
#
# Cluster setup result
# Each VM/VM scale set in the cluster is added to ACM by a PowerShell job.
# "Completed" means a job is completed or not. Note: even when a job is
# completed, the VM/VM scale set may still fail in adding to ACM. Usually,
# that's because required VM extension failed installing/starting on a Vm.
#
VM/VM Scale Set Completed JobId
--------------- --------- -----
centos7500 True 2
centos7501 True 3
centos7502 True 4
...
###################################
#
# Summary of cluster setup result
#
Total Completed Percent
----- --------- -------
93 93 100.00%
For more help on Add-AcmCluster, run the following command:
help Add-AcmCluster -Detailed
When you have added your cluster to ACM, you can use ACM Pack CLI to test your cluster, or run arbitrary commands. You can also use the New-AcmTest function with the -NoSetup parameter to do basic MPI test as described in the next section.
Add and test cluster in ACM in one step
To add and test an Azure cluster in one step, run the following command in PowerShell:
New-AcmTest -SubscriptionId "YourSubscriptionId" -ResourceGroup "YourResourceGroupNameOfVmCluster" -AcmResourceGroup "YourResourceGroupNameOfAcmCluster" 2>error_log 6>info_log
Replace the arguments for your own values. The command records errors in error_log and information output in file info_log, both under the current working directory.
This command creates output results like those below, with comments beginning with a number sign (#):
...
############################################################################
#
# MPI Pingpong test result
# "Good for Test" means a node is able to and has participated in the test.
# "Good in MPI Pingpong" means a node passed the basic MPI Pingpong test.
#
Node Good for Test Good in MPI Pingpong
---- ------------- --------------------
centos7500 True True
centos7501 True True
centos7502 True True
...
######################################
#
# Summary of MPI Pingpong test result
#
Total Good Percent
----- ---- -------
93 93 100.00%
When you have added your cluster to ACM, you can skip the setup procedure and only do the test by specifying the -NoSetup parameter, as in the following command.
New-AcmTest -SubscriptionId "YourSubscriptionId" -ResourceGroup "YourResourceGroupNameOfVmCluster" -AcmResourceGroup "YourResourceGroupNameOfAcmCluster" -NoSetup 2>error_log 6>info_log
For more help on New-AcmTest, run the following command:
help New-AcmTest -Detailed
Run PowerShell command outside of PowerShell
You might want to run a PowerShell command without opening a PowerShell window.
For PowerShell Core on Linux/Mac
pwsh -Command "New-AcmTest ... 2>err_log 6>info_log"For Windows PowerShell
powershell -Command "..."
You can also save and run PowerShell commands in a .ps1 file.
For PowerShell Core on Linux/Mac
pwsh -File your-file-pathFor Windows PowerShell
powershell -File your-file-path
Parse string output in Bash
You might want to parse the output of New-AcmTest in Bash.
Suppose the output snippet is saved in sample.input.
Node Good for Test Good in MPI Pingpong
---- ------------- --------------------
centos7500 True True
centos7501 True True
centos7502 True True
The following Bash script, saved in sample.sh, parses the output.
#!/bin/bash
# Read record line by line and break it into varibles for each line
while read node good_for_test passed_test; do
if [[ "$node" = "Node" || "$node" = ----* ]]; then
continue
fi
# Process one record:
echo "$node is good: $passed_test"
done
Then run the following command:
sample.sh < sample.input
The command creates these results:
centos7500 is good: True
centos7501 is good: True
centos7502 is good: True