Troubleshooting the DSC Extension for Azure

  • Article

The DSC Extension for Azure has been public for just over a month since the initial release during the first week of August (see https://blogs.msdn.com/b/powershell/archive/2014/08/07/introducing-the-azure-powershell-dsc-desired-state-configuration-extension.aspx).  In the short time that it has been available, it has already been updated twice and is currently version 1.2 (as of Oct. 7).  If you’ve been using any of the Azure extensions in your Azure VMs, you will note that they update themselves to the latest version (and I’ll show you how to check in just a minute).  You can use the –Version parameter on Set-AzureVMDSCExtension to specify a version to install and use, but doing so will cause it to NOT be auto-updated.

Those who aren’t familiar with the cmdlets available for the DSC Extension and how to use them should check out the previous link.  To date, there have been no changes to the cmdlets used by the extension, specifically Publish-AzureVMDSCConfiguration and Set-AzureVMDSCExtension.   As such, I’m not going to cover that ground as it was already well covered in the previous post.

What’s the Current Version

As in most things, the very first step is to identify what version of the extension you are dealing with.  This is easily accomplished thanks to the cmdlet made available in Azure PowerShell SDK 0.8.6:

Get-AzureVMAvailableExtension

If you’ve never looked into the extensions that are available, surprise!  At the time of this post, there were 26 extensions available.  Extensions for Visual Studio, Monitoring, Security, Linux, and of course the one we are really interested in: DSC.  To make this a little easier to find, try the following:

 PS C:\> Get-AzureVMAvailableExtension -ExtensionName DSC

Publisher                   : Microsoft.Powershell
ExtensionName               : DSC
Version                     : 1.2
Label                       : DSC
Description                 : PowerShell DSC (Desired State Configuration) Extension
PublicConfigurationSchema   : 
PrivateConfigurationSchema  : 
IsInternalExtension         : False
SampleConfig                : 
ReplicationCompleted        : True
Eula                        : https://azure.microsoft.com/en-us/support/legal/
PrivacyUri                  : https://www.microsoft.com/
HomepageUri                 : https://blogs.msdn.com/b/powershell/
IsJsonExtension             : True
DisallowMajorVersionUpgrade : False
SupportedOS                 : 
PublishedDate               : 10/7/2014 3:50:12 PM
CompanyName                 : Microsoft Corporation

As you can see, 1.2 is the current version and it was just released.

What Version Do I Have

If you have already used the extension on your Azure VM, then it should already be 1.2.  If it was 1.1 (or even 1.0) and your VM was Shutdown, then as soon as it is started the extension will bootstrap and upgrade to the latest version.  This is an awesome benefit to the extensions as it means you always get the benefit of updates and enhancements without needing to do anything on your Azure VM!  But we are curious people and we want to validate this for ourselves, right?  Go ahead, take a look:

On your Azure VM, you’ll see under C:\Packages\Plugins\Microsoft.Powershell.DSC a folder for the current version.  I tried to get a screenshot with 1.1.0.0, but it updated so quickly after Startup I wasn’t fast enough.  Fortunately when the Extension is updated, it will leave log files in place from previous versions.  So in this way, you can see that I used to have 1.1.0.0.

Diving further into the package version folder, we can see that ultimately, the DSC Extension is just made up of more PowerShell and JSON:

Auto-Upgrades?

Yes, I said auto-upgrades.  What, you want to see this for yourself?  Ok!  Let’s dive into the Azure VM Agent log, C:\WindowsAzure\Logs\WaAppAgent.txt.  You’ll see a bunch of boot, extension, network, and heartbeat information.  For DSC Extension 1.2.0.0, the log entry will look like this:

[00000004] [10/08/2014 02:09:19.47] [INFO]  Auto-Upgrade mode. Highest public version for plugin 'Microsoft.Powershell.DSC' with requested version: '1.2.0.0', is: '1.2.0.0'

The next several steps are the download, unpack, installation, and registering of the extension as the latest version on the Azure VM.  And here’s the entry showing that it completed successfully:

[00000010] [10/08/2014 02:09:27.44] [INFO]  Command C:\Packages\Plugins\Microsoft.Powershell.DSC\1.2.0.0\bin\update.cmd of Microsoft.Powershell.DSC has exited with Exit code: 0
[00000010] [10/08/2014 02:09:27.44] [INFO]  Successfully installed plugin Microsoft.Powershell.DSC.

Checking on the Publish

Now that we’ve walked through making sure the correct version is on our VM (assuming that we had used it previously), let’s walk the process a bit.  The first step is to call the Publish-AzureVMDSCConfiguration cmdlet.  As long as the cmdlet doesn’t return an error or fail, you can check the Azure Portal to see if your DSC Configuration ZIP got uploaded correctly.  From this screenshot (Azure Portal ? Storage ? Storage Account ? Containers ? Container Details), you can also see that I left the default ‘windows-powershell-dsc’ container name by not using the –ContainerName parameter:

Fortunately, there isn’t much else to validate for the Publish phase of using the Extension.

Applying a Configuration

Once the Configuration is Published, it can be communicated to the extension using the cmdlet Set-AzureVMDSCExtension along with either New-AzureVM or Update-AzureVM.  Regardless of updating or creating an Azure VM, the background process is ultimately the same.  A create scenario may just take longer before the Extension is installed, initialized and executed.

  1. [Local] Sends the ConfigurationData (if any), Configuration Arguments (if any), and Configuration Data Path to the DSC.
  2. [DSC Extension] Stores both the Configuration Arguments and ConfigurationData locally, if provided.
  3. [DSC Extension] Creates working space for the Configuration.
  4. [DSC Extension] Downloads the Configuration from the Blob storage using the 1-hour token.
  5. [DSC Extension] Executes the Configuration + Configuration Arguments.

We can validate that the Configuration Arguments arrived on the Azure VM by looking at C:\Packages\Plugins\Microsoft.Powershell.DSC\1.2.0.0\RuntimeSettings.  In this folder are <#>.settings files that are JSON formatted and should contain the Arguments passed via the cmdlet earlier (as well as some other details).  If you believe the DSC Extension is having a problem downloading the Configuration from the Blob, you can combine the values of ModulesUrl and SasToken and paste the single combined string into your web browser.  If it tries to download the file, life is good.  Otherwise, a 403 error may indicate that the 1-hour token has expired or is invalid.  If this happens, the only way to fix it is re-issue the Set-AzureVMDSCExtension (thus resetting the SasToken with a new 1-hour timer) and Update-AzureVM.

Steps 3 – 5 of the process are written to the log in C:\WindowsAzure\Logs\Plugins\Microsoft.Powershell.DSC\1.2.0.0.  Here you’ll see a file named ‘DscExtensionHandler.<#>.<DateTimeStamp>’ (see that <#> ?  It correlates to the <#> of the settings file we looked at earlier!).  This file shows the creation of the workspace, the steps to download the Configuration from the Storage Blob, and the eventual running of the Configuration on the machine itself.  Any errors here (post-download) are DSC errors and should be reviewed using the same steps to troubleshoot DSC on node.

In the Portal UI

For those that want a quick and easy way to check on both the version and the status of the extension, you can get this information in the Azure Portal.  On the Dashboard for the VM, scroll to the bottom and you’ll see the Extension information (Name, Version, Status, and Message):

As you can see, my DSC Extension is showing as 1.2.0.0.  Note the Message given is the error we talked about earlier (403 error due to the 1-hour SasToken expiring).  For those with a keen eye, the Status shows ‘Ready’ even though the Message is clearly an error.  This has been fixed in the new UI which should be available soon.

Review

Hopefully I’ve been able to provide a little insight into the DSC Extension for Azure, what the general flow is, and where the log files are.  Once the Extension executes the DSC Configuration, regular DSC troubleshooting takes over (DSC logs, event logs, etc).

Special Thanks

The Azure cloud changes, improves, and grows at an incredible speed.  Without the help of Norberto Arrieta and Abhik Chatterjee, I would not have been able to write this post.  Thanks to both for their knowledge, guidance, and patience as I learned and asked questions about DSC and the DSC Extension for Azure.

/David