win_dsc – Invokes a PowerShell DSC configuration — Ansible Documentation

- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# win_dsc – Invokes a PowerShell DSC configuration

New in version 2.4.

- Synopsis
- Parameters
- Notes
- Examples
- Return Values
- Status

## 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 string / 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[]`. If the type of the DSC resource option is a `DateTime`, you should use a string in the form of an ISO 8901 string to ensure the exact date is used. Since Ansible 2.8, Ansible will now validate the input fields against the DSC resource definition automatically. Older versions will silently ignore invalid fields.
module_version string | 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 string / 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/resources/resources 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.
- To see the valid options for a DSC resource, run the module with `-vvv` to show the possible module invocation. Default values are not shown in this output but are applied within the DSC engine.

## 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_dsc:
        resource_name: Registry
        Ensure: Present
        Key: HKEY_CURRENT_USER\ExampleKey
        ValueName: TestValue
        ValueData: TestData
        PsDscRunAsCredential_username: '{{ansible_user}}'
        PsDscRunAsCredential_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

    - name: Call DSC resource with DateTime option
      win_dsc:
        resource_name: DateTimeResource
        DateTimeOption: '2019-02-22T13:57:31.2311892+00:00'

    # 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
--- | --- | ---
module_version string | always | 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
verbose_set list | Ansible verbosity is -vvv or greater and a change occurred | The verbose output as a list from executing the DSC Set method. Sample: ["Perform operation 'Invoke CimMethod' with the following parameters, ", '[SERVER]: LCM: [Start Set ] [[File]DirectResourceAccess]', "Operation 'Invoke CimMethod' complete."]
verbose_test list | Ansible verbosity is -vvv or greater | The verbose output as a list from executing the DSC test method. Sample: ["Perform operation 'Invoke CimMethod' with the following parameters, ", '[SERVER]: LCM: [Start Test ] [[File]DirectResourceAccess]', "Operation 'Invoke CimMethod' complete."]

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Trond Hindenes (@trondhindenes)

Hint

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