Introducing the DscLcm utility for PowerShell

Dr Scripto

March 30th, 2018

Summary: Desired State Configuration is a great deployment tool to meet your organization’s infrastructure-as-code goals. I recently came across a situation for a project that uses the Push Service (as opposed to the Pull Service). It required me to be able to apply a new partial configuration to a node, without any knowledge of what partial configurations were already in place. This led to the development of the DscLcm module, which solved that problem for my team.

DscLcm module

The DscLcm PowerShell module is a utility that interacts with the Local Configuration Manager (LCM) of a target machine. You don’t have to define your configuration as a script block. This functionality is useful in both push and pull scenarios. But the full benefit comes from a push model, because a lot of this functionality is built into the pull model already.

My goal with this module is to provide standard PowerShell functions that allow you to interact with the LCM. At the moment, DscLcm allows you to:

Modify an LCM Setting (for example, RebootNodeIfNeeded ).

). Add a partial configuration to the LCM.

Remove a partial configuration from the LCM.

Modify properties of an existing partial configuration block on the LCM.

Reset the LCM to a default state.

Before now, you would have to define an LCM setting in a configuration script block, as seen here:

[DSCLocalConfigurationManager()]

configuration LCMConfig

{

Node localhost

{

Settings

{

RefreshMode = 'Push'

}

}

}

With the new DscLcm PowerShell module, this same setting can be applied with the following command:

Set-LcmSetting -RefreshMode Push

This format is more conventional for working directly with the LCM, versus having to set up an entire configuration block for potentially only one setting change. In the following example, notice that modifying the few settings with the Set-LcmSetting command did not alter any of the already existing settings!

As I mentioned, one of the cool features of DscLcm is that it gives you the ability to append a DSC partial configuration to an LCM, without losing any of its current settings. Traditionally, one would have to re-define all the partial configurations and other LCM settings in the LCM configuration block, before deploying the resulting Managed Object Format (.mof) file. The main benefit of this functionality is that it gives you the ability to apply a new partial configuration, without having to know what partial configurations are already on the target.

In the following example, suppose that the localhost LCM configuration already knows about a partial configuration called ‘ServiceAccountConfig’. In order to apply a new partial to that LCM, you would have to define both ‘ServiceAccountConfig’ and the new partial, ‘SharePointConfig’, in the meta configuration.

[DSCLocalConfigurationManager()]

configuration PartialConfigDemo

{

Node localhost

{

PartialConfiguration ServiceAccountConfig

{

Description = 'Configuration to add the SharePoint service account to the Administrators group.'

RefreshMode = 'Push'

}

PartialConfiguration SharePointConfig

{

Description = 'Configuration for the SharePoint server'

RefreshMode = 'Push'

}

}

}

PartialConfigDemo

With DscLcm, this same function can be performed with the following command:

Add-LcmPartialConfiguration `

-PartialName SharePointConfig `

-RefreshMode Push `

-Description 'Configuration for the SharePoint server'

For the exact opposite scenario, we can also remove individual partial configurations by name. In addition to removing the partial configuration object, this function will also remove any dependencies on that partial as well. The next time the consistency check runs, the LCM will also automatically remove the partial configuration .mof for you.

Remove-LcmPartialConfiguration -PartialName ServiceAccountConfig

For those times when you have a defined partial configuration on a target and just want to adjust one of its settings, you can modify those settings as follows:

Set-LcmPartialConfiguration `

-PartialName SharePointConfig `

-DependsOn "ServiceAccountConfig" `

-Description "New Description"

The last cmdlet in this version of the module lets you reset the LCM to a blank state. This comes in handy for just about any scenario when you need to scrap a configuration altogether.

Reset-LcmConfiguration

As you can see, these functions greatly reduce the overhead for defining your LCM settings in any environment. Keep in mind, this is only one step in the DSC publishing process. Even though we are adding a partial configuration to the LCM, we still need to publish a partial configuration .mof in order for the full process to be completed. I have found these functions to be very handy as I work with DSC, and I hope you will too. Please feel free to leave any feedback or suggestions at either of the links below.

The module can be installed directly with PowerShell, by using the PowerShell Gallery repository with:

https://github.com/aromano2/DscLcm

https://www.powershellgallery.com/packages/DscLcm

Anthony Romano

Consultant, Microsoft