- Historical Background of DSC
- Basic Tenets of DSC
- DSC Authoring Environment
- Configuring the DSC Environment
- Writing Your First Configuration Script
- A Word on DSC Push Configuration
- Summary
- Q&A
- Workshop
This chapter is from the book
This chapter is from the book
This chapter is from the book
Writing Your First Configuration Script
Okay, it’s time to start building out our DSC infrastructure, the first step of which is authoring our configuration script. Remember that although target nodes can apply only one MOF file for a given configuration, you can apply multiple MOFs to a single host as long as you don’t have conflicting configuration definitions. I’m sure that, over time, the Windows PowerShell team will make it easier for administrators to manage these manifold MOF manifests (alliteration alert).
I want you to understand before we get started that creating the MOF files via a PowerShell configuration script represents only one possibility for creating the MOFs. If, perchance, you understood MOF syntax, there’s nothing stopping you from creating your own MOFs from scratch using only a text editor.
In other words, we should start to see MOF authoring tools emerge from independent software vendors (ISVs) and the community at large as we progress over time. Welcome to the world of vendor neutrality and community-driven software architectures.
More About MOF Files
Remember that the MOF is not a Microsoft proprietary format, but instead is a vendor-neutral data representation format developed by the Distributed Management Task Force, of which Microsoft is a member.
MOF is used to define both management objects in CIM/WMI, and is also closely related to Web-Based Enterprise Management (WBEM) protocols such as WS-Man.
Figure 18.5 shows you what a typical MOF file looks like. I can’t stress enough that DSC is a potentially vendor-neutral technology, and the tool that you use to create the MOF doesn’t have to be Windows PowerShell. I submit that we’ll see graphical user interface (GUI) MOF creation utilities for DSC not too long in the future; perhaps these tools already exist by the time you’re reading this book.
)
Figure 18.5 A MOF file can be created by using PowerShell, another utility or programming language, or from scratch. As long as the MOF uses legal syntax, the method by which you produce the file is irrelevant.
Spend a moment studying the configuration script code in Figure 18.6, and I’ll walk you through each line. I strongly suggest you write your DSC configuration script in the Windows PowerShell integrated scripting environment (ISE) so that you can take advantage of IntelliSense and the easy script execution controls.
)
Figure 18.6 This DSC configuration script will produce one MOF file that is named after the specified target node.
- Line 1: We use the Configuration keyword in our script to denote a DSC configuration file. The configuration name is arbitrary.
- Line 2: The Configuration element is enclosed in top-level curly braces.
- Line 3: The Node keyword specifies the target node. In this first example, we’re hardcoding the name of a Windows Server 2012 R2 host named dscclient01. In a later example, we’ll parameterize this element with a variable so we can use one config script to target multiple nodes.
- Line 4: Indenting curly braces is optional, but an excellent practice to minimize the chance of our forgetting to close a script block and generate a runtime script failure.
- Line 5: The “meat and potatoes” of the configuration script are these subblocks. Here we specify the File DSC resource type, passing in an arbitrary name.
- Line 6: Another indented curly brace, this time enclosing the File resource script block.
- Line 7: Each DSC resource contains a number of named parameters. Like anything else in PowerShell, read the resource’s online documentation to learn the acceptable values for each parameter. The Ensure=“Present” line is ubiquitous in DSC configuration scripts, in my experience. This ensures that the policy is enforced.
- Lines 8-10: Here we plug in the details for our File DSC resource declarations. What we’re doing is copying the scripts shared folder on my deployment server to a local path on the target node. As of this writing, I needed to add the source and destination node computer accounts to the shared folder’s discretionary access control list (DACL) to make a UNC path work.
- Lines 11–14: Here we close up all the script blocks.
- Line 15. This is an optional line in which we call the configuration. That way we actually execute the Configuration block when we run the script in the Windows PowerShell ISE.
When you’re ready, run the entire configuration script. If all goes well, you’ll see output that is similar to this:
PS C:\Users\Trainer> C:\Users\Trainer\Desktop\DSC\SampleConfig1.ps1
Directory: C:\Users\Trainer\SampleConfig1
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 12/22/2014 8:23 AM 1736 dscclient01.mof
You’ll note that Windows PowerShell does a couple things when you run the DSC configuration script:
- Creates a directory in the root of the C: drive with the same name as the .ps1 script file
- Creates one MOF for each node referenced in the script; the MOF files are named with the node’s hostname
Customizing the Local Configuration Manager
Earlier in this hour, I told you that all DSC-enabled Windows nodes have a client component called the Local Configuration Manager (LCM) that is installed as part of WMF v4.
We can (and probably should) push a separate configuration script to our target nodes to customize the deployment parameters. First, let’s run Get-DscLocalConfigurationManager to see what’s what on my dscserver01 machine:
PS C:\> Get-DscLocalConfigurationManager
ActionAfterReboot : ContinueConfiguration
AllowModuleOverWrite : False
CertificateID :
ConfigurationDownloadManagers : {}
ConfigurationID :
ConfigurationMode : ApplyAndMonitor
ConfigurationModeFrequencyMins : 15
Credential :
DebugMode : False
DownloadManagerCustomData :
DownloadManagerName :
LCMCompatibleVersions : {1.0, 2.0}
LCMState : Ready
LCMVersion : 2.0
MaxPendingConfigRetryCount :
StatusRetentionTimeInDays : 7
PartialConfigurations : {}
RebootNodeIfNeeded : False
RefreshFrequencyMins : 30
RefreshMode : PUSH
ReportManagers : {}
ResourceModuleManagers : {}
PSComputerName :
Some of the LCM parameters are more important than others. The ConfigurationMode parameter tells the node what to do in terms of how it applies and refreshes DSC configurations. The options here are as follows:
- Apply: Applies the configuration once and then doesn’t check for an update or refresh again (one-time application, in other words).
- ApplyAndMonitor: Applies the configuration and continues to validate that the node is in compliance with the policy. If configuration drift occurs, the node does nothing.
- ApplyAndAutoCorrect: Applies the configuration, periodically checks for compliance, and reapplies the configuration if something changes within the scope of active configurations.
Note also the RefreshFrequencyMins parameter. In push mode, the node checks for DSC compliance every 30 minutes. This may be far too frequent for your business needs, so let’s deploy a new set of LCM settings to our localhost and dscclient01 nodes.
Once again, take a look at our script shown in Figure 18.7, and I’ll walk you through selected parts:
)
Figure 18.7 By deploying an LCM configuration, we can take fine-grained control over how DSC policies are evaluated and applied by target nodes.
- Lines 3–5: These lines create an input parameter for our LCM script. Note that the $NodeName parameter is defined as a string array, [], which makes it a snap to target multiple nodes without having to repeat code blocks in the script file.
- Line 10: Here we specify a 4-hour refresh interval for the LCM policy refresh mode.
- Line 17: Again for convenience, we run the configuration in-line with the code, specifying two target nodes by hostname. Of course, you can import the script into your runspace by using dot sourcing. However, I like the convenience of calling the function directly in the script file. Your mileage may vary, as I’ve said in this book about a hundred times before.
- An exhaustive discussion of how to import scripts into your runspace using dot sourcing is included in Hour 19, “Introduction to Windows PowerShell Scripting.”
When you run the LCM config script, you wind up with a single “meta” MOF regardless of how many nodes you target in the script. Likewise, we use a different cmdlet to apply an LCM script: Set-DscLocalConfigurationManager. The -Path parameter points to the directory that contains our LCM script:
Set-DscLocalConfigurationManager -Path “C:\SetupLCM”
Let’s do a Try It Yourself exercise so that you can shore up your Windows PowerShell skills and see how DSC works with your own eyes.
Creating and Pushing a DSC Configuration
In this Try It Yourself exercise, you’ll apply much of the PowerShell skills you’ve accrued throughout the book to apply a specific configuration to a target node.
Specifically, you’ll configure a Windows Server 2012 R2 member server named dscclient01 to keep the Internet Information Services (IIS) web server installed and the default website stopped.
We’ll start by using OneGet to download and install the xWebAdministration custom DSC resource module. Next we’ll author our configuration script and push it to a target node. Finally, we’ll verify that the configuration “took” by intentionally producing configuration drift and testing autocorrection. If you don’t have WMF v5 installed on your nodes, go with v4 and simply download the xWebAdministration DSC resource package from TechNet (http://bit.ly/13VAcvz).
On your DSC authoring server (dscserver01 in my case), fire up an elevated PowerShell v5 session and install the xWebAdministration package:
Find-Package -Name “xWebAdministration” | Install-Package -Verbose
Remember that you need to run this command on all DSC nodes, which means both my authoring server as well as my dscclient01.company.pri target node.
You’ll also want to verify that the DSC resource has been installed in the proper location on disk:
PS C:\Program Files\WindowsPowerShell\Modules> dir Directory: C:\Program Files\WindowsPowerShell\Modules Mode LastWriteTime Length Name ---- ------------- ------ ---- d----- 12/22/2014 12:49 PM xWebAdministrationNow open an elevated ISE instance and create a new .ps1 script file named WebServerConfig.ps1. Check out Figure 18.8, and I’ll walk you through the most important code lines, as has become my habit:
Figure 18.8 Our DSC configuration script ensures that IIS is installed and that the Default Web Site website is stopped.
Line 5: Once again, we parameterize the Node name to make the script more flexible.
Line 8: This is a bit of “smoke and mirrors.” We need to run Import-DscResource to load our custom DSC resource into the runspace. However, this is a “dynamic keyword” and is not an honest-to-goodness PowerShell cmdlet.
Lines 13–17: Here we invoke the built-in WindowsFeature resource to ensure that IIS is installed on the target node.
Lines 19–25: Now we call our xWebSite custom DSC resource to stop the default website.
Line 25: The DependsOn property is helpful when a configuration setting will work only if another one is active. Logically, then, we understand that we can stop the default website only if there exists an IIS web server to begin with.
Line 29: Modify the call to the configuration to target your own machines.
- Run your WebServerConfig.ps1 script by pressing F5 in the integrated scripting environment (ISE) and verify that PowerShell created two MOF files in a separate directory named after the script file.
When you’re ready, unleash the proverbial hounds and apply the new configuration by running Start-DscConfiguration:
Start-DscConfiguration -Path “C:\SetupIIS”
Because PowerShell runs DSC configuration pushes as background jobs, we can use traditional syntax to check on job status:
PS C:\> Receive-Job -id 7 -Keep
PSComputerName
--------------
dscclient01
dscserver01
Cool. No errors on my end. How has everything gone in your neck of the woods?
Connect to one of your target modes and see whether you can start the IIS Manager. If so, is the default website stopped? Figure 18.9 demonstrates my dscclient01 machine’s compliance.
Figure 18.9 I’m just going to go ahead and say it: DSC rocks! Here we see the configuration applied to my dscclient01 member server.
Use Windows PowerShell on one of your target nodes to start the default website. Of course, this will produce configuration drift. (If you haven’t configured your LCM to perform autocorrection, go back and do that now.)
Start-Website -Name “Default Web Site”
If you want, you can simply wait for the next DSC LCM refresh interval to test whether your server turned the default website back off. Alternatively, and perhaps more conveniently, we can force a manual update:
Update-DscConfiguration
The update will once again exist as a configuration background job. Note also that you can try Get-DscConfigurationStatus to review a node’s current relationship to DSC.
Surprise! You should find that the Update-DscConfiguration job fails:
PS C:\> Receive-Job -Name Job4 -Keep No attempt was made to get a configuration from the pull server because LCM RefreshMode is currently set to Push. + CategoryInfo : NotSpecified: (root/Microsoft/...gurationManager:String) [], CimException + FullyQualifiedErrorId : MI RESULT 1 + PSComputerName : localhostHere’s the deal: DSC push mode is great for test/demo situations because it’s easy to set up. However, we’ll have to run Start-DscConfiguration again from the authoring computer to refresh this policy. It’s only in a pull server scenario that nodes have the ability to refresh their policies. This makes sense because in a client refresh, we need some server from which the client can check to verify it has the correct policies applied.
)
)