Easy Debugging of PowerShell DSC for Azure Virtual Machines

Many of the Kloud team have recently been buried deep in the world of Azure Resource Manager (ARM) as it becomes the preferred way to create and manage Azure resources.

One extension point offered via ARM for Virtual Machine automation is the use of PowerShell Desired State Configuration (DSC) to control the Windows OS (and now Linux too!) and application software setup on a VM post creation.

I hadn’t touched PowerShell DSC much prior to the last year and have found that it’s not that hard to pick up, especially if you come from a programming, scripting or Linux sysadmin background.

Azure VM and DSC Provisioning Process

I’m going to talk a bit about this process because it directly impacts how you build and debug your custom Azure VM DSC Modules.

When you use PowerShell DSC in an Azure VM deployment process a set of steps occurs as shown below.

Once the Virtual Machine is provisioned, the post-provisioning process will install any extensions required (such as PowerShell DSC). While this is great, one downside is that it does generally result in longer provisioning times for VMs as some extensions require server reboots.

When the DSC framework is ready to run, any DSC Module you have defined in your ARM template (see an example template on GitHub) is downloaded and executed.

Tip: Consider provisioning a larger VM initially so that provisioning times are reduced through use of the additional compute resources available. Once provisioning is finished you can downsize the VM accordingly.

Debugging Fun

So… given the time it can take to provision a VM and deploy the DSC framework components it is apparent that you have to find a quicker way to debug your custom DSC Modules. This is what we’re looking at now!

In the remainder of this post I’m going to use the DSC Module associated with the below snippet as way to show you how we can debug Modules quickly.

When deployed, the DSC extension (the extension is currently at version 2.8) creates a folder at this location on the target Azure VM:

C:\Packages\Plugins\Microsoft.Powershell.DSC\2.8.0.0\DSCWork\

Once that is done it downloads the referenced Module zip file from the URL provided and upacks that into a subfolder as so:

C:\Packages\Plugins\Microsoft.Powershell.DSC\2.8.0.0\DSCWork\ConfigureWebServer.ps1.0\

Note: I’ve found that the current release of the extension will not download a new zip file on each execution which is why I came up with this debugging process.

You can remote into the VM, start an Admin-level PowerShell command prompt and change to the above folder and use the following process to debug / develop.

You will find any custom Module code your package has deployed is downloaded and held here:

C:\Program Files\WindowsPowerShell\Modules\

Executing a change

When you change your PowerShell you need to regenerate the Management Object Format (MOF) file that goes with it.

We can do this by “dot sourcing” the PowerShell script at our already open command prompt thus:

[code language=”PowerShell”]
. .\ConfigureWebServer.ps1
[/code]

Literally type a full stop, a space and then the name of your PowerShell DSC file. At this point you have full access to the internals of the PowerShell file and can force the DSC framework to create MOF file for the local machine using this command (at the same command prompt you dot-sourced at above):

[code language=”PowerShell”]
Main -MachineName localhost
[/code]

Note that “Main” above is the name of the Configuration in the ConfigureWebServer.ps1 file. This can (and will) change depending on the source of the DSC configuration. You may also have different parameters you need to pass in (in my sample I am expecting “MachineName” to be provided).

Once you’ve done this you can now test out your new DSC code by running this command at the PowerShell command prompt:

[code language=”PowerShell”]
Start-DscConfiguration Main -Wait -Force -Verbose
[/code]

Once you have your configuration running as you want you can then package up the PowerShell and MOF files in a zip file and use the configuration going forward in your ARM templates.

Happy days!