Tutorial: Create and manage a virtual machine scale set with Azure PowerShell

Applies to: ✔️ Linux VMs ✔️ Windows VMs ✔️ Uniform scale sets

A virtual machine scale set allows you to deploy and manage a set of identical, auto-scaling virtual machines. Throughout the lifecycle of a virtual machine scale set, you may need to run one or more management tasks. In this tutorial you learn how to:

If you don't have an Azure subscription, create a free account before you begin.

Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article without having to install anything on your local environment.

To start Azure Cloud Shell:

Option	Example/Link
Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell.
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser.
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal.

To run the code in this article in Azure Cloud Shell:

1. Start Cloud Shell.

2. Select the Copy button on a code block to copy the code.

3. Paste the code into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux or by selecting Cmd+Shift+V on macOS.

4. Select Enter to run the code.

Create a resource group

An Azure resource group is a logical container into which Azure resources are deployed and managed. A resource group must be created before a virtual machine scale set. Create a resource group with the New-AzResourceGroup command. In this example, a resource group named myResourceGroup is created in the EastUS region.

New-AzResourceGroup -ResourceGroupName "myResourceGroup" -Location "EastUS"

The resource group name is specified when you create or modify a scale set throughout this tutorial.

Create a scale set

First, set an administrator username and password for the VM instances with Get-Credential:

$cred = Get-Credential

Now create a virtual machine scale set with New-AzVmss. To distribute traffic to the individual VM instances, a load balancer is also created. The load balancer includes rules to distribute traffic on TCP port 80, as well as allow remote desktop traffic on TCP port 3389 and PowerShell remoting on TCP port 5985:

New-AzVmss `
  -ResourceGroupName "myResourceGroup" `
  -VMScaleSetName "myScaleSet" `
  -Location "EastUS" `
  -VirtualNetworkName "myVnet" `
  -SubnetName "mySubnet" `
  -PublicIpAddressName "myPublicIPAddress" `
  -LoadBalancerName "myLoadBalancer" `
  -Credential $cred

It takes a few minutes to create and configure all the scale set resources and VM instances.

View the VM instances in a scale set

To view a list of VM instances in a scale set, use Get-AzVmssVM as follows:

Get-AzVmssVM -ResourceGroupName "myResourceGroup" -VMScaleSetName "myScaleSet"

The following example output shows two VM instances in the scale set:

ResourceGroupName         Name Location             Sku InstanceID ProvisioningState
-----------------         ---- --------             --- ---------- -----------------
MYRESOURCEGROUP   myScaleSet_0   eastus Standard_DS1_v2          0         Succeeded
MYRESOURCEGROUP   myScaleSet_1   eastus Standard_DS1_v2          1         Succeeded

To view additional information about a specific VM instance, add the -InstanceId parameter to Get-AzVmssVM. The following example views information about VM instance 1:

Get-AzVmssVM -ResourceGroupName "myResourceGroup" -VMScaleSetName "myScaleSet" -InstanceId "1"

List connection information

A public IP address is assigned to the load balancer that routes traffic to the individual VM instances. By default, Network Address Translation (NAT) rules are added to the Azure load balancer that forwards remote connection traffic to each VM on a given port. To connect to the VM instances in a scale set, you create a remote connection to an assigned public IP address and port number.

To list the NAT ports to connect to VM instances in a scale set, first get the load balancer object with Get-AzLoadBalancer. Then, view the inbound NAT rules with Get-AzLoadBalancerInboundNatRuleConfig:

# Get the load balancer object
$lb = Get-AzLoadBalancer -ResourceGroupName "myResourceGroup" -Name "myLoadBalancer"

# View the list of inbound NAT rules
Get-AzLoadBalancerInboundNatRuleConfig -LoadBalancer $lb | Select-Object Name,Protocol,FrontEndPort,BackEndPort

The following example output shows the instance name, public IP address of the load balancer, and port number that the NAT rules forward traffic to:

Name             Protocol FrontendPort BackendPort
----             -------- ------------ -----------
myScaleSet3389.0 Tcp             50001        3389
myScaleSet5985.0 Tcp             51001        5985
myScaleSet3389.1 Tcp             50002        3389
myScaleSet5985.1 Tcp             51002        5985

The Name of the rule aligns with the name of the VM instance as shown in a previous Get-AzVmssVM command. For example, to connect to VM instance 0, you use myScaleSet3389.0 and connect to port 50001. To connect to VM instance 1, use the value from myScaleSet3389.1 and connect to port 50002. To use PowerShell remoting, you connect to the appropriate VM instance rule for TCP port 5985.

View the public IP address of the load balancer with Get-AzPublicIpAddress:

Get-AzPublicIpAddress -ResourceGroupName "myResourceGroup" -Name "myPublicIPAddress" | Select IpAddress

Example output:

IpAddress
---------
52.168.121.216

Create a remote connection to your first VM instance. Specify your public IP address and port number of the required VM instance, as shown from the preceding commands. When prompted, enter the credentials used when you created the scale set (by default in the sample commands, azureuser and P@ssw0rd!). If you use the Azure Cloud Shell, perform this step from a local PowerShell prompt or Remote Desktop Client. The following example connects to VM instance 1:

mstsc /v 52.168.121.216:50001

Once logged in to the VM instance, you could perform some manual configuration changes as needed. For now, close the remote connection.

Understand VM instance images

Azure marketplace includes many images that can be used to create VM instances. To see a list of available publishers, use the Get-AzVMImagePublisher command.

Get-AzVMImagePublisher -Location "EastUS"

To view a list of images for a given publisher, use Get-AzVMImageSku. The image list can also be filtered by -PublisherName or -Offer. In the following example, the list is filtered for all images with publisher name of MicrosoftWindowsServer and an offer that matches WindowsServer:

Get-AzVMImageSku -Location "EastUS" -PublisherName "MicrosoftWindowsServer" -Offer "WindowsServer"

The following example output shows all of the available Windows Server images:

Skus                                  Offer         PublisherName          Location
----                                  -----         -------------          --------
2008-R2-SP1                           WindowsServer MicrosoftWindowsServer eastus
2008-R2-SP1-smalldisk                 WindowsServer MicrosoftWindowsServer eastus
2012-Datacenter                       WindowsServer MicrosoftWindowsServer eastus
2012-Datacenter-smalldisk             WindowsServer MicrosoftWindowsServer eastus
2012-R2-Datacenter                    WindowsServer MicrosoftWindowsServer eastus
2012-R2-Datacenter-smalldisk          WindowsServer MicrosoftWindowsServer eastus
2016-Datacenter                       WindowsServer MicrosoftWindowsServer eastus
2016-Datacenter-Server-Core           WindowsServer MicrosoftWindowsServer eastus
2016-Datacenter-Server-Core-smalldisk WindowsServer MicrosoftWindowsServer eastus
2016-Datacenter-smalldisk             WindowsServer MicrosoftWindowsServer eastus
2016-Datacenter-with-Containers       WindowsServer MicrosoftWindowsServer eastus
2016-Datacenter-with-RDSH             WindowsServer MicrosoftWindowsServer eastus
2016-Nano-Server                      WindowsServer MicrosoftWindowsServer eastus

When you created a scale set at the start of the tutorial, a default VM image of Windows Server 2016 DataCenter was provided for the VM instances. You can specify a different VM image based on the output from Get-AzVMImageSku. The following example would create a scale set with the -ImageName parameter to specify a VM image of MicrosoftWindowsServer:WindowsServer:2016-Datacenter-with-Containers:latest. As it takes a few minutes to create and configure all the scale set resources and VM instances, you don't have to deploy the following scale set:

New-AzVmss `
  -ResourceGroupName "myResourceGroup2" `
  -Location "EastUS" `
  -VMScaleSetName "myScaleSet2" `
  -VirtualNetworkName "myVnet2" `
  -SubnetName "mySubnet2" `
  -PublicIpAddressName "myPublicIPAddress2" `
  -LoadBalancerName "myLoadBalancer2" `
  -UpgradePolicyMode "Automatic" `
  -ImageName "MicrosoftWindowsServer:WindowsServer:2016-Datacenter-with-Containers:latest" `
  -Credential $cred

Understand VM instance sizes

A VM instance size, or SKU, determines the amount of compute resources such as CPU, GPU, and memory that are made available to the VM instance. VM instances in a scale set need to be sized appropriately for the expected work load.

VM instance sizes

The following table categorizes common VM sizes into use cases.

Find available VM instance sizes

To see a list of VM instance sizes available in a particular region, use the Get-AzVMSize command.

Get-AzVMSize -Location "EastUS"

The output is similar to the following condensed example, which shows the resources assigned to each VM size:

Name                   NumberOfCores MemoryInMB MaxDataDiskCount OSDiskSizeInMB ResourceDiskSizeInMB
----                   ------------- ---------- ---------------- -------------- --------------------
Standard_DS1_v2                    1       3584                4        1047552                 7168
Standard_DS2_v2                    2       7168                8        1047552                14336
[...]
Standard_A0                        1        768                1        1047552                20480
Standard_A1                        1       1792                2        1047552                71680
[...]
Standard_F1                        1       2048                4        1047552                16384
Standard_F2                        2       4096                8        1047552                32768
[...]
Standard_NV6                       6      57344               24        1047552               389120
Standard_NV12                     12     114688               48        1047552               696320

When you created a scale set at the start of the tutorial, a default VM SKU of Standard_DS1_v2 was provided for the VM instances. You can specify a different VM instance size based on the output from Get-AzVMSize. The following example would create a scale set with the -VmSize parameter to specify a VM instance size of Standard_F1. As it takes a few minutes to create and configure all the scale set resources and VM instances, you don't have to deploy the following scale set:

New-AzVmss `
  -ResourceGroupName "myResourceGroup3" `
  -Location "EastUS" `
  -VMScaleSetName "myScaleSet3" `
  -VirtualNetworkName "myVnet3" `
  -SubnetName "mySubnet3" `
  -PublicIpAddressName "myPublicIPAddress3" `
  -LoadBalancerName "myLoadBalancer3" `
  -UpgradePolicyMode "Automatic" `
  -VmSize "Standard_F1" `
  -Credential $cred

Change the capacity of a scale set

When you created a scale set, you requested two VM instances. To increase or decrease the number of VM instances in the scale set, you can manually change the capacity. The scale set creates or removes the required number of VM instances, then configures the load balancer to distribute traffic.

First, create a scale set object with Get-AzVmss, then specify a new value for sku.capacity. To apply the capacity change, use Update-AzVmss. The following example sets the number of VM instances in your scale set to 3:

# Get current scale set
$vmss = Get-AzVmss -ResourceGroupName "myResourceGroup" -VMScaleSetName "myScaleSet"

# Set and update the capacity of your scale set
$vmss.sku.capacity = 3
Update-AzVmss -ResourceGroupName "myResourceGroup" -Name "myScaleSet" -VirtualMachineScaleSet $vmss 

If takes a few minutes to update the capacity of your scale set. To see the number of instances you now have in the scale set, use Get-AzVmss:

Get-AzVmss -ResourceGroupName "myResourceGroup" -VMScaleSetName "myScaleSet"

The following example output shows that the capacity of the scale set is now 3:

Sku        :
  Name     : Standard_DS2
  Tier     : Standard
  Capacity : 3

Common management tasks

You can now create a scale set, list connection information, and connect to VM instances. You learned how you could use a different OS image for your VM instances, select a different VM size, or manually scale the number of instances. As part of day to day management, you may need to stop, start, or restart the VM instances in your scale set.

Stop and deallocate VM instances in a scale set

To stop one or more VMs in a scale set, use Stop-AzVmss. The -InstanceId parameter allows you to specify one or more VMs to stop. If you do not specify an instance ID, all VMs in the scale set are stopped. The following example stops instance 1:

Stop-AzVmss -ResourceGroupName "myResourceGroup" -VMScaleSetName "myScaleSet" -InstanceId "1"

By default, stopped VMs are deallocated and do not incur compute charges. If you wish the VM to remain in a provisioned state when stopped, add the -StayProvisioned parameter to the preceding command. Stopped VMs that remain provisioned incur regular compute charges.

Start VM instances in a scale set

To start one or more VMs in a scale set, use Start-AzVmss. The -InstanceId parameter allows you to specify one or more VMs to start. If you do not specify an instance ID, all VMs in the scale set are started. The following example starts instance 1:

Start-AzVmss -ResourceGroupName "myResourceGroup" -VMScaleSetName "myScaleSet" -InstanceId "1"

Restart VM instances in a scale set

To restart one or more VMs in a scale set, use Retart-AzVmss. The -InstanceId parameter allows you to specify one or more VMs to restart. If you do not specify an instance ID, all VMs in the scale set are restarted. The following example restarts instance 1:

Restart-AzVmss -ResourceGroupName "myResourceGroup" -VMScaleSetName "myScaleSet" -InstanceId "1"

Clean up resources

When you delete a resource group, all resources contained within, such as the VM instances, virtual network, and disks, are also deleted. The -Force parameter confirms that you wish to delete the resources without an additional prompt to do so. The -AsJob parameter returns control to the prompt without waiting for the operation to complete.

Remove-AzResourceGroup -Name "myResourceGroup" -Force -AsJob

Next steps

In this tutorial, you learned how to perform some basic scale set creation and management tasks with Azure PowerShell:

Advance to the next tutorial to learn about scale set disks.