dsc_lite

Table of Contents

1. Module Description - What the module does and why it is useful
2. Setup - The basics of getting started with dsc_lite
3. Usage - Configuring options and additional functionality
   • Specifying a DSC Resource version
   • Using PSCredential or MSFT_Credential
   • Using EmbeddedInstance or CimInstance
   • Handling Reboots with DSC
4. Reference - An under-the-hood peek at what the module is doing and how
5. Limitations - OS compatibility, etc.
   • Known Issues
   • Running Puppet and DSC without Administrative Privileges
6. Development - Guide for contributing to the module
7. Learn More About DSC
8. License

Module description

The Puppet dsc_lite module allows you to manage target nodes using arbitrary Windows PowerShell DSC (Desired State Configuration) Resources.

Warning:

Using dsc_lite requires advanced experience with DSC and PowerShell, unlike our other modules that are far easier to use. It is an alternative approach to Puppet's family of DSC modules, providing more flexibility for certain niche use cases. There are many drawbacks to this approach and we highly recommend that you use the existing family of DSC modules instead, where possible.

The dsc_lite module contains a lightweight dsc type, which is a streamlined and minimal representation of a DSC Resource declaration in Puppet syntax. This type does not contain any DSC resources itself, but can invoke arbitrary DSC Resources that already exist on the managed node. Much like the exec type, it simply passes parameters through to the underlying DSC Resource without any validation.

This means that you are responsible for:

1. Distributing the DSC Resources as needed to your managed nodes.
2. Validating all configuration data for dsc declarations to prevent runtime errors.
3. Troubleshooting all errors without property status reporting.

The existing family of DSC modules will manage all the DSC administration for you, meaning that all you need to do is install the module and start writing code. These modules also do parameter validation, meaning that errors surface during development instead of at runtime. And the VS Code integration will show you usage documentation as you write the code. These modules are automatically imported from the PowerShell Gallery on a daily basis, so they're always up to date.

You should only use the dsc_lite module when any of these cases apply to you:

• You need to use multiple versions of the same DSC resource
• The upstream DSC Resource's implementation does not match its declared API but is usable otherwise and needed.
  • In this case, dsc_lite should be treated as a stop-gap solution until the upstream DSC Resource can be patched to fix the misimplementation.
• You need to use a DSC Resource that isn't published to the Puppet Forge.
  • If you find a DSC Resource that hasn't been automatically imported, it's very likely due to an API mismatch as described above.
  • If you have custom DSC Resources, you can use the Puppet.dsc module builder to build your own Puppet module from it.

Windows system prerequisites

At least PowerShell 5.0, which is included in Windows Management Framework 5.0.

Note: PowerShell version as obtained from $PSVersionTable must be 5.0.10586.117 or greater.

Setup

puppet module install puppetlabs-dsc_lite

See known issues for troubleshooting setup.

Usage

The generic dsc type is a streamlined and minimal representation of a DSC Resource declaration in Puppet syntax. You can use a DSC Resource by supplying the same properties you would set in a DSC Configuration script, inside the properties parameter. For most use cases, the properties parameter accepts the same structure as the PowerShell syntax, with the substitution of Puppet syntax for arrays, hashes, and other data structures. You can use PowerShell on the command-line to identify the available parameters.

PS C:\Users\Administrator> Get-DscResource WindowsFeature | Select-Object -ExpandProperty Properties

Name                 PropertyType   IsMandatory Values
----                 ------------   ----------- ------
Name                 [string]              True {}
Credential           [PSCredential]       False {}
DependsOn            [string[]]           False {}
Ensure               [string]             False {Absent, Present}
IncludeAllSubFeature [bool]               False {}
LogPath              [string]             False {}
PsDscRunAsCredential [PSCredential]       False {}
Source               [string]             False {}

An example of that DSC resource specified in PowerShell:

WindowsFeature IIS {
  Ensure => 'present'
  Name   => 'Web-Server'
}

Would look like this in Puppet:

dsc {'iis':
  resource_name => 'WindowsFeature',
  module        => 'PSDesiredStateConfiguration',
  properties    => {
    ensure => 'present',
    name   => 'Web-Server',
  }
}

For the simplest cases, the above example is enough. However there are more advanced use cases in DSC that require more custom syntax in the dsc Puppet type. Since the dsc Puppet type has no prior knowledge of the type for each property in a DSC Resource, it can't format the hash correctly without some hints.

The properties parameter recognizes any key with a hash value that contains two keys: dsc_type and dsc_properties, as a indication of how to format the data supplied. The dsc_type contains the CimInstance name to use, and the dsc_properties contains a hash or an array of hashes, representing the data for the CimInstances.

A contrived, but simple example follows:

dsc {'foo':
  resource_name => 'xFoo',
  module        => 'xFooBar',
  properties    => {
    ensure  => 'present',
    fooinfo => {
      'dsc_type'       => 'FooBarBaz',
      'dsc_properties' => {
        "wakka"  => "woot",
        "number" => 8090
      }
    }
  }
}

Specifying a DSC Resource version

When there is more than one version installed for a given DSC Resource module, you must specify the version in your declaration. You can specify the version with similar syntax to a DSC configuration script, by using a hash containing the name and version of the DSC Resource module.

dsc {'iis_server':
  resource_name => 'WindowsFeature',
  module        => {
    name    => 'PSDesiredStateConfiguration',
    version => '1.1'
  },
  properties => {
    ensure => 'present',
    name   => 'Web-Server',
  }
}

Distributing DSC Resources

There are several methods to distribute DSC Resources to the target nodes for the dsc_lite module to use.

PowerShell Gallery

You can choose to install DSC Resources using a mechanism that calls the builtin PowerShell package management system called PackageManagement. It uses the PowerShellGet module and pulls from the PowerShell Gallery. You are responsible for orchestrating this before Puppet is run on the host, or you can do so using exec in your Puppet manifest. This gives you control of the process, but requires you to manage the complexity yourself.

The following example shows how to install the xPSDesiredStateConfiguration DSC Resource, and can be extended to support different DSC Resource names. This example assumes a package repository has been configured.

exec { 'xPSDesiredStateConfiguration-Install':
  command   => 'Install-Module -Name xPSDesiredStateConfiguration -Force',
  provider  => 'powershell',
}

Puppet hbuckle/powershellmodule module

The community created module hbuckle/powershellmodule handles using PackageMangement and PowerShellGet to download and install DSC Resources on target nodes. It is another Puppet package provider, so it similar to how you install packages with Puppet for any other use case.

Installing a DSC Resource can be as simple as the following declaration:

package { 'xPSDesiredStateConfiguration':
  ensure   => latest,
  provider => 'windowspowershell',
  source   => 'PSGallery',
}

The module supports configuring repository sources and other PackageManagement options, for example configuring trusted package repositories and private or on-premise package sources. For more information, please see the forge page.

Chocolatey

Puppet already works well with chocolatey. You can create chocolatey packages that wrap the DSC Resources you need.

package { 'xPSDesiredStateConfiguration':
  ensure   => latest,
  provider => 'chocolatey',
}

This works well for users that already have a chocolatey source feed setup internally, as all you need to do is to push the DSC Resource chocolatey packages to the internal feed. If you use the community feed, you will have to check that the DSC Resource you use is present there.

Using PSCredential or MSFT_Credential

Specifying credentials in DSC Resources requires using a PSCredential object. The dsc type automatically creates a PSCredential if the dsc_type has MSFT_Credential as a value.

dsc {'foouser':
  resource_name => 'User',
  module        => 'PSDesiredStateConfiguration',
  properties    => {
    'username'    => 'jane-doe',
    'description' => 'Jane Doe user',
    'ensure'      => 'present',
    'password'    => {
      'dsc_type'       => 'MSFT_Credential',
      'dsc_properties' => {
        'user'     => 'jane-doe',
        'password' => Sensitive('StartFooo123&^!')
      }
    },
    'passwordneverexpires' => false,
    'disabled'             => true,
  }
}

Some DSC Resources require a password or passphrase for a setting, but do not need a user name. All credentials in DSC must be a PSCredential, so these passwords still have to be specified in a PSCredential format, even if there is no user to specify. How you specify the PSCredential depends on how the DSC Resource implemented the password requirement. Some DSC Resources accept an empty or null string for user, others do not. If it does not accept an empty or null string, then specify a dummy value. Do not use undef as it will error out.

You can also use the Puppet Sensitive type to ensure logs and reports redact the password.

dsc {'foouser':
  resource_name => 'User',
  module        => 'PSDesiredStateConfiguration',
  properties    => {
    'username'    => 'jane-doe',
    'description' => 'Jane Doe user',
    'ensure'      => 'present',
    'password'    => {
      'dsc_type'       => 'MSFT_Credential',
      'dsc_properties' => {
        'user'     => 'jane-doe',
        'password' => Sensitive('StartFooo123&^!')
      }
    },
    'passwordneverexpires' => false,
    'disabled'             => true,
  }
}

Using CimInstance

A DSC Resource may need a more complex type than a simple key value pair, for example, an EmbeddedInstance. An EmbeddedInstance is serialized as CimInstance over the wire. In order to represent a CimInstance in the dsc type, use the dsc_type key to specify which CimInstance to use. If the CimInstance is an array, append a [] to the end of the name.

For example, create a new IIS website using the xWebSite DSC Resource, bound to port 80. Use dsc_type to specify a MSFT_xWebBindingInformation CimInstance, and append [] to indicate that it is an array. Note that you do this even if you are only putting a single value in dsc_properties.

dsc {'NewWebsite':
  resource_name => 'xWebsite',
  module        => 'xWebAdministration',
  properties    => {
    ensure       => 'Present',
    state        => 'Started',
    name         => 'TestSite',
    physicalpath => 'C:\testsite',
    bindinginfo  => {
      'dsc_type'       => 'MSFT_xWebBindingInformation[]',
      'dsc_properties' => {
        "protocol" => "HTTP",
        "port"     => 80
      }
    }
  }
}

To show using more than one value in dsc_properties, create the same site but bound to both port 80 and 443.

dsc {'NewWebsite':
  resource_name => 'xWebsite',
  module        => 'xWebAdministration',
  properties    => {
    ensure       => 'Present',
    state        => 'Started',
    name         => 'TestSite',
    physicalpath => 'C:\testsite',
    bindinginfo  => {
      'dsc_type'       => 'MSFT_xWebBindingInformation[]',
      'dsc_properties' => [
        {
          "protocol" => "HTTP",
          "port"     => 80
        },
        {
          'protocol'              => 'HTTPS',
          'port'                  => 443,
          'certificatethumbprint' => 'F94B4CC4C445703388E418F82D1BBAA6F3E9E512',
          'certificatestorename'  => 'My',
          'ipaddress'             => '*'
        }
      ]
    }
  }
}

Handling reboots with DSC

Add the following reboot resource to your manifest. It must have the name dsc_reboot for the dsc module to find and use it.

reboot { 'dsc_reboot' :
  message => 'DSC has requested a reboot',
  when    => 'pending',
  onlyif  => 'pending_dsc_reboot',
}

Reference

For information on the types, see REFERENCE.md.

Limitations

• DSC Composite Resources are not supported.

• DSC requires PowerShell Execution Policy for the LocalMachine scope to be set to a less restrictive setting than Restricted. If you see the error below, see MODULES-2500 for more information.

  Error: /Stage[main]/Main/Dsc_xgroup[testgroup]: Could not evaluate: Importing module MSFT_xGroupResource failed with
  error - File C:\Program
  Files\WindowsPowerShell\Modules\PuppetVendoredModules\xPSDesiredStateConfiguration\DscResources\MSFT_xGroupR
  esource\MSFT_xGroupResource.psm1 cannot be loaded because running scripts is disabled on this system. For more
  information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170.
  

• You cannot use forward slashes for the MSI Path property for the Package DSC Resource. The underlying implementation does not accept forward slashes instead of backward slashes in paths, and it throws a misleading error that it could not find a Package with the Name and ProductId provided. See MODULES-2486 for more examples and information on this subject.

• Using this module with the 3.8.x x86 version of Puppet is highly discouraged, though it is supported. Normally, this module employs a technique to dramatically improve performance by reusing a PowerShell process to execute DSC related commands. However, due to the Ruby 1.9.3 runtime used with the 3.8.x x86 version of Puppet, this technique must be disabled, resulting in at least a 2x slowdown.

Known Issues

--noop mode, puppet resource and property change notifications are currently not implemented. See MODULES-2270 for details.

Running Puppet and DSC without administrative privileges

While there are options for using Puppet with a non-administrative account, DSC is limited to accounts with administrative privileges. The underlying CIM implementation DSC uses for DSC Resource invocation, and the Invoke-DscResource cmdlet, require administrative credentials.

The Puppet agent on a Windows node can run DSC with a normal default install. If the Puppet agent is configured to use an alternate user account, it must have administrative privileges on the system to run DSC.

Troubleshooting

When Puppet runs, the dsc_lite module takes the code supplied in your Puppet manifest and converts it into PowerShell code that is sent directly to the DSC engine using Invoke-DscResource. You can see both the commands sent and the result of this by running Puppet interactively, for example, puppet apply --debug. It outputs the PowerShell code that is sent to DSC to execute and return data from DSC. For example:

Notice: Compiled catalog for win2012r2 in environment production in 0.82 seconds
Debug: Creating default schedules
Debug: Loaded state in 0.03 seconds
Debug: Loaded state in 0.05 seconds
Info: Applying configuration version '1475264065'
Debug: Reloading posix reboot provider
Debug: Facter: value for uses_win32console is still nil
Debug: PowerShell Version: 5.0.10586.117
$invokeParams = @{
Name          = 'ExampleDSCResource'
Method        = 'test'
Property      = @{
property1 = 'value1'
property2 = 'value2'
}
ModuleName = 'ExampleDscResourceModule'
}
############### SNIP ################
Debug: Waited 50 milliseconds...
############### SNIP ################
Debug: Waited 500 total milliseconds.
Debug: Dsc Resource returned: {"rebootrequired":false,"indesiredstate":false,"errormessage":""}
Debug: Dsc Resource Exists?: false
Debug: ensure: present
############### SNIP ################
$invokeParams = @{
Name          = 'ExampleDSCResource'
Method        = 'set'
Property      = @{
property1 = 'value1'
property2 = 'value2'
}
ModuleName = 'ExampleDscResourceModule'
}
############### SNIP ################\
Debug: Waited 100 total milliseconds.
Debug: Create Dsc Resource returned: {"rebootrequired":false,"indesiredstate":true,"errormessage":""}
Notice: /Stage[main]/Main/Dsc_exampledscresource[foober]/ensure: invoked
Debug: /Stage[main]/Main/Dsc_exampledscresource[foober]: The container Class[Main] will propagate my refresh event
Debug: Class[Main]: The container Stage[main] will propagate my refresh event
Debug: Finishing transaction 56434520
Debug: Storing state
Debug: Stored state in 0.10 seconds
############### SNIP ################

This shows us that there wasn't a problem parsing the manifest and turning it into a command to send to DSC. It also shows that there are two commands/operations for every DSC Resource executed, a SET and a test. DSC operates in two stages, it first tests if a system is in the desired state, and then it sets the state of the system to the desired state. You can see the result of each operation in the debug log.

By using the debug logging of a Puppet run, you can troubleshoot the application of DSC Resources during the development of your Puppet manifests.

Development

Acceptance tests for this module leverage puppet_litmus. To run the acceptance tests follow the instructions here. You can also find a tutorial and walkthrough of using Litmus and the PDK on YouTube.

If you run into an issue with this module, or if you would like to request a feature, please file a ticket. Every Monday the Puppet IA Content Team has office hours in the Puppet Community Slack, alternating between an EMEA friendly time (1300 UTC) and an Americas friendly time (0900 Pacific, 1700 UTC).

If you have problems getting this module up and running, please contact Support.

If you submit a change to this module, be sure to regenerate the reference documentation as follows:

puppet strings generate --format markdown --out REFERENCE.md

Contributors

To see who's already involved, see the list of contributors.

Learn More About DSC

You can learn more about PowerShell DSC from the following online resources:

• Microsoft PowerShell Desired State Configuration Overview - Starting point for DSC topics
• Microsoft PowerShell DSC Resources page - For more information about built-in DSC Resources
• Microsoft PowerShell xDSCResources Github Repo - For more information about xDscResources
• Windows PowerShell Blog - DSC tagged posts from the Microsoft PowerShell Team
• Using Puppet and DSC to Report on Environment Change - PuppetConf 10-2017 talk and slides
• Puppet Inc Windows DSC & WSUS Webinar 9-17-2015 webinar - How DSC works with Puppet
• Better Together: Managing Windows with Puppet, PowerShell and DSC - PuppetConf 10-2015 talk and slides
• PowerShell.org - Community based DSC tagged posts
• PowerShell Magazine - Community based DSC tagged posts

There are several books available as well. Here are some selected books for reference:

• Learning PowerShell DSC 2nd Edition - James Pogran is a member of the team here at Puppet Inc working on the DSC/Puppet integration
• The DSC Book - Powershell.org community contributed content
• Pro PowerShell Desired State Configuration - Ravikanth Chaganti

License

• Copyright (c) 2014 Marc Sutter, original author
• Copyright (c) 2015 - Present Puppet Inc
• License: Apache License, Version 2.0

Reference

Table of Contents

Resource types

• base_dsc_lite: The base Puppet DSC type that all of the types inherit from. Do not use this directly.
• dsc: The dsc type allows specifying any DSC Resource declaration as a minimal Puppet declaration.

Resource types

base_dsc_lite

The base Puppet DSC type that all of the types inherit from. Do not use this directly.

Parameters

The following parameters are available in the base_dsc_lite type.

• name
• provider

name

namevar

A name to describe your resource, used for uniqueness.

provider

The specific backend to use for this base_dsc_lite resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

dsc

The dsc type allows specifying any DSC Resource declaration as a minimal Puppet declaration.

Examples

dsc {'iis':
  resource_name => 'WindowsFeature',
  module        => 'PSDesiredStateConfiguration',
  properties    => {
    ensure => 'present',
    name   => 'Web-Server',
  }
}

Properties

The following properties are available in the dsc type.

ensure

Valid values: present

An optional property that specifies that the DSC resource should be invoked.

Parameters

The following parameters are available in the dsc type.

• module
• name
• properties
• provider
• resource_name

module

Name of the DSC Resource module to use. For example, the xPSDesiredStateConfiguration DSC Resource module contains the xRemoteFile DSC Resource.

name

namevar

Name of the declaration. This has no affect on the DSC Resource declaration and is not used by the DSC Resource.

properties

Hash of properties to pass to the DSC Resource.

To express EmbeddedInstances, the properties parameter recognizes any key with a hash value that contains two keys — dsc_type and dsc_properties — as a indication of how to format the data supplied. The dsc_type contains the CimInstance name to use, and the dsc_properties contains a hash or an array of hashes representing the data for the CimInstances. If the CimInstance is an array, we append a [] to the end of the name.

provider

The specific backend to use for this dsc resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

resource_name

Name of the DSC Resource to use. For example, the xRemoteFile DSC Resource.

Change log

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

v3.2.0 (2022-01-27)

Full Changelog

Added

• (maint) Add messaging about the differences between this and the dsc modules #188 (binford2k)

v3.1.0 (2021-03-31)

Full Changelog

Added

• (MODULES-10985) - Raise Reboot upper bound to 5 #175 (david22swan)
• pdksync - (feat) - Add support for Puppet 7 #171 (daianamezdrea)

Fixed

• (MODULES-10471) Allow namevar to have special chars #148 (jarretlavallee)

v3.0.1 (2020-01-16)

Full Changelog

Fixed

• (MAINT) Safeguard loading ruby-pwsh #143 (michaeltlombardi)

v3.0.0 (2019-12-13)

Full Changelog

Changed

• (FM 8425) - Replace Library Code #134 (david22swan)

v2.0.2 (2019-09-05) (Supported Release 2.0.2)

Fixed

• Fixed function that validates paths in $env:lib variable (MODULES-9800)

2019-08-22 - Supported Release 2.0.1

Fixed

• Fixed regression in guarding of library code which caused facter runs to fail on non-Windows systems.

2019-08-20 - Supported Release 2.0.0

Added

• Added a note to the readme specifying the exact PowerShell version required for the module to function (MODULES-7762)

Changed

• Increase the named pipe timeout to 180 seconds to prevent runs from failing waiting for a pipe to open (MODULES-9086)

Removed

• Support for Puppet 4x, raising the minimum supported version of Puppet to 5.5.10 (MODULES-9336)

2019-04-23 - Supported Release 1.2.1

Fixed

• Ensure sensitive values are redacted in debug output (MODULES-8856)

2019-02-07

Summary

Release fixes sensitive data types to function when master and agent are different major versions of Puppet.

Changed

• Updated README.md to prevent daily unwanted reboots when handling reboots with dsc_lite MODULES-7716
• PDK update to version 1.8.0 MODULES-8532

Fixed

• Ensure that using sensitive values in dsc_lite resource declarations functions when the master and agent are different major versions MODULES-8175

2018-11-20

Changed

Updated metadata for Puppet version 6.x

2018-08-30 - Supported Release 1.0.0

Changed

• Clarify target user for dsc_lite in README (MODULES-7556)
• General README improvements

2018-08-02 - Unsupported Release 0.6.0

Summary

Small release with bug fixes and a reporting improvement.

Changed

• Ensure the output report for resources prefixes type names with dsc_lite_#{resource_name} for improved reporting (MODULES-7178)

Fixed

• Fix validation for required parameters (MODULES-7485)
• Fix crash on Puppet 4 / WMF < 5 (MODULES-7554)

2018-07-10 - Unsupported Release 0.5.0

Summary

MODULES-7253 introduced a breaking change, where the repetitive use of dsc_resource_... was removed.

Changed

• BREAKING: Renamed all parameters for resource declarations, will require manifest modifications. (MODULES-7253)
• Refactor acceptance tests into beaker rpsec (MODULES-6572, MODULES-6751, MODULES-6517)
• Changed created event to invoked (MODULES-7179)

Removed

• Removed unused ensurable values (MODULES-7197)
• Removed redundant acceptance tests (MODULES-7041)

2018-06-07 - Unsupported Release 0.4.0

Summary

Small release with bug fixes.

Fixed

• Support for Sensitive data type (MODULES-7141)
• UTF-8 support in ERB template creation (MODULES-7143)

2018-05-23 - Unsupported Release 0.3.0

Summary

Small release with documentation and minor bug fixes.

Added

• Added Server 2016 to metadata (MODULES-4271)

Changed

• Bump the puppetlabs-reboot module dependancy to reflect that the new version is 2.0.0 (MODULES-6678)
• Documented null username PSCredential (MODULES-6992)
• Emit a better message when PowerShell version is unsuitable for provider (MODULES-6860)
• Documented the DSC Resource Distribution process (MODULES-7105)

Fixed

• Fixed Named Pipes Server on Windows Server 2008r2 (MODULES-6930)

2018-02-02 - Unsupported Release 0.2.0

Summary

Small release with breaking change to support for DSC Versions.

Changed

• Implement DSC resource version support (MODULES-5845)

2018-01-11 - Unsupported Release 0.1.0

Summary

Initial unsupported release of the dsc_lite module.

Added

• Implement generic DSC resource (MODULES-5842)
• Update generic dsc resource invoker to support CIM Instances (MODULES-6323)
• Copy Powershell manager from existing DSC module (MODULES-5844)
• Document tradeoffs between generic DSC and current DSC (MODULES-5847)

Changed

• Rename assets named DSC in the module to the new name of DSC_Lite (MODULES-5843)
• Use dsc_puppetfakeresource in acceptance tests (MODULES-6132)
• Update readme for dsc_lite changes (MODULES-6378)

Removed

• Remove generated types and vendored code from module (MODULES-5968)
• Remove build tasks and assets from module (MODULES-6019)

* This Changelog was automatically generated by github_changelog_generator