New module: win dsc (#24872)

* Added win_dsc module file * mute output and track reboot requirements * added tests * proper conditionals for test * Added moar conditionals for test * ci fixes * Added metadata * fixed integration test yaml * ci fix * ci fix * added module_version param and output, no longer chokes on multiple versions found. * ci fix * code review improvements, make return vars more pythonic, cleanup removed reference to handles in commit message * Fixed tests, clearer documentation * fixed trailing whitespace
2025-07-02 06:30:19 -07:00 · 2017-06-01 23:50:12 +02:00 · 2017-06-01 23:50:12 +02:00 · 055fd6f5f5
commit 055fd6f5f5
parent 055cc32830
5 changed files with 475 additions and 0 deletions
--- a/lib/ansible/modules/windows/win_dsc.py
+++ b/lib/ansible/modules/windows/win_dsc.py
@ -0,0 +1,110 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# (c) 2015, Trond Hindenes <trond@hindenes.com>, and others
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+# this is a windows documentation stub.  actual code lives in the .ps1
+# file of the same name
+
+ANSIBLE_METADATA = {'metadata_version': '1.0',
+                    'status': ['preview'],
+                    'supported_by': 'community'}
+
+DOCUMENTATION = r'''
+---
+module: win_dsc
+version_added: "2.4"
+short_description: Invokes a PowerShell DSC configuration
+description: |
+     Invokes a PowerShell DSC Configuration. Requires PowerShell version 5 (February release or newer).
+     Most of the parameters for this module are dynamic and will vary depending on the DSC Resource.
+     In order to find the required parameters for a given DSC resource, you can use the following on-liner:
+     'Get-DscResource <dsc_resource> | select -ExpandProperty properties'
+     Also note that credentials are handled as follows: If the resource accepts a credential type property called "cred",
+     the ansible parameters would be cred_username and cred_password.
+     These will be used to inject a credential object on the fly for the DSC resource.
+options:
+  resource_name:
+    description:
+      - The DSC Resource to use. Must be accessible to PowerShell using any of the default paths.
+    required: true
+  module_version:
+    description: |
+      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.
+    default: latest
+author: Trond Hindenes
+'''
+
+EXAMPLES = r'''
+# Playbook example
+  - name: Extract zip file
+    win_dsc:
+      resource_name: archive
+      ensure: Present
+      path: "C:\\Temp\\zipfile.zip"
+      destination: "C:\\Temp\\Temp2"
+
+  - name: Invoke DSC with check mode
+    win_dsc:
+      resource_name: windowsfeature
+      name: telnet-client
+'''
+
+RETURN = r'''
+resource_name:
+    description: The name of the invoked resource
+    returned: always
+    type: string
+    sample: windowsfeature
+module_version:
+    description: The version of the dsc resource/module used.
+    returned: success
+    type: string
+    sample: "1.0.1"
+attributes:
+    description: The attributes/parameters passed in to the DSC resource as key/value pairs
+    returned: always
+    type: complex
+    sample:
+    contains:
+      Key:
+          description: Attribute key
+      Value:
+          description: Attribute value
+dsc_attributes:
+    description: The attributes/parameters as returned from the DSC engine in dict format
+    returned: always
+    type: complex
+    contains:
+      Key:
+          description: Attribute key
+      Value:
+          description: Attribute value
+reboot_required:
+    description: flag returned from the DSC engine indicating whether or not the machine requires a reboot for the invoked changes to take effect
+    returned: always
+    type: boolean
+    sample: True
+message:
+    description: any error message from invoking the DSC resource
+    returned: error
+    type: string
+    sample: Multiple DSC modules found with resource name xyz
+'''