mirror of
https://github.com/ansible-collections/community.general.git
synced 2025-07-22 04:40:22 -07:00
win_dsc - Add argument validation and other fixes (#53093)
* win_dsc - Add argument validation and other fixes * Fix doc issues
This commit is contained in:
Jordan Borean
GitHub
parent
853a65eead
commit
6b294eab4d
27 changed files with 1585 additions and 990 deletions
|
|
@ -29,7 +29,7 @@ DSC and Ansible modules have a common goal which is to define and ensure the sta
|
|||
resource. Because of
|
||||
this, resources like the DSC `File resource <https://docs.microsoft.com/en-us/powershell/dsc/fileresource>`_
|
||||
and Ansible ``win_file`` can be used to achieve the same result. Deciding which to use depends
|
||||
on the scenario.
|
||||
on the scenario.
|
||||
|
||||
Reasons for using an Ansible module over a DSC resource:
|
||||
|
||||
|
|
@ -99,6 +99,67 @@ This is what the Ansible task version of the above DSC Registry resource would l
|
|||
ValueName: TestValue
|
||||
ValueData: TestData
|
||||
|
||||
Starting in Ansible 2.8, the ``win_dsc`` module automatically validates the
|
||||
input options from Ansible with the DSC definition. This means Ansible will
|
||||
fail if the option name is incorrect, a mandatory option is not set, or the
|
||||
value is not a valid choice. When running Ansible with a verbosity level of 3
|
||||
or more (``-vvv``), the return value will contain the possible invocation
|
||||
options based on the ``resource_name`` specified. Here is an example of the
|
||||
invocation output for the above ``Registry`` task::
|
||||
|
||||
changed: [2016] => {
|
||||
"changed": true,
|
||||
"invocation": {
|
||||
"module_args": {
|
||||
"DependsOn": null,
|
||||
"Ensure": "Present",
|
||||
"Force": null,
|
||||
"Hex": null,
|
||||
"Key": "HKEY_LOCAL_MACHINE\\SOFTWARE\\ExampleKey",
|
||||
"PsDscRunAsCredential_password": null,
|
||||
"PsDscRunAsCredential_username": null,
|
||||
"ValueData": [
|
||||
"TestData"
|
||||
],
|
||||
"ValueName": "TestValue",
|
||||
"ValueType": null,
|
||||
"module_version": "latest",
|
||||
"resource_name": "Registry"
|
||||
}
|
||||
},
|
||||
"module_version": "1.1",
|
||||
"reboot_required": false,
|
||||
"verbose_set": [
|
||||
"Perform operation 'Invoke CimMethod' with following parameters, ''methodName' = ResourceSet,'className' = MSFT_DSCLocalConfigurationManager,'namespaceName' = root/Microsoft/Windows/DesiredStateConfiguration'.",
|
||||
"An LCM method call arrived from computer SERVER2016 with user sid S-1-5-21-3088887838-4058132883-1884671576-1105.",
|
||||
"[SERVER2016]: LCM: [ Start Set ] [[Registry]DirectResourceAccess]",
|
||||
"[SERVER2016]: [[Registry]DirectResourceAccess] (SET) Create registry key 'HKLM:\\SOFTWARE\\ExampleKey'",
|
||||
"[SERVER2016]: [[Registry]DirectResourceAccess] (SET) Set registry key value 'HKLM:\\SOFTWARE\\ExampleKey\\TestValue' to 'TestData' of type 'String'",
|
||||
"[SERVER2016]: LCM: [ End Set ] [[Registry]DirectResourceAccess] in 0.1930 seconds.",
|
||||
"[SERVER2016]: LCM: [ End Set ] in 0.2720 seconds.",
|
||||
"Operation 'Invoke CimMethod' complete.",
|
||||
"Time taken for configuration job to complete is 0.402 seconds"
|
||||
],
|
||||
"verbose_test": [
|
||||
"Perform operation 'Invoke CimMethod' with following parameters, ''methodName' = ResourceTest,'className' = MSFT_DSCLocalConfigurationManager,'namespaceName' = root/Microsoft/Windows/DesiredStateConfiguration'.",
|
||||
"An LCM method call arrived from computer SERVER2016 with user sid S-1-5-21-3088887838-4058132883-1884671576-1105.",
|
||||
"[SERVER2016]: LCM: [ Start Test ] [[Registry]DirectResourceAccess]",
|
||||
"[SERVER2016]: [[Registry]DirectResourceAccess] Registry key 'HKLM:\\SOFTWARE\\ExampleKey' does not exist",
|
||||
"[SERVER2016]: LCM: [ End Test ] [[Registry]DirectResourceAccess] False in 0.2510 seconds.",
|
||||
"[SERVER2016]: LCM: [ End Set ] in 0.3310 seconds.",
|
||||
"Operation 'Invoke CimMethod' complete.",
|
||||
"Time taken for configuration job to complete is 0.475 seconds"
|
||||
]
|
||||
}
|
||||
|
||||
The ``invocation.module_args`` key shows the actual values that were set as
|
||||
well as other possible values that were not set. Unfortunately this will not
|
||||
show the default value for a DSC property, only what was set from the Ansible
|
||||
task. Any ``*_password`` option will be masked in the output for security
|
||||
reasons, if there are any other sensitive module options, set ``no_log: True``
|
||||
on the task to stop all task output from being logged.
|
||||
|
||||
|
||||
Property Types
|
||||
--------------
|
||||
Each DSC resource property has a type that is associated with it. Ansible
|
||||
|
|
@ -110,9 +171,9 @@ require certain rules.
|
|||
PSCredential
|
||||
++++++++++++
|
||||
A ``[PSCredential]`` object is used to store credentials in a secure way, but
|
||||
Ansible 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.
|
||||
Ansible 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:
|
||||
|
||||
.. code-block:: yaml+jinja
|
||||
|
|
@ -123,9 +184,12 @@ For example:
|
|||
SourceCredential_username: AdminUser
|
||||
SourceCredential_password: PasswordForAdminUser
|
||||
|
||||
.. Note:: You should set ``no_log: yes`` on the task definition in
|
||||
Ansible to ensure any credentials used are not stored in any log file or
|
||||
console output.
|
||||
.. Note:: On versions of Ansible older than 2.8, you should set ``no_log: yes``
|
||||
on the task definition in Ansible to ensure any credentials used are not
|
||||
stored in any log file or console output.
|
||||
|
||||
A ``[PSCredential]`` is defined with ``EmbeddedInstance("MSFT_Credential")`` in
|
||||
a DSC resource MOF definition.
|
||||
|
||||
CimInstance Type
|
||||
++++++++++++++++
|
||||
|
|
@ -144,13 +208,20 @@ For example, to define a ``[CimInstance]`` value in Ansible:
|
|||
Windows: yes
|
||||
|
||||
In the above example, the CIM instance is a representation of the class
|
||||
``MSFT_xWebAuthenticationInformation <https://github.com/PowerShell/xWebAdministration/blob/dev/DSCResources/MSFT_xWebsite/MSFT_xWebsite.schema.mof>``_.
|
||||
`MSFT_xWebAuthenticationInformation <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 on
|
||||
the class it represents. Please read through the documentation of the resource
|
||||
to determine the keys that can be used and the types of each key value. The
|
||||
class definition is typically located in the ``<resource name>.schema.mof``.
|
||||
|
||||
HashTable Type
|
||||
++++++++++++++
|
||||
A ``[HashTable]`` object is also a dictionary but does not have a strict set of
|
||||
keys that can/need to be defined. Like a ``[CimInstance]``, define it like a
|
||||
normal dictionary value in YAML. A ``[HashTable]]`` is defined with
|
||||
``EmbeddedInstance("MSFT_KeyValuePair")`` in a DSC resource MOF definition.
|
||||
|
||||
Arrays
|
||||
++++++
|
||||
Simple type arrays like ``[string[]]`` or ``[UInt32[]]`` are defined as a list
|
||||
|
|
@ -192,17 +263,39 @@ like this example:
|
|||
Port: 80
|
||||
IPAddress: '*'
|
||||
|
||||
The above example, is an array with two values of the class ``MSFT_xWebBindingInformation <https://github.com/PowerShell/xWebAdministration/blob/dev/DSCResources/MSFT_xWebsite/MSFT_xWebsite.schema.mof>``_.
|
||||
The above example, is an array with two values of the class `MSFT_xWebBindingInformation <https://github.com/PowerShell/xWebAdministration/blob/dev/DSCResources/MSFT_xWebsite/MSFT_xWebsite.schema.mof>`_.
|
||||
When defining a ``[CimInstance[]]``, be sure to read the resource documentation
|
||||
to find out what keys to use in the definition.
|
||||
|
||||
DateTime
|
||||
++++++++
|
||||
A ``[DateTime]`` object is a DateTime string representing the date and time in
|
||||
the `ISO 8601 <https://www.w3.org/TR/NOTE-datetime>`_ date time format. The
|
||||
value for a ``[DateTime]`` field should be quoted in YAML to ensure the string
|
||||
is properly serialized to the Windows host. Here is an example of how to define
|
||||
a ``[DateTime]`` value in Ansible:
|
||||
|
||||
.. code-block:: yaml+jinja
|
||||
|
||||
# As UTC-0 (No timezone)
|
||||
DateTime: '2019-02-22T13:57:31.2311892+00:00'
|
||||
|
||||
# As UTC+4
|
||||
DateTime: '2019-02-22T17:57:31.2311892+04:00'
|
||||
|
||||
# As UTC-4
|
||||
DateTime: '2019-02-22T09:57:31.2311892-04:00'
|
||||
|
||||
All the values above are equal to a UTC date time of February 22nd 2019 at
|
||||
1:57pm with 31 seconds and 2311892 milliseconds.
|
||||
|
||||
Run As Another User
|
||||
-------------------
|
||||
By default, DSC runs each resource as the SYSTEM account and not the account
|
||||
that Ansible use to run the module. This means that resources that are dynamically
|
||||
loaded based on a user profile, like the ``HKEY_CURRENT_USER`` registry hive,
|
||||
will be loaded under the ``SYSTEM`` profile. The parameter
|
||||
`PsDscRunAsCredential`` is a parameter that can be set for every DSC resource
|
||||
will be loaded under the ``SYSTEM`` profile. The parameter
|
||||
``PsDscRunAsCredential`` is a parameter that can be set for every DSC resource
|
||||
force the DSC engine to run under a different account. As
|
||||
``PsDscRunAsCredential`` has a type of ``PSCredential``, it is defined with the
|
||||
``_username`` and ``_password`` suffix.
|
||||
|
|
@ -331,7 +424,7 @@ Interact with Azure
|
|||
win_psmodule:
|
||||
name: xAzure
|
||||
state: present
|
||||
|
||||
|
||||
- name: Create virtual machine in Azure
|
||||
win_dsc:
|
||||
resource_name: xAzureVM
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue