ansible.windows.win_updates – Download and install Windows updates
ansible.windows.win_updates – Download and install Windows updates
Note
This plugin is part of the ansible.windows collection (version 1.3.0).
To install it use: ansible-galaxy collection install ansible.windows
.
To use it in a playbook, specify: ansible.windows.win_updates
.
Synopsis
- Searches, downloads, and installs Windows updates synchronously by automating the Windows Update client.
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
blacklist list / elements=string |
A list of update titles or KB numbers that can be used to specify which updates are to be excluded from installation. If an available update does match one of the entries, then it is skipped and not installed. Each entry can either be the KB article or Update title as a regex according to the PowerShell regex rules. | |
category_names list / elements=string |
Default: ["CriticalUpdates", "SecurityUpdates", "UpdateRollups"] |
A scalar or list of categories to install updates from. To get the list of categories, run the module with Some possible categories are Application, Connectors, Critical Updates, Definition Updates, Developer Kits, Feature Packs, Guidance, Security Updates, Service Packs, Tools, Update Rollups and Updates. |
log_path path |
If set, | |
reboot boolean |
|
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 ansible.windows.win_reboot task after this one and ensures all updates for that category is installed in one go. Async does not work when |
reboot_timeout string |
Default: 1200 |
The time in seconds to wait until the host is back online from a reboot. This is only used if |
server_selection string |
|
Defines the Windows Update source catalog.
|
state string |
|
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 |
use_scheduled_task boolean |
|
Will not auto elevate the remote process with become and use a scheduled task instead. Set this to Can also be set to |
whitelist list / elements=string |
A list of update titles or KB numbers that can be used to specify which updates are to be searched or installed. If an available update does not match one of the entries, then it is skipped and not installed. Each entry can either be the KB article or Update title as a regex according to the PowerShell regex rules. The whitelist is only validated on updates that were found based on category_names. It will not force the module to install an update if it was not in the category specified. |
Notes
Note
- ansible.windows.win_updates must be run by a user with membership in the local Administrators group.
- ansible.windows.win_updates will use the default update service configured for the machine (Windows Update, Microsoft Update, WSUS, etc).
- ansible.windows.win_updates will become SYSTEM using runas unless
use_scheduled_task
isyes
- By default ansible.windows.win_updates does not manage reboots, but will signal when a reboot is required with the reboot_required return value. reboot can be used to reboot the host if required in the one task.
- ansible.windows.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.
- Beware that just after ansible.windows.win_updates reboots the system, the Windows system may not have settled yet and some base services could be in limbo. This can result in unexpected behavior. Check the examples for ways to mitigate this.
- More information about PowerShell and how it handles RegEx strings can be found at https://technet.microsoft.com/en-us/library/2007.11.powershell.aspx.
See Also
See also
- chocolatey.chocolatey.win_chocolatey
- The official documentation on the chocolatey.chocolatey.win_chocolatey module.
- ansible.windows.win_feature
- The official documentation on the ansible.windows.win_feature module.
- community.windows.win_hotfix
- The official documentation on the community.windows.win_hotfix module.
- ansible.windows.win_package
- The official documentation on the ansible.windows.win_package module.
Examples
- name: Install all security, critical, and rollup updates without a scheduled task
ansible.windows.win_updates:
category_names:
- SecurityUpdates
- CriticalUpdates
- UpdateRollups
- name: Install only security updates as a scheduled task for Server 2008
ansible.windows.win_updates:
category_names: SecurityUpdates
use_scheduled_task: yes
- name: Search-only, return list of found updates (if any), log to C:\ansible_wu.txt
ansible.windows.win_updates:
category_names: SecurityUpdates
state: searched
log_path: C:\ansible_wu.txt
- name: Install all security updates with automatic reboots
ansible.windows.win_updates:
category_names:
- SecurityUpdates
reboot: yes
- name: Install only particular updates based on the KB numbers
ansible.windows.win_updates:
category_name:
- SecurityUpdates
whitelist:
- KB4056892
- KB4073117
- name: Exclude updates based on the update title
ansible.windows.win_updates:
category_name:
- SecurityUpdates
- CriticalUpdates
blacklist:
- Windows Malicious Software Removal Tool for Windows
- \d{4}-\d{2} Cumulative Update for Windows Server 2016
# One way to ensure the system is reliable just after a reboot, is to set WinRM to a delayed startup
- name: Ensure WinRM starts when the system has settled and is ready to work reliably
ansible.windows.win_service:
name: WinRM
start_mode: delayed
# Optionally, you can increase the reboot_timeout to survive long updates during reboot
- name: Ensure we wait long enough for the updates to be applied during reboot
ansible.windows.win_updates:
reboot: yes
reboot_timeout: 3600
# Search and download Windows updates
- name: Search and download Windows updates without installing them
ansible.windows.win_updates:
state: downloaded
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description | |
---|---|---|---|
failed_update_count integer |
always |
The number of updates that failed to install.
| |
filtered_updates complex |
success |
List of updates that were found but were filtered based on blacklist, whitelist or category_names. The return value is in the same form as updates, along with filtered_reason.
Sample: see the updates return value | |
filtered_reason string |
always |
The reason why this update was filtered.
Sample: skip_hidden | |
found_update_count integer |
success |
The number of updates found needing to be applied.
Sample: 3 | |
installed_update_count integer |
success |
The number of updates successfully installed or downloaded.
Sample: 2 | |
reboot_required boolean |
success |
True when the target server requires a reboot to complete updates (no further updates can be installed until after a reboot).
Sample: True | |
updates complex |
success |
List of updates that were found/installed.
| |
categories list / elements=string |
always |
A list of category strings for this update.
Sample: ['Critical Updates', 'Windows Server 2012 R2'] | |
failure_hresult_code boolean |
on install failure |
The HRESULT code from a failed update.
Sample: 2147942402 | |
id string |
always |
Internal Windows Update GUID.
Sample: fb95c1c8-de23-4089-ae29-fd3351d55421 | |
installed boolean |
always |
Was the update successfully installed.
Sample: True | |
kb list / elements=string |
always |
A list of KB article IDs that apply to the update.
Sample: ['3004365'] | |
title string |
always |
Display name.
Sample: Security Update for Windows Server 2012 R2 (KB3004365) |
Authors
- Matt Davis (@nitzmahone)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.10/collections/ansible/windows/win_updates_module.html