Learning PowerShell DSC - Second Edition

By James Pogran
    What do you get with a Packt Subscription?

  • Instant access to this title and 7,500+ eBooks & Videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies
  1. Free Chapter
    Introducing PowerShell DSC
About this book
The main goal of this book is to teach you to configure, deploy, and manage your system using the new features of PowerShell v5/v6 DSC. This book begins with the basics of PowerShell Desired State Configuration, covering its architecture and components. It familiarizes you with the set of Windows PowerShell language extensions and new Windows PowerShell commands that make up DSC. Then it helps you create DSC custom resources and work with DSC configurations with the help of practical examples. Finally, it describes how to deploy configuration data using PowerShell DSC. Throughout this book, we will be focusing on concepts such as building configurations with parameters, the local configuration manager, and testing and restoring configurations using PowerShell DSC. By the end of the book, you will be able to deploy a real-world application end-to-end and will be familiar enough with the powerful Desired State Configuration platform to achieve continuous delivery and efficiently and easily manage and deploy data for systems.
Publication date:
September 2017


Introducing PowerShell DSC

"Begin at the beginning," the King said, very gravely, "and go on till you come to the end: then stop."
- Lewis Carroll, Alice in Wonderland
"Don't Panic."
- Douglas Adams, The Hitchhiker's Guide to the Galaxy

Welcome to PowerShell Desired State Configuration (DSC), the new configuration management platform from Microsoft. We begin with a quote from Alice in Wonderland. Besides pertinent advice from the author, it is apropos of what DSC is at its very core. DSC, by the very simplest definition, allows you to write down the beginning, the middle, and the end of your deployment story. The second quote we see is from The Hitchhiker's Guide to the Galaxy, and it is something to remember throughout this book. We will cover a lot of new concepts, some old concepts with new importance, and a lot of PowerShell. Don't panic; we'll get through fine.

This book will begin with the basics of PowerShell DSC, covering its architecture and many components. It will familiarize you with the set of Windows PowerShell language extensions and new Windows PowerShell commands that comprise DSC. Then, it will help you create custom DSC resources and work with DSC configurations with the help of practical examples. Finally, it will describe how to deploy a configuration data set using PowerShell DSC.

By the end of this book, you will be able to deploy a real-world application end to end.

In this chapter, we will cover the following topics:

  • What is PowerShell DSC?
  • Why do we need configuration management and what is DevOps?
  • How does DSC help?
  • A high-level overview of DSC
  • DSC requirements
  • DSC versions

What is PowerShell DSC?

Do you have some software that needs to be installed in a certain order? Software with special configuration steps? Software along with some security policies that must be applied to every server? How about ensuring that a set of services are never enabled to start? Have you ever written scripts to handle this kind of work but found them brittle because of changes in software from release to release? Needed to make these changes on dozens or hundreds of servers repeatedly on schedule? Ever had someone change something and have your script break because the state is not what you expected? These and many more scenarios are handled by DSC.

PowerShell DSC is a new management platform in Windows PowerShell that enables the deployment and management of configuration data for systems and software services and the management of the environment in which these services run. DSC allows you to define the current state of a machine and ensure that the machine is always in that state.

What we mean by state here is everything that is on that machine, including the operating system and software installed, all the configuration settings for the OS and software, and any files or process that need to be present or set with specific content; the list goes on. Whether you considered this earlier or not, all this makes up the configuration of your system. DSC is designed to help you deal with all this configuration data and execute it consistently and repeatedly.

What is PowerShell?

While we assume in this book that you have a basic understanding of PowerShell command-line use and scripting, before we go too much into DSC, it is helpful to describe what PowerShell is compared to PowerShell DSC.

First released in 2006, PowerShell is a scripting language and command-line shell built on the .NET framework. PowerShell provides complete access to COM, WMI, and .NET and also provides a large set of commands called cmdlets to perform administrative tasks on both local and remote systems.

PowerShell can execute PowerShell scripts, PowerShell cmdlets, and standalone executable programs or other language files. PowerShell also provides a hosting API that allows programs to run PowerShell natively inside their program, enabling scripting or automation scenarios. Being both a shell language and a scripting language allows it to be quick as well as terse on the command line, along with being verbose and consistent in scripts.

Over the years, PowerShell has become the de facto way to administer and automate Windows OS and software. As computing environments grow larger and engineering teams become smaller, it is paramount in automating processes and procedures that used to be done by hand. PowerShell provides a consistent command-line language to automate the administration of a large number of scenarios, which are growing every day and were previously not available on Windows. Because of PowerShell's hosting API, applications such as Microsoft Exchange have enabled a command line, first, GUI—second, mode of development, which enables quick deployment and management using automated tools.

PowerShell not only enables the automation at the single system level, but it also scales out to the multi-node environment. Being able to automate your system from the command line or script is fine, but if you have to manually run that script on every system in your environment by hand, then we still have a bottleneck on efficiency. Using an industry standard protocol, PowerShell provides PowerShell remoting as a way of running commands or scripts on any number of remote hosts in parallel. Thousands of computers can be managed at the same time, consistently, in a repeatable and automated manner.

Consistent repeatable automation is important, but PowerShell is also extensible, which is not only essential, but it also leads us into DSC. PowerShell is a both a typed and dynamic scripting language, which means that it supports both static typed objects (System.IO.FileInfo) and objects with methods and properties that are defined at runtime (PSCustomObject and Add-Member). This enables PowerShell to be extended to suit the needs of the user. You do this every day to an extent, by creating functions and scripts to wrap common operations into reusable components or modules. Taking this a step further, PowerShell can be extended to support specific scenarios that were not envisioned when the product was made. DSC is such an extension, as it builds on the existing PowerShell language and infrastructure to enable new uses of the program.

On to PowerShell DSC

PowerShell DSC is released as a feature of PowerShell, so it comes bundled with specific versions of PowerShell that are part of the Windows Management Framework (WMF). The PowerShell DSC version section goes into greater detail about the versions of PowerShell and PowerShell DSC and the available features in each, so we won't get into too much detail here.

The WMF release notes describe DSC in this way:

"Windows PowerShell DSC helps ensure that the resources in your data center are correctly configured. DSC is a set of Windows PowerShell language extensions and providers that enable declarative, autonomous, and idempotent (repeatable) deployment, configuration, and conformity of data center resources. DSC enables an IT Pro, developer, or fabric administrator to define the configuration of target nodes (computers or devices) and prevent configuration inconsistencies or drift."

PowerShell DSC provides a set of Windows PowerShell language extensions, new Windows PowerShell cmdlets, and resources that you can use to declaratively specify how you want your operating system and software environment to be configured. It also provides a means to maintain and manage existing configurations. It supports both an interactive push model, where configurations are executed on target nodes on demand, and a pull model, where a central server manages and distributes configurations.

We won't delve into too much architecture talk here. (The next chapter discusses the architecture and inner workings of DSC in detail.) For now, it is sufficient to say DSC is comprised of both a data file and configuration file that are translated into a text file following the Managed Object Format (MOF). This file is then parsed and executed on the target server, using DSC features that know how to configure the system.

That was a lot of information in a short space, so don't worry if it is a lot to take in at once. We will go over each part as we move on. You don't have to know right away what MOF is or how DSC executes the configuration to use DSC. DSC abstracts all the details away for you. When you get to the point that you need to know these details, DSC still exposes them so you can tweak them under the hood or find out what is really going on.

At a high level, DSC work isn't programming work; it lists how you want a server to look in a special format. The execution of this list is abstracted from the listing, allowing the how to work separately from the why. This is an important concept and really the key to understanding the importance of DSC. Jeffrey Snover, the architect and inventor of PowerShell, explained it best using Star Trek. Captain Picard often used the line "Make it so," and Commander Riker had to figure out how to actually make what the Captain wanted to happen, happen. Captain Picard knew what needed to be done but didn't particularly care how it got done. Commander Riker knew how to get things done but did not concern himself (most of the time) with deciding when and what to do. This separation allowed both officers to be good at their jobs without interfering with each other.

It may be useful to see the following short, complete example of an entire DSC configuration:

configuration BaseServerConfiguration
File ExampleTextFile
Ensure = 'Present'
Type = 'File'
DestinationPath = 'D:FooProductfoo.txt'
Contents = "this is example text"

WindowsFeature DotNet
Ensure = 'Present'
Name = 'NET-Framework-45-Core'

That's it! Sure, there is more to understand and cover, but as we can see here, this is plain PowerShell code that is as readable as any script you've written before, and all it does is list what should be on a system. What this DSC configuration does is ensure that a file is created in the D:FooProduct folder called foo.txt, with the contents this is example text. It then ensures that the .NET framework V4.5 is installed. Yes, .NET 4.5 is most likely already there, but the point of DSC is to describe the state of the target node regardless of what you think might be there. This way, if someone removes .NET 4.5, DSC will ensure that it is installed, thereby maintaining the known good state of the target node.

We will get into this further later, but now you may be asking why it is important to manage the configuration of your systems this way. Read on.


Why do we need configuration management?

Whether you manage a few servers or several thousands, the traditional methods of server and software installation and deployment are failing to address your current needs. These methods treat servers as special singular entities that have to be protected and taken care of, with special configurations that may or may not be documented, and if they go down, they take the business with them.

For a long while, this worked out. But as the number of servers and applications and configuration points grows, it becomes untenable to keep it all in your head or consistently documented by a set of people. New patches that are released, feature sets change, employee turnover, poorly documented software—all these reasons introduce variance and change into the system. If not accounted for and handled, these special servers become ticking time bombs that will explode the moment a detail is missed.

Written installation or configuration specifications that have to be performed by humans and be error-free time and time again on numerous servers are increasingly self-evident as brittle and error-prone affairs. To further complicate things, despite the obvious interdependence of software development and other IT-related departments, the software developers are often isolated from the realities faced by IT professionals during the deployment and maintenance of the software.

The answer to this is automation: defining a repeatable process that configures servers the right way every time. Servers move from being special snowflakes to being disposable numbers on a list that can be created and destroyed without requiring someone to remember the specific incantation to make it work. Instead of a golden image that has to be kept up to date with all the complexities of image storage and distribution, there is instead a set of steps to bring all servers to compliance regardless of whether they are a fresh installation or a number of years old.

What is being described is Configuration Management (CM). CM ensures that the current design and build state of a system is a known good state. It ensures trust by not relying on the knowledge of one person or a team of people; it's an objective truth that can be verified at any time. It provides a historical record of what was changed as well, which is useful not only for reporting purposes (such as for management), but also for troubleshooting purposes (this file used to be there, now it's not). CM detects variance between builds, so changes to the environment are both easily apparent and well known to all who work on the system.

This allows anyone to see what the given state of the system is at any time, at any granularity, whether on one system or over the span of thousands. If a target system fails, it's a matter of re-running the CM build on a fresh installation to bring the system back to a steady state.

CM is part of a set of ideas called Infrastructure as Code. It requires that every step in provisioning an environment be automated and written down in files that can be run any time to bring the environment to a known good state. While CM is infrastructure automation (replicating steps multiple times on any amount of target nodes), Infrastructure as Code takes things one step further and codifies every step required to get an entire environment running. It encompasses the knowledge of server provisioning, server configuration, and server deployment into a format that is readable by sysadmins, developers, and other technical staff. Like CM, Infrastructure as Code uses existing best practices from software development, such as source control, automated code testing, and continuous integration, to ensure a redundant and repeatable process.

The approaches being described are not that new and are part of a larger movement that has been slowly accepted among companies as the optimal way of managing servers and software, called DevOps.

What is DevOps?

The set of concepts we have been describing is collectively termed DevOps and is a part of a larger process called continuous delivery. DevOps is a shortened form of development operations and describes a close working relationship between the development of software and the deployment and operation use of that software. Continuous delivery is a set of practices that enables software to be developed and continuously deployed to production systems on a frequent basis, usually in an automatic fashion that happens multiple times a week or day.

Each year, a company called Puppet Labs surveys over 4,000 IT operations professionals and developers about their operations procedures. Of those surveyed, companies that have implemented DevOps practices have reported improved software deployment quality and more frequent software releases. Their report states that these companies shipped code 30 times faster and completed those deployments 8,000 times faster than their peers. They had 50% fewer failures and restored service 12 times faster than their peers.

Results such as the ones shown in the Puppet Labs survey show that organizations adopting DevOps are up to five times more likely to be high performing than those who have not. It's a cumulative effect; the longer you practice, the greater the results from adoption and the easier it is to continue doing that. How DevOps enables high performance is something that centers around deployment frequency.

To define and explain the entirety of DevOps and, since continuous delivery is out of the scope of this book, for the purposes here the goals can be summarized as follows: to improve the deployment frequency, lower the failure rate of new releases, and shorten the recovery time if a new release is faulty. Even though the term implies strict developer and operations roles as the only ones involved, the concept really applies to any person or department involved in the developing, deployment, and maintenance of the product and the servers it runs on.

These goals work toward one end: minimizing the risk of software deployment by making changes safe through automation. The root cause of poor quality is variation, whether that is in the system, software settings, or in the processes performing actions on the system or software. The solution to variation is repeatability. By figuring out how to perform an action repeatedly, you have removed the variation from the process and can continually make small changes to the process without causing unforeseen problems.


DSC quick wins

While there are many aspects to DSC that are beneficial, it is useful to pause here and list some quick wins that DSC brings us to inspire us to keep reading:

  • DSC configuration and supporting files are all written in the PowerShell syntax. Investments in knowledge about PowerShell are improved upon and expanded in using DSC.
  • DSC is designed to support continuous deployment, so it will react and adjust as your environment changes.
  • When DSC applies a configuration to a target node, DSC resources only change that which does not match the expected state (we will cover the terminology for this and how important this is in Chapter 2, DSC Architecture), ensuring a quick deployment.
  • DSC separates configuration logic from configuration data, reducing the rate of change in your configuration scripts and the variation in your deployments.
  • DSC operates on more platforms than just Windows. DSC has a set of DSC resources that know how to install, configure, and manage Linux target nodes and some network switches. In a heterogeneous environment, having one tool that can address many different platforms is a huge time and cost saver.

DSC high-level overview

We will look into the DSC architecture in much greater detail in the next chapter, but it is useful to show a quick overview of how all the concepts we just covered fit together. DSC has several steps that can be bucketed together into three large phases.

The authoring phase

You begin with DSC by writing a configuration script in PowerShell. The script itself doesn't actually do anything. You can run the script interactively all you want; it won't change a thing. Since the configuration script is the DSL we were talking about earlier, it's only a list of things to do, not the things that actually execute the list. Because there can only be one MOF per target host and each configuration script is translated to an MOF, this means there is usually only one configuration script you write, which handles all the variances in your environment. This sounds like it will get complicated and difficult to manage quickly, but there are DSC patterns to follow in order to manage this. We will cover these in Chapter 3, DSC Configuration Files.

The next step is to translate the configuration script to an MOF file. The translation, or compiling, happens only once—when you deploy the MOF file to the target node or to the DSC pull server. The configuration script is often kept in a version control system and only compiles and deploys the MOF file when the configuration script changes.

The staging phase

The next step is to get it over to the target computer. The deployment of the MOF happens in two ways: push and pull. A push method is when you execute the Start-DSCConfiguration cmdlet, which compiles the MOF and copies over to the target system. The pull method involves putting the MOF file on the DSC pull server, which handles distributing it to all the target hosts.

The execution phase

Whether an MOF file was pushed (using Start-DSCConfiguration) or pulled (using a DSC pull server), the next step is the actual execution of the MOF file. If pushed, the execution happens interactively or in a PowerShell job depending on how you called the cmdlet. If pulled, the Local Configuration Manager (LCM) schedules and executes the MOF file without user input or oversight.

LCM is part of the DSC system installed on the target node and is responsible for receiving, coordinating, and executing configurations on target nodes. LCM itself is configurable using DSC and is flexible enough to allow multiple types of deployments.

The phases described earlier will be covered in much more detail in the upcoming chapters, so do not worry if some of it does not make sense.


Why all the abstraction?

It seems like we are writing scripts just to have them turned into another format altogether, which in turn is converted into something else. Why all the indirection and abstraction? Why don't we write the final result ourselves the first time? The primary reasons are readability and flexibility.

DSC configuration files are written in the PowerShell syntax, which we already established as being consistent and readable. When the configuration is human-readable, it's understandable to the whole team and not just the implementer. It's written down in textual format, so it can be controlled in a source control system such as Git, Subversion (SVN), or Team Foundation Server. Deployment processes (sets of instructions on how to complete a task) are automatically saved and backed up by the source control system and made available to the entire team instead of one person's desktop.

Readability serves more than just the implementer and the team. Written configuration files codify the deployment process in a historical record. In that record, we can see the progression of the system by comparing the text files between releases, thereby monitoring drift and variation.

This increases flexibility by enabling a variety of tools to produce the output DSC can execute. You may have noticed that we keep referring to the compiling to MOF, that the DSC engine reads MOF, and that there is only one MOF per target host. There's a good reason why the end format is MOF and not something else, such as a PowerShell Script.

The MOF was defined by the Distributed Management Task Force (DMTF), which is a vendor-neutral organization that works toward standardized interoperation between platforms. You may not be aware of it, but you have been using their work for quite some time if you have been using Windows Management Instrumentation (WMI). WMI is an implementation of Common Information Model (CIM), which is a DMTF standard that defines a structured way to describe a system and its properties. The Microsoft Developer Network (MSDN) site, https://msdn.microsoft.com/en-us/library/aa389234.aspx, explains that WMI can use CIM on target nodes. The Wikipedia site, https://en.wikipedia.org/wiki/Common_Information_Model_(computing), goes into more information about the history and open standards of CIM.

The DMTF defined the MOF syntax and format so that any vendor or system could implement it. Microsoft happens to be the largest implementer so far, but other tooling companies use it as well. Since any vendor can implement the standard, it means that several important things can happen.

If all DSC needs to function is the MOF file, you don't necessarily need PowerShell to produce the MOF file. Any third-party tool can implement the specification and provide their own (possibly improved) way of compiling MOF files. An open market for tooling gives options to the user. For example, there are many different text editors to write your scripts in; each has its benefits and compromises that you can evaluate and choose between. This enables third-party vendors to compete and provide solutions that suit a given user's needs. Companies such as Puppet and Chef can implement their own or extend what Microsoft has already done.

The most exciting thing is that since the MOF standard is platform independent, the configuration scripts you write can run on multiple operating systems. So whether you run Windows or Linux or both, you can manage the configuration of your systems with PowerShell DSC using a single standard and consistent syntax.


How does DSC help?

PowerShell DSC enables a DevOps structure by providing a consistent, standardized configuration of operating systems and software as part of a continuous deployment pipeline. It increases the rate at which you can deploy by reducing the variation and drift from your existing configurations.

In simpler terms, DSC separates the who from the what and how. This separation of what and how is the core of DSC. Because they are separated, you can continually change the data points of your systems without touching the parts that actually set the system to the desired state.

The who

Band name jokes aside, the who DSC refers to is any target node. Why the separation and distinction? Well, as explained in the MOF earlier, we aren't dealing with just Windows servers. We could possibly be dealing with network switches, Linux servers, storage devices, and so on; the list potentially includes any device in your environment. By setting target node definitions in a structured way, we can describe the nodes in ways that make sense to anyone reading the configurations, as well as the computer's processing the configurations.

The what

The DSC Domain Specific Language (DSL) defines a standardized way of describing the expected configuration of a target system, whether that is one system or several thousand systems. It describes the what of the target node.

A DSL is a specialized set of language extensions and grammar that makes it easier to codify a specific set of problems. On the other hand, a product such as PowerShell is a general-purpose language, DSLs are specifically built to address a specific set of problems.

You may wonder why we are bothering to define and discuss DSL here. You may think it's an advanced topic or something only developers need to know, but you would be incorrect to discount it. DSLs are all around you, and you use them every day. For example, HTML is a human-readable DSL for web browsers to display content. The actual content is binary, but the HTML specification allows humans to write in a language they understand yet also have the computer understand it.

In the case of DSC, the DSL is oriented at expressing all the different ways in which you can describe the expected state of a system in an easy-to-read manner. If you can read PowerShell code, then the DSC DSL is no different than reading a function declaration with a set of parameters. Most importantly, this easy-to-read structure for you is also easy for the DSC parser to read and turn into an MOF file. This abstraction of an abstraction allows you to write configurations in a language you understand and for that to be translated into a language the system understands.

For example, the target system should have a list of software installed, several settings modified, some services that should be enabled and started, some users to be created and then added to a local group, and several files to be created and have content added to them. It reads like a grocery list to you, but the computer can understand and execute it the same way every time it runs.

The how

The DSC language extensions, cmdlets, and resources provide a standardized way of testing whether the expected state is present on a target system.

This allows the different aspects of the actual execution of configuring a system to be codified away from the information, deciding what settings to change or software to install. While the what dealt with writing down the expected state, the how is concerned with how to make it happen that way. Or, as Captain Picard would say, how to make it so.

This separation is important because it is expected that the list of things to do on a target computer will change, but it is not expected that how to execute that setting will change frequently. For example, there will be many types of files that you will create on many filesystems, but there are only a few ways to create these files. By separating the listing of the what, it allows the how to reduce variation by employing the idempotent DSC resources, an important part of a DevOps workflow.

To summarize the preceding content, we can say:

  • The DSC DSL defines a standardized way of describing the expected configuration of a target system, whether that is one system or several thousand systems
  • The DSC set of language extensions, cmdlets, and resources provide a standardized way of testing whether the expected state is present on the target system(s)
  • The DSC engine provides a structured way of executing this expected state in an idempotent manner

We have seen the word idempotent in several places in this chapter so far, yet we haven't really defined it or covered why it is important. Let's clarify what exactly idempotence means now.


Idempotence is an important concept, sometimes confusing, that we will touch on many times throughout this book. Idempotence is defined as an operation that has no additional effect if it is called more than once with the same input. Put another way, it is an operation that can be executed as many times as desired, and it will only change the system state if, and only if, it is not what the desired state is. For example, a PowerShell function looks for the x state and guarantees that it will only change the state of the system if it is not x.

It may seem silly to state something as obvious as this. If you feel this way, think of an MSI installer that installs version of an imaginary software product. When you run the MSI, it only ever installs the software if it isn't already present on the system or if the version present is older than the current version. No matter how many times you execute the MSI, it will only change the system if version is not on the system. This is idempotency. The MSI will only ever change the system state if it is not the desired state, no matter how many times you run it.

Idempotent operations are often used in network protocols or API design between dependent systems and are used in DSC by DSC resources. DSC resources are required to be idempotent in that they do not change the system if the system is in the state that the resource expects it to be in. For example, a DSC resource that operates on Windows Services will only try to start a given service if it is stopped, not if it is started. Another example is the DSC file resource, as that will change a file only if the contents do not match the expected string. By requiring idempotency, DSC resources can be run as many times as you want without ever performing an unexpected change.

When you install a piece of software on a machine that already has that software installed on it, you don't want there to be two copies of the software after you're done. You want the installer to be smart enough to detect the version of the currently installed software and then examine the version that you're attempting to install and ultimately decide that the versions match and no installation needs to be done. That is idempotency in a nutshell.

Isn't this Group Policy or SCCM?

At this point, you may be wondering whether DSC isn't a re-implementation of Group Policy (GPO) or System Center Configuration Manager (SCCM). It's a valid question, as there are some overlaps in these technologies.

Group Policy is similar in that it is also a system of configuring operating systems, applications, and user settings in an environment. However, Group Policy is tied to Active Directory (AD) and has a lot of configuration overhead, a complex and sometimes confusing deployment methodology, and is very inflexible. This is not to say that GPO is bad; some of these apparent limitations are by design. GPO has been around since Windows 2000 days and has had to deal with several decades of different approaches to software and server management.

In comparison, DSC is not tied to AD or a specific operating system platform. It is, by design, very flexible. As we have covered, it is designed to be responsive to the frequently changing technology and dynamic business environments we have today. Instead of obtuse schedules, DSC deployments are declarative and upfront about what exactly will happen and when it will happen. GPO has rudimentary tooling that writes binary files for its configuration that can't be read by a human and can't be version controlled. DSC has human-readable configuration files that are version controllable.

SCCM is also a configuration management system and is a huge piece of software that requires several servers and many hours to set up and maintain. It is not a small expense to purchase and continue to run, and it is clearly designed for a large enterprise that not only manages servers, but also manages user devices such as desktops and laptops. It is definitely an all-purpose tool that tries to encompass any need. Managing servers comes free with PowerShell and requires little setup time. While clearly designed for server management, some desktop management scenarios are supported. It is definitely a fine-honed tool for specific purposes.


DSC features

At this point, we have covered what PowerShell DSC is and how it relates to DevOps and configuration management, and lightly stepped through how it is structured and how it compares to other solutions out there.

We will now cover the requirements and available versions of PowerShell DSC.

DSC requirements

To use DSC, both the computer you author the configuration files on (more on this later) and the target computers must have PowerShell 4 or higher installed. This means that at least WMF 4 is installed on all target hosts and the computer in which you are making your configuration files.

PowerShell DSC comes as part of PowerShell starting in version 4. PowerShell 4 will already be present on the following operating systems and no further action is needed to enable PowerShell V4:

  • Windows Server 2012 R2
  • Windows 8.1

PowerShell 4 will have to be installed on the following operating systems:

  • Windows Server 2012
  • Windows 7 SP1
  • Windows Server 2008 R2 SP1

PowerShell 5 and 6 support the installation on all the preceding operating systems.

Windows 8.1 and Windows Server 2012 R2, DSC require an update to function correctly. The Windows update KB2883200 (also known as the GA Update Rollup) is required.

While it may already be installed depending on your patching process, you can check whether it is installed or not by running the following command:

    [PS]> Get-HotFix -Id KB2883200
Source Description HotFixID InstalledBy InstalledOn
------ ----------- -------- ----------- -----------
HOSTNAME Update KB2883200 HOSTNAMEAdmini... 9/30/2013 12:00:00 AM

The only dependency PowerShell has is on the .NET framework. PowerShell V4 and V5 require .NET framework V4.5. If you have Windows 2008 R2, read the release notes at https://www.microsoft.com/en-US/download/details.aspx?id=40855, carefully because the WMF 4 installer will not alert you that .NET 4.5 is not already installed.

Some functions of DSC do not work on the client operating systems as either the features needed aren't present on the client OS, or due to various other reasons, such as licensing or software availability. Where applicable, we'll call out these differences as we come across them. Something to note is that some DSC resources, the ones provided by the community or the xDSCResourceDesigner project (more on that later in Chapter 4, DSC Resources), do not work on Windows 2008. You will have to check the release notes for each DSC resource to determine what operating systems it is compatible with.

DSC versions

In the next chapter, we will delve into the details and inner workings of the DSC architecture. Before we do that, it will help to have an overview of the cmdlets and tools at your disposal when working with DSC. Some terms and concepts may be fuzzy here but will be explained in much more detail in further chapters. We can also use this section as a reference while authoring our own DSC configurations and resources.

PowerShell DSC is released as a feature of PowerShell, so its versioning scheme follows that of PowerShell. PowerShell is distributed as part of the WMF. When referring to the installed version of DSC, we use the version of PowerShell that is installed to denote which version of DSC it is currently running.

PowerShell V6, at the time of writing this, has not been released yet and is still in the alpha status, but we will still cover V4, V5, and V6 in this book. This will make things somewhat more complex to explain, as we will have to list, compare, contrast, and cover all the similarities and differences between the two versions as we move along. However, it is important to cover these because we fully expect you to have to deal with both PowerShell V4 and V5 deployed in your environments at the same time while looking at the future with V6. The final version of PowerShell V6 does not have a release date published yet, so realistically, you will have PowerShell V4 and V5 on your production systems for quite a while before moving to V6.


PowerShell V4 DSC

PowerShell V4 was released as part of WMF 4 on October 24, 2013, and contained the first released version of DSC. Even though this was the first release of DSC, it is still referred to as being version 4 of DSC. While confusing at first, this is largely something you can ignore, as versioning of DSC resources is a more frequent point of variance.

As the first release, this version of DSC largely focuses on bringing a minimally viable product to the market for Microsoft. Microsoft is a little late to the DevOps game with DSC, as there are several toolsets out there that have been in use for many years. Puppet and Chef are the most notable, but there are many others. What sets DSC apart here is that it is not an add-on or separate product; it's a core part of the Windows OS and can be used by other tools as much as it can be used by itself.

The first version contains most features needed out of the gate to start automating your deployment process, but only the built-in DSC resources were available and were lacking in addressing commonly used products such as IIS, SQL, or Exchange. In the early days, Microsoft relied heavily on the community to expand its DSC resource list, which resulted in mixed success. Microsoft released a set of DSC resources it authored to the community in batches to address the gap. The combination of community and Microsoft contributions has greatly expanded the reach of DSC, and it has been expanding it ever since.

V4 DSC language extensions

DSC adds three new functions as language extensions to support declaring the expected state of a machine:

  • Configuration: The configuration keyword is a DSC function that declares a set of operations to perform on a target system.
  • Node: The node configuration keyword is a DSC function that declares the target host to perform operations on.
  • Import-DscResource: This looks like a PowerShell cmdlet but really is a keyword. It locates the DSC resources needed to parse and compile the DSC configuration script.

V4 DSC base resources

The following table lists the DSC base resources of V4:

Base resource



The Service DSC resource performs operations against Windows services. It can start or stop a service or configure the account it runs under and the startup type of the service. This resource cannot install services; it operates only on services that are already present. Look at the xService resource for additional functionality.


The Script resource is a versatile generic resource. It allows you to specify an arbitrary block of code to be executed on the target host. There are some restrictions such as variable expansion and access to some system resources. Generally, this should be used for short term or one-off situations that are not handled by an existing DSC resource, as error handling and proper idempotency is difficult to achieve in the limited space you have.


The User DSC resource performs operations on local users on the target system. It allows the creation or deletion of users and setting passwords and password policies as well as basic attributes of the user.


The WindowsProcess DSC resource performs operations on processes on the target system. This is commonly used to execute arbitrary executables with specific parameters that are not handled by an existing DSC resource.


The WindowsFeature DSC resource adds or removes features of the Windows operating system. This uses the built-in Deployment Image Servicing and Management (DISM) infrastructure of the Windows Server platform; some features are not operable using this resource on a client OS.


The Registry DSC resource adds, removes, or modifies registry entries in the target system. Support for the full range of registry keys and values is present.


The Environment DSC resource adds, removes, or modifies environment variables on the target system.


The Archive DSC resource performs operations on compressed files.


The Group DSC resource performs operations on local groups on the target system. It can add, remove, or modify membership on local groups.


The Package DSC resource installs software bundled in MSI or EXE formats. In the case of MSI, it can also remove software if all the necessary options are provided to the MSI command line. Refer to the MSI documentation for more information on this.


The Log DSC resource writes messages to the DSC operational log. This is useful for troubleshooting or diagnostic purposes.

V4 DSC cmdlets




This cmdlet returns the current DSC configuration status of the node if the configuration exists. If it does not, this will throw an error. This can also be run on remote systems.


This returns the current settings, or meta-configuration, of the LCM on the system if the settings exist. This can be run on remote systems and is useful for troubleshooting DSC deployments that use DSC pull servers.


This cmdlet returns a list of all DSC resources on the system. This is vital in troubleshooting and authoring DSC resources, as it helps show what resources are present on the system. If the resource you are authoring is not present, then DSC cannot read the resource.


This cmdlet returns a hash from the DSC configuration MOF file. This is used to deploy MOF files to pull servers.


This cmdlet removes the compiled MOF from the target node, along with additional cleanup tasks.

This cmdlet is available only as part of the November 2014 update rollup for Windows RT 8.1, Windows 8.1, and Windows Server 2012 R2: http://support.microsoft.com/en-us/kb/3000850, from the Microsoft support library. Before you use this cmdlet, review the information in What's New in Windows PowerShell: http://technet.microsoft.com/library/hh857339.aspx in the TechNet library.


This cmdlet restores the previous configuration for the target node if a previous successful configuration exists on the target node.


This cmdlet stops a currently running configuration on a target node. This is useful in aborting interactive configuration runs initiated using Start-DSCConfiguration.

This cmdlet is available only as part of the November 2014 update rollup for Windows RT 8.1, Windows 8.1, and Windows Server 2012 R2: http://support.microsoft.com/en-us/kb/3000850 from the Microsoft Support library. Before you use this cmdlet, review the information in What's New With PowerShell: https://docs.microsoft.com/en-us/powershell/scripting/What-s-New-With-PowerShell?view=powershell-6 in the TechNet library.


This cmdlet runs the specified configuration against a target node but does not execute it. It compares the current state of the system to the expected configuration and reports back if they match. No changes are made to the system using this cmdlet.


This cmdlet is used to change the settings, or meta-configuration, on the LCM on the target computer. This is most often used in pull server scenarios.


This cmdlet executes the specified MOF file against the target computer. This is by far the cmdlet you will use the most, as it's helpful in both authoring and troubleshooting DSC configurations and DSC resources.


This cmdlet is really a dynamic function that is only available at runtime. It specifies which DSC resources need to be loaded to parse and compile the DSC configuration script.

V4 DSC pull server

The DSC pull server is the management server that the DSC agents on target nodes pull DSC configurations and DSC resources from. This will be explained in greater detail in Chapter 6, Pulling DSC Configurations.


PowerShell V5 DSC

PowerShell V5 was released on February 24, 2016, and contains the next version of DSC.

New DSC-specific features focus on improving upon the existing functionality provided by DSC in PowerShell 4, while introducing new ways to organize and execute configurations on target hosts.

V5 DSC language extensions

DSC V5 brings several new language extensions that are explained in the V5 Improvements section. It would be redundant to list them in both places, so we will only cover them later.

V5 DSC base resources

The built-in DSC resource list has not expanded, but the existing Microsoft-released community DSC resource project has provided over a hundred new DSC resources and is now available on GitHub with an open issue page and source.

V5 DSC cmdlets

Several new cmdlets have been added or improved upon in the DSC V5 release. Listed here are the most interesting ones for the purpose of our book:




This cmdlet reports the high-level status of the configuration on the target node. You can obtain the last status or all statuses of all configurations that have been run.


This cmdlet compares a specified configuration against the actual state of a target node. This is useful to determine configuration drift interactively and compare differences between actual and expected states of your systems.


This cmdlet copies the configuration to the target node but does not perform initial execution of the configuration on the target node. The configuration will be applied to the next consistency pass or when you run Update-DSCConfiguration.


This cmdlet forces the configuration to be processed when the cmdlet is executed. If the target node is attached to a DSC pull server, the agent will pull the configuration from the pull server before applying it.

V5 improvements

The V5 improvements are meant to call out certain aspects of the new release. It would be both futile and redundant to just list the release notes here, not to mention a waste of time. Instead, certain features are called out and explained in short detail to help you evaluate what is to come.

The PowerShell ISE

The PowerShell Integrated Scripting Environment (ISE) has been improved for authoring DSC configuration files. IntelliSense and inline help on demand increase the usability and discoverability of DSC resources.

PowerShell ISE IntelliSense allows the dynamic discovery of all the DSC resources inside a DSC configuration block by entering Ctrl + spacebar. Automatic completion of DSC resource names, property name and type, and enum is now supported. Automatically completing the value for DependsOn is a huge time saver when completing long dependency graphs.

Partial configurations and dependencies

DSC partial configurations allow you to deliver configurations in fragments to nodes. This is potentially a great feature to break up the large configuration documents you may have or help stagger the deployment of some distributed applications.

Support for cross-computer dependencies has also been added. This provides node-to-node synchronization without external input using CIM session connections between nodes. This means one configuration can wait for another to finish executing before executing itself. For example, a member server can wait to execute until the configuration on a domain controller has finished creating the domain the member server has to join.

Additional support for the DSC RefreshModes has been added to partial configurations. This allows you to specify whether a configuration is supposed to be pulled or pushed on an individual configuration level.

This feature is still in an experimental status at the time of writing this, so we are unable to accurately cover the feature in this book.

Class-based DSC resources

Instead of PowerShell module folders and supporting module files, DSC resources have been simplified to one file using class-based code.

We will cover how to make DSC resources in Chapter 4, DSC Resources, for both PowerShell V4 and V5, but we will briefly mention the improvements V5 brings. If this is confusing at this point, don't worry; we will get into more detail in Chapter 5, Pushing DSC Configurations.

Each file has the get, set, and test functions declared as methods to a single class, which DSC knows how to parse and execute. This is a huge feature in and of itself and leads to several exciting possibilities, not the least of which is class inheritance, which reduces some of the duplication required in DSC V4.

The concept of software classes, functions, and methods may sound more like programming than what you want to know, but it is not as scary as it sounds, and it will be further explained in the PowerShell class-base DSC resource section in this book.

DSC built-in support for help

DSC configuration blocks now support the addition of PowerShell standard comment-based help text. This is a real improvement regarding documenting your configuration scripts, as the help text added here will show up in the PS ISE help text added here will show up in the PS ISE IntelliSense or using the Get-Help cmdlet.

DSC run as credential support

In DSC V5, you can now specify a credential that DSC will use to execute the DSC resource under.

In DSC V4, all configurations were run under the LocalSystem account. This means care must be taken when executing commands or DSC resources and expecting them to be able to do things like network access or other normal user actions.

DSC resource side-by-side installation

In DSC V4, you can only have one version of a DSC resource installed. DSC V5 detects versions of DSC resources now, which allows you to have more than one version present on the filesystem. Different DSC configurations can now rely on different versions of DSC resources and not affect each other.

Currently, class-based DSC resources do not allow more than one version of a DSC resource on a target node. This will most likely be fixed by the time of release, as what is currently available is only in preview. We mention it here as a warning while using the preview releases and expect it not to matter when the final version is released.

DSC resource script debugging

With DSC V5, you can debug DSC resources as they run on target nodes. This uses the remote debugging enhancements introduced by PowerShell V5 that allow you to attach to remote PowerShell runspaces and interact with the running code. This is hugely helpful, as often, the remote system is different from the system you are authoring the DSC resources on.

Separation of node and configuration IDs

In DSC V4, the ID of the specific DSC configuration applied to a given node uniquely represented the actual configuration and node that it was run on. In DSC V5, this has been separated into a configuration name and agent ID. The configuration name identifies the configuration on a target node, and the agent ID uniquely identifies a node.

This allows you to track both the configuration and node status independently and in relation to the other, giving a holistic picture of the coverage deployment of the whole environment.

DSC LCM MetaConfig updates

Since configuration names have friendly names instead of unique IDs, anyone can set them. This is mitigated by adding a registration step for the target node before the node can start requesting configurations to apply. This registration uses a shared secret that both the DSC pull server and the target node know already, as well as the name of the configuration it will request.

DSC LCM rich state information

The amount of detail about the LCM state has been improved to include the status of the DSC configuration on the machine. It will report whether the LCM is Idle, Busy, PendingReboot, or PendingConfiguration.

This is very useful in determining the status of your target nodes as time moves on when using DSC.

DSC LCM RefreshMode values

DSC V5 introduces a new RefreshMode value, Disabled. The LCM will not manage the configuration documents on the system and any third-party can invoke DSC resources directly using the Invoke-DSCResource cmdlet. This is yet another addition to allow outside vendors to take advantage of the consistent common tooling provided by DSC.

DSC status from a central location

This is very much an experimental feature, but it is an important one in viewing DSC as an entire replacement of existing products in this space, such as Puppet or Chef. As of DSC v4, there is no way to report the status of configurations centrally or at a granular level. Terse information describes the current state, with very little information on what went wrong or right. Information is available on a per-pull server basis.

In DSC V5, this information is improved with more detail and can be forwarded to a central DSC pull server. High-level status can be sent to a central server running the DSC service, which is then stored in a database. A new OData endpoint is created when the DSC service is installed, which exposes the information stored and can be queried by any tool able to make HTTP calls.


PowerShell V6 DSC

The PowerShell V6 release has been focused on several non-DSC specific features, but DSC benefits from their inclusion indirectly. No new built-in resources or cmdlets have been added.

While there hasn't been much new core to DSC, there has been a huge focus on making DSC cross-platform. Early support for Linux that was released around the first edition of this book has been fleshed out into fully featured support. Not only can DSC run on Linux, but it also has a complete set of built-in DSC resources. Underpinning this is a version of PowerShell that can run on Linux.



PowerShell DSC is a configuration management platform that enables a DevOps deployment of systems and services. In this chapter, we covered the different DSC versions, the available features in each version, and the concepts of configuration management and continuous delivery.

In the next chapter, we will cover DSC architecture and how DSC manages both systems and software in detail.

About the Author
  • James Pogran

    James Pogran has been working with computers in one way or another for over 15 years. His first job involved systems administration for a large military installation. He then moved on to develop monitoring software and automate large-scale Windows environments for a major managed services provider. He is currently a senior software engineer at Puppet, Inc where he helps to make Windows automation even better with Puppet.

    Browse publications by this author
Latest Reviews (2 reviews total)
Compared to the first edition the content was mediocre.
Assists in development of my Powershell knowledge
Learning PowerShell DSC - Second Edition
Unlock this book and the full library FREE for 7 days
Start now