win_dsc - Invokes a PowerShell DSC configuration¶

New in version 2.4.

Synopsis
Parameters
Notes
Examples
Return Values
Status
Maintenance
- Author

Synopsis ¶

Configures a resource using PowerShell DSC.
Requires PowerShell version 5.0 or newer.
Most of the options for this module are dynamic and will vary depending on the DSC Resource specified in resource_name.
See Desired State Configuration for more information on how to use this module.

Parameters ¶

Parameter	Choices/Defaults	Comments
free_form required		The win_dsc module takes in multiple free form options based on the DSC resource being invoked by resource_name. There is no option actually named `free_form` so see the examples. This module will try and convert the option to the correct type required by the DSC resource and throw a warning if it fails. If the type of the DSC resource option is a `CimInstance` or `CimInstance[]`, this means the value should be a dictionary or list of dictionaries based on the values required by that option. If the type of the DSC resource option is a `PSCredential` then there needs to be 2 options set in the Ansible task definition suffixed with `_username` and `_password`. If the type of the DSC resource option is an array, then a list should be provided but a comma separated string also work. Use a list where possible as no escaping is required and it works with more complex types list `CimInstance[]`.
module_version	Default: latest	Can be used to configure the exact version of the DSC resource to be invoked. Useful if the target node has multiple versions installed of the module containing the DSC resource. If not specified, the module will follow standard PowerShell convention and use the highest version available.
resource_name required		The name of the DSC Resource to use. Must be accessible to PowerShell using any of the default paths.

Notes ¶

Note

By default there are a few builtin resources that come with PowerShell 5.0, see https://docs.microsoft.com/en-us/powershell/dsc/builtinresource for more information on these resources.
Custom DSC resources can be installed with win_psmodule using the name option.
The DSC engine run’s each task as the SYSTEM account, any resources that need to be accessed with a different account need to have PsDscRunAsCredential set.

Examples ¶

- name: Extract zip file
  win_dsc:
    resource_name: Archive
    Ensure: Present
    Path: C:\Temp\zipfile.zip
    Destination: C:\Temp\Temp2

- name: Install a Windows feature with the WindowsFeature resource
  win_dsc:
    resource_name: WindowsFeature
    Name: telnet-client

- name: Edit HKCU reg key under specific user
  win_regedit:
    resource_name: Registry
    Ensure: Present
    Key: HKEY_CURRENT_USER\ExampleKey
    ValueName: TestValue
    ValueData: TestData
    PsDscRunAsCredential_username: '{{ansible_user}}'
    PsDscRunAsCredentual_password: '{{ansible_password}}'
  no_log: true

- name: Create file with multiple attributes
  win_dsc:
    resource_name: File
    DestinationPath: C:\ansible\dsc
    Attributes: # can also be a comma separated string, e.g. 'Hidden, System'
    - Hidden
    - System
    Ensure: Present
    Type: Directory

# more complex example using custom DSC resource and dict values
- name: Setup the xWebAdministration module
  win_psmodule:
    name: xWebAdministration
    state: present

- name: Create IIS Website with Binding and Authentication options
  win_dsc:
    resource_name: xWebsite
    Ensure: Present
    Name: DSC Website
    State: Started
    PhysicalPath: C:\inetpub\wwwroot
    BindingInfo: # Example of a CimInstance[] DSC parameter (list of dicts)
    - Protocol: https
      Port: 1234
      CertificateStoreName: MY
      CertificateThumbprint: C676A89018C4D5902353545343634F35E6B3A659
      HostName: DSCTest
      IPAddress: '*'
      SSLFlags: '1'
    - Protocol: http
      Port: 4321
      IPAddress: '*'
    AuthenticationInfo: # Example of a CimInstance DSC parameter (dict)
      Anonymous: no
      Basic: true
      Digest: false
      Windows: yes

Return Values ¶

Common return values are documented here, the following are the fields unique to this module:

Key	Returned	Description
message string	error	any error message from invoking the DSC resource Sample: Multiple DSC modules found with resource name xyz
module_version string	success	The version of the dsc resource/module used. Sample: 1.0.1
reboot_required boolean	always	Flag returned from the DSC engine indicating whether or not the machine requires a reboot for the invoked changes to take effect. Sample: True

Status ¶

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Maintenance ¶

This module is flagged as community which means that it is maintained by the Ansible Community. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Community, see here.

Author ¶

Trond Hindenes (@trondhindenes)

Hint

If you notice any issues in this documentation you can edit this document to improve it.