PowerShell DSC

kitchen-dsc is a Test Kitchen provisioner that applies PowerShell Desired State Configuration configurations to test instances, so you can test DSC configurations and resources the same way you would test a cookbook.

It does not require Chef Infra or Cinc on the instance at all — it applies DSC configurations directly.

kitchen-dsc is no longer under active development and has no active maintainers. It may continue to work for some or all use cases, but issues filed on GitHub will most likely not be triaged. If you are interested in maintaining it, come talk in #test-kitchen on Chef Community Slack.

Requirements

Windows test instances only. The instance must be running WMF 4 or newer.
A driver that can provide Windows instances, such as kitchen-vagrant, kitchen-hyperv, or kitchen-ec2
WMF 5 if you want to install modules from a PowerShell gallery

Installation

Add the provisioner to your Gemfile alongside Test Kitchen and a driver:

gem "test-kitchen"
gem "kitchen-dsc"
gem "kitchen-vagrant"

bundle install

Or install it directly:

gem install kitchen-dsc

Two ways to lay out a project

How you configure this provisioner depends on what you are testing.

Module style keeps the DSC configuration next to the module it exercises. Point configuration_script_folder and configuration_script at that file.

Repository style keeps a modules directory of DSC resources at the root of the repository, which the provisioner uploads to the instance before applying the configuration. modules_path controls where that directory is.

Quick start

Put a DSC configuration in examples/dsc_configuration.ps1, then:

---
driver:
  name: vagrant

provisioner:
  name: dsc
  dsc_local_configuration_manager_version: wmf5

platforms:
  - name: windows-2022

suites:
  - name: default

kitchen test

Or step through it:

kitchen create    # build the Windows instance
kitchen converge  # apply the DSC configuration
kitchen verify    # run your tests
kitchen destroy   # remove the instance

By default the provisioner looks for a configuration named after the suite, in examples/dsc_configuration.ps1.

The verbose stream is returned after the DSC job completes rather than while it runs, because WMF versions differ in how they expose that stream. Expect a delay before you see run details — a converge that appears to hang is often just working.

Setting Provisioner Configuration

All options are set under the provisioner: key in kitchen.yml, or per suite under suites[].provisioner:.

Configuration script

Option	Default	Description
`configuration_script_folder`	`examples`	Directory holding the PowerShell scripts that define the DSC configuration.
`configuration_script`	`dsc_configuration.ps1`	Name of the PowerShell script containing the DSC configuration command, and possibly its configuration data.
`configuration_name`	the suite name	Name of the configuration command to run.

Configuration data

Option	Default	Description
`configuration_data`	(unset)	YAML representation of the data passed to the configuration. Overrides any configuration data assigned in the script itself.
`configuration_data_variable`	`ConfigurationData`	Name of the variable holding the ConfigurationData hashtable. Can be set here or defined in the configuration script.

Local Configuration Manager

Option	Default	Description
`dsc_local_configuration_manager_version`	`wmf4`	Which LCM is in place. Also accepts `wmf4_with_update` and `wmf5`.
`dsc_local_configuration_manager`	(see below)	Hash of LCM settings.

wmf4_with_update means WMF 4 with KB3000850 applied, which adds support for configurations generated by WMF 5 along with a number of fixes. Today the only differences between wmf4 and the other two values are the action_after_reboot and debug_mode settings.

The LCM settings and their defaults:

Setting	Default	Notes
`action_after_reboot`	`StopConfiguration`	`wmf4_with_update` and `wmf5` only.
`reboot_if_needed`	`false`
`allow_module_overwrite`	`false`
`certificate_id`	`nil`
`configuration_mode`	`ApplyAndAutoCorrect`
`configuration_mode_frequency_mins`	`30`	`15` on `wmf5`.
`debug_mode`	`All`	`wmf4_with_update` only.
`refresh_frequency_mins`	`15`	`30` on `wmf5`.
`refresh_mode`	`PUSH`

Modules from a gallery

Installing modules from a gallery requires WMF 5 on the instance.

Option	Default	Description
`modules_from_gallery`	(unset)	Modules to install from a gallery. A string for one module, an array for several, or a hash matching the parameters of `Install-Module`. `Name` is required; `Force` is always applied and need not be given.
`gallery_name`	(unset)	Name of a custom PowerShell gallery to install from. If no package source with this name is registered on the machine, `gallery_uri` must be set too.
`gallery_uri`	(unset)	URI of a custom PowerShell gallery feed.
`nuget_force_bootstrap`	`true`	Bootstrap the NuGet package provider for PowerShell PackageManagement before installing modules.

Repository style testing

Option	Default	Description
`modules_path`	`modules`	Directory of modules containing DSC resources to upload to the instance, relative to the root of the repository, next to `kitchen.yml`.

Reboot handling

These are standard Test Kitchen provisioner options to which this provisioner gives DSC-specific defaults.

Option	Default	Description
`retry_on_exit_code`	`[35]`	Exit codes that cause the converge to be retried. Exit code 35 is DSC signalling that a reboot is required.
`max_retries`	`3`	Number of times to retry the converge on one of those exit codes.
`root_path`	driver default	Directory on the instance where the configuration and modules are staged.

Examples

Module style, with modules from a custom gallery

provisioner:
  name: dsc
  dsc_local_configuration_manager_version: wmf5
  dsc_local_configuration_manager:
    reboot_if_needed: true
    debug_mode: none
  configuration_script_folder: .
  configuration_script: SampleConfig.ps1
  gallery_uri: https://ci.appveyor.com/nuget/xWebAdministration
  gallery_name: xWebDevFeed
  modules_from_gallery:
    - xWebAdministration
    - name: xComputerManagement
      requiredversion: 1.4.0.0
      repository: PSGallery

suites:
  - name: test
    provisioner:
      configuration_data:
        AllNodes:
          - nodename: localhost
            role: webserver

Repository style

provisioner:
  name: dsc
  dsc_local_configuration_manager_version: wmf5
  modules_path: modules
  configuration_script_folder: examples
  configuration_script: webserver.ps1
  configuration_name: WebServer

Allowing reboots during a converge

provisioner:
  name: dsc
  dsc_local_configuration_manager_version: wmf5
  dsc_local_configuration_manager:
    reboot_if_needed: true
    action_after_reboot: ContinueConfiguration
  max_retries: 5

See Reboots for how Test Kitchen handles instances that restart mid-converge.

Per-suite configuration data

provisioner:
  name: dsc
  configuration_script_folder: examples
  configuration_script: webserver.ps1

suites:
  - name: default
    provisioner:
      configuration_data:
        AllNodes:
          - nodename: localhost
            role: webserver
  - name: minimal
    provisioner:
      configuration_data:
        AllNodes:
          - nodename: localhost
            role: minimal

Verifying DSC configurations

Pair this provisioner with kitchen-pester to write your assertions in Pester, which keeps the whole project in PowerShell:

provisioner:
  name: dsc

verifier:
  name: pester