Powershell

Announcing Microsoft Desired State Configuration v3.2.0

Leave a comment
This post was originally published on this site

Announcing DSC v3.2.0

We’re excited to announce the General Availability of Microsoft Desired State Configuration (DSC)
v3.2.0. This release delivers new built-in Windows resources, experimental Bicep integration via
gRPC, version pinning, a richer expression language, custom functions, and continued adapter
improvements. All these changes are driven by real-world use, partner feedback, and community
contributions. Special thanks to the WinGet team and the incredible DSC community.

For background on the DSC v3 platform, see:

What’s New in DSC v3.2

New Windows resources

DSC v3.2 ships several new built-in Windows resources, significantly expanding what you can manage
out of the box:

  • Microsoft.Windows/Service — manage Windows services
  • Microsoft.Windows/OptionalFeatureList — manage Windows Optional features
    • Requires using the ZIP package of DSC for now
  • Microsoft.Windows/FeatureOnDemandList — manage Windows Features on Demand
    • Requires using the ZIP package of DSC for now
  • Microsoft.Windows/FirewallRuleList — manage Windows Firewall rules
  • Microsoft.OpenSSH.SSHD/sshd_config — manage entire SSH server configuration
  • Microsoft.OpenSSH.SSHD/Subsystem and Microsoft.OpenSSH.SSHD/SubsystemList — manage SSH server
    configuration for subsystem entries
  • Microsoft.OpenSSH.SSHD/Windows — manage Windows SSH server configuration, such as the default
    shell

These resources are included in the DSC package and ready to use without additional installation.

Bicep integration via gRPC (experimental)

DSC v3.2 introduces a gRPC server, enabling Bicep to orchestrate DSC resources directly. The
dsc-bicep-ext extension is now included in the MSIX package and exposed on PATH.

This is the foundation for the Bicep to DSC integration. Write your configuration in Bicep. Bicep
orchestrates the execution directly over gRPC without going through ARM.

Extended WhatIf support

DSC v3.2 adds --what-if support to the dsc resource set command, letting you preview changes
before applying them:

dsc resource set --what-if --resource Microsoft.Windows/Service --input '{
    "name": "spooler",
    "startupType": "disabled"
}'

Prior to this release there was no way to run --what-if against individual resources. You could
use the --what-if flag with the dsc config set command, which ran all resources in your
configuration in --what-if mode.

Resource manifests can now declare whatIfReturns to describe what a what-if operation returns,
enabling richer preview output across resources.

Version pinning

DSC v3.2 supports pinning configuration documents to specific versions of DSC and pinning resource
instances in configuration documents to specific versions of the resource.

Now you can author a DSC configuration document and ensure that it only executes when the given
versions of DSC and resources that are available on the system. Prior to this release, DSC always
used the latest version of a resource discovered on a system for configuration operations.

The following example shows how to pin a configuration document to a specific version of DSC using
the version directive and how to pin individual resource instances to specific versions using the
requireVersion field.

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
directives:
  version: '=3.2.0' # This configuration is only valid for exactly version 3.2.0
resources:
- name: os
  type: Microsoft/OSInfo
  requireVersion: '^1.0' # Resource versions >= 1.0.0 and < 2.0.0 are valid
  properties: {}
- name: echo
  type: Microsoft.DSC.Debug/Echo
  requireVersion: '>=1.0.0, <1.3'
  properties:
    output: echo

When DSC evaluates a resource version pin in a configuration document, it looks for the latest
version of the resource that meets the given requirement. If no compatible version is discovered
on the system, DSC raises an error.

Starting with version 3.2, when you specify the version directive, DSC raises an error when the
version of DSC operating on the configuration document isn’t compatible.

Expression language improvements

Configuration documents now support a richer expression syntax:

  • Lambda expressions with map() and filter() functions (ARM syntax)
  • dataUri() and dataUriToString() functions
  • reference() usage inside copy loops
  • requireVersion replaces apiVersion for version requirements

These additions make configuration documents more expressive and reduce the need to duplicate
values across resources.

Adapter improvements

DSC 3.2 adds support for adapted resource manifests to the PowerShell adapters. Resource authors can
create adapted resource manifests that prevent adapters from needing to do more intensive
discovery operations.

This release also includes other improvements to the PowerShell adapters:

  • Added automatic conversion of PowerShell streams to DSC traces. Resource authors can participate
    in DSC’s tracing model by using the normal Write-* cmdlets.
  • Fixed passing credentials to adapted PSDSC resource instances.

Metadata and execution improvements

  • Microsoft.DSC metadata is now split into directives and executionInformation — cleaner
    separation of configuration intent from execution context.
  • _refreshEnv resource metadata updates Windows environment variables during deployment without
    requiring a restart.
  • Resource manifests can now specify requireSecurityContext per operation, helping users avoid
    problems where they retrieve data for a resource with a get or test operation and then get an
    access denied error when they try to run the set command.
  • Resources and extensions can now be marked as deprecated, with a deprecation message surfaced
    at runtime.

New extension capabilities

DSC 3.2 adds support for two new extension capabilities: importing configurations and retrieving
secrets.

You can use an extension with the import capability to process arbitrary files as DSC
configuration documents. For example, a hypothetical extension with this capability could transform
the following TOML snippet into a DSC configuration document:

# example.dsc.toml
[directives]
version = '3.2.0'
[resources.os]
type       = 'Microsoft/OSInfo'
properties = {}

The resulting DSC configuration document:

# effective DSC configuration document
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
directives:
  version: '=3.2.0' # This configuration is only valid for exactly version 3.2.0
resources:
- name: os
  type: Microsoft/OSInfo
  properties: {}

When you use the --file option with the dsc config * commands, DSC checks the file extension to
see whether an extension can process that file. If there is no DSC extension that handles the given
file extension, DSC tries to parse the file as a configuration document.

You can use a DSC extension with the secret capability to retrieve secrets at runtime. Presenting
secret retrieval through the extension model enables DSC to be used with secrets in a variety of
contexts without requiring the core engine to handle these operations directly. This capability is
paired with the new secret() configuration expression for retrieving secrets by name.

Experimental PowerShell discovery extension

DSC now includes a discovery extension for finding DSC resources in PowerShell modules. This
extension looks for resource manifests and adapted resource manifests located inside PowerShell
modules on the system. This makes it possible for resource authors to ship DSC resources written
in PowerShell that are not PSDSC resources.

For example, with this extension, DSC could discover a resource implemented as a PowerShell script
as long as the module also includes a valid manifest for the resource.

Bug fixes

  • Fixed duplicate resources appearing in dsc resource list
  • Added a clear error when attempting to use DISM resources via Appx (previously a silent failure)
  • Fixed executionInformation in config export results
  • Fixed discovery failures when encountering unsupported manifests

Community contributions

DSC v3.2 reflects the work of an active and growing contributor community. The following community
members made notable contributions to this release:

  • @Gijsreyn (Gijs Reijn) — experimental PowerShell discovery extension, lambda/map/filter
    expressions, dataUri functions, adapted resource manifest fixes, and more.
  • @mimachniak — PowerShell adapter credentials fix for passing username and password.

Thank you to everyone who filed issues, tested previews, and submitted fixes during the DSC v3.2
release cycle.

Installing DSC

On Windows, you can install DSC from the Microsoft Store using winget. Installing from the Store
gives you automatic updates.

Search for the latest version of DSC:

winget search DesiredStateConfiguration --source msstore

Name                              Id           Version
------------------------------------------------------
DesiredStateConfiguration         9NVTPZWRC6KQ Unknown
DesiredStateConfiguration-Preview 9PCX3HX4HZ0Z Unknown

Install DSC using the id parameter:

# Install latest stable
winget install --id 9NVTPZWRC6KQ --source msstore
# Install latest preview
winget install --id 9PCX3HX4HZ0Z --source msstore

To install the ZIP package on Windows, Linux, or macOS:

  1. Download the latest release from the PowerShell/DSC repository.
  2. Expand the release archive.
  3. Add the folder containing the expanded archive contents to your PATH environment variable.

Support lifecycle

DSC follows semantic versioning. DSC v3.2.0 is the current stable release. Patch releases update
the third digit of the semantic version number — for example, 3.2.1 is a patch update to 3.2.0.

Stable releases receive patches for critical bugs and security vulnerabilities for three months
after the next stable release. For example, v3.2.0 is supported for three months after v3.3.0 is
released.

Always update to the latest patch version of the release you’re using.

Looking ahead

Work continues on DSC v3.3, with previews starting shortly after the v3.2.0 GA release.

Call to action

For more information about DSC, see the DSC documentation. We value your feedback. Stop by our
GitHub repository and let us know of any issues you find.

Jason Helmick

Sr. Product Manager, PowerShell

The post Announcing Microsoft Desired State Configuration v3.2.0 appeared first on PowerShell Team.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.