Desired State Configuration

    More details on DSC can be viewed at DSC Overview.

    Host Requirements

    To use the win_dsc module, a Windows host must have PowerShell v5.0 ornewer installed. All supported hosts, except for Windows Server 2008 (non R2) can beupgraded to PowerShell v5.

    Once the PowerShell requirements have been met, using DSC is as simple ascreating a task with the win_dsc module.

    DSC and Ansible modules have a common goal which is to define and ensure the state of aresource. Because ofthis, resources like the DSC and Ansible win_file can be used to achieve the same result. Deciding which to use dependson the scenario.

    Reasons for using an Ansible module over a DSC resource:

    • The host does not support PowerShell v5.0, or it cannot easily be upgraded
    • The DSC resource does not offer a feature present in an Ansible module. For examplewin_regedit can manage the REG_NONE property type, while the DSCRegistry resource cannot
    • DSC resources have limited check mode support, while some Ansible modules havebetter checks
    • DSC resources do not support diff mode, while some Ansible modules do
    • Custom resources require further installation steps to be run on the hostbeforehand, while Ansible modules are in built-in to Ansible
    • There are bugs in a DSC resource where an Ansible module works

    Reasons for using a DSC resource over an Ansible module:

    • The Ansible module does not support a feature present in a DSC resource
    • There is no Ansible module available
    • There are bugs in an existing Ansible module

    In the end, it doesn’t matter whether the task is performed with DSC or anAnsible module; what matters is that the task is performed correctly and theplaybooks are still readable. If you have more experience with DSC over Ansibleand it does the job, just use DSC for that task.

    How to Use DSC?

    The win_dsc module takes in a free-form of options so that it changesaccording to the resource it is managing. A list of built in resources can befound at resources.

    Using the resource as an example, this is the DSC definition as documented by Microsoft:

    When defining the task, resource_name must be set to the DSC resource beingused - in this case the resource_name should be set to Registry. Themodule_version can refer to a specific version of the DSC resourceinstalled; if left blank it will default to the latest version. The otheroptions are parameters that are used to define the resource, such as Key andValueName. While the options in the task are not case sensitive,keeping the case as-is is recommended becuase it makes it easier to distinguish DSCresource options from Ansible’s win_dsc options.

    1. - name: use win_dsc module with the Registry DSC resource
    2.   win_dsc:
    3.     resource_name: Registry
    4.     Ensure: Present
    5.     Key: HKEY_LOCAL_MACHINE\SOFTWARE\ExampleKey
    6.     ValueName: TestValue
    7.     ValueData: TestData

    Each DSC resource property has a type that is associated with it. Ansiblewill try to convert the defined options to the correct type during execution.For simple types like [string] and [bool] this is a simple operation,but complex types like [PSCredential] or arrays (like [string[]]) thisrequire certain rules.

    PSCredential

    A object is used to store credentials in a secure way, butAnsible has no way to serialize this over JSON. To set a DSC PSCredential property,the definition of that parameter should have two entries that are suffixed with_username and _password for the username and password respectively.For example:

    1. PsDscRunAsCredential_username: '{{ansible_user}}'
    2. PsDscRunAsCredential_password: '{{ansible_password}}'
    3.  
    4. SourceCredential_username: AdminUser
    5. SourceCredential_password: PasswordForAdminUser

    Note

    You should set no_log: true on the task definition inAnsible to ensure any credentials used are not stored in any log file orconsole output.

    CimInstance Type

    A [CimInstance] object is used by DSC to store a dictionary object based ona custom class defined by that resource. Defining a value that takes in a[CimInstance] in YAML is the same as defining a dictionary in YAML.For example, to define a [CimInstance] value in Ansible:

    1. # [CimInstance]AuthenticationInfo == MSFT_xWebAuthenticationInformation
    2. AuthenticationInfo:
    3.   Anonymous: no
    4.   Basic: yes
    5.   Digest: no
    6.   Windows: yes

    In the above example, the CIM instance is a representation of the classMSFTxWebAuthenticationInformation <https://github.com/PowerShell/xWebAdministration/blob/dev/DSCResources/MSFT_xWebsite/MSFT_xWebsite.schema.mof>``.This class accepts four boolean variables, ``Anonymous, Basic,Digest, and Windows. The keys to use in a [CimInstance] depend onthe class it represents. Please read through the documentation of the resourceto determine the keys that can be used and the types of each key value. Theclass definition is typically located in the <resource name>.schema.mof.

    Arrays

    Simple type arrays like [string[]] or [UInt32[]] are defined as a listor as a comma separated string which are then cast to their type. Using a listis recommended because the values are not manually parsed by the win_dscmodule before being passed to the DSC engine. For example, to define a simpletype array in Ansible:

    Complex type arrays like [CimInstance[]] (array of dicts), can be definedlike this example:

    1. # [CimInstance[]]BindingInfo == MSFT_xWebBindingInformation
    2. BindingInfo:
    3. - Protocol: https
    4.   Port: 443
    5.   CertificateStoreName: My
    6.   CertificateThumbprint: C676A89018C4D5902353545343634F35E6B3A659
    7.   HostName: DSCTest
    8.   SSLFlags: 1
    9. - Protocol: http
    10.   Port: 80
    11.   IPAddress: '*'

    The above example, is an array with two values of the class MSFTxWebBindingInformation <.When defining a ``[CimInstance[]], be sure to read the resource documentationto find out what keys to use in the definition.

    Run As Another User

    By default, DSC runs each resource as the SYSTEM account and not the accountthat Ansible use to run the module. This means that resources that are dynamicallyloaded based on a user profile, like the registry hive,will be loaded under the SYSTEM profile. The parameter_PsDscRunAsCredential` is a parameter that can be set for every DSC resourceforce the DSC engine to run under a different account. AsPsDscRunAsCredential has a type of PSCredential, it is defined with the_username and _password suffix.

    1. - name: use win_dsc with PsDscRunAsCredential to run as a different user
    2.   win_dsc:
    3.     resource_name: Registry
    4.     Ensure: Present
    5.     Key: HKEY_CURRENT_USER\ExampleKey
    6.     ValueName: TestValue
    7.     ValueData: TestData
    8.     PsDscRunAsCredential_username: '{{ansible_user}}'
    9.     PsDscRunAsCredential_password: '{{ansible_password}}'
    10.   no_log: true

    DSC resources are not limited to the built-in options from Microsoft. Custommodules can be installed to manage other resources that are not usually available.

    You can use thePSGallery to find custom resources, along with documentation on how to install them on a Windows host.

    The Find-DscResource cmdlet can also be used to find custom resources. For example:

    1. # find all DSC resources in the configured repositories
    2. Find-DscResource
    3.  
    4. # find all DSC resources that relate to SQL
    5. Find-DscResource -ModuleName "*sql*"

    Note

    DSC resources developed by Microsoft that start with x, means theresource is experimental and comes with no support.

    Installing a Custom Resource

    There are three ways that a DSC resource can be installed on a host:

    • Manually with the Install-Module cmdlet
    • Using the win_psmodule Ansible module
    • Saving the module manually and copying it another host

    This is an example of installing the xWebAdministration resources usingwin_psmodule:

    Once installed, the win_dsc module will be able to use the resource by referencing itwith the resource_name option.

    The first two methods above only work when the host has access to the internet.When a host does not have internet access, the module must first be installedusing the methods above on another host with internet access and then copiedacross. To save a module to a local filepath, the following PowerShell cmdletcan be run:

    1. Save-Module -Name xWebAdministration -Path C:\temp

    This will create a folder called xWebAdministration in C:\temp whichcan be copied to any host. For PowerShell to see this offline resource, it mustbe copied to a directory set in the PSModulePath environment variable.In most cases the path C:\Program Files\WindowsPowerShell\Module is setthrough this variable, but the module can be used to add differentpaths.

    Examples

    1. - name: extract a zip file
    2.   win_dsc:
    3.     resource_name: Archive
    4.     Destination: c:\temp\output
    5.     Path: C:\temp\zip.zip
    6.     Ensure: Present

    Create a directory

    1. - name: create file with some text
    2.   win_dsc:
    3.     resource_name: File
    4.     DestinationPath: C:\temp\file
    5.     Contents: |
    6.         Hello
    7.         World
    8.     Ensure: Present
    9.     Type: File
    10.  
    11. - name: create directory that is hidden is set with the System attribute
    12.   win_dsc:
    13.     resource_name: File
    14.     DestinationPath: C:\temp\hidden-directory
    15.     Attributes: Hidden,System
    16.     Ensure: Present
    17.     Type: Directory

    Setup IIS Website

    1. - name: install xWebAdministration module
    2.   win_psmodule:
    3.     name: xWebAdministration
    4.     state: present
    5.  
    6. - name: install IIS features that are required
    7.     resource_name: WindowsFeature
    8.     Name: '{{item}}'
    9.     Ensure: Present
    10.   with_items:
    11.   - Web-Server
    12.   - Web-Asp-Net45
    13.  
    14. - name: setup web content
    15.   win_dsc:
    16.     resource_name: File
    17.     DestinationPath: C:\inetpub\IISSite\index.html
    18.     Type: File
    19.     Contents: |
    20.       <html>
    21.       <head><title>IIS Site</title></head>
    22.       <body>This is the body</body>
    23.       </html>
    24.     Ensure: present
    25.  
    26. - name: create new website
    27.   win_dsc:
    28.     resource_name: xWebsite
    29.     Name: NewIISSite
    30.     State: Started
    31.     PhysicalPath: C:\inetpub\IISSite\index.html
    32.     BindingInfo:
    33.     - Protocol: https
    34.       Port: 8443
    35.       CertificateStoreName: My
    36.       CertificateThumbprint: C676A89018C4D5902353545343634F35E6B3A659
    37.       HostName: DSCTest
    38.       IPAddress: '*'
    39.       SSLFlags: 1
    40.     - Protocol: http
    41.       Port: 8080
    42.       IPAddress: '*'
    43.     AuthenticationInfo:
    44.       Anonymous: no
    45.       Basic: yes
    46.       Digest: no
    47.       Windows: yes