Using the native DSC resources

In my previous posts the focus was on giving some background into how desired state configuration DSC works, some ideas about how to use it, and some details around a very simple example.

Here I am going to walkthrough a configuration that uses a number of the built in DSC resources to apply a configuration.

First, I want to back up a bit and mention a concept.  If you read through many of the blog posts and TechNet documents out there all of the examples you see you could easily describe as being installation focused.  Or only making changes to the system that one would do when installing something.  And this observation is correct.  DSC is still in that v1 state at this writing which means that folks are getting used to it, using it, extending it.  And frankly talking about installation actions is relatively easy. 

One thing I want to mention now is that anyone can build a Custom Resource.  And if you want to configure an application, this is the way to go.  Put all of your complex logic into that custom resource.  Or, wait for the software vendor to write that custom resource so you can use it.  And you may need to ask them to do that for you to get the ball rolling.  There is nothing that says that DSC cannot be used to configure the applications that it also installs in a previous step.  We will get closer to that later on.

Back to this example, installing a Citrix License Server using DSC resources.

Before we get into my example I want to mention a couple things:

1. In my setup I am using the full XenDesktop media ISO as a ZIP archive and I am hosing it on an HTTP endpoint (IIS Server).  This is an internally hosted, isolated, and unsecured endpoint - it is strictly an example to demonstrate different resources and possibilities.  In other words, please learn from the example but please "don't do this at home". 
2. Also,  I am not demonstrating any commands that are not already documented in Citrix eDocs nor the DSC documentation in TechNet.  You need to read those sources for the definitive and current documentation.

Here is the configuration script sample:

Lets start to work through this example.

On line 3 is something new; Import-DscResource.  This is now modules are invoked when they are not shipped as part of the operating system.  Prior to being able to apply this configuration the module xPSDesiredStateConfiguration must be in the PowerShell path.  If you observe the behavior of a Pull configuration you will notice that it uses the path "%programfiles%\WindowsPowerShell\Modules" - and because of that I tend to use that one myself.  More on custom resources later.

On lines 7 - 12 you see the [File]citrixFolder resource that I have been showing in the previous articles.

On lines 14 - 31 is something new as well.  The Script resource. 

This is a utility resource that fills a gap when there is no other resource available to perform your actions.  When you use the Script resource you essentially write a mini custom resource - it has all the same base requirements of a custom resource provider. 

In this case I am using the web client to download the XenDesktop media to the %programdata% path I defined with [File]citrixFolder.  You might also notice that there is a dependency on that previous resource to ensure that the path exists prior to downloading.

Lines 33 - 39 use the Archive resource.  Here I define the path where I know the ZIP exists (previous dependency), and the destination I want it extracted to.

If you run the -Verbose switch when applying this configuration you will notice some interesting behavior with this provider.  The archive provider actually opens the ZIP, reads every file and tests the destination for the existence of the file.  If a file exists, it is not extracted, if it does not exist it is extracted.  This is just a bit of insight into the thinking around how desired state works and what it means to apply a configuration.

Lines 41 - 50 use the Package resource.  This resource is used to install or uninstall packages.  It is centric to MSI packages but it can also be used with EXE packages.  The installer must support silent installation.  Also, as you can see I left the ProductId empty - that is a property of MSI packages so I had to define it this way.

Lines 52 - 57 are the reason for the Import-DscResource.  Within that module is the provider xRemoteFile.  This resource allows me to use a URI as the source.  I defined the source file and my destination - and this places my license file right where my license server default path is.  Ready to go!

Why didn't I use this in place of the script extension?  Good question.  It is because the file I am downloading using the script resource is too large and the download fails at 1.7 Gb in a very reliable way (it is actually a very old bug).

That is it.  The hardest part is getting the infrastructure working to get the media and files delivered.

But quite honestly, MSFT is working on that problem.  Have you heard of OneGet or PSGet?  OneGet is all about packages, packages that could be used by DSC.  PSGet is about PowerShell modules.  And, you can set up your own internal version if you don't trust the public repositories.  But the nifty thing is this; ISVs can publish their packages to OneGet - and then their customer just points to it and before you know it that application is downloaded and installed.  Really nifty delivery method - almost like yum for Windows.

The next step for DSC configurations

Just to recap, this is a series regarding Desired State Configuration which shipped with Windows Management Framework v4 (Server 2012 R2 / Windows 8.1).  There are some references in my first article if you want to get deeper, and there is always TechNet and MSDN documentation.

In this article I am going to expand on my simple example from the last article.  Step it up a notch if you will.

The first thing I am going to cover is the DependsOn property.

This is why each of your declared resources has a name.

Lets consider the following sample:

The Log resource DependsOn the File resource citrixFolder.  What this means is that the File citrixFolder must complete or else the Log afterCitrixFolder will not be attempted.  Another way to say this is that the test for citrixFolder must return True.

This allows a chain of dependencies to be defined.  Defining them here, the configuration author must know about the dependencies and declare them.  Another option is that the resource provider itself is aware of dependencies and enforces them, but that is definitely an advanced topic.

In the last article I had mentioned that the Local Configuration Manager configuration could be changed.  This to is a configuration, and a special command.

Here is my scenario, I have a package installation that DSC is handling for me.  This is a complex installation and it requires two reboots for everything to be installed properly.  I want DSC to handle the rebooting, I don't want to have to setup jobs and start-up commands and the like as in the past.

For this I use the following example;

The first thing to notice is lines 6 through 10.  This is a special resource; localconfigurationmanager.  It supports modifying the properties of the LCM itself.  In this case the reboot behavior is false by default and I want to set that.

After I generate the MOF document, there will be two documents in the .\sample path.  The localhost.mof as before and a localhost.meta.mof that defines the behavior of the LCM.  Set-DscLocalConfiguraitonManager applies the LCM configuration and then Start-DscConfiguration applies the remainder.

If you have done any blog reading of DSC you would most likely have run across the 'Pull' model (and realize that I have been showing the 'push' model) of applying and managing configurations.

I bring this up now just to mention that the Pull model requires the LCM to be configured this way; as shown here:

In this sample I am setting the GUID that matches the configuration of this machine, I am telling it that it is using WebDownloadManager to download its configuration, the URL of my DSC Pull Server, that it will only apply the configuration and then stop, that it will reboot, and I set the frequency down to the minimum since I am impatient.

Just like above, This is a modification of the Local Configuration Manager on the target machine.

The Pull model is pretty handy, as there is simply one web endpoint where configurations call home to and then fetch their configuration and apply it.  If I change the configuration, I change it here and when the node performs its refresh it will look to see if the configuration changed and if it did the new configuration is downloaded and applied.

Pretty slick feature.  But I have to admit, keeping a bunch of GUIDs straight is not the easiest thing.  In this mode each configuration is the GUID identified by the ConfigurationID.  And you have to make sure you give the right configuration ID to the right VM.

Optimally, you set up an array and simply randomly assign one configuration to a machine out of a bunch of machines and wait for the magic to happen.  That is really where that model works.

If you really want to get into all of the possibilities of applying configurations to machines there is a good blog article that describes the options when you want your machine to automatically configure on boot up with DSC.  There are some interesting options in there such as

• using mini-setup and the unattend.xml to set a task to run a configuration script on boot.
• drop a pending.mof in the path %systemdrive%\Windows\System32\Configuration (mount the vhd and copy the file in) that the LCM will automatically process on boot
• inject a meta-configuration (the configuration of the LCM) to download its configuration document

Not mentioned is that you can use and agent in the VM to execute a script, set a MOF, or trigger the LCM in a number of combinations.  And there is also remote applying a configuration as this is what Start-DscConfiguration uses by default using the -ComputerName of a remote machine (you have to be administrator).

Using SCVMM Service Templates the DSC configuration script would be the 'script application package' being executed by the SCVMM agent.  And the model is similar for a Windows Azure Pack Gallery Image.  If you are deploying to Azure you can use the VM DSC Extension or the VM Script Extension - both through the Azure API.

So, as you can see, the flexibility is all over the place.

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.

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: http://www.citrix.com/content/citrix/en_us/downloads/xendesktop/betas-and-tech-previews/desired-state-configuration-resource-provider.html

This goes along side the SCVMM Service Template and the Windows Azure Pack Gallery Image - which are available from here: http://www.citrix.com/go/xendesktop-for-the-private-cloud.html

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!

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:

• The DSC Book - A free resource from Don Jones and Steve Murarwski
• Windows PowerShell Desired State Configuration Revealed - from Ravikanth Chaganti  
• PowerShell.org and PowerShellMagazine.com

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.

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 Citrix.com.

(Yea!)

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.

https://www.citrix.com/downloads/xendesktop/betas-and-tech-previews/xendesktop-75-windows-azure-pack-gallery-image-tech-preview

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.