win_updates: action plugin-ify it (#33216)

* converted win_updates to an action plugin for automatic reboots

* do not set final result when running under async

* Updated documentation around win_updates with async and become

lib/ansible/modules/windows/win_updates.py

@@ -1,22 +1,9 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2015, Matt Davis <mdavis_ansible@rolpdog.com>
-#
-# 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/>.
+# Copyright (c) 2015, Matt Davis <mdavis_ansible@rolpdog.com>
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name
@@ -52,6 +39,23 @@ options:
         - Tools
         - UpdateRollups
         - Updates
+    reboot:
+        description:
+        - Ansible will automatically reboot the remote host if it is required
+          and continue to install updates after the reboot.
+        - This can be used instead of using a M(win_reboot) task after this one
+          and ensures all updates for that category is installed in one go.
+        - Async does not work when C(reboot=True).
+        type: bool
+        default: 'no'
+        version_added: '2.5'
+    reboot_timeout:
+        description:
+        - The time in seconds to wait until the host is back online from a
+          reboot.
+        - This is only used if C(reboot=True) and a reboot is required.
+        default: 1200
+        version_added: '2.5'
     state:
         description:
         - Controls whether found updates are returned as a list or actually installed.
@@ -67,9 +71,11 @@ options:
         required: false
 author: "Matt Davis (@nitzmahone)"
 notes:
-- C(win_updates) must be run by a user with membership in the local Administrators group
-- C(win_updates) will use the default update service configured for the machine (Windows Update, Microsoft Update, WSUS, etc)
-- C(win_updates) does not manage reboots, but will signal when a reboot is required with the reboot_required return value.
+- C(win_updates) must be run by a user with membership in the local Administrators group.
+- C(win_updates) will use the default update service configured for the machine (Windows Update, Microsoft Update, WSUS, etc).
+- By default C(win_updates) does not manage reboots, but will signal when a
+  reboot is required with the I(reboot_required) return value, as of Ansible 2.5
+  C(reboot) can be used to reboot the host if required in the one task.
 - C(win_updates) can take a significant amount of time to complete (hours, in some cases).
   Performance depends on many factors, including OS version, number of updates, system load, and update server load.
 '''
@@ -91,6 +97,43 @@ EXAMPLES = r'''
     category_names: SecurityUpdates
     state: searched
     log_path: c:\ansible_wu.txt
+
+- name: Install all security updates with automatic reboots
+  win_updates:
+    category_names:
+    - SecurityUpdates
+    reboot: yes
+
+# Note async on works on Windows Server 2012 or newer - become must be explicitly set on the task for this to work
+- name: Search for Windows updates asynchronously
+  win_updates:
+    category_names:
+    - SecurityUpdates
+    state: searched
+  async: 180
+  poll: 10
+  register: updates_to_install
+  become: yes
+  become_method: runas
+  become_user: SYSTEM
+
+# Async can also be run in the background in a fire and forget fashion
+- name: Search for Windows updates asynchronously (poll and forget)
+  win_updates:
+    category_names:
+    - SecurityUpdates
+    state: searched
+  async: 180
+  poll: 0
+  register: updates_to_install_async
+
+- name: get status of Windows Update async job
+  async_status:
+    jid: '{{ updates_to_install_async.ansible_job_id }}'
+  register: updates_to_install_result
+  become: yes
+  become_method: runas
+  become_user: SYSTEM
 '''
 
 RETURN = r'''