Getting Started with PowerShell Desired State Configuration (DSC)

As I’ve mentioned in other posts, Desired State Configuration (DSC) is a powerful technology with a lot of potential. However, due to how new it is and how rapidly it’s evolving, it can be difficult to get started and figure out how to accomplish your specific goals. My intention here is not to give an exhaustive look at the ins and outs of DSC (I’m not qualified to do that), but rather to give you the tools to get started and be successful with it .

Step 1: Get a Baseline

After years of cobbling together information, then having to go back later and relearn how to do it the right way, I’ve learned the value of getting the framework right from the start. If you have a strong framework in mind for how something is built and how it’s intended to be used, then building useful things on top of it is much easier. I had the same experience when learning DSC. There is a lot of information on the internet about it, but much of it is “old” and out of date. Also, everyone has their own opinions for how it should be used. Eventually I came across two videos on Microsoft Virtual Academy that put everything into perspective. They are taught by “Jeffrey Snover, Microsoft Distinguished Engineer and inventor of PowerShell,  along with Windows PowerShell MVP Jason Helmick”. This is a fantastic starting point for diving into DSC and I can’t recommend them enough.

Getting Started with PowerShell Desired State Configuration (DSC) – Microsoft Virtual Academy

Advanced PowerShell Desired State Configuration (DSC) and Custom Resources – Microsoft Virtual Academy

Step 2: Working With New Resources

Now that you know all about DSC and how it can be used, it’s time to put that knowledge to work. You eagerly download the module you want to use (let’s say xSQLServer, for example) and are ready to have machines install SQL for you. The first inclination is probably to google it to see how it’s used, which will lead you to github or PowerShell Gallery. Those are great for getting information about the package and its change tracking, but not much use for actually implementing the module. So here you are with a brand new toy and no manual.


The first thing to do with a new module is always check for an examples folder. Your module was probably installed in C:\Program Files\WindowsPowerShell\Modules.

Opening the examples folder within that module will reveal a list of scripts made by the creating team for various scenarios they see the module being used in. Your mileage may vary depending on the module you’re using and who made it, but generally those produced by Microsoft have useful information. This is where I obtained the example file that my last post, “Installing SQL Server Using Desired State Configuration“, was based on. Again, how much explanation is included within each script is completely up to the discretion of the creator. That’s why it’s important to first watch the videos linked above. Then, whether there is proper documentation or not you can make sense of it yourself.

(Upon further inspection, the examples are sometimes also available on the github site.)

Interrogating Resources

Even when you have an example file that closely matches your needs it’s likely that you will still want to customize it. Many times, the module you are working with will have a resource you need but not an example of it listed in the file. Or you simply want to know what all you can do with the module. As usual, it’s PowerShell to the rescue.

Using PowerShell we can easily find which resources are available to us in a module using Get-DscResource.

After finding a resource that interests us, we can dig further down into its specifics. In order to get more than cursory information, it s necessary to expand the properties field.

From this information we can tell which fields are available to us, what their data types are, and which ones are required.

It should also be noted that you can discover these from right within ISE as well. This is the improvised method that I used before discovering the PowerShell cmdlets above. If you type anything within the resource block that it doesn’t recognize, intellisense will automatically suggest the proper fields to use by hovering over the angry red line.

And, if all else fails, in the end resources are just PowerShell scripts. You can go to their folder and open them like any other file (ie C:\Program Files\WindowsPowerShell\Modules\xSQLServer\DSCResources\MSFT_xSQLServerLogin).

Step 3: Be Brave

Armed with all of this knowledge there is but one thing to do, be brave. Start putting some configurations together, make mistakes, then use the lessons learned to make better configurations. This is an exciting technology in which things are rapidly moving and changing. In fact, within days of my last post (and while writing this one) I discovered that xSQLServer had been retired in favor of SqlServerDsc, and I’d had no idea.

So get at it, make your own creations, keep your eyes open daily for changes, and let me know if you have any questions. I look forward to learning with you.

Installing SQL Server Using Desired State Configuration

(Update: I’ve since discovered that SqlServerDsc has replaced xSQLServer.)

One of my growing passions is using PowerShell Desired State Configuration (DSC) to automate all the things. I started out with simple configurations for testing but wanted to dive into more complex\useful situations for my day-to-day DBA life. To be honest, I was intimidated by the idea of doing a SQL installation. Configuring simple parameters or creating a directory are easy enough to wrap my head around, but something as complex as a DBMS installation gave me pause. I’m here to tell you that my worries were unfounded, and that you should have none as well.

The blessing and curse of DSC is that it’s so new. It is without doubt a very powerful tool, but as of yet there isn’t a lot of documentation around the individual resources. Or worse yet, the pace of improvement moves so quickly that information from two years ago is now out of date. I plan on doing a separate post for how to approach DSC given these realities. With this post, however, I wanted to fill one of those documentation gaps. Specifically, how to install and configure an instance of SQL server. I based my file off of an example one provided by Microsoft in the “Examples” folder of the xSQLServer module named “SQLPush_SingleServer.ps1”. Pro tip: always look for example folders in the modules you want to work with. It should be noted that you can address much more complicated scenarios, such as setting up clusters or Availability Groups, but for simplicity this configuration will be creating a single instance on one node.

If you have experience with DSC or simply don’t want to listen to me drone on about the details, the full configuration is at the bottom. For those interested in the play by play, or just bored and looking for something to do, I’ll address each piece individually.

The script starts out with compulsory documentation on the script and what it does. Kidding aside, get into the habit of doing small sections like this. Your coworkers (and you years from now when you’ve forgotten what you did) will thank you.

Next, we hard-code a couple of items specific to your individual run of the script. List the computer(s) that you want to deploy to as well as a local path for the configuration file that DSC will create.

Following that, we will set how the Local Configuration Manager on the target nodes is to behave. We’re specifying that the configuration is being pushed to it, that it should automatically check every so often for compliance to this configuration and auto-correct anything that’s not aligned, that modules on the node can be overwritten, and that it can reboot if needed.

Following that is the actual configuration details, where all the fun is defined. Mine is named “SQLSA”, but it really doesn’t matter what you name it. This is like defining a function; so as long as you call it by that same name later, little else is relevant. You’ll see at the top of this section there are three “Import-DscResource” lines. This tells the configuration which DSC modules will be needed to perform the actions we’re requesting.

The WindowsFeature item is one of the most handy in DSC. This allows us, as you might guess, to install Windows Features (in this case the .NET Framework).

Next I’ve created a firewall rule to make sure our instance’s port will be open (this is defined later under xSQLServerNetwork). It’s worth noting that there is a resource built into xSQLServer that allows you to configure firewall rules for SQL. However, I did not like the behavior of it and found that xFirewall from the module xNetworking provided a lot more flexibility.

Up next is the actual meat of installing SQL Server. The if($Node.Features) block is something I picked up from the example file. I’d say it’s redundant to check for whether you’re installing SQL when you came here to install SQL, but hey, it works well so I left it.

One way I’ve altered this section from the original is to parameterize everything. If you look further down there is a $ConfigurationData section. Having all of our customizable fields there allows us to easily change them for each deployment (dev, test, prod) without having to search through the code. You and your team will know exactly where to go and what to change for each situation.

I’ve also included some examples of basic SQL Server tasks like creating a database, disabling the sa account, disabling a feature like xp_cmdshell, and configuring the network port (referenced earlier). The naming on these items looks odd but makes sense. By adding in the node name we can ensure that they are unique should we deploy to more than one target node. And adding a friendly name to the configuration item, like “sa”, makes it easy to tell DSC which item depends on which. Speaking of which, note that each of the configurations depends on the base installation. That way DSC will not run those if there is nothing to actually configure.

After the configuration definition we have the $ConfigurationData mentioned earlier. It’s a great idea to get in the habit of using sections like this. It will make your transition between various environments much easier.

The next section details what we’d like the instance name to be as well as what features should be installed. It’s very picky about the feature names, and they don’t line up exactly with a standard command line install. So be careful with what you place here. It won’t install anything incorrectly, just simply cause the configuration not to run and you to lose your mind.

Also in this section, we’re copying over the modules that each node will need in order to perform this configuration. This isn’t necessary when using DSC in pull mode, but that’s a story for a different post.

I know you thought it’d never come, but at last it’s time to actually do something with all of this. We call our “SQLSA” configuration, passing in the $ConfigurationData and specifying to place the resulting .mof file in $OutputPath. After that, configuration is started on each node using Start-DscConfiguration and calling the .mof that was just created. Lastly, the node is tested to make sure it’s not out of compliance.

If all goes well, your output will lack red and eventually will end in a message stating that the configuration tests as “True”.


And that’s all there is to it! Not so scary after all. I deployed my first DSC SQL Server while making tea and wondered why I’d been doing it any other way…