win_updates: Add flag to only download updates without installing them (#58631)

* win_updates: Add flag to only download updates without installing them

* Fix test

* Fixes ansible-test (pep8)

* Fix integration test

* Fix actual fix.

lib/ansible/modules/windows/win_updates.ps1

@@ -13,7 +13,7 @@ $check_mode = Get-AnsibleParam -obj $params -name "_ansible_check_mode" -type "b
 
 $category_names = Get-AnsibleParam -obj $params -name "category_names" -type "list" -default @("CriticalUpdates", "SecurityUpdates", "UpdateRollups")
 $log_path = Get-AnsibleParam -obj $params -name "log_path" -type "path"
-$state = Get-AnsibleParam -obj $params -name "state" -type "str" -default "installed" -validateset "installed", "searched"
+$state = Get-AnsibleParam -obj $params -name "state" -type "str" -default "installed" -validateset "installed", "searched", "downloaded"
 $blacklist = Get-AnsibleParam -obj $params -name "blacklist" -type "list"
 $whitelist = Get-AnsibleParam -obj $params -name "whitelist" -type "list"
 $server_selection = Get-AnsibleParam -obj $params -name "server_selection" -type "string" -default "default" -validateset "default", "managed_server", "windows_update"
@@ -296,6 +296,14 @@ $update_script_block = {
             $update_index++
         }
 
+        # Early exit for download-only
+        if ($state -eq "downloaded") {
+            Write-DebugLog -msg "Downloaded $($updates_to_install.Count) updates..."
+            $result.failed = $false
+            $result.msg = "Downloaded $($updates_to_install.Count) updates"
+            return $result
+        }
+
         Write-DebugLog -msg "Installing updates..."
         # install as a batch so the reboot manager will suppress intermediate reboots
 

lib/ansible/modules/windows/win_updates.py

@@ -78,10 +78,10 @@ options:
         version_added: '2.8'
     state:
         description:
-        - Controls whether found updates are returned as a list or actually installed.
+        - Controls whether found updates are downloaded or installed or listed
         - This module also supports Ansible check mode, which has the same effect as setting state=searched
         type: str
-        choices: [ installed, searched ]
+        choices: [ installed, searched, downloaded ]
         default: installed
     log_path:
         description:
@@ -188,6 +188,11 @@ EXAMPLES = r'''
   win_updates:
     reboot: yes
     reboot_timeout: 3600
+
+# Search and download Windows updates
+- name: Search and download Windows updates without installing them
+  win_updates:
+    state: downloaded
 '''
 
 RETURN = r'''
@@ -254,7 +259,7 @@ found_update_count:
     type: int
     sample: 3
 installed_update_count:
-    description: The number of updates successfully installed.
+    description: The number of updates successfully installed or downloaded.
     returned: success
     type: int
     sample: 2

lib/ansible/plugins/action/win_updates.py

@@ -141,9 +141,9 @@ class ActionModule(ActionBase):
         use_task = boolean(self._task.args.get('use_scheduled_task', False),
                            strict=False)
 
-        if state not in ['installed', 'searched']:
+        if state not in ['installed', 'searched', 'downloaded']:
             result['failed'] = True
-            result['msg'] = "state must be either installed or searched"
+            result['msg'] = "state must be either installed, searched or downloaded"
             return result
 
         try:

test/integration/targets/win_updates/tasks/tests.yml

@@ -3,7 +3,7 @@
   win_updates:
     state: invalid
   register: invalid_state
-  failed_when: invalid_state.msg != 'state must be either installed or searched'
+  failed_when: invalid_state.msg != 'state must be either installed, searched or downloaded'
 
 - name: ensure log file not present before tests
   win_file:

test/units/plugins/action/test_win_updates.py

@@ -19,7 +19,7 @@ class TestWinUpdatesActionPlugin(object):
         (
             {"state": "invalid"},
             False,
-            "state must be either installed or searched"
+            "state must be either installed, searched or downloaded"
         ),
         (
             {"reboot": "nonsense"},