win_updates – Download and install Windows updates

From Get docs
Ansible/docs/2.8/modules/win updates module


win_updates – Download and install Windows updates

New in version 2.0.


Synopsis

  • Searches, downloads, and installs Windows updates synchronously by automating the Windows Update client.

Parameters

Parameter Choices/Defaults Comments

blacklist

list

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

list

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 and Updates.

log_path

path

If set, win_updates will append update progress to the specified file. The directory must already exist.

reboot

boolean

added in 2.5

  • no

  • yes

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=yes.

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=yes and a reboot is required.

server_selection

string

added in 2.8

  • default

  • managed_server
  • windows_update

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), Systems Center Configuration Manager (SCCM), 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), Systems Center Configuration Manager (SCCM), or similar corporate update servers, this option selects the defined corporate update source.

windows_update Use the Microsoft Windows Update catalog.

state

string

  • installed

  • searched

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

use_scheduled_task

boolean

added in 2.6

  • no

  • yes

Will not auto elevate the remote process with become and use a scheduled task instead.

Set this to yes when using this module with async on Server 2008, 2008 R2, or Windows 7, or on Server 2008 that is not authenticated with basic or credssp.

Can also be set to yes on newer hosts where become does not work due to further privilege restrictions from the OS defaults.

whitelist

list

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.



Notes

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).
  • By default win_updates does not manage reboots, but will signal when a reboot is required with the reboot_required return value, as of Ansible v2.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.
  • Beware that just after 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

win_chocolatey – Manage packages using chocolatey
The official documentation on the win_chocolatey module.
win_feature – Installs and uninstalls Windows Features on Windows Server
The official documentation on the win_feature module.
win_hotfix – Install and uninstalls Windows hotfixes
The official documentation on the win_hotfix module.
win_package – Installs/uninstalls an installable package
The official documentation on the win_package module.


Examples

- name: Install all security, critical, and rollup updates without a scheduled task
  win_updates:
    category_names:
      - SecurityUpdates
      - CriticalUpdates
      - UpdateRollups

- name: Install only security updates as a scheduled task for Server 2008
  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
  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: Exclude 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

# 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
  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
  win_updates:
    reboot: yes
    reboot_timeout: 3600

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.


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 of strings

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 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)




Status

Red Hat Support

More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.

Authors

  • Matt Davis (@nitzmahone)

Hint

If you notice any issues in this documentation you can edit this document to improve it.


© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/win_updates_module.html