PowerShell DSC: The next generation

We have some exciting news for you about Puppet's support for the PowerShell DSC configuration framework for Windows. In short, content from the PowerShell Gallery will simply appear on the Puppet Forge and can be added to your Puppetfile and used just like any other Puppet module. This makes it by far the most flexible and maintainable iteration of DSC integration we've ever had. Pick and choose whatever DSC Resources you want and get all the VSCode IntelliSense magic you've come to expect.

So why are we making these changes?

Let's start out with some history. The first puppetlabs-dsc module was released in 2015 and it vendored the entire known DSC universe at the time. This was great for users — all they had to do was install the one module to get access to the power of DSC right in their Puppet codebase. But it also meant that the module was huge and had a ton of tiny files. This made Puppet's pluginsync process take ages and even fail in some circumstances.

The build process for vendoring all those DSC Resources and building the module was fragile too. In theory, anyone could rebuild a version of that module with any DSC Resources they wanted, even their own private code. In reality, the DSC ecosystem was in such flux that we struggled to keep the builder working. Eventually the changes caught up with us and it failed for good. This means that the module still works, but the DSC Resources that it uses are stuck in time and won't ever be updated.

To alleviate those concerns, we iterated the second approach, the puppetlabs-dsc_lite module, in 2018. This module didn't vendor any DSC Resources, and instead pulled out the abstraction layer and let you invoke any arbitrary DSC Resources via a simple resource type. That was great because the build pipeline was solid and testable and maintainable, and the module itself was tiny and reliable. Best of all, you could once again use modern DSC Resources.

The problem (you knew this was coming, right?) was it achieved those goals by simply offloading the hard administrative work to the user. The user was responsible for distributing all the underlying DSC Resources they wanted to use, and for knowing all the parameters of each resource. Since it supported arbitrary resources with arbitrary parameters, we couldn't even validate manifests other than the basic Puppet syntax, much less provide modern editor support like autocomplete or type validation.

So that brings us to today. Instead of providing a translation module, we extracted the core translation engine into a shared library and then created a tool (the Puppet.Dsc PowerShell Module) that vendors a single PowerShell module with DSC Resources into a shim Puppet module with all the proper parameters and type validation built in for each of those resources. Then we built a pipeline that crawls the PowerShell Gallery and generates a Puppet module for each new release of every PowerShell module with DSC Resources that it finds. These are published directly to the Forge and marked as Supported by Puppet. This means that now users will simply add any DSC Resource they want to use directly to their Puppetfile and start writing Puppet code.

You no longer need to be concerned with the under-the-hood implementation details. You don't need to care which tools were invoked to effect a change. Describe what you need in Puppet's effortlessly declarative language and then let Puppet do what it does best: abstract away the details and just make the changes you need.

Best of all, when paired with Puppet's VS Code extension, you'll get all the IntelliSense goodness that you've come to expect as you're writing your profile classes. Not only do you get context-sensitive syntax highlighting and autocompletion, but you'll get parameter validation that knows what data types to use and even which values are acceptable — and that all comes automatically from the wrapped DSC Resources!

DSC roadmap

We are currently recommending that all users begin moving to the new modules at their earliest convenience. The legacy puppetlabs-dsc module is now deprecated and will be officially unsupported as of July 21, 2021. The puppetlabs-dsc_lite module will be deprecated at that time and will be officially unsupported one year later. At that point, the DSC modules on the Forge will become the only supported solution.

User migration path

Users of the original puppetlabs-dsc module should remove that module from their Puppetfile and replace it with declarations for each of the modules they want. To achieve a no-code-changes migration, users can pin the DSC modules to the versions shipped in the latest release of puppetlabs-dsc following this guide.

Remember that much of the benefit of this new approach is that you don't need everything under the sun. Choose only the resources you will be using from this list and add the appropriate declarations to your Puppetfile:

• mod 'dsc-activedirectorycsdsc', '3.1.0-0-0'
• mod 'dsc-auditpolicydsc', '1.4.0-0-1'
• mod 'dsc-certificatedsc', '4.4.0-0-0'
• mod 'dsc-computermanagementdsc', '6.2.0-0-0'
• mod 'dsc-dfsdsc', '4.3.0-0-0'
• mod 'dsc-networkingdsc', '7.0.0-0-0'
• mod 'dsc-officeonlineserverdsc', '1.2.0-0-0'
• mod 'dsc-securitypolicydsc', '2.7.0-0-0'
• mod 'dsc-sharepointdsc', '3.2.0-0-0'
• mod 'dsc-sqlserverdsc', '12.3.0-0-0'
• mod 'dsc-storagedsc', '4.5.0-0-0'
• mod 'dsc-systemlocaledsc', '1.2.0-0-0'
• mod 'dsc-xactivedirectory', '2.24.0-0-0'
• mod 'dsc-xazure', '0.2.0-0-0'
• mod 'dsc-xazurepack', '1.4.0-0-0'
• mod 'dsc-xbitlocker', '1.4.0-0-0'
• mod 'dsc-xcredssp', '1.3.0-0-0'
• mod 'dsc-xdatabase', '1.9.0-0-0'
• mod 'dsc-xdefender', '0.2.0-0-0'
• mod 'dsc-xdhcpserver', '2.0.0-0-0'
• mod 'dsc-xdisk', '1.0.0-0-0'
• mod 'dsc-xdismfeature', '1.3.0-0-0'
• mod 'dsc-xdnsserver', '1.11.0-0-0'
• mod 'dsc-xexchange', '1.27.0-0-0'
• mod 'dsc-xfailovercluster', '1.12.0-0-0'
• mod 'ddsc-xhyper_v', '3.16.0-0-0'
• mod 'dsc-xinternetexplorerhomepage', '1.0.0-0-0'
• mod 'dsc-xjea', '0.2.16-6-0'
• mod 'dsc-xmysql', '2.1.0-0-0'
• mod 'dsc-xpendingreboot', '0.4.0-0-0'
• mod 'dsc-xphp', '1.2.0-0-0'
• mod 'dsc-xpowershellexecutionpolicy', '3.1.0-0-0'
• mod 'dsc-xpsdesiredstateconfiguration', '8.5.0-0-0'
• mod 'dsc-xremotedesktopadmin', '1.1.0-0-0'
• mod 'dsc-xremotedesktopsessionhost', '1.8.0-0-0'
• mod 'dsc-xrobocopy', '2.0.0-0-0'
• mod 'dsc-xscdpm', '1.2.0-0-0'
• mod 'dsc-xscom', '1.3.3-0-0'
• mod 'dsc-xscsma', '2.0.0-0-0'
• mod 'dsc-xscspf', '1.3.1-0-0'
• mod 'dsc-xscsr', '1.3.0-0-0'
• mod 'dsc-xscvmm', '1.2.4-0-0'
• mod 'dsc-xsmbshare', '2.1.0-0-0'
• mod 'dsc-xsqlps', '1.4.0-0-0'
• mod 'dsc-xtimezone', '1.8.0-0-0'
• mod 'dsc-xwebadministration', '2.5.0-0-0'
• mod 'dsc-xwebdeploy', '1.2.0-0-0'
• mod 'dsc-xwindowseventforwarding', '1.0.0-0-0'
• mod 'dsc-xwindowsrestore', '1.0.0-0-0'
• mod 'dsc-xwindowsupdate', '2.7.0-0-0'
• mod 'dsc-xwineventlog', '1.2.0-0-0'
• mod 'dsc-xwordpress', '1.1.0-0-0'

Then, if desired, modules can be updated to the latest versions one at a time while testing each change thoroughly, since the underlying DSC versions are likely to have changed significantly. No code changes will be required except to correct for DSC updates.

Users of the lightweight puppetlabs-dsc_lite module will have a few steps. First you will need to refactor your codebase to declare the proper resources. You can do this iteratively, since puppetlabs-dsc_lite can coexist with the new DSC modules. Make sure to add the required Puppet modules to your Puppetfile as you refactor each resource.

For example, this code:

dsc {'Download WebContent Zip':
  resource_name => 'XRemoteFile',
  module        => 'PSDesiredStateConfiguration',
  properties    => {
    ensure          => 'present',
    destinationpath => $zipfile,
    uri             => $zipuri,
  }
}

should be converted to look more like this:

dsc_xremotefile {'Download WebContent Zip':
  dsc_destinationpath => $zipfile,
  dsc_uri             => $zipuri,
}

One you've eliminated the use of the DSC Resource, then remove the puppetlabs-dsc_lite module and turn off any automation you're using to distribute the underlying DSC Resources. As always, after major refactors, the codebase should be tested heavily as you go.

Support policy for the new modules

These modules are a little unlike the other modules on the Forge in that they're autogenerated and they mostly consist of vendored code that we do not own and cannot support. Puppet will support the modules themselves just like any other Supported module, but not the vendored DSC content within the module.

To be specific:

1. As with all iterations of DSC integration, the team supports the translation layer between Puppet and DSC — if there is an issue with how Puppet is interacting with DSC then we will correct the problem.
2. We fully support the build of the autogenerated modules, even your own private modules. We will ensure that the tool accurately converts PowerShell modules with DSC Resources into functional Puppet modules.
3. Puppet does not provide support for bugs or features of the upstream PowerShell modules and their DSC Resources; if the correct values are being passed to DSC but the resource is failing or behaving unexpectedly, those issues are the domain of the upstream maintainers and should be reported upstream. We may, on a best-effort basis, offer advice on reporting issues.

Learn More

The team has posted a series of tutorials with more complete advice and testing or troubleshooting strategies. Follow that space, especially articles tagged as #dsc, for more resources as they're made available.

• Converting to use Puppetized DSC Modules
• Troubleshooting Puppetized DSC Modules