Invokes a PowerShell DSC configuration
- 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.
Note
- By default there are a few builtin resources that come with PowerShell 5.0, See https://docs.microsoft.com/en-us/powershell/scripting/dsc/resources/resources for more information on these resources.
- Custom DSC resources can be installed with :ref:`community.windows.win_psmodule <community.windows.win_psmodule_module>` 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. - The DSC engine requires the HTTP WSMan listener to be online and its port configured as the default listener for HTTP. This is set up by default but if a custom HTTP port is used or only a HTTPS listener is present then the module will fail. See the examples for a way to check this out in PowerShell.
- The Local Configuration Manager
LCMon the targeted host in question should be disabled to avoid any conflicts with resources being applied by this module. See https://devblogs.microsoft.com/powershell/invoking-powershell-dsc-resources-directly/ for more information on hwo to disableLCM.
- name: Verify the WSMan HTTP listener is active and configured correctly
ansible.windows.win_shell: |
$port = (Get-Item -LiteralPath WSMan:\localhost\Client\DefaultPorts\HTTP).Value
$onlinePorts = @(Get-ChildItem -LiteralPath WSMan:\localhost\Listener |
Where-Object { 'Transport=HTTP' -in $_.Keys } |
Get-ChildItem |
Where-Object Name -eq Port |
Select-Object -ExpandProperty Value)
if ($port -notin $onlinePorts) {
"The default client port $port is not set up as a WSMan HTTP listener, win_dsc will not work."
}
- name: Extract zip file
ansible.windows.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
ansible.windows.win_dsc:
resource_name: WindowsFeature
Name: telnet-client
- name: Edit HKCU reg key under specific user
ansible.windows.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
ansible.windows.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
ansible.windows.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
ansible.windows.win_psmodule:
name: xWebAdministration
state: present
- name: Create IIS Website with Binding and Authentication options
ansible.windows.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: yesCommon return values are documented here, the following are the fields unique to this module:
- Trond Hindenes (@trondhindenes)