Tutorial: Modify a Virtual Machine Scale Set using PowerShell
Throughout the lifecycle of your applications, you may need to modify or update your Virtual Machine Scale Set. These updates may include how to update the configuration of the scale set, or change the application configuration. This article describes how to modify an existing scale set using PowerShell.
Update the scale set model
A scale set has a "scale set model" that captures the desired state of the scale set as a whole. To query the model for a scale set, you can use Get-AzVmss.
Get-AzVmss -ResourceGroupName myResourceGroup -Name myScaleSet
The exact presentation of the output depends on the options you provide to the command. The following example shows condensed sample output from PowerShell:
Sku :
Name : Standard_DS1_v2
Tier : Standard
Capacity : 2
ProvisioningState : Succeeded
SinglePlacementGroup : False
Id : /subscriptions/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachineScaleSets/myScaleSet
Name : myScaleSet
Type : Microsoft.Compute/virtualMachineScaleSets
Location : eastus
VirtualMachineProfile :
ComputerNamePrefix : myScaleSe
ProvisionVMAgent : True
EnableAutomaticUpdates : True
PatchMode : AutomaticByOS
AssessmentMode : ImageDefault
EnableVMAgentPlatformUpdates : False
AllowExtensionOperations : True
StorageProfile :
Publisher : MicrosoftWindowsServer
Offer : WindowsServer
Sku : 2016-Datacenter
Version : latest
OsDisk :
Caching : None
CreateOption : FromImage
DiskSizeGB : 127
OsType : Windows
StorageAccountType : Premium_LRS
DeleteOption : Delete
NetworkProfile :
NetworkInterfaceConfigurations[0] :
Name : myScaleSet
Primary : True
DisableTcpStateTracking : False
Name : myScaleSet
Subnet :
Id : /subscriptions/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/myScaleSet/subnets/myScaleSet
PrivateIPAddressVersion : IPv4
LoadBalancerBackendAddressPools[0] :
/subscriptions/resourceGroups/myResourceGroup/providers/Microsoft.Network/loadBalancers/myScaleSet/backendAddressPools/myScaleSet
EnableIPForwarding : False
DeleteOption : Delete
NetworkApiVersion : 2020-11-01
OrchestrationMode : Flexible
TimeCreated : 12/2/2022 5:41:21 PM
You can also use Update-AzVmss to update various properties of your scale set. For example, updating your license type.
$myVmss = Get-AzVmss -ResourceGroupName myResourceGroup -Name myScaleSet
Update-AzVmss -ResourceGroupName myResourceGroup -VirtualMachineScaleSet $myVMss -VMScaleSetName myScaleSet -LicenseType Windows_Server
Updating individual VM instances in a scale set
Similar to how a scale set has a model view, each VM instance in the scale set has its own model view. To query the model view for a particular VM instance in a scale set, you can use Get-AzVM.
Get-AzVM -ResourceGroupName myResourceGroup -name MyScaleSet_Instance1
ResourceGroupName : myResourceGroup
Id : /subscriptions/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachines/myScaleSet_Instance1
Name : myScaleSet_Instance1
Type : Microsoft.Compute/virtualMachines
Location : eastus
Extensions : {MicrosoftMonitoringAgent}
HardwareProfile : {VmSize}
NetworkProfile : {NetworkInterfaces}
OSProfile : {ComputerName, AdminUsername, WindowsConfiguration, Secrets, AllowExtensionOperations, RequireGuestProvisionSignal}
ProvisioningState : Succeeded
StorageProfile : {ImageReference, OsDisk, DataDisks}
VirtualMachineScaleSet : {Id}
TimeCreated : 12/2/2022 5:41:23 PM
You can also add the -Status flag to get the Instance View, which provides more details about the VM.
Get-AzVM -ResourceGroupName myResourceGroup -name MyScaleSet_Instance1 -Status
ResourceGroupName : myResourceGroup
Name : MyScaleSet_Instance1
OsName : Windows Server 2016 Datacenter
OsVersion : 10.0.14393.5501
HyperVGeneration : V1
Disks[0] :
Name : myScaleSet_Instance1_disk1_cab60acccff7414b81d60572eeecb9e3
Statuses[0] :
Code : ProvisioningState/succeeded
Level : Info
DisplayStatus : Provisioning succeeded
Time : 12/2/2022 5:41:25 PM
Disks[1] :
Name : disk1
Statuses[0] :
Code : ProvisioningState/succeeded
Level : Info
DisplayStatus : Provisioning succeeded
Time : 12/2/2022 6:33:36 PM
Extensions[0] :
Name : MicrosoftMonitoringAgent
Type : Microsoft.EnterpriseCloud.Monitoring.MicrosoftMonitoringAgent
TypeHandlerVersion : 1.0.18067.0
Statuses[0] :
Code : ProvisioningState/succeeded
Level : Info
DisplayStatus : Provisioning succeeded
Message : Latest configuration has been applied to the Microsoft Monitoring Agent.
VMAgent :
VmAgentVersion : 2.7.41491.1071
ExtensionHandlers[0] :
Type : Microsoft.EnterpriseCloud.Monitoring.MicrosoftMonitoringAgent
TypeHandlerVersion : 1.0.18067.0
Status :
Code : ProvisioningState/succeeded
Level : Info
DisplayStatus : Ready
Message : This virtual machine has successfully connected to Azure Log Analytics.
Statuses[0] :
Code : ProvisioningState/succeeded
Level : Info
DisplayStatus : Ready
Message : GuestAgent is running and processing the extensions.
Time : 12/2/2022 6:34:55 PM
Statuses[0] :
Code : ProvisioningState/succeeded
Level : Info
DisplayStatus : Provisioning succeeded
Time : 12/2/2022 6:33:42 PM
Statuses[1] :
Code : PowerState/running
Level : Info
DisplayStatus : VM running
These properties describe the configuration of a VM instance within a scale set, not the configuration of the scale set as a whole.
You can perform updates to individual VM instances in a scale set just like you would a standalone VM. For example, attaching a new data disk to instance 1:
$VirtualMachine = Get-AzVM -ResourceGroupName "myResourceGroup" -Name "myScaleSet_Instance1".
Add-AzVMDataDisk -VM $VirtualMachine -Name "disk1" -LUN 0 -Caching ReadOnly -DiskSizeinGB 128 -CreateOption Empty
Update-AzVM -ResourceGroupName "myResourceGroup" -VM $VirtualMachine
Add an Instance to your scale set
There are times where you might want to add a new VM to your scale set but want different configuration options than then listed in the scale set model. VMs can be added to a scale set during creation by using the Get-AzVmss command and specifying the scale set name you want the instance added to.
New-AzVM -Name myNewInstance -ResourceGroupName myResourceGroup -image Ubuntu2204 -VmssId /subscriptions/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachineScaleSets/myScaleSet
ResourceGroupName : myResourceGroup
Id : /subscriptions/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachines/myNewInstance
Name : myNewInstance
Type : Microsoft.Compute/virtualMachines
Location : eastus
Tags : {}
HardwareProfile : {VmSize}
NetworkProfile : {NetworkInterfaces}
OSProfile : {ComputerName, AdminUsername, LinuxConfiguration, Secrets, AllowExtensionOperations, RequireGuestProvisionSignal}
ProvisioningState : Succeeded
StorageProfile : {ImageReference, OsDisk, DataDisks}
FullyQualifiedDomainName : mynewinstance-21bc01.eastus.cloudapp.azure.com
VirtualMachineScaleSet : {Id}
TimeCreated : 12/2/2022 6:40:20 PM
By running Get-AzVM again, we can see the new instance was created and added to the existing scale set.
Get-AzVm -ResourceGroupName myResourceGroup
ResourceGroupName Name Location VmSize OsType NIC ProvisioningState
----------------- ---- -------- ------ ------ --- -----------------
myResourceGroup myNewInstance eastus Standard_D2s_v3 Linux myNewInstance Succeeded
myResourceGroup myScaleSet_Instance1 eastus Standard_DS1_v2 Windows myScaleSet-a9f1d54c Succeeded
myResourceGroup myScaleSet_Instance2 eastus Standard_DS1_v2 Windows myScaleSet-4dc708e5 Succeeded
Bring VMs up-to-date with the latest scale set model
Note
Upgrade modes are not currently supported on Virtual Machine Scale Sets using Flexible orchestration mode.
Scale sets have an "upgrade policy" that determine how VMs are brought up-to-date with the latest scale set model. The three modes for the upgrade policy are:
- Automatic - In this mode, the scale set makes no guarantees about the order of VMs being brought down. The scale set may take down all VMs at the same time.
- Rolling - In this mode, the scale set rolls out the update in batches with an optional pause time between batches.
- Manual - In this mode, when you update the scale set model, nothing happens to existing VMs until a manual update is triggered.
If your scale set is set to manual upgrades, you can trigger a manual upgrade using Update-AzVmss.
$myVmss = Get-AzVmss -ResourceGroupName myResourceGroup -Name myScaleSet
Update-AzVmss -ResourceGroupName myResourceGroup -VirtualMachineScaleSet $myVMss -VMScaleSetName myScaleSet
Note
Service Fabric clusters can only use Automatic mode, but the update is handled differently. For more information, see Service Fabric application upgrades.
Reimage a scale set
Virtual Machine Scale Sets will generate a unique name for each VM in the scale set. The naming convention differs by orchestration mode:
- Flexible orchestration Mode:
{scale-set-name}_{8-char-guid} - Uniform orchestration mode:
{scale-set-name}_{instance-id}
In the cases where you need to reimage a specific instance, use Set-AzVmss and specify the instance name.
Set-AzVmssVM -ResourceGroupName myResourceGroup -VMScaleSetName myScaleSet -InstanceId myScaleSet_Instance1 -Reimage
To reimage all instances in a scale set simply specify the scale set name and omit any instanceIDs.
Set-AzVmssVM -Reimage -ResourceGroupName myResourceGroup -VMScaleSetName myScaleSet
Update the OS image for your scale set
You may have a scale set that runs an old version of Ubuntu LTS 18.04. You want to update to a newer version of Ubuntu LTS 16.04, such as version 18.04.202210180. The image reference version property isn't part of a list, so you can directly modify these properties using Update-AzVmss.
$myVmss = Get-AzVmss -ResourceGroupName myResourceGroup -Name myScaleSet
Update-AzVmss -ResourceGroupName myResourceGroup -VirtualMachineScaleSet $myVMss -VMScaleSetName myScaleSet -ImageReferenceVersion virtualMachineProfile.storageProfile.imageReference.version=18.04.202210180
Alternatively, you may want to change the image your scale set uses. For example, you may want to update or change a custom image used by your scale set. You can change the image your scale set uses by updating the image reference ID property. The image reference ID property isn't part of a list, so you can directly modify this property using Update-AzVmss.
$myVmss = Get-AzVmss -ResourceGroupName myResourceGroup -Name myScaleSet
Update-AzVmss -ResourceGroupName myResourceGroup -VirtualMachineScaleSet $myVMss -VMScaleSetName myScaleSet -ImageReferenceVersion virtualMachineProfile.storageProfile.imageReference.id=/subscriptions/{subscriptionID}/resourceGroups/myResourceGroup/providers/Microsoft.Compute/images/myNewImage
If you use Azure platform images, you can update the image by modifying the imageReference (more information, see the REST API documentation).
Note
With platform images, it is common to specify "latest" for the image reference version. When you create, scale out, and reimage, VMs are created with the latest available version. However, it does not mean that the OS image is automatically updated over time as new image versions are released. A separate feature provides automatic OS upgrades. For more information, see the Automatic OS Upgrades documentation.
If you use custom images, you can update the image by updating the imageReference ID (more information, see the REST API documentation).
Next steps
In this tutorial, you learned how to modify various aspects of your scale set and individual instances using PowerShell.
- Update the scale set model
- Update an individual VM instance in a scale set
- Add an instance to your scale set
- Bring VMs up-to-date with the latest scale set model
- Reimage a scale set
- Update the OS image for your scale set