Windows PowerShell Desired State Configuration: Push and Pull Configuration Modes

What are push and pull modes?

The Windows PowerShell Desired State Configuration (DSC) system has two configuration modes, which are referred to as push and pull modes. Each mode allows the user to apply a desired state over a target node.

Push mode vs. pull mode

How push mode works

As illustrated in the preceding diagram, the push model is unidirectional and immediate. . The configuration is pushed to its intended targets, and they are configured.

How to push a configuration

In push mode, the user initiates configuration processing via the Start-DscConfiguration cmdlet. This command immediately applies the configuration to the target, which can be specified by the -ComputerName parameter of the Start-DscConfiguration DSC cmdlet. By default, this cmdlet uses the files in the -Path folder to find the target node details.

How pull mode works

In the preceding diagram, we have 4 machines that participate in the request, delivery and application of the configuration. Each one of the pull client machines is configured to get its desired state configuration from the pull server. Likewise, the pull server has been set up to host the DSC service, and has been provisioned with the configurations and resources that are required by the pull clients.

Each one of the pull clients has a scheduled task that performs a periodic compliance check on the configuration of the node. When the event is triggered the first time, it causes the Local Configuration Manager (LCM) on the pull client to validate the configuration. If the pull client is configured as desired, nothing happens. Otherwise, the LCM makes a request to the pull server to get a given configuration. If that configuration exists on the pull server, and it passes initial validation checks, the configuration is transmitted to the pull client, where it is then executed by the LCM.

How to pull a configuration

Pulling a configuration requires that a series of steps be taken on the pull server and target nodes. We will look at this series of steps in detail in the section titled The pull mode configuration steps  in this post.

Push and pull configuration deployment steps

Push sequence

Authoring a configuration

First thing to do when configuring nodes through DSC is to define a configuration. Consider the following example, and then we’ll examine each part of the configuration.

InstallDscService.ps1

configurationInstall_DSCService

{

    node localhost

    {     

        WindowsFeature DSCService

        {

            Name  ="DSC-Service"

            Ensure ="Present"

        }

    }

}

InstallDSCService-output"." 

In this simple example, we have the following main elements:

a)      The configurationkeyword, followed by a user-supplied name.

b)      The Nodekeyword, followed by the name of the node to be configured. In this case, it is the localhost. Note that the Node keyword is not case-sensitive.

c)       Within the scope of the node definition, we list the resources we will use to configure the node. In this case, we are using the WindowsFeature built-in resource provider to install the DSC Service feature on the local machine.

d)      Finally, we have a statement making an invocation of the configuration, designating the location of the .mof output as the current directory.

Generate configuration MOF file

Now that we have our .ps1 file with the configuration defined above, we need to generate the MOF file that we will use to initiate the configuration. To generate the MOF file, all that is needed is to execute the .ps1 file containing the configuration. This generates a MOF file named with the same name as the node within the configuration, with the .mof file name extension. In this case, we’ll end up with localhost.mof.

PS D:\> .\InstallDscService.ps1

    Directory: D:\InstallDscService

Mode                LastWriteTime     Length Name                                                                                                                                                                                                   

----                -------------     ------ ----                                                                                                                                                                                                   

-a---         8/28/2013   4:17 PM       1260 localhost.mof                                                                                                                                                                                          

Push the desired configuration to target nodes

Once we have the configuration mof file generated, we are ready to start the configuration using the Start-DscConfiguration command. In the following example, we provide a few extra parameters, explained below.

PS D:\InstallDscService> Start-DscConfiguration -Wait -Verbose -ComputerName localhost -Path .

VERBOSE: Perform operation 'Invoke CimMethod' with the following parameters, ''methodName' = SendConfigurationApply,'className' = MSFT_DSCLocalConfigurationManager,'namespaceName' = root/Microsoft/Windows/DesiredStateConfiguration'.

VERBOSE: An LCM method call arrived from computer LOUISC-VMHOSTD with user sid S-1-5-21-2800768176-829124343-4290817346-1106.

VERBOSE: [LOUISC-VMHOSTD]: LCM:  [ Start  Set      ]

VERBOSE: [LOUISC-VMHOSTD]: LCM:  [ Start  Resource ]  [[WindowsFeature]DSCService]

VERBOSE: [LOUISC-VMHOSTD]: LCM:  [ Start  Test     ]  [[WindowsFeature]DSCService]

VERBOSE: [LOUISC-VMHOSTD]:                            [[WindowsFeature]DSCService] The operation 'Get-WindowsFeature' started: DSC-Service

VERBOSE: [LOUISC-VMHOSTD]:                            [[WindowsFeature]DSCService] The operation 'Get-WindowsFeature' succeeded: DSC-Service

VERBOSE: [LOUISC-VMHOSTD]: LCM:  [ End    Test     ]  [[WindowsFeature]DSCService]  in 1.6720 seconds.

VERBOSE: [LOUISC-VMHOSTD]: LCM:  [ Skip   Set      ]  [[WindowsFeature]DSCService]

VERBOSE: [LOUISC-VMHOSTD]: LCM:  [ End    Resource ]  [[WindowsFeature]DSCService]

VERBOSE: [LOUISC-VMHOSTD]: LCM:  [ End    Set      ]

VERBOSE: [LOUISC-VMHOSTD]: LCM:  [ End    Set      ]    in  2.3120 seconds.

VERBOSE: Operation 'Invoke CimMethod' complete.

VERBOSE: Time taken for configuration job to complete is 2.365 seconds

·         -Wait: This parameter ensures that the invocation of configuration is interactive and synchronous with user commands. Otherwise, a job object is returned that continues the operation in the background.

·         -Verbose: This parameter ensures that any status or progress messages that are written by the resource implementation are displayed in the console. This is particularly helpful during development and debugging.

·         -ComputerName: If this parameter is omitted, the Local Configuration Manager (LCM) will try to use all the files in the configuration folder. Because we specified localhost as the name of the MOF file, the configuration is applied to the local computer.

·         -Path: Points to the path where the MOF file resides. In this case, it is in the current directory.

The pull mode configuration steps

Set up configuration

The following sections describe how to set up the configuration.

Author configuration for a target node

Authoring a configuration to work in pull mode is almost identical to the process of authoring a configuration for push. There are some special considerations, however, which we’ll cover in this section of the post.

First, let’s look at a simple configuration that we can use for pull mode.

SimpleConfigurationForPullSample.ps1

There is not much difference in the way that configurations are constructed for pull scenarios. The main difference to note in this simple example is the node name, which is a GUID. This is because we provide a configuration ID that matches this GUID when we are performing the pull from the pull server.

Designate configuration to target machine

To define the configuration above, we must have a GUID value that we can use in the node definition. To generate a new GUID, refer to Create GUID (guidgen.exe) or Guid.NewGuid Method.

Using unique identifiers for configurations ensures that the mapping between the pull server and its pull clients is unambiguous, and each receives its own configuration.

Generate configuration MOF

Once the configuration script is complete, the next step is to run the script to generate a new <yournewguid>.mof. Once you run the script is, there is a new folder with the name of the configuration containing the MOF file. It is always good practice to ensure that the contents of the new MOF file match the contents of the configuration before moving forward.

Generate MOF file checksum

A checksum file is required before deploying the configuration to the pull server. This allows the LCM to validate the configuration before applying it. To generate a new checksum for the configuration, we need to run the New-DSCCheckSum command as follows.

PS D:\CISTEX\DSC_E2E\tests\Scenarios\vhd_scenario\Samples> New-DSCCheckSum -ConfigurationPath .\SimpleConfigurationForPullSample -OutPath .\SimpleConfigurationForPullSample -Verbose -Force

VERBOSE: Create checksum file 'D:\CISTEX\DSC_E2E\tests\Scenarios\vhd_scenario\Samples\SimpleConfigurationForPullSample\1C707B86-EF8E-4C29-B7C1-34DA2190AE24.mof.checksum'

When the .ps1 script was generated, it was generated under the folder SimpleConfigurationForPullSample, which is created and named after the configuration. The new MOF file is placed in that directory, so in the call to New-DSCCheckSum, we must provide the configuration path. It is recommended to use the output path to have the new checksum file stored in the same place as the MOF file. Later, during the preparation of the pull server, we must copy both of these files to a specific location on the pull server.

Set up the pull server

Configure the target node for pull mode

Each pull client must be able to contact the pull server, and must have access to the settings to use in its configuration of the LCM on the local machine. This is accomplished via the use of a meta-configuration file designed for the client. Let’s take a closer look at what this meta-configuration file looks like.

First, we must provide the LCM with contact information about the pull server. This is accomplished in the preceding example by applying the appropriate key/value pairs to the DownloadManagerCustomData property of the meta-configuration. As seen above, there are two distinct key/value pairs that are used to configure the node.

·         ServerUrl. This value must point to the URL of the DSC pull service on the pull server machine. Note that we are using HTTP port 8080 to access the service, and in this simple example, we are using an unsecured connection, so we set this value to True.

·         ConfigurationID value. This is the value of the new GUID that was used to create the configuration for the pull client.

We also should set the RefreshMode for the node. In this case, since we are using a pull server to use pull mode, we set this value to PULL.

Configure a machine resource as a pull server

Once we have defined all the necessary artifacts required by the pull clients, we must configure a machine as a pull server from which the pull clients get their respective configurations. The process of setting up a pull server is as follows.

1.       Create a configuration file that installs the DSC service on the computer you’re using as the pull server.

2.       Setup an IIS endpoint for the pull server service.

3.       Validate the configuration of the pull server.

Steps 1 and 2 above can be accomplished by a single configuration file, which configures the machine with the DSC service, and sets up the IIS endpoint for the DSC service.

Deploy MOF and checksum files to the pull server

The MOF files containing the configurations of the pull clients must be stored on the pull server. Specifically, the location should be $env:SystemDrive\Program Files\WindowsPowershell\DscService\Configuration. Note that both the MOF file and its corresponding checksum files must be placed in this location for normal processing to take place.

Set up DSC on target node

Setting LCM on pull clients

In the Configure target node for pull mode section of this post, we saw how a configuration can be modeled to set the configuration of the Local Configuration Manager. To revisit, we saw the following configuration:

Localhost.meta.mof

Now, to configure the LCM, we need to run the Set-DscLocalConfigurationManager command on each of the pull clients. The example configuration above addresses one client, because it has a unique configuration identifier which differentiates it from other configurations intended for other clients.

To run Set-DscLocalConfigurationManager, we provide the following parameters.

-          ComputerName: In this case, the value of the ComputerName parameter is localhost, because we are configuring the local node.

-          Path: The path to the location where the localhost.meta.mof file resides. If the -Verbose switch is used on invocation, we can see the following output on a successful execution of Set-DscLocalConfigurationManager.

Finally, once all the pull clients are configured, each node can get its configuration from the pull server. From this point on, the DSC components ensure that the desired state is retained over time until it is explicitly changed by the user.

Conclusion

In this blog post, we have seen how we can use DSC to configure machines locally and remotely, and have looked at the two modes of deployment, push and pull. In this series of blogs, we plan to cover custom resources, security, and other important aspects of the DSC platform.