New in version 2.0.
| Parameter | Choices/Defaults | Comments |
|---|---|---|
|
blacklist
(added in 2.5) |
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 |
[u'CriticalUpdates', u'SecurityUpdates', u'UpdateRollups']
|
A scalar or list of categories to install updates from
|
| log_path |
If set,
win_updates will append update progress to the specified file. The directory must already exist. |
|
|
reboot
(added in 2.5) |
|
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 win_reboot task after this one and ensures all updates for that category is installed in one go.
Async does not work when
reboot=True. |
|
reboot_timeout
(added in 2.5) |
Default: 1200
|
The time in seconds to wait until the host is back online from a reboot.
This is only used if
reboot=True and a reboot is required. |
| state |
|
Controls whether found updates are returned as a list or actually installed.
This module also supports Ansible check mode, which has the same effect as setting state=searched
|
|
whitelist
(added in 2.5) |
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.
|
Note
win_updates must be run by a user with membership in the local Administrators group.win_updates will use the default update service configured for the machine (Windows Update, Microsoft Update, WSUS, etc).win_updates does not manage reboots, but will signal when a reboot is required with the reboot_required return value, as of Ansible 2.5 reboot can be used to reboot the host if required in the one task.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.- name: Install all security, critical, and rollup updates
win_updates:
category_names:
- SecurityUpdates
- CriticalUpdates
- UpdateRollups
- name: Install only security updates
win_updates:
category_names: SecurityUpdates
- name: Search-only, return list of found updates (if any), log to C:\ansible_wu.txt
win_updates:
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
- name: Install only particular updates based on the KB numbers
win_updates:
category_name:
- SecurityUpdates
whitelist:
- KB4056892
- KB4073117
- name: Exlude updates based on the update title
win_updates:
category_name:
- SecurityUpdates
- CriticalUpdates
blacklist:
- Windows Malicious Software Removal Tool for Windows
- \d{4}-\d{2} Cumulative Update for Windows Server 2016
# Note async 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
Common return values are documented here, the following are the fields unique to this module:
| Key | Returned | Description | |
|---|---|---|---|
|
failed_update_count
int
|
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 or whitelist. The return value is in the same form as updates.
Sample:
see the updates return value
|
|
|
found_update_count
int
|
success |
The number of updates found needing to be applied
Sample:
3
|
|
|
installed_update_count
int
|
success |
The number of updates successfully installed
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
|
|
|
kb
list of strings
|
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)
|
|
|
failure_hresult_code
boolean
|
on install failure |
The HRESULT code from a failed update
Sample:
2147942402
|
|
|
id
string (guid)
|
always |
Internal Windows Update GUID
Sample:
fb95c1c8-de23-4089-ae29-fd3351d55421
|
|
|
installed
boolean
|
always |
Was the update successfully installed
Sample:
True
|
|
This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.
For more information about Red Hat’s support of this module, please refer to this Knowledge Base article
Hint
If you notice any issues in this documentation you can edit this document to improve it.