From 5549788c8d30d868fb249ac056100aa21dbf79a0 Mon Sep 17 00:00:00 2001
From: Ruben-Bosch <spam+github@rubenb.nl>
Date: Wed, 28 Aug 2019 01:46:59 +0200
Subject: [PATCH] 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          | 10 +++++++++-
 lib/ansible/modules/windows/win_updates.py           | 11 ++++++++---
 lib/ansible/plugins/action/win_updates.py            |  4 ++--
 test/integration/targets/win_updates/tasks/tests.yml |  2 +-
 test/units/plugins/action/test_win_updates.py        |  2 +-
 5 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/lib/ansible/modules/windows/win_updates.ps1 b/lib/ansible/modules/windows/win_updates.ps1
index b3e9b5b1541..5961bf33793 100644
--- a/lib/ansible/modules/windows/win_updates.ps1
+++ b/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
 
diff --git a/lib/ansible/modules/windows/win_updates.py b/lib/ansible/modules/windows/win_updates.py
index 217abbc7981..511c2e2e490 100644
--- a/lib/ansible/modules/windows/win_updates.py
+++ b/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
diff --git a/lib/ansible/plugins/action/win_updates.py b/lib/ansible/plugins/action/win_updates.py
index de162fb0bd2..56fbff1b77d 100644
--- a/lib/ansible/plugins/action/win_updates.py
+++ b/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:
diff --git a/test/integration/targets/win_updates/tasks/tests.yml b/test/integration/targets/win_updates/tasks/tests.yml
index 950f5bcc6bb..fe54a4b9c8d 100644
--- a/test/integration/targets/win_updates/tasks/tests.yml
+++ b/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:
diff --git a/test/units/plugins/action/test_win_updates.py b/test/units/plugins/action/test_win_updates.py
index f07d1c61ea5..039e73c304d 100644
--- a/test/units/plugins/action/test_win_updates.py
+++ b/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"},