Troubleshooting the DSC Extension for Azure


The DSC Extension for Azure has been public for just over a month since the initial release during the first week of August (see http://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                        : http://azure.microsoft.com/en-us/support/legal/
PrivacyUri                  : http://www.microsoft.com/
HomepageUri                 : http://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

Comments (5)

  1. What if I want to check the status of the DSC configuration in my script, right after the Update-AzureVm call? I wanted to automate this and report any errors to my script caller. I made this question in StackOverflow for this purpose:

    http://stackoverflow.com/questions/26631821/how-do-i-get-feedback-about-dsc-execution-on-an-azure-vm

  2. DCtheGeek says:

    Juliano – There are a few ways to do this. You can call the REST-based API as I described in a recent post (http://blogs.technet.com/b/learningittogether/archive/2014/10/27/using-rest-api-from-powershell-to-get-additional-azure-vm-status-details.aspx).
    You could also use Get-AzureVM to drill into the value (just like parsing the REST response) like so:
    ((Get-AzureVM -ServiceName "" -Name "").ResourceExtensionStatusList | Where-Object { $_.HandlerName -eq ‘Microsoft.PowerShell.DSC’ }).ExtensionSettingStatus.Status

  3. Anonymous says:

    If you haven’t yet started using the Azure Preview Portal and are a fan of PowerShell DSC and the Azure

  4. aw says:

    hai, I just want to tell you that I am just very new to blogs and seriously loved this website. More than likely I’m planning to bookmark your blog post .
    You amazingly come with really good posts. Thanks a lot for sharing your blog Microsoft.
    http://www.wisatasia.id/2016/02/pantai-dreamland-bali-destinasi-pantai.html Pantai Dreamland Bali, Destinasi Pantai yang Eksotis dan Alami

    http://www.wisatasia.id/2016/02/pantai-kuta-bali-dari-romantisme-yang.html Pantai Kuta Bali, dari Romantisme yang Kental hingga Berselancar

    http://www.wisatasia.id/2016/02/pantai-pandawa-bali-nuansa-eksotis.html Pantai Pandawa Bali, Nuansa Eksotis Penuh Ketenangan

    http://www.wisatasia.id/2016/02/pantai-selong-belanak-lombok-wisata.html Pantai Selong Belanak Lombok, Wisata Bahari Penuh Kedamaian

    http://www.wisatasia.id/2016/02/pesona-10-tempat-wisata-di-bali-paling.html Pesona 10 Tempat Wisata di Bali Paling Menawan

    http://www.wisatasia.id/2016/02/pesona-diving-di-tempat-wisata-pulau.html Pesona Diving di Tempat Wisata Pulau Weh Sabang

    http://www.wisatasia.id/2016/02/pesona-menakjubkan-di-pantai-senggigi.html Pesona Menakjubkan di Pantai Senggigi Lombok

    http://www.wisatasia.id/2016/02/pulau-wayag-surga-penyelaman-di-raja.html Pulau Wayag, Surga Penyelaman di Raja Ampat

    http://www.wisatasia.id/2016/02/wisata-gili-trawangan-pesona-bahari.html Wisata Gili Trawangan, Pesona Bahari Lombok yang Menawan

    http://www.wisatasia.id/2016/02/wisata-gunung-rinjani-lombok-lanskap.html Wisata Gunung Rinjani Lombok, Lanskap Eksotis dari Ketinggian

    http://www.wisatasia.id/2016/02/wisata-karimunjawa-satu-destinasi.html Wisata Karimunjawa, Satu Destinasi Bahari Menawan di Indonesia

    http://www.wisatasia.id/2016/02/wisata-pulau-komodo-taman-nasional-di.html Wisata Pulau Komodo, Taman Nasional di NTT Paling Populer

    http://www.wisatasia.id/2016/02/wisata-tanjung-lesung-destinasi-bahari.html Wisata Tanjung Lesung, Destinasi Bahari Banten yang Memikat

    http://www.wisatasia.id/2016/02/wisata-tumbak-pesona-bunaken-jilid-ii.html Wisata Tumbak, Pesona Bunaken Jilid II di Minahasa Tenggara

    http://www.wisatasia.id/2016/02/wisata-ubud-bali-kedamaian-mengagumkan.html Wisata Ubud Bali, Kedamaian Mengagumkan di Pulau Dewata

    http://www.wisatasia.id/2016/02/wisata-ujung-kulon-perjalanan-ke-taman.html Wisata Ujung Kulon, Perjalanan ke Taman Nasional Banten Terpopuler

    http://www.wisatasia.id/search/label/Wisata-Indonesia wisata indonesia
    http://www.wisatasia.id wisatanya indonesia dan dunia

  5. I delight in the details on your web sites. Thanks a ton!|

Skip to main content