New PowerShell Cmdlets on Azure

Blog

One of the new features released within the last month on Windows Azure was the Remote Desktop capability.  This gives you the ability to connect into one of your running instances via the standard Remote Desktop capability that most operations folks would be used to.  If you want some quick instruction to get this set up for yourself check out the MSDN docs.  If you want to hear about it from Ryan Dunn and Steve Marx, you can watch the recent Channel 9 Cloud Cover episode (the remote desktop feature discussions start at about 27:08 in the video). Pay really close attention to their warnings about making changes to your instances via RDP without updating your deployment so that those changes are included in the next deployment of that service.  That really is the danger of this type of feature in the Azure environment.

Something that Ryan and Steve didn’t talk about was that there are a few new PowerShell Cmdlets that are included only on Azure Role Instances.  These were showed off a bit at PDC during one of the demos.  Ever since then I’ve been waiting to see all the cmdlets that would be made available.  Turns out, there are four:

  • Set-RoleInstanceStatus – Set the status of the instance to either Busy or Ready.  (This is what was shown in the PDC Demo)
  • Get-ConfigurationSettting – Get a value from the ServiceConfiguration file.
  • Get-LocalResource – Get a handle to a local resource that was defined in the service definition file for the service.
  • Get-RoleInstance – Get role instance information for the current instance or another instance in the deployment.

To get started with using these cmdlets after you remote into the instance you’ll first have to load the snappin that contains them (which is something I originally forgot about and thought that they didn’t make it into the release).  Open up PowerShell on the remote instance and type the following:

Get-PsSnapin –registered

image

This will get a list of the registered PowerShell Snappins that are registered on the machine, but aren’t loaded.  This step really isn’t necessary, other than you’ll need the name of the snappin before you can load it.  Once you know the name you can skip straight to loading it with:

Add-PSSnapin Microsoft.WindowsAzure.ServiceRuntime

This tells PowerShell to load up the snapin and make the cmdlets available to the PowerShell session.  Now we can get the list of available commands by using the following:

Get-Command -PsSnapin Microsoft.WindowsAzure.ServiceRuntime

image

You can then use PowerShell’s excellent built in command discovery by typing help {commandName} –full, so for example:

Help Get-ConfigurationSetting -full

The Cmdlets

The Set-RoleInstanceStatus cmdlet makes a lot of sense for the main use case of the Remote Desktop feature – troubleshooting issues.  You can remote onto the machine and then use this cmdlet to take the instance out of the load balancer rotation by calling:

Set-RoleInstanceStatus -Busy

This will inform the fabric to take the instance out of the load balancer rotation, but it only lasts as long as the PowerShell instance that called it is running (even if the PowerShell process dies unexpectedly! I killed the process just to see how it would react and the instance came back on line), or until you call the cmdlet again with a -Ready argument.  Note that this isn’t instantaneous.  There is some time where the fabric agent communicates this change to the fabric and then the load balancers are updated.  But, if you run this command you should see the instance go “busy” in the management portal within a minute or so.  I did this with a single instance deployment and when I attempt to hit the site I got “Connection failed”, which makes sense.

The Get-ConfigurationSetting cmdlet could be useful in scripts to help pull out what is in the service configuration file for specific settings.  Note that you have to ask for a setting that is configured, you can’t use this to get a list of the settings or iterate them. 

You can use Get-LocalResource to get at the local resources that were defined in the ServiceDefinition file and exposes the RoleEnvironment.GetLocalResource method to PowerShell.  This would be useful for getting the physical path on the server where the local resource is stored. So if you have a local resource set aside for scratch file IO during your processing you can use this cmdlet to get the physical directory and take a peek at the on machine local store.  For troubleshooting this makes a lot of sense.

The Get-RoleInstance cmdlet is probably the most powerful cmdlet of the four.  It gives you the ability to take a peek into the deployment by getting access to data for any of the running instances of the deployment.  You can get at data for the roles that are running, number of instances of each role, how they are spread across update and fault domains and the endpoints for each of the instances. 

Conclusion

It will be interesting to see if/what other cmdlets appear on the Azure boxes in the future.  While I think the main idea of these cmdlets is to help in troubleshooting issues on deployed instances I think I could also see a use for them during instance start ups for scripts run in PowerShell (thought I’ve not tried doing that…maybe another blog post).