PowerShell DSC is a management platform in Windows PowerShell that allows you to define the current state of a machines and ensure that machines are always in that state and ideally preventing them from drifting from that ideal state.

PowerShell DSC provides a set of Windows PowerShell language extensions, cmdlets and resources that you can use to declaratively specify how you want your operating system and software environment to be configured. 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.

Something that is really cool with DSC is that domain membership is not required. You can configure both domain computers and those that are in a workgroup. We can push configs to workgroup computers, join them to a domain etc. We will cover all of this step-by-step.

DSC configuration script?

A PowerShell Desired State Configuration script is nothing more than a PS1 script that we’re all used to having in our environment. However, it defines a special keyword called Configuration. That Configuration is where you’re gonna go and define what
the desired state for your environment is gonna be. In there, you’re gonna go and define different components and what their ideal state should be. Once you call that PS1 file, you’re gonna be compiling it into what we refer to as a mof file.

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 is a plain-text file that contains your configuration specifications. Then this file is parsed and executed on the target server, using DSC features that know how to configure the system. We have 2 mof files, one holds configuration that we will push/pull to the servers and the second holds local configuration manager configuration.

MOF file contains the machine-readable version of a DSC configuration file.

META.MOF has the local configuration manager configuration

DSC REQUIREMENTS

To use DSC, both the computer you author the configuration files on 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. So if your environment has at least PowerShell 4 or PowerShell
5, 5.1, you’re allowed to use Desired State Configuration. Make sure if  for some reason PS Remoting is disabled to enable it (It is enabled by default on server 2012 and above) and check your execution policy.

LOCAL CONFIGURATION MANAGER

The Local Configuration Manager (LCM) is the PowerShell DSC engine. It is the heart and soul of DSC. It runs on all target nodes (It is built into the OS) and controls the execution of DSC configurations and DSC resources whether you are using a push or pull deployment model. It is a Windows service that is part of the WMI service host, so there is no direct service named LCM for you to look at. This is just a short info, we will explore LCM in the next post.

DSC RESOURCES

Desired State Configuration (DSC) Resources provide the building blocks for a DSC configuration. A resource exposes properties that can be configured (schema) and contains the PowerShell script functions that the Local Configuration Manager (LCM) calls to “make it so”.

A resource can model something as generic as a file or as specific as an IIS server setting. Groups of resources are combined in to a DSC Module, which organizes all the required files in to a structure that is portable and includes metadata to identify how the resources are intended to be used. So we will use these resources for our config that will do work for us.

Built-In DSC resources

So you’re going to need resources, and those resources are available on your system. There is a cmdlet that will show you the DSC resources called Get-DSCResources, and these are in the box what shipped. Remember these are the things you’re going to use in your configuration that will do the work for you. Only 23 of them, things like file and registry and environment.

2019-01-03 09_43_32-Window

Now to find all dsc resources on the internet we need to use Find-DSCResource command. Right now there are 1428 dsc resources out there that we can use.

2019-01-03 11_09_05-Window.png

Now when you scroll down through the list you will notice that many of these resources  begin with a C and with an X.

X –> stands for experimental and may not work 100 % in all cases. They’re written by a wide range of people, typically Microsoft. This is when Microsoft asking for feedback and these resources may change.

C –> stands for community resources. These are resources that Microsoft might have
an X version out there, and the community says, hey, we want to change that.

We will use many of these through the DSC posts so be patient. Let’s start to write our configuration and see how we can use this tool to make our life easier. First we will use Push method. In other post we will discuss about Pull method.

DSC Structure

First we are going to put in a keyword called configuration. Next we need to give it a name (Basically you want to think of it exactly like function. It defines a name that then can be invoked and it runs code). The difference between a function and a configuration is that a config runs code whose, job it is to produce a configuration which is to say a configuration document. But then there are special keywords, these resources that you’ll declare. When you declare them PowerShell, underneath the covers, collects them all and organizes them. Then when you’re done you output them to a series of files. These configuration files are then pushed to the servers.

Next keyword is Node. Here we specify the machine that we would like to send the config. (Later we will discuss how we can parametarize this)

Third keyword is what Resource we want to use. In this example I will use WindowsFeature. So the basic structure looks like this

2019-01-03 22_47_40-Window.png

You may ask yourself what shall we type in under the WindowsFeature? Everytime you need to know something about the resource (the structure) or how to use it you can type in Get-DscResource and then -syntax. This shows me the things that I can set using Windows features. The properties that are available. It also tells me whether they’re mandatory. It will give us code sample. You can just copy and paste this, and fill it in or pipe it to clip or you can use IntelliSense in ISE.

2019-01-03 23_31_49-Window.png

So with this our config would look like this. We would write Configuration and give it a name. Next comes Node so whatever nodes we wanted it to go to. I’m going to send it to DC01 and then comes WindowsFeature resource (Hit Ctrl + space in ISE and it will show you the syntax). Name is the name of the Windows feature that you want to install. You get the name by running Get-WindowsFeature. You will notice that I have Ensure = ‘Present’.

ENSURE EXPLANATION

We have 2 options here (Present and Absent). Present is the default option. You may ask yourself what ensure means? It is here because you’re not performing an operation. You’re not saying add Windows feature. Because if you add it and then you try and add it again, you will get an error. My desire is to have that feature installed. If it’s not there put it there, if it is there don’t touch it.

2019-01-03 23_51_32-Window.png

When we run this, it will create a MOF file (It contains the machine-readable version of a DSC configuration file). You will notice a warning message but don’t worried about it right now. We will take care of that later.

2019-01-03 23_57_49-Window.png

Before we push this config to our server, let’s explore the MOF file. Just to point that you do not need to know how to write or read a MOF, I’ll just bring up the MOF  that we just generated so that you see how it looks like. Browse to the file and open it with notepad.

So we can see here where it’s going (TargetNode). GeneratedBY user N, when did it get generated, where did it get generated and some additional info. You do not need to explore this or to know how to generate this.

2019-01-04 00_10_54-Window.png

Close the file and let’s push it to our server. Now before doing this let’s see what commands we can use. In Powershell type in Get-Help -DSC This will give us the cmdlets that we’re going to be working with. We’re going to be going through several of these through our DSC posts but for now command which we are interested in is Start-DscConfiguration. 

2019-01-04 00_20_56-Window.png

Start-DscConfiguration is a way to send (push) a config out to a box. We’re going to give it the path for where the MOF is located and then we’re going to tell this to wait and then be verbose.

-wait –> If we run Start-DscConfiguration without -wait it’s going to create a PowerShell background job. By putting in -wait it’s going to do it right in front of us in real time. In other posts we will run it as a background job as well so you see how that looks like and what you can do.

-verbose -> it will give us additional info as it runs

Start-DscConfiguration -Path ‘C:\’ -ComputerName DC01 -Wait -Verbose

2019-01-04 00_33_07-Window.png

VERBOSE OUTPUT EXPLANATION

When you first start using desired state configuration what you’ll do is you’ll read the verbose output. I encourage you to do that. It’ll give you a clue what the engine is doing and why it’s doing it etc. You’ll see that it’s extremely regularly structured in terms of like lining up on columns. So let’s break this in to small peaces so that you see what is happening. Key point is to understand how DSC works. First it’s testing if the machine is in the desired state, so TEST TEST TEST and if it is not in the desired state it will do a SET.

See it from the beginning, verbose. Then it tells you what machine, DC01. Who’s telling you the information? This is the LCM (We will cover LCM in the next post). It’s going to start the SET. It’s then going to start the resource.  (WindowsFeature IIS). It first starts with a test. Then it comes back and now you see it doesn’t have the LCM, those next few lines. The providers are telling you this information. Not the LCM itself. The LCM gets the document. Then it dispatches that document to various pieces of code called providers. That’s where they come to play. It started this, it succeeded. In this case it’s doing the Get-WindowsFeature so it’s testing the state.

2019-01-04 12_22_04-Window.png

Second part of the verbose output. We can see that it starts a SET which means that the test found that it wasn’t in the desired state configuration. Now it’s going to set the desired state configuration. Then it tells you what it does. It started the installation, goes through all that. The provider is providing all that. Then the LCM tells you that it is finished. It ended the set of that resource.

2019-01-04 12_32_55-window

We can verify that the feature is installed by running get-windowsfeature

2019-01-04 12_52_16-Window.png

Now let’s run the same command one more time so that we see what will happen when our machine is in the desired state. You will notice that it is a lot shorter. Here again it is starting set, start resource, start test etc. Notice it does the test and it succeeded. It comes back and say SKIP SET. Skip and so it’s not going to do that because it’s in the correct desired state.

2019-01-04 12_56_26-Window.png

It is very important that you understand this especially when you are going to create your own custom resources because we have to create this, we’re going to test to see
if it is necessary or needed. If it’s there we’re going do nothing else. We’re going to skip setting it but if it’s not there we need to actually set it or make that change. It is very important that you go through those built-in resources (File, Group, User, Service etc)  and test it so that you know how things work.

I hope that this general part gave you information needed to start with DSC. In the next part we will focus on Local configration manager (LCM) and cover that in deep.

Cheers,

Nedim