Tutorial: Create and manage a Virtual Machine Scale Set with the Azure CLI

A Virtual Machine Scale Set allows you to deploy and manage a set of 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 an Azure free account before you begin.

Prerequisites

• Use the Bash environment in Azure Cloud Shell. For more information, see Quickstart for Bash in Azure Cloud Shell.

  

• If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

  • If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.

  • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.

  • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

This article requires version 2.0.29 or later of the Azure CLI. If using Azure Cloud Shell, the latest version is already installed.

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 az group create command. In this example, a resource group named myResourceGroup is created in the eastus region.

az group create --name myResourceGroup --location eastus

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

Create a scale set

You create a Virtual Machine Scale Set with the az vmss create command. The following example creates a scale set named myScaleSet, and generates SSH keys if they don't exist:

az vmss create \
  --resource-group myResourceGroup \
  --name myScaleSet \
  --orchestration-mode flexible \
  --image <SKU image> \
  --admin-username azureuser \
  --generate-ssh-keys

It takes a few minutes to create and configure all the scale set resources and VM instances. To distribute traffic to the individual VM instances, a load balancer is also created.

View information about the VM instances in your scale set

To view a list of VM instances in a scale set, use az vm list as follows:

az vm list --resource-group myResourceGroup --output table

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

Name                 ResourceGroup    Location    Zones
-------------------  ---------------  ----------  -------
myScaleSet_instance1  myResourceGroup  eastus
myScaleSet_instance2  myResourceGroup  eastus

To see additional information about a specific VM instance, use az vm show and specify the VM name.

az vm show --resource-group myResourceGroup --name myScaleSet_instance1

{
  "hardwareProfile": {
    "vmSize": "Standard_DS1_v2",
  },
  "id": "/subscriptions/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachines/myScaleSet_instance1",
  "location": "eastus",
  "name": "myScaleSet_instance1",
  "networkProfile": {
    "networkInterfaces": [
      {
        "deleteOption": "Delete",
        "id": "/subscriptions/resourceGroups/myResourceGroup/providers/Microsoft.Network/networkInterfaces/mysca2215Nic-0396c71c",
        "primary": true,
        "resourceGroup": "myResourceGroup"
      }
    ]
  },
  "osProfile": {
    "adminUsername": "azureuser",
    "allowExtensionOperations": true,
    "computerName": "myScaleSN30BP1",
    "linuxConfiguration": {
      "disablePasswordAuthentication": true,
      "enableVmAgentPlatformUpdates": false,
      "patchSettings": {
        "assessmentMode": "ImageDefault",
        "patchMode": "ImageDefault"
      },
      "provisionVmAgent": true,
      "ssh": {
        "publicKeys": [
          {
            "keyData": "ssh-rsa",
            "path": "/home/azureuser/.ssh/authorized_keys"
          }
        ]
      }
    },
    "requireGuestProvisionSignal": true,
    "secrets": [],
  },
  "provisioningState": "Succeeded",
  "resourceGroup": "myResourceGroup",
  "storageProfile": {
    "dataDisks": [],
    "imageReference": {
      "exactVersion": "XXXXX",
      "offer": "myOffer",
      "publisher": "myPublisher",
      "sku": "mySKU",
      "version": "latest"
    },
    "osDisk": {
      "caching": "ReadWrite",
      "createOption": "FromImage",
      "deleteOption": "Delete",
      "diskSizeGb": 30,
      "managedDisk": {
        "id": "/subscriptions/resourceGroups/myResourceGroup/providers/Microsoft.Compute/disks/myScaleSet_instance1_disk1",
        "resourceGroup": "myResourceGroup",
        "storageAccountType": "Premium_LRS"
      },
      "name": "myScaleSet_instance1_disk1",
      "osType": "Linux",
    }
  },
  "tags": {},
  "timeCreated": "2022-11-16T20:32:15.024581+00:00",
  "type": "Microsoft.Compute/virtualMachines",
  "virtualMachineScaleSet": {
    "id": "/subscriptions/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachineScaleSets/myScaleSet",
    "resourceGroup": "myResourceGroup"
  },
}

Create a scale set with a specific VM instance size

When you created a scale set at the start of the tutorial, a default VM SKU of Standard_D1_v2 was provided for the VM instances. You can specify a different VM instance size based on the output from az vm list-sizes. The following example would create a scale set with the --vm-sku 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:

az vmss create \
  --resource-group myResourceGroup \
  --name myScaleSet \
  --orchestration-mode flexible \
  --image <SKU image> \
  --vm-sku Standard_F1 \
  --admin-user azureuser \
  --generate-ssh-keys

Change the capacity of a scale set

When you created a scale set at the start of the tutorial, two VM instances were deployed by default. You can specify the --instance-count parameter with az vmss create to change the number of instances created with a scale set. To increase or decrease the number of VM instances in your existing 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.

To manually increase or decrease the number of VM instances in the scale set, use az vmss scale. The following example sets the number of VM instances in your scale set to 3:

az vmss scale \
  --resource-group myResourceGroup \
  --name myScaleSet \
  --new-capacity 3

It 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 az vm list and query on the associated resource group.

az vm list --resource-group myResourceGroup --output table

Name                 ResourceGroup    Location    Zones
-------------------  ---------------  ----------  -------
myScaleSet_instance1  myResourceGroup  eastus
myScaleSet_instance2  myResourceGroup  eastus
myScaleSet_instance3  myResourceGroup  eastus

Stop and deallocate VM instances in a scale set

To stop all the VM instances in a scale set, use az vmss stop.

az vmss stop \
  --resource-group myResourceGroup \
  --name myScaleSet

To stop individual VM instances in a scale set, use az vm stop and specify the instance name.

az vm stop \
  --resource-group myResourceGroup \
  --name myScaleSet_instance1

Stopped VM instances remain allocated and continue to incur compute charges. If you instead wish the VM instances to be deallocated and only incur storage charges, use az vm deallocate and specify the instance names you want deallocated.

az vm deallocate \
  --resource-group myResourceGroup \
  --name myScaleSet_instance1

Start VM instances in a scale set

To start all the VM instances in a scale set, use az vmss start.

az vmss start \
  --resource-group myResourceGroup \
  --name myScaleSet

To start individual VM instances in a scale set, use az vm start and specify the instance name.

az vm start \
  --resource-group myResourceGroup \
  --name myScaleSet_instance1

Restart VM instances in a scale set

To restart all the VM instances in a scale set, use az vmss restart.

az vmss restart \
  --resource-group myResourceGroup \
  --name myScaleSet

To restart individual VM instances in a scale set, use az vm restart and specify the instance name.

az vm restart \
  --resource-group myResourceGroup \
  --name myScaleSet_instance1

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 --no-wait parameter returns control to the prompt without waiting for the operation to complete. The --yes parameter confirms that you wish to delete the resources without an extra prompt to do so.

az group delete --name myResourceGroup --no-wait --yes

Next steps

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

Advance to the next tutorial to learn how to connect to your scale set instances.