Automating Windows Azure Virtual Machines with PowerShell

With the release of the June 2012 Windows Azure PowerShell cmdlets I’m excited to tell you that I have officially passed the buck!

In this release we have added some exciting functionality to the Windows Azure PowerShell cmdlets and have transitioned ownership and support of the cmdlets to the Windows Azure Engineering teams. The benefit to you as the cmdlet user is the code will be officially supported and much better documented with more frequent release cycles.

To make all of this happen did take a lot of coordination with the different teams so there is a difference in functionality regarding what was previously on CodePlex. For example, the Windows Azure Scaffolding cmdlets for Node.JS have been integrated along with a lot of new functionality for building scaffolding around PHP projects. However, for the first release we were not quite ready to bring forward all of the existing functionality in the Windows Azure cmdlets so with this release a few areas will be delayed: Diagnostics, Traffic Manager and the SQL Azure cmdlets will all come in later waves.

In this blog post I’m going to cover the some of the new functionality around automating Windows Azure Virtual Machines.

Getting Started

Download the Windows Azure PowerShell Cmdlets

Launch the cmdlets by clicking the Windows Azure PowerShell link on the start menu.
If you can’t find this link OR you want to use the cmdlets in your own editor you have to load the modules a little different than normal:

Manual Import of the PowerShell Modules

Import-Module 'C:\Program Files (x86)\Microsoft SDKs\Windows Azure\PowerShell\Azure\Azure.psd1'

(Note: We do plan to add a module in the Users module location soon – we did not forget)

Configuring Your Subscription

The easiest way to get started is to download and import your publish settings file. You can do this by using your web browser and browsing directly to the site: OR by using a handy cmdlet that was previously part of the Node.JS cmdlets Get-AzurePublishSettingsFile which will launch a browser to this URL automatically.
Once you have downloaded the publish settings file it’s a simple matter of importing it.

Import-AzurePublishSettingsFile 'c:\temp\mysub.publishsettings'

To see the resulting configuration run the following command:


If you prefer to manually configure your subscription you can use Set-AzureSubscription to configure your subscription ID and management certificate.

$cert = Get-Item Cert:\CurrentUser\My\YOURCERTTHUMBPRINT
Set-AzureSubscription -SubscriptionName 'testsub1' -SubscriptionId $subid -Certificate $cert 

Note the subscription settings that are imported or set manually are persisted in the following location:
C:\Users\user\AppData\Roaming\Windows Azure Powershell

This means you do not have to run Set-AzureSubscription for each script since it is already there!

The cmdlets do support multiple subscriptions and to allow you to choose which subscription to work on we provide the Select-AzureSubscription cmdlet to switch the active subscription.

Configure Storage
Finally, one new addition is the –CurrentStorageAccount parameter of Set-AzureSubscription. This parameter tells the cmdlets what storage account they should use if they need to access storage. When dealing with virtual machines this comes up quite a bit.

To set it you can run the following:

Get-AzureStorageAccount   # Enumerates your storage accounts 

If you do NOT have a storage account returned above you should create one first.
Run the following to determine the data center to create your storage account in. Ensure you pick a data center that shows support for PersistentVMRole.


Create your storage account:

New-AzureStorageAccount -StorageAccountName 'myuniquelynamedstorage' -Location 'East US'

Finally, set the -CurrentStorageAccount property of your subscription. The -CurrentStorageAccount parameter specifies the storage account to use for VHD storage during the later exercises

Set-AzureSubscription -SubscriptionName 'testsub1'  -CurrentStorageAccount 'mystorage'

For the remainder of this blog post I’m going to walk you through some exercises from our hands on lab to get you familiar with some of the great things you can automate with Windows Azure Virtual Machines and PowerShell.

Before continuing you should start an elevated PowerShell session and run the following command:
Set-ExecutionPolicy RemoteSigned

Provisioning a Virtual Machine using PowerShell CmdLets

Create a new variable and assign it the location you used to create your storage account or whatever location your selected storage account is currently in.
The virtual machines have to be created in the same location/region as your storage account.

$dclocation = '[YOUR-LOCATION]'

Determine the name of the cloud service that will act as the container for your virtual machines:

Check to see if the name is available (Test returns True if the name already exists)

Test-AzureName -Service '[YOUR-CLOUD-SERVICE-NAME]'

Create a variable to use the unique name of your cloud service.


Determine which platform image your want to use as the basis of your virtual machine by running:

Get-AzureVMImage | select ImageName

Create a variable to hold virtual machine image name:


Now let’s create a virtual machine!

If you chose a Windows image you would use the following parameter set:

Quick Create of a Windows VM with PowerShell

$adminPassword = '[YOUR-PASSWORD]'
$vmname = 'mytestvm1'
New-AzureQuickVM -Windows -ServiceName $cloudSvcName -Name $vmname -ImageName $image -Password $adminPassword 

For Linux:
Quick Create of a Linux VM using PowerShell

$linuxuser = '[CHOOSE-USERNAME]'
$adminPassword = '[YOUR-PASSWORD]'
$vmname = 'mytestvm1'

New-AzureQuickVM -Linux -ServiceName $cloudSvcName -Name $vmname -ImageName $image -LinuxUser $linuxuser 

Once the virtual machines have been created you can check their status by running:

Viewing Virtual Machine Settings

Get-AzureVM -ServiceName $cloudSvcName 

This cmdlet when -Name is omitted returns all of the virtual machines within the cloud service. You can of course specify a single VM with the -Name parameter.

Restart, Shutdown and Start of a Windows Azure Virtual Machine

# Restart
Restart-AzureVM -ServiceName $cloudSvcName -Name $vmname

# Shutdown 
Stop-AzureVM -ServiceName $cloudSvcName -Name $vmname

# Start
Start-AzureVM -ServiceName $cloudSvcName -Name $vmname

This exercise showed how you can quickly provision a new virtual machine. What about if you wanted to provision a VM with some settings already configured?

Advanced Provisioning Options

So the following script may put you in PowerShell overload but let me explain it a bit.

The New-AzureVMConfig cmdlet allows you to create a virtual machine configuration object that you can then modify with other cmdlets. You can add data disks, configure endpoints and even modify the disk cache behavior for the OS Disk or the data disks at this stage. You can also add endpoints that are needed for the virtual machine such as port 80 and port 443 (we automatically add endpoints for RDP and SSH when you create a VM off of an image – there is a bug where we do not when creating off of a disk).

So each call to New-AzureVMConfig returns back a object you can then modify with Add-AzureDataDisk, Set-AzureOSDisk, Add-AzureEndpoint etc.. You then take the VM object(s) and pass them to the New-AzureVM cmdlet to actually create the VM(s).

Creating Windows Virtual Machines with PowerShell

   $vmname2 = 'mytestvm2'
   $vmname3 = 'mytestvm3'

   $vm2 = New-AzureVMConfig -Name $vmname2 -InstanceSize ExtraSmall -ImageName $image |
             Add-AzureProvisioningConfig -Windows -Password $adminPassword |
             Add-AzureDataDisk -CreateNew -DiskSizeInGB 50 -DiskLabel 'datadisk1' -LUN 0 |
             Add-AzureEndpoint -Protocol tcp -LocalPort 80 -PublicPort 80 -Name 'web' `
                 -LBSetName 'lbweb' -ProbePort 80 -ProbeProtocol http -ProbePath '/' 

   $vm3 = New-AzureVMConfig -Name $vmname3 -InstanceSize ExtraSmall -ImageName $image |
          Add-AzureProvisioningConfig -Windows -Password $adminPassword  |
           Add-AzureDataDisk -CreateNew -DiskSizeInGB 50 -DiskLabel 'datadisk2' -LUN 0  |
           Add-AzureEndpoint -Protocol tcp -LocalPort 80 -PublicPort 80 -Name 'web' `
                 -LBSetName 'lbweb' -ProbePort 80 -ProbeProtocol http -ProbePath '/' 

   New-AzureVM -ServiceName $cloudSvcName -VMs $vm2,$vm3

Creating Linux Virtual Machines with PowerShell

   $vmname2 = 'mytestvm2'
   $vmname3 = 'mytestvm3'

   $vm2 = New-AzureVMConfig -Name $vmname2 -InstanceSize ExtraSmall -ImageName $image |
          Add-AzureProvisioningConfig -Linux -LinuxUser $linuxUser -Password $adminPassword |
          Add-AzureDataDisk -CreateNew -DiskSizeInGB 50 -DiskLabel 'datadisk1' -LUN 0 |
           Add-AzureEndpoint -Protocol tcp -LocalPort 80 -PublicPort 80 -Name 'web' `
                 -LBSetName 'lbweb' -ProbePort 80 -ProbeProtocol http -ProbePath '/' 

   $vm3 = New-AzureVMConfig -Name $vmname3 -InstanceSize ExtraSmall -ImageName $image |
            Add-AzureProvisioningConfig -Linux -LinuxUser $linuxUser -Password $adminPassword |
            Add-AzureDataDisk -CreateNew -DiskSizeInGB 50 -DiskLabel 'datadisk2' -LUN 0 |
            Add-AzureEndpoint -Protocol tcp -LocalPort 80 -PublicPort 80 -Name 'web' `
                -LBSetName 'lbweb' -ProbePort 80 -ProbeProtocol http -ProbePath '/' 

   New-AzureVM -ServiceName $cloudSvcName -VMs $vm2,$vm3

In this example is I have added the -LBSetName, ProbePort, ProbeProtocol and ProbePath parameters. These are optional for creating a single endpoint but in this case they configure the load balancer for these two virtual machines.

Configuring Other Protocols for the Load Balancer

In addition to configuring HTTP requests, the PowerShell cmdlets can also configure endpoints for UDP and TCP connections as well.
For TCP sockets applications you can specify -ProbeProtocol as tcp instead of http and remove the -ProbePath parameter. The load balancer will attempt to connect to the TCP port specified in -ProbePort and if successful will keep the VM in the load balancer.
For load balancing UDP connections you will need to specify an alternate probe endpoint that can tell the load balancer whether the UDP service is available. This could be a simple http page that returns a 200 assuming the service is up.

Updating Existing Virtual Machines

Modifying an existing virtual machine requires retrieving the current settings by calling Get-AzureVM, modifying them and then calling the Update-AzureVM cmdlet to save the changes.
You can hot add and remove data disks and networking endpoints. Changing disk cache settings requires a reboot as does changing the virtual machine’s instance size.
The following example uses the Get-AzureVM cmdlet to retrieve the VM object and send it to the PowerShell Pipeline.

Add-AzureDataDisk with the CreateNew parameter allows you to dynamically add storage to the virtual machine. In this case we are calling it twice to attach to unformatted blank VHDs to the server each 50 gigs of storage each. The -LUN parameter tells the order of the device being attached and optionally uses the -MediaLocation to specify the location in Storage to keep the newly created VHDs.

Add-AzureDataDisk also supports the Import parameter to attach a disk in the disk library and -ImportFrom to attach a disk that already exists in storage.

The example also adds a new endpoint for TCP port 1433 internally that is listening externally on port 2000 using the Add-AzureEndpoint command.

$vmname = 'mytestvm1'

Get-AzureVM -Name $vmname -ServiceName $cloudSvcName |
    Add-AzureDataDisk -CreateNew -DiskSizeInGB 50 -DiskLabel 'datadisk1' -LUN 0 |
    Add-AzureDataDisk -CreateNew -DiskSizeInGB 50 -DiskLabel 'translogs1' -LUN 1 |
    Add-AzureEndpoint -Protocol tcp -LocalPort 1433 -PublicPort 2000 -Name 'sql' |

Once the virtual machine has been updated you can RDP into the VM to configure the disks using Computer Manager -> Disk Management.

Get-AzureRemoteDesktopFile -ServiceName $cloudSvcName -Name $vmname -Launch 

Get-AzureRemoteDesktopFile also allows you to save the RDP files for your VMs to the local file system.

Saving RDP files for all VMs in a Cloud Service

Get-AzureVM -ServiceName fabrikam-cloudapps | foreach { 
	$rdpfile = 'D:\User-Data\Scratch\' + $_.Name + '.rdp'
	Get-AzureRemoteDesktopFile -ServiceName $cloudSvcName -Name $_.Name -LocalPath $rdpfile

Modifying Disk Cache Settings

There is a disk cache built into Windows Azure VMs. Essentially, Windows Azure can use the local physical disk attached to the VM for caching.

The OS disk can support ReadOnly and ReadWrite cache settings with the default being ReadOnly
Data Disks can support None, ReadOnly and ReadWrite with the default being None (The safest choice for data files)

Modifying the Data Disks Host Cache Settings

Get-AzureVM -ServiceName $cloudSvcName -Name $vmName  |
       Set-AzureDataDisk -HostCaching ReadWrite -LUN 0 |
       Set-AzureDataDisk -HostCaching ReadWrite -LUN 1 |

Get-AzureVM -ServiceName $cloudSvcName -Name $vmname | Get-AzureDataDisk

Modifying the OS Disk Host Cache Settings (Requires a Reboot)

    Get-AzureVM -ServiceName $cloudSvcName -Name $vmName |   # Retrieve existing VM 
        Set-AzureOSDisk -HostCaching ReadOnly | # Perform an operation that modifies the returned VM and pipe the results
        Update-AzureVM  # Update the modified VM 

Modifying the VM Size

You are allowed to change the instance size of your VM through the portal and through PowerShell.

Get-AzureVM -ServiceName $cloudSvcName -Name $vmName |
    Set-AzureVMSize -InstanceSize Medium |

TIP: I have separated these updates into separate examples but you should know that they can be combined into one batch update.

Modifying the OS Disk Cache Settings

    Get-AzureVM -ServiceName $cloudSvcName -Name $vmName |   # Retrieve existing VM 
        Set-AzureOSDisk -HostCaching ReadOnly | # Perform an operation that modifies the returned VM and pipe the results
        Update-AzureVM  # Update the modified VM 

P.S. I’ll document some of the changes to the existing deployment cmdlets soon. One thing you will immediately notice though is it is no longer necessary to call Get-OperationStatus after every cmdlet. The cmdlets now handle the waiting automatically.

With this post I hope I get you started learning how to create and manage your virtual machines with the new Windows Azure PowerShell cmdlets. Look for more articles in the very near future that detail some of the more advanced scenarios you can accomplish.

Michael Washam
Senior Technical Evangelist – Windows Azure