ansible.windows.win_updates 模块 – 下载并安装 Windows 更新

注意

此模块是 ansible.windows 集合（版本 2.5.0）的一部分。

如果您正在使用 ansible 包，您可能已经安装了此集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install ansible.windows。

要在剧本中使用它，请指定：ansible.windows.win_updates。

概要 

通过自动化 Windows 更新客户端同步搜索、下载和安装 Windows 更新。

注意

此模块有一个对应的 action 插件。

参数 

参数	注释
_operation 字符串	仅供内部使用。选项 `"start"` ←（默认） `"cancel"` `"poll"`
_operation_options 字典	仅供内部使用。
accept_list 列表 / 元素=字符串	可以使用更新标题或 KB 编号的列表来指定要搜索或安装的更新。如果可用更新与其中一个条目不匹配，则会跳过该更新且不安装。每个条目可以是 KB 文章或更新标题，作为根据 PowerShell 正则表达式规则的正则表达式。仅在基于 category_names 找到的更新上验证接受列表。如果更新不在指定的类别中，它不会强制模块安装该更新。
category_names 列表 / 元素=字符串	一个或多个用于安装更新的类别。要获取类别列表，请运行 `state=searched` 模块。类别必须是完整的类别字符串，但不区分大小写。一些可能的类别是应用程序、连接器、关键更新、定义更新、开发人员工具包、功能包、指南、安全更新、服务包、工具、更新汇总、更新和升级。自 `v1.7.0` 起，值 `` 将匹配所有类别。默认值：* `["CriticalUpdates", "SecurityUpdates", "UpdateRollups"]`
log_path 路径	如果设置，`win_updates` 会将更新进度附加到指定的文件中。该目录必须已存在。
reboot 布尔值	如果需要，Ansible 会自动重启远程主机，并在重启后继续安装更新。这可以代替在此任务之后使用 ansible.windows.win_reboot 任务，并确保一次安装该类别的所有更新。当 `reboot=true` 时，异步不起作用。选项 `false` ←（默认） `true`
reboot_timeout 整数	等待主机从重启恢复在线状态的时间（以秒为单位）。仅当 `reboot=true` 且需要重启时才使用此项。默认值： `1200`
reject_list 列表 / 元素=字符串	可以使用更新标题或 KB 编号的列表来指定要从安装中排除的更新。如果可用更新与其中一个条目匹配，则会跳过该更新且不安装。每个条目可以是 KB 文章或更新标题，作为根据 PowerShell 正则表达式规则的正则表达式。
server_selection 字符串	定义 Windows 更新源目录。 `default` 使用默认搜索源。对于许多系统，默认设置为 Microsoft Windows 更新目录。参与 Windows Server 更新服务 (WSUS) 或类似公司更新服务器环境的系统可以默认为那些托管的更新源，而不是 Windows 更新目录。 `managed_server` 使用托管服务器目录。对于使用 Windows Server 更新服务 (WSUS) 或类似公司更新服务器的环境，此选项选择定义的公司更新源。 `windows_update` 使用 Microsoft Windows 更新目录。选项 `"default"` ←（默认） `"managed_server"` `"windows_update"`
skip_optional 布尔值在 ansible.windows 1.8.0 中添加	跳过 Microsoft 将 BrowseOnly 设置为可选的更新。 Microsoft 文档显示 BrowseOnly 表示不应自动安装更新，并且会显示为可选更新。选项 `false` ←（默认） `true`
state 字符串	控制找到的更新是下载、安装还是列出此模块还支持 Ansible 检查模式，其效果与设置 state=searched 相同选项 `"installed"` ←（默认） `"searched"` `"downloaded"`

说明 

注意

ansible.windows.win_updates 必须由本地 Administrators 组中的用户运行。
ansible.windows.win_updates 将使用为机器配置的默认更新服务（Windows 更新、Microsoft 更新、WSUS 等）。
默认情况下，ansible.windows.win_updates 不管理重启，但会在需要重启时通过 reboot_required 返回值发出信号。如果需要，可以使用 reboot 在一个任务中重启主机。
ansible.windows.win_updates 可能需要很长时间才能完成（在某些情况下，需要数小时）。性能取决于许多因素，包括操作系统版本、更新数量、系统负载和更新服务器负载。
请注意，在 ansible.windows.win_updates 重启系统后，Windows 系统可能尚未稳定，某些基本服务可能处于不稳定状态。这可能会导致意外行为。请查看示例，了解如何缓解这种情况。
有关 PowerShell 及其如何处理 RegEx 字符串的更多信息，请访问 https://technet.microsoft.com/en-us/library/2007.11.powershell.aspx。
当前模块不支持 Systems Center Configuration Manager (SCCM)。请参阅 https://github.com/ansible-collections/ansible.windows/issues/194
默认情况下，ansible.builtin.ssh 连接插件配置为没有服务器超时。由于 Windows 更新可能会重启网络适配器，建议设置 -o ServerAliveInterval=30 并在 ansible_ssh_args 中禁用控制主进程，以确保客户端可以处理网络重置。请参阅示例，了解如何设置此项的一种方式。
默认情况下，该模块将使用 Windows 上的任务计划程序启动后台进程。如果任务计划程序不可用、不可靠或无法工作，请使用 become 运行该任务。

另请参阅 

另请参阅

chocolatey.chocolatey.win_chocolatey: 使用 chocolatey 管理软件包。
ansible.windows.win_feature: 在 Windows Server 上安装和卸载 Windows 功能。
community.windows.win_hotfix: 安装和卸载 Windows 热修复程序。
ansible.windows.win_package: 安装/卸载可安装的软件包。

示例 

- name: Install all updates and reboot as many times as needed
  ansible.windows.win_updates:
    category_names: '*'
    reboot: true

- name: Set a server alive interval during update stage for the ssh connection plugin
  ansible.windows.win_updates:
    category_names: '*'
    reboot: true
  vars:
    # This can be set in a few ways, see the ssh connection plugin for more
    # information. ControlMaster should be disabled to ensure the new timeout
    # value is applied for this connection instead of through the cached
    # connection.
    ansible_ssh_args: -o ControlMaster=no -o ServerAliveInterval=30

- name: Install all security, critical, and rollup updates without a scheduled task
  ansible.windows.win_updates:
    category_names:
      - SecurityUpdates
      - CriticalUpdates
      - UpdateRollups
  become: true
  become_method: runas
  become_user: SYSTEM

- 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: true

- name: Install only particular updates based on the KB numbers
  ansible.windows.win_updates:
    category_names:
      - SecurityUpdates
    accept_list:
      - KB4056892
      - KB4073117

- name: Exclude updates based on the update title
  ansible.windows.win_updates:
    category_names:
      - 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: true
    reboot_timeout: 3600

# Search and download Windows updates
- name: Search and download Windows updates without installing them
  ansible.windows.win_updates:
    state: downloaded

返回值 

常见的返回值记录在此处，以下是此模块特有的字段

键	描述
failed_update_count 整数	安装失败的更新数量。返回: 始终示例: `0`
filtered_updates 字典	已找到但基于 blacklist、whitelist 或 category_names 筛选的更新。返回值与 updates 具有相同的形式，并带有 filtered_reason。返回: 成功示例: `"请参阅更新返回值"`
filtered_reason 字符串	此更新被筛选的原因。此值自 `1.7.0` 版本起已弃用，请使用 `filtered_reasons`，其中包含更新被筛选的所有原因的列表。返回: 始终示例: `"skip_hidden"`
filtered_reasons 列表 / 元素=字符串在 ansible.windows 1.7.0 中添加	更新被筛选的原因列表。可以是 `accept_list`、`reject_list`、`hidden`、`category_names` 或 `skip_optional`。返回: 成功示例: `["category_names", "accept_list"]`
found_update_count 整数	找到需要应用的更新数量。返回: 成功示例: `3`
installed_update_count 整数	成功安装或下载的更新数量。返回: 成功示例: `2`
reboot_required 布尔值	当目标服务器需要重启才能完成更新时为 True（在重启之前无法安装其他更新）。返回: 成功示例: `true`
rebooted 布尔值在 ansible.windows 1.14.0 中添加	当目标 Windows 主机已被 `win_updates` 重启时设置为 `true`。返回: 成功示例: `false`
updates 字典	已找到/安装的更新。每个更新的键都是更新的 `id`。返回: 成功
categories 列表 / 元素=字符串	此更新的类别字符串列表。返回: 始终示例: `["重要更新", "Windows Server 2012 R2"]`
downloaded 布尔值在 ansible.windows 1.7.0 中添加	是否已下载更新。返回: 始终示例: `true`
failure_hresult_code 布尔值	来自失败更新的 HRESULT 代码。返回: 在安装或下载失败时示例: `2147942402`
failure_msg 字符串在 ansible.windows 1.7.0 中添加	包含有关失败的更多详细信息的错误消息。返回: 在安装或下载失败且未以异步方式运行时示例: `"操作未完成，因为没有登录的交互式用户 (WU_E_NO_INTERACTIVE_USER 0x80240020)"`
id 字符串	内部 Windows 更新 GUID。返回: 始终示例: `"fb95c1c8-de23-4089-ae29-fd3351d55421"`
installed 布尔值	是否已成功安装更新。返回: 始终示例: `true`
kb 列表 / 元素=字符串	适用于该更新的 KB 文章 ID 列表。返回: 始终示例: `["3004365"]`
title 字符串	显示名称。返回: 始终示例: `"适用于 Windows Server 2012 R2 的安全更新 (KB3004365)"`

作者

Matt Davis (@nitzmahone)