Monday, September 22, 2014

How does Desired State Configuration work

Windows Management Framework v4 included a new feature; Desired State Configuration.  This is the second in a series of articles describing Desired State Configuration with the intent on giving a sip instead of a fire hose to get you into it.

In the previous post I made an attempt to introduce all of the moving parts of Desired State Configuration.  This is an introduction to the basics of the ability it brings and I am going to describe how it works by walking through a very basic sample.

Just to avoid confusion, I am going to follow the pattern that you see in many of the blogs, with a lot of words around it.  That said, it is rare to find a discussion of the MOF document itself.  Most articles focus on generating the MOF configuration and then applying it.  But I want you to be clear that there is a separation.

In my sample I am working in the PowerShell ISE instead of a console.  It is still just a PowerShell session running in my security context.

I am going to assume that you know what localhost is (the machine where I am executing commands).

First of all, I have a PowerShell script (a series of commands) that creates a configuration in memory, writes that configuration to a MOF document, and then applies that configuration to localhost.  MSFT refers to this configuration as configuration data at this point.  It is not a configuration until it is written to the MOF.

Here is the sample that relates to this article:

Lets first look at lines 2 - 14.  The special function 'configuration' is being used to declare a configuration named 'sample' surrounded in brackets.

Within the configuration 'sample' is one node element, it is named 'localhost'.  This node specifies the computer(s) the configuration applies to. It must match / resolve to a computer name for the configuration to be applied.  I could quickly get complex here and I am consciously trying to avoid that.  Lets just keep this to the local computer at the moment*.

Within the node is a state of a DSC Resource.  In this case the File resource which is built-in.  I named this File state 'citrixFolder' (each defined state has a name, I will mention more about that later).

The File resource has parameters.  I have defined that ensure is 'present' (it exists), the type as 'Directory' (so that it does not think I am defining a File), and the path.  If I stated this I would say: "ensure that a directory named 'EasyButton' exists at the path C:\ProgramData\Citrix\EasyButton"

I then close each element of the configuration.

On line 17 I call the configuration named sample - the same way you would call a function.

What this does is generate a folder .\sample and within that a MOF document - .\sample\localhost.mof  (note the '.\' in the path.  Since I did not define a literal path for the output).

If I look at localhost.mof, I can see how this looks in the MOF format.

You can see that it was generated by me, and my workstation is named scooter, as well as the time and date, and the configuration that I defined for the node localhost.

Now, lets apply this configuration - make it a reality.  That is where line 20 of the sample script comes into play.

I start the DSC Configuration engine and tell it to apply the configurations found at .\sample to the computer localhost.  I force the action, I request verbose output, and I want to wait.  Verbose is handy to show you what is happening.  Waiting makes the configuration run within the session, instead of off on a job thread.  Useful for debugging.

As you can see from the verbose output the first thing that happens is that the current state is evaluated.  Then the local configuration manager decides if it needs to make a change.  In this case the test of "is the directory C:\ProgramData\Citrix\EasyButton present" returned false.  So the Set is called to make that change.  The change returns a success and the local configuration manager moves on.

The behavior of the local configuration manager can be modified as well.  Since a configuration can be applied (make the changes), or applied and enforced (make the changes and be sure nothing changes), or applied and monitored (make the changes and toss an event if something changes).  More about that later.

* I am sure that some of you could imagine multiple node names, or multiple node elements (one big document defining multiple nodes) with the same document fed to them all.  Then only the configuration that matches the computer name is applied.

Friday, September 19, 2014

DSC resource for XenDesktop in TechPreview

In true form to the blogging I am doing around desired state configuration - the resource for XenDesktop went live as a Technology Preview today.

You can find it here:

This goes along side the SCVMM Service Template and the Windows Azure Pack Gallery Image - which are available from here:

Why is there a DSC resource for XenDesktop?  Frankly, DSC is a really cool feature of windows management framework (aka PowerShell) v4 and I think everyone wants to play in the DevOps pool (or should at least learn how to).

Most of all, I really want your feedback about the desired state configuration resource.  How you use it, what more you would like to see, what it is lacking, what it does not do for you.  I want to know it all.

We have a survey to capture this.  Or, you can simply reply with comments.  There is also a support forum where I will be fielding issues.

Happy hands off installs!

Wednesday, September 17, 2014

What is Desired State Configuration?

Desired State Configuration (DSC) is a feature of the Windows Management Framework v4 (many folks just call this PowerShell v4) which ships natively with Server 2012 R2 and Windows 8.1.

One thing to be clear on; DSC is not a single thing, it is a feature with different components.  And this is an exploration of the main components at a high level to understand all of the concepts.  Lets take a look at the moving parts that work together to enable DSC; the configuration keyword, a configuration, the Local Configuration Manager, resource providers, WinRM, PowerShell.

Before I get to deep into this I want to thank some fellow MVPs who have the award area of PowerShell for helping me with a few things as I worked through my understanding.  I also want to thank the product team at MSFT for taking some time to sit with me and talk as a customer, helping give me more insight and giving them feedback into my scenarios and my customers' scenarios.

The MVP community is great at producing resources and communicating out.  Here are a few good resources:

Lets begin with the first stumbling block.  Windows Remote Management (WinRM)

WinRM is required for DSC to receive and process configurations in a Push or Pull model (more about those later).  Let me say here that if you are learning and follow any of the examples and apply a configuration; you will likely be applying a configuration interactively at the console (Push model).  This will simply work out of the box if your target is Server 2012 R2.  This is will simply fail out of the box if your target is Windows 8.1.

The difference?  WinRM is enabled by default on Server and disabled by default on Client.  So plan accordingly, or you will get error messages that you cannot apply your configuration because WinRM is not running.

PowerShell is the enabling technology and the owning product team at MSFT.  If you are following recent PowerShell developments you have heard about OMI.  And if you recently listen to Jeffry Snover talk about DSC you will hear mention of the Monad Manifesto, and that DSC is a component of the original Monad vision that is realized as 'PowerShell'.

The Local Configuration Manager (LCM) can be thought of as the agent that makes it happen. 

The LCM is essentially a service that takes the configuration, parses the configuration, sorts out the dependencies defined in the configuration, then makes that configuration happen.  The key thing to understand is that all configuration are applied in the security context of the Local System.  By default this allows no access to anything outside the machine, and can only act on objects that are local to the machine.  For example; if a software package is being installed, that package must be local to the machine, or the machine must be able to access it within its security context.

Did you get that DSC is not a management layer?  It is the lowest level execution engine / the enabler / the Riker to Picard (this is the analogy that the PowerShell team originally used). 

In fact companies like Puppet and Chef are already taking advantage of DSC, using it to do their dirty work and are not threatened by it.  And MSFT has enabled DSC as a VM Extension to apply configurations to Azure IaaS virtual machines through the API.  Also, if you have SCVMM Service Templates or Windows Azure Pack Gallery Items; they too can use DSC as then end engine that performs the configuration actions.

Now we get down to the configuration itself.

The configuration is a MOF format document that defines the end result that the Local Configuration Manager must make happen.  The MOF can be generated in a number of ways, but the easiest by far is to use the configuration keyword within a PowerShell script.

The configuration keyword is nearly the last enabler.  You can call it within a script to define this special thing called a configuration.  That is then realized as a MOF file.  That is in turn applied to the LCM.  Which in turn makes it so.

Now, there is the last enabler.  The resource provider. 

These are special modules - they are task built and their whole job is to Get the state of some resource, Set the state of some resource, and Test the state of some resource.  The resource is the item being manipulated.

There are resource providers that are built into the OS; archive (handling ZIP files), file (manipulating files), package (installing / uninstalling packages), and so on.  Each one of these is declared in a configuration with the state you desire it to have.  And you can perform actions such as unzipping an archive, copying a file to a specific path, installing / uninstalling a specific MSI, and so on.

There is also a framework for custom resource providers.  This is to extend support to third party applications such as XenDesktop, or to allow the community to build modules that do far more than the ones provided by MSFT.

There are also MSFT provided 'x' resource providers.  But frankly, I am hoping that PowerShell v5 will include many of these at a release quality level.  Until then, they are just like any other custom resource.

Wednesday, September 3, 2014

XenDesktop Windows Azure Pack Gallery Image Tech Preview

Today we launched our XenDesktop 7.5 Windows Azure Pack Gallery Image Tech Preview as a download from


This is open to customers and prospective customers and is intended to simplify and automate XenDesktop deployments for large enterprises and service providers who leverage Windows Azure Pack, System Center, and the Microsoft Cloud OS stack.

If you are not already familiar; a Windows Azure Pack Gallery Image is a standard, reusable, and sharable artifact that allows customers of a large enterprise or service provider to self-serve provision virtual machine roles as a repeatable configuration.

The current XenDesktop specific Gallery Image can installs all XenDesktop roles.

We are also looking for feedback regarding where to take this next. So as always, you can add comments here, or find me on Twitter, or email me directly. 

This is a continuation of similar efforts to streamline XenDesktop deployments that we rolled out with the XenDesktop System Center Templates launched for XenDesktop 7.1 late last year and for XenDesktop 7.5 in the last couple of months.


Friday, August 15, 2014

Getting errors from the Azure VM customer script extension without RDP

Since Azure has begun adding the VM agent and other extension to IaaS virtual machines (persistent VM Roles) a number of scenarios and possibilities have opened up.

The extension is a simple binary that is dropped into your VM and built to be triggered and to perform very specific actions in the security context of Local System.

The Desired State Configuration Azure extension is the very latest. 

Prior to this I have been spending some time with the Custom Script Extension.  And it is rather nifty.  But the biggest pain that I have had is in working through the process of troubleshooting the script as I develop it.

I have found no way to capture the standard output - other than directing to a text file.  But then I have to RDP into the VM to fetch it.

I can also look at the runtime status of the extension while connected over RDP - that that is one file with bad line endings, making it difficult to read in Notepad.

Trough a bit of searching I came across a few tips and started poking around a bit with the Azure PowerShell cmdlets. 

What I discovered is that you cannot get the standard output, but you can get the standard error through the API.  So, if the script tosses some terminating error, there is output to be fetched. If there was no error, there is no output to be returned.

What I ended up doing is the following:

New-AzureVM -Location $location -VM $vmConfig -ServiceName $Service

(Get-Date -Format s) + " .. Watch the script extionsion to monitor the deployment and configuration"
Do {
    $Vm = Get-AzureVM -Name $vmName -ServiceName $Service

    Get-Date -Format s
    "  Machine status: " + $Vm.Status
    "  Guest agent status: " + $Vm.GuestAgentStatus.FormattedMessage.Message
    foreach ( $extension in $Vm.ResourceExtensionStatusList ) {
        If ( $extension.HandlerName -match 'CustomScriptExtension' ) {
            "  ExtensionStatus: " + $extension.ExtensionSettingStatus.FormattedMessage.Message
            $scriptStatus = $extension.ExtensionSettingStatus.FormattedMessage.Message
            $scriptError = foreach ($substatus in $extension.ExtensionSettingStatus.SubStatusList) { ($substatus.FormattedMessage.Message).Replace("\n","`n") }
    Start-Sleep 10
} until ( ($scriptStatus -eq "Finished executing command") )

I fetch the VM, then drill into the object for the Custom Script Extension, then I dig into the Extension status, and it even has sub status.  It is in this sub status where the Standard Error ends up being bubbled up for the extension.

I realize that this leaves me waiting around and calling back and forth.  But a green light on "Finished executing command" only means the script extension is completed running whatever I told it to run, not that it worked.

I just wish I could get the standard output.