Note
This plugin is part of the ansible.windows collection (version 1.7.3).
You might already have this collection installed if you are using the ansible
package. It is not included in ansible-core
. To check whether it is installed, run ansible-galaxy collection list
.
To install it, use: ansible-galaxy collection install ansible.windows
.
To use it in a playbook, specify: ansible.windows.win_updates
.
Note
This module has a corresponding action plugin.
Parameter | Choices/Defaults | Comments |
---|---|---|
_output_path string | Internal use only. | |
_wait boolean |
| Internal use only. |
accept_list 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 accept list 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. The alias whitelist is deprecated and will be removed in a release after 2023-06-01 .aliases: whitelist | |
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 state=searched . The category must be the full category string, but is case insensitive.Some possible categories are Application, Connectors, Critical Updates, Definition Updates, Developer Kits, Feature Packs, Guidance, Security Updates, Service Packs, Tools, Update Rollups, Updates, and Upgrades. Since v1.7.0 the value * will match all categories. |
log_path path | If set, win_updates will append update progress to the specified file. The directory must already exist. | |
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=yes . |
reboot_timeout integer | Default: 1200 | The time in seconds to wait until the host is back online from a reboot. This is only used if reboot=yes and a reboot is required. |
reject_list 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. The alias blacklist is deprecated and will be removed in a release after 2023-06-01 .aliases: blacklist | |
server_selection string |
| Defines the Windows Update source catalog. default Use the default search source. For many systems default is set to the Microsoft Windows Update catalog. Systems participating in Windows Server Update Services (WSUS) or similar corporate update server environments may default to those managed update sources instead of the Windows Update catalog.managed_server Use a managed server catalog. For environments utilizing Windows Server Update Services (WSUS) or similar corporate update servers, this option selects the defined corporate update source.windows_update Use the Microsoft Windows Update 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 |
| This option is deprecated and no longer does anything since v1.7.0 of this collection.The option will be removed in a release after 2023-06-01 . |
Note
See also
The official documentation on the chocolatey.chocolatey.win_chocolatey module.
The official documentation on the ansible.windows.win_feature module.
The official documentation on the community.windows.win_hotfix module.
The official documentation on the ansible.windows.win_package module.
- name: Install all updates and reboot as many times as needed ansible.windows.win_updates: category_names: '*' reboot: yes - name: Install all security, critical, and rollup updates without a scheduled task ansible.windows.win_updates: category_names: - SecurityUpdates - CriticalUpdates - UpdateRollups - 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 accept_list: - KB4056892 - KB4073117 - name: Exclude updates based on the update title ansible.windows.win_updates: category_name: - SecurityUpdates - CriticalUpdates reject_list: - Windows Malicious Software Removal Tool for Windows - \d{4}-\d{2} Cumulative Update for Windows Server 2016 # 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
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. This value has been deprecated since 1.7.0 , use filtered_reasons which contain a list of all the reasons why the update is filtered.Sample: skip_hidden | |
filtered_reasons list / elements=string added in 1.7.0 of ansible.windows | success | A list of reasons why the update has been filtered. Can be accept_list , reject_list , hidden , or category_names .Sample: ['category_names', 'accept_list'] | |
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'] | |
downloaded boolean added in 1.7.0 of ansible.windows | always | Was the update downloaded. Sample: True | |
failure_hresult_code boolean | on install or download failure | The HRESULT code from a failed update. Sample: 2147942402 | |
failure_msg string added in 1.7.0 of ansible.windows | on install or download failure and not running with async | The error message with more details on the failure. Sample: Operation did not complete because there is no logged-on interactive user (WU_E_NO_INTERACTIVE_USER 0x80240020) | |
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) |
© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/ansible/windows/win_updates_module.html