win_dsc – Invokes a PowerShell DSC configuration¶
New in version 2.4.
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¶
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 PsDscRunAsCredentialset.
- To see the valid options for a DSC resource, run the module with -vvvto 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:
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.
