See what's new in Desired State Configuration v3

What is Desired State Configuration?

DSC is a declarative configuration tool that keeps the components of a system in a specific state. In this context, declarative means the admin defines the state rather than the technical method to meet that state. DSC is agentless, similar to Ansible, meaning it does not require any additional software.

For example, if your servers need a specific registry setting, instead of writing a script to make the change, a DSC configuration file includes the desired path and value. DSC then executes the changes by using a resource.

DSC uses the concept of idempotent operations, which means DSC can apply a configuration change several times, but it does not deviate from the first application and cause unintended issues. DSC scans a system for differences from the desired state and then only changes the areas that need adjustment. In addition to maintaining a consistent environment, this method is more efficient by avoiding excessive processing.

DSC's extensibility to work with orchestration tools, such as WinGet, gives admins a tool to ease the setup process for a new device or project by automatically installing needed applications on a machine.

What problems does DSC try to solve?

In server environments, particularly large ones, maintaining consistent configuration across all machines is a cumbersome task, especially when done manually. If you have learned how to use a management tool, such as PowerShell, then you can streamline that task with scripts.

With DSC, you can automate the entire process to avoid configuration drift without defining the steps for each item. This approach scales to let administrators focus on the desired state of the infrastructure rather than how to get there.

By setting a configuration for machines, DSC provides consistency by controlling role deployments on servers, ensuring compliance by applying patches and updates and regulating file and folder permissions.

How does PowerShell DSC v2 differ from DSC v3?

The most obvious change from PowerShell DSC v2 to DSC v3 is the name. DSC v3 no longer requires PowerShell and is no longer exclusive to just Windows systems. Its core dependencies are contained within the standalone executable. Other notable changes include the following:

• Language-agnostic resources. DSC v3 supports resources written in any language. The only requirement is that the provider can execute the resource and the resource provides JSON output to DSC. For example, Microsoft's DSC samples repository has a sample DSC v3 resource written in the Go programming language. After compiling the resource, an accompanying JSON file instructs DSC v3 how to execute the resource. If the compiled binary can run on the targeted system, then DSC v3 uses it as a DSC resource. For users more familiar with Bash or Python, they can use those languages to manage resources.
• Introduction of adapters. A big concern surrounding the new version of DSC was backward compatibility with PowerShell DSC. Microsoft said DSC v3 supports all previous resources with adapters. A DSC v3 adapter is a resource type that allows the use of resources without a DSC resource manifest by acting as a substitute resource manifest.
• Standardization on JSON. Microsoft designed DSC v3 to conduct all data communications serialized in JSON, which is easier to use than Managed Object Format in PowerShell DSC v2. You also have the option to use YAML to write resource manifests and the input and output from DSC. The move from PowerShell dependency and use of JSON or YAML makes DSC v3 more flexible for use beyond Windows systems.
• Connection to the cloud. Microsoft aligned DSC more closely with organizations that use the Azure cloud platform to tighten integration with services such as Azure Automanage to maintain consistency with Azure VMs. This change makes DSC v3 more attractive to enterprises in a hybrid cloud arrangement.

What are the benefits of DSC v3?

For Windows Server administrators, a move from PowerShell DSC might not seem logical because it is built into Windows PowerShell and Windows Management Framework. However, there are many benefits to a switch to DSC v3 when it is generally available:

• Cross-platform support. Building expertise in PowerShell DSC limits your expertise to Windows. By using adapters in DSC v3, you can still use those PowerShell DSC skills, while expanding your skill set with a tool that works with Windows, Linux and macOS. Microsoft overhauled the PSDesiredStateConfiguration PowerShell module to make it cross-platform by removing the dependence on Windows Management Instrumentation to avoid using a local configuration manager.
• Ease of use. PowerShell DSC resources written as PowerShell classes were easy to read, but in DSC v3, you don't need to understand PowerShell code to know what a resource does or even how to use it. DSC v3 is standardized on JSON, which is a cross-functional industry standard.
• Improved scalability and integration. Because DSC v3 is invoked as a command and no longer runs as a service or requires a local configuration manager, it is easier to use and scale. Any tool that can execute a command on Windows Server can apply DSC configurations. Microsoft updated DSC v3 to work with orchestration tools, such as WinGet and Azure Machine Configuration.

How to use DSC v3

Installing DSC v3 is simple. Download the latest release from the DSC v3 repository. For the purposes of this tutorial, there is a focus on the Windows version.

Extract the zip file into a folder. From there, you execute dsc.exe with your favorite shell.

DSC v3 is still in prerelease, and the output might look different in later versions.

To see the resources available for use in configurations, run the following command.

.\dsc.exe resource list

How to build a configuration in DSC v3

The following instructions explain how to write a configuration in DSC v3 in YAML. This example uses the registry resource.

At a minimum, a configuration document must reference the DSC resource schema and at least one resource. The following YAML example sets a value in the registry on a Windows machine to force the control panel to display using the classic icon view.

# registryExample.dsc.config.yaml
$schema:
https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
resources:
  - name: Force icon view in Control Panel
    type: Microsoft.Windows/Registry
    properties:
      keyPath:
HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\Explorer\
      valueName: ForceClassicControlPanel
      valueData:
        DWord: 1

Even if you are new to DSC v3 configuration documents, the YAML should not be difficult to understand. The code tells the system to use the Windows registry resource type and passes several properties to that resource.

To discover the properties to pass, use the following command to investigate the resource with DSC.

.\dsc.exe resource schema --resource Microsoft.Windows/Registry

The properties list shows keyPath, valueData and valueName. The $ref field refers to data further down in the output that explains each value. For example, here is the first part of RegistryValueData.

RegistryValueData:
oneOf:
- type: object
required:
- String
properties:
String:
type: string
additionalProperties: false
- type: object
required:
- ExpandString
properties:
ExpandString:
type: string
additionalProperties: false
- type: object
required:
- Binary
properties:
Binary:
type: array
items:
type: integer
format: uint8
minimum: 0.0
additionalProperties: false
- type: object
required:
- DWord
properties:
DWord:
type: integer
format: uint32
minimum: 0.0
additionalProperties: false

At the bottom, pass a DWord value, which is part of the example configuration document.

How to apply a configuration with DSC v3

After defining the configuration, test it with the following.

.\dsc.exe config get -p .\registryExample.dsc.config.yaml

The -p option references the path to the configuration document.

To apply the YAML configuration file with DSC v3, use the following command.

.\dsc.exe config set -p .\registryExample.dsc.config.yaml

In the output, the last message indicates there were no errors and indicates the Windows registry was changed to match the configuration file. There is also some good information in here, such as the securityContext. Execute the get command in a nonelevated PowerShell session and the set command while running PowerShell as administrator.

In this case, the following PowerShell code verifies the change.

$splat = @{
    Path =
'HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\Explorer\'
    Name = 'ForceClassicControlPanel'
}
Get-ItemProperty @splat

The changes to Microsoft's DSC configuration management tool attempt to fill some of the gaps in the earlier versions by expanding coverage both to cloud resources and to other OSes to make DSC v3 a more flexible tool for admins. It's worth investigating to see how it compares to similar offerings. The recent uptick in development and the visibility of DSC v3 as an open source project on GitHub bodes well for the future of this automation tool.

Anthony Howell is an IT strategist with extensive experience in infrastructure and automation technologies. His expertise includes PowerShell, DevOps, cloud computing, and working in both Windows and Linux environments.