How to push out a Desired State Configuration Pull Server

Hyper-V's new Desired State Configuration feature enables administrators to eliminate configuration drift. Deploy a DSC Pull Server and get started.

Deploying a Desired State Configuration file one server at a time defeats the purpose of the large scale management automation should offer. In a previous tip, I performed a simple deployment to a single server using a simple Desired State Configuration file. It was an important first step, but if you're like me, the joy of discovery was soon replaced by nagging questions. How would I do this to multiple computers? How do I make sure they stay exactly as I describe in the configuration file? How does it all tie together?

I hope to answer some of those questions with this tip, as I show you how to deploy a Desired State Configuration (DSC) Pull Server. Keep in mind that DSC is improving rapidly, so expect to see some changes.

These are the main tasks in setting up a DSC infrastructure:

  1. Deploy a Pull Server.
  2. Configure target computers with a unique configuration ID and Pull Server location.
  3. Create and deploy a configuration script to the Pull Server, which will be received by the target computers.

Sounds simple, but it can be confusing at first. In this tip, we are going to start with configuring the Pull Server.

The ground rules

Make sure you are testing this in a lab environment until you get the hang of things. I have three virtual machines (VMs). One is the domain controller that is going to become my Pull Server, and I have two other servers I'm going to use for deployments. Server S1 is a domain-joined computer and server S2 is not a domain-joined computer. All servers must be running Windows Management Framework (WMF) 4.

Properly deploying DSC configurations

Try setting up a Pull Server yourself

Download a text file containing the PowerShell code used in this article's example.

We deploy DSC configurations using the concept of a Pull Server. There isn't too much black magic in this concept: The target computers will retrieve -- or pull -- their assigned configurations from the Pull Server. The Pull Server can be nothing more than a Server Message Block (SMB) share on any computer in your network. I like the simple SMB share for testing purposes, but there many advantages to setting up a Hypertext Transfer Protocol Secure (HTTPS) Pull Server that the target computers will contact for new or updated configurations. An HTTPS Pull Server makes it easy to deploy modules and custom resources, and is much easier to manage. It therefore is the best for production, and is the one I will focus on here.

When WMF 4 originally shipped, building a Pull Server was more complicated. You had to install Internet Information Server (IIS) and additional components, then properly create the website that will be used by the target computers to retrieve configurations. Today, there is a new custom resource from Microsoft that can do all the hard work. We just need to download the custom resource and write a simple configuration script for the Pull Server.

Getting the latest DSC resources

WMF 4 includes a built-in set of DSC resources, which are actually PowerShell modules. These resources make it easy for you to write and configure servers. After the initial release of WMF 4, Microsoft (along with the PowerShell community) has been feverishly writing additional resources. One example is the new resource that simplifies building an HTTPS Pull Server. First, you need to get the new resources, which were recently released as a downloadable DSC Resource Kit.

Here are a few important points to note with these additional resources:

  • You will need them on every server that uses them in a configuration.
  • You don't need to worry about deploying them because the DSC HTTPS Pull Server will do it automatically.
  • The modules must be copied to this special location on the Pull Server: C:\Program Files\WindowsPowerShell\Modules\
  • The x at the beginning of the modules' names means experimental. So, there is no official support for the resources yet. But if you go to PowerShell.org and post to the forums, there are plenty of DSC pioneers who will help!

You should verify that you properly copied the resource modules to the correct location. Open a Powershell prompt and type:

PS> Get-Module -ListAvailable

You will see the modules listed towards the top with the x at the beginning of the name.

Building the Pull Server

The specific resource needed to help build the Pull Server is called the xPSDesiredStateConfiguration module. You must import this resource before you can use it in your configuration script. Below is a snippet of the important part of the configuration that imports and configures the Pull Server.

DSC modules must exist on the target pull server

The Import-DSCResource cmdlet imports the xPSDesiredStateConfiguration module. Now I can start to define my configuration. First, I'm going to need to install the role service that creates the Pull Server. The DSC-Service role will also install IIS and the additional Web components needed for the Pull Server. I like to also install the Web-Mgmt-Console role service. This is the graphical IIS Manager, and I like to have it around in case I need to perform some troubleshooting or logging in the future.

Import the DSC resource module to the target pull server

The meat of the Pull Server configuration is the xDSCWebService section. This creates a website using port 8080 and allows unencrypted traffic. Before you start screaming for HTTPS, keep in mind that at this point we are sending only configuration information across the wire, not credentials. For an internal set of servers, HTTP is fine, but you can easily put a certificate on the website. The paths to the website and the locations of future configuration files are also defined. PhysicalPath is the location to the main website, ModulePath is the location of custom modules that you want deployed to target servers and ConfigurationPath is the location of the target server's configuration files.

Use the script to create the MOF file and push it to the Pull Server

Using the full script, you will need to create the Microsoft Operations Framework (MOF) file and push it to the Pull Server.

To do this, I added the following lines to the bottom of the configuration script. The first line creates the DSC.MOF configuration in a subfolder named CreatePullServer. The second line pushes the configuration.

CreatePullServer -ComputerName DC

Start-DscConfiguration .\CreatePullServer -wait

In this example, ComputerName DC is the name of my Pull Server. When you run the script, you will soon have a fully-configured Pull Server! I like to verify that the Pull Server is responding by opening a browser and typing the address: http://localhost:8080/psDSCPullServer.svc/

If everything is working, you will receive an XML response similar to the following image:

Test to check that the DSC Pull Server is working

We're not quite done yet. The only task we have accomplished is to create the Pull Server. In a following article, I'll explain how to configure the target computers to retrieve their configurations from the Pull Server and create a configuration for the targets.

Editor's note: This article is the second in a series on learning and using Desired State Configuration.

Dig Deeper on Microsoft Hyper-V management