In Chapter 1, Introduction to PowerShell DSC, we covered a high-level overview of DSC and introduced the three phases of DSC use. We also covered the MOF file and its importance in the grand scheme of DSC usage. Since we have already established the why of these concepts, we will now dive into the details of each phase.
What follows won't be a step-by-step process; that will be handled in Chapter 3, DSC Configuration Files. Instead, what we discuss here will be more explanatory and might jump around a bit. Concepts that are introduced may not be fully explained until later, when supporting concepts are fleshed out. DSC is a very modular product, each module a separate entity that is also interdependent on other entities. This makes explaining some concepts a chicken and egg scenario, so we will try our best to reference other sections as they apply.
The following diagram shows the authoring, staging, and execution phases of the DSC workflow. You will notice that it does not look much different to the push or pull model diagrams. This similarity is intentional, as the architecture of DSC allows its usage in either a push or pull deployment to be the same until the execution phase. This reduces the complexity of your configuration files and allows them to be used in either deployment mode without modification. Let's have a look at the entire DSC workflow:
In order to tell DSC what state the target node should be in, you have to describe that state in the DSC DSL syntax. The end goal of the DSL syntax is to create a MOF file. This listing and compilation process comprises the entirety of the authoring phase. Even so, you will not be creating the MOF files directly yourself. The MOF syntax and format is very verbose and detailed, too much so for a human to reliably produce it. You can create a MOF file using a number of different methods-anything from Notepad to third-party tools, not just DSC tooling. The third-party vendors other than Microsoft will eventually implement their own compilers, as the operations to compile MOF is standardized and open for all to use, enabling authoring DSC files on any operating system.
For the purposes of this book, we will concentrate on how to create MOF files using PowerShell tooling. We will assume you are using Windows 8.1 or Windows 2012 R2 OS with at least PowerShell v4 installed. If you are targeting the use of PowerShell v5, then we assume you are using Windows 10 or one of the production releases of WMF on your platform of choice.
DSC provides a DSL to help you create MOF files. We call the file that holds the DSL syntax the DSC configuration file. Even though it is a PowerShell script file (a text file with a .ps1 extension), it can't do anything on its own. You can try to execute a configuration file all you want; it won't do anything to the system by itself. A DSC configuration file holds the information for the desired state, not the execution code to bring the node to the desired state. We talked about this separation of configuration information and execution logic before, and we are going to keep seeing this repeatedly throughout our use of DSC.
The DSC DSL allows both imperative and declarative commands. What this means is that configuration files can both describe what has to be done (declarative) as well as have a PowerShell code that is executed inline (imperative).
Declarative code will typically be DSC functions and resource declarations, and will make up the majority of code inside your DSC configuration file. Remember, the purpose of DSC is to express the expected state of the system, which you do by declaring it in these files in the human-readable language.
Imperative code will typically make decisions based on metadata provided inside the configuration file; for example, choosing whether to apply a configuration to a target node inside the $AllNodes variable or deciding which files or modules to apply based on some algorithm. You will find that putting a lot of imperative code inside your configuration files will cause maintenance and troubleshooting problems in the future. Generally, a lot of imperative code indicates that you are performing actions or deciding on logic that should be in a DSC Resource, which is the best place to put imperative code. We will cover what indicators for this are and other important aspects of DSC Resources in Chapter 4, DSC Resources.
The DSC configuration file is compiled to a MOF format by invoking the declared DSC configuration block inside the DSC configuration file. When this is done, it creates a folder and one or more MOF files inside it. Each MOF file is for a single target node, containing all the configuration information needed to ensure the desired state on the target machine.
Note
It's important to understand before we get too far into explaining MOF compilation that defining a DSC configuration script does not mean you have to compile it to a MOF right away. The two actions are separate because the MOF file is either copied to the target node or DSC Pull Server and the DSC configuration file is kept in source control or another safe place.
Sometimes, compilation is not needed at all, as in the case of the Azure DSC tooling. All you need to do with Azure and DSC is copy the DSC configuration script, and Azure will handle the rest.
If at this point you are looking for example code of what this looks like, The example workflow section has what you are looking for. We will continue explaining MOF compilation here, but if you want to jump ahead and take a look at the example and come back here when you are done, that's fine.
You can only have one MOF file applied to any target node at any given time. Why one MOF file per target node? This is a good question. Due to the architecture of DSC, an MOF file is the one source of truth for a server. It holds everything that can describe that server so that nothing is missed.
You might be thinking that, if there can be only one MOF file per target node, does that mean you can have only one DSC configuration file? There are two answers to this question. You can either have one DSC configuration block applied to a target node, or use DSC partial configurations. With the one DSC configuration block, you can use the power of the PowerShell language (pun intended) to filter which target nodes to apply settings to or do complicated logic operations to decide whether software is installed or not.
With DSC partial configurations, you can have separate DSC configuration blocks to delineate different parts of your installation or environment. This enables multiple teams to collaborate and participate in defining configurations for the environment instead of forcing all teams to use one DSC configuration script to track. For example, you can have a DSC partial configuration for a SQL server that is handled by the SQL team, and another DSC partial configuration for the base operating system configuration that is handled by the operations team. Both partial configurations are used to produce one MOF file for a target node while allowing either DSC partial configuration to be worked on separately.
In some cases, it's easier to have a single DSC configuration script that has the logic to determine what a target node needs to have installed or configured than a to have set of DSC partial configuration files that have to be tracked together by different people. Which one you choose is largely determined by your environment. We will cover more on this subject in Chapter 3, DSC Configuration Files.
After authoring the configuration files and compiling them into MOF files, the next step is the staging phase. This phase slightly varies depending on whether you are using a push or pull model of deployment.
When using the push model, the MOF files are pushed to the target node and executed immediately. There isn't much staging with push, as the whole point is to be interactive and immediate. In PowerShell v4, if a target node is managed by a DSC Pull Server, you cannot push the MOF file to it by using the Start-DscConfiguration Cmdlet. In PowerShell v4, a target node is either managed by a DSC Pull Server or it is not. This distinction is somewhat blurred in PowerShell v5, as a new DSC mode allows a target node to both be managed by a DSC Pull Server and have MOF files pushed to it.
When using the pull model, the MOF files are pushed to the DSC Pull Server by the user and then pulled down to target nodes by DSC agents. As the local LCMs on each target node pull the MOF when they hit the correct interval, MOF files are not immediately processed, and thus are staged. They are only processed when the LCM pulls the MOF from the Pull Server. When attached to a Pull Server, the LCM performs other actions to stage or prepare the target node. The LCM will request all required DSC resources from the Pull Server in order to execute the MOF in the next phase.
Whatever process the MOF file uses to get to the target node, the LCM processes the MOF file by naming it pending.mof file and placing it inside the $env:systemRoot/system32/configuration path. If there was an existing MOF file executed before, it takes that file and renames it the previous.mof file.
After staging, the MOF files are ready for execution on the target node. An MOF is always executed as soon as it is delivered to a target node, regardless of whether the target node is configured for push or pull management. The LCM does run on a configurable schedule, but this schedule controls when the LCM pulls the new MOFs from the DSC Pull Server and when it checks the system state against the described desired state in the MOF file. When the LCM executes the MOF successfully, it changes the name of the pending.mof file to current.mof file.
The following diagram shows the execution phase:
The execution phase operates the same no matter which deployment mode is in use, push or pull. However, different operations are started in the pull mode than those started in the push mode, besides the obvious interactive nature of the push mode.
In the push mode, the LCM expects all DSC resources to be present on the target node. Since the LCM doesn't have a way to know where to get the DSC resources used by the MOF file, it can't get them for you. Before running any push deployment on a target node, you must put all DSC resources needed there first. If they are not present, then the execution will fail.
Using the Start-DscConfiguration Cmdlet, the MOF files are executed immediately. This kind of execution only happens when the user initiates it. The user can opt for the execution caused by the Start-DscConfiguration Cmdlet to happen interactively and see the output as it happens, or have it happen in the background and complete without any user interaction.
The execution can happen again if the LCM ConfigurationMode mode is set to ApplyAndMonitor or ApplyAndAutoCorrect mode, but will only be applied once if ConfigurationMode is set to ApplyOnly.
In the pull mode, the LCM contacts the Pull Server for a new configuration, and the LCM downloads a new one if present. The LCM will parse the MOF and download any DSC resources that are specified in the configuration file, respecting the version number specified there.
The MOF file is executed on a schedule that is set on each target node's LCM configuration. The same LCM schedule rules apply to a target node that is attached to a Pull Server as to one that is not attached. The ApplyAndMonitor and ApplyAndAutoCorrect modes will continue to monitor the system state and change it if necessary. If it is set to the ApplyOnly mode, then LCM will check with the Pull Server to see if there are new MOF files to download, but will only apply them if the last execution failed. The execution happens continuously on a schedule that the LCM was set to use. In the next section, we will cover exactly how the LCM schedules configuration executions.