ansible.builtin.wait_for 模块 – 等待满足条件后继续

注意

此模块是 ansible-core 的一部分，并包含在所有 Ansible 安装中。在大多数情况下，即使不指定集合关键字，您也可以使用短模块名称 wait_for。但是，我们建议您使用完全限定集合名称 (FQCN) ansible.builtin.wait_for，以便轻松链接到模块文档，并避免与其他可能具有相同模块名称的集合发生冲突。

概要 

您可以等待一段设定的时间 timeout，如果未指定任何内容，或者仅指定 timeout，则这是默认行为。这不会产生错误。
等待端口变得可用对于在服务启动脚本返回后并非立即可用的情况很有用，某些 Java 应用程序服务器就是如此。
当使用 community.libvirt.virt 模块启动虚拟机并且需要暂停直到它们准备就绪时，它也很有用。
此模块还可用于等待文件中出现与正则表达式匹配的字符串。
在 Ansible 1.6 及更高版本中，此模块还可用于等待文件在文件系统上可用或不存在。
在 Ansible 1.8 及更高版本中，此模块还可用于等待活动连接关闭后再继续，如果节点正在从负载均衡器池中轮换退出，则此功能很有用。
对于 Windows 目标，请改用 ansible.windows.win_wait_for 模块。

参数 

参数	注释
active_connection_states 列表 / 元素=字符串	被视为活动连接的 TCP 连接状态列表。默认值： `["ESTABLISHED", "FIN_WAIT1", "FIN_WAIT2", "SYN_RECV", "SYN_SENT", "TIME_WAIT"]`
connect_timeout 整数	在关闭并重试之前，等待连接发生的最长时间（以秒为单位）。默认值： `5`
delay 整数	开始轮询之前等待的秒数。默认值： `0`
exclude_hosts 列表 / 元素=字符串	在查找 `drained` 状态的活动 TCP 连接时要忽略的主机或 IP 的列表。
host 字符串	要等待的可解析主机名或 IP 地址。默认值： `"127.0.0.1"`
msg 字符串	这会覆盖因未满足所需条件而产生的正常错误消息。
path path	在继续之前必须存在的文件系统上的文件路径。 `path` 和 `port` 是互斥参数。
port 整数	要轮询的端口号。 `path` 和 `port` 是互斥参数。
search_regex 字符串	可用于匹配文件或套接字连接中的字符串。默认为多行正则表达式。
sleep 整数	每次检查之间休眠的秒数。在 Ansible 2.3 之前，此值被硬编码为 1 秒。默认值： `1`
state 字符串	可以是 `present`、`started` 或 `stopped`、`absent` 或 `drained`。在检查端口时，`started` 将确保端口已打开，`stopped` 将检查端口是否已关闭，`drained` 将检查活动连接。在检查文件或搜索字符串时，`present` 或 `started` 将确保在继续之前文件或字符串存在，`absent` 将检查文件是否不存在或已删除。选择 `"absent"` `"drained"` `"present"` `"started"` ← （默认） `"stopped"`
timeout 整数	等待的最长时间（以秒为单位），如果与其他条件一起使用，则会强制产生错误。如果不与其他条件一起使用，则等同于仅休眠。默认值： `300`

属性 

属性	支持	描述
check_mode	支持：无	可以在 check_mode 中运行，并返回已更改的状态预测，而无需修改目标，如果不支持，则将跳过该操作。
diff_mode	支持：无	在 diff 模式下，将返回有关已更改内容（或在 check_mode 中可能需要更改的内容）的详细信息
platform	平台： posix	可以对其进行操作的目标操作系统/系列

备注 

注意

在 Ansible 1.7 中添加了将 search_regex 与端口连接一起使用的功能。
在 Ansible 2.4 之前，测试目录或 UNIX 套接字的不存在无法正常工作。
在 Ansible 2.4 之前，如果远程用户没有对该文件的读取权限，则测试文件的存在无法正常工作。
在某些情况下，当使用强制访问控制时，即使路径存在，也可能始终被视为不存在，但远程用户也无法修改或创建该路径。
当等待路径时，将遵循符号链接。许多其他操作文件的模块不遵循符号链接，因此使用其他模块对路径执行操作可能无法完全按预期工作。

另请参阅 

另请参阅

ansible.builtin.wait_for_connection: 等待直到远程系统可访问/可用。
ansible.windows.win_wait_for: 有关 ansible.windows.win_wait_for 模块的官方文档。
community.windows.win_wait_for_process: 有关 community.windows.win_wait_for_process 模块的官方文档。

示例 

- name: Sleep for 300 seconds and continue with play
  ansible.builtin.wait_for:
    timeout: 300
  delegate_to: localhost

- name: Wait for port 8000 to become open on the host, don't start checking for 10 seconds
  ansible.builtin.wait_for:
    port: 8000
    delay: 10

- name: Waits for port 8000 of any IP to close active connections, don't start checking for 10 seconds
  ansible.builtin.wait_for:
    host: 0.0.0.0
    port: 8000
    delay: 10
    state: drained

- name: Wait for port 8000 of any IP to close active connections, ignoring connections for specified hosts
  ansible.builtin.wait_for:
    host: 0.0.0.0
    port: 8000
    state: drained
    exclude_hosts: 10.2.1.2,10.2.1.3

- name: Wait until the file /tmp/foo is present before continuing
  ansible.builtin.wait_for:
    path: /tmp/foo

- name: Wait until the string "completed" is in the file /tmp/foo before continuing
  ansible.builtin.wait_for:
    path: /tmp/foo
    search_regex: completed

- name: Wait until regex pattern matches in the file /tmp/foo and print the matched group
  ansible.builtin.wait_for:
    path: /tmp/foo
    search_regex: completed (?P<task>\w+)
  register: waitfor
- ansible.builtin.debug:
    msg: Completed {{ waitfor['match_groupdict']['task'] }}

- name: Wait until the lock file is removed
  ansible.builtin.wait_for:
    path: /var/lock/file.lock
    state: absent

- name: Wait until the process is finished and pid was destroyed
  ansible.builtin.wait_for:
    path: /proc/3466/status
    state: absent

- name: Output customized message when failed
  ansible.builtin.wait_for:
    path: /tmp/foo
    state: present
    msg: Timeout to find file /tmp/foo

# Do not assume the inventory_hostname is resolvable and delay 10 seconds at start
- name: Wait 300 seconds for port 22 to become open and contain "OpenSSH"
  ansible.builtin.wait_for:
    port: 22
    host: '{{ (ansible_ssh_host|default(ansible_host))|default(inventory_hostname) }}'
    search_regex: OpenSSH
    delay: 10
  connection: local

# Same as above but you normally have ansible_connection set in inventory, which overrides 'connection'
- name: Wait 300 seconds for port 22 to become open and contain "OpenSSH"
  ansible.builtin.wait_for:
    port: 22
    host: '{{ (ansible_ssh_host|default(ansible_host))|default(inventory_hostname) }}'
    search_regex: OpenSSH
    delay: 10
  vars:
    ansible_connection: local

返回值 

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

键	描述
elapsed 整数	等待时经过的秒数已返回：始终示例： `23`
match_groupdict 字典	包含匹配的所有命名子组的字典，子组名称作为键，由 https://docs.pythonlang.cn/3/library/re.html#re.MatchObject.groupdict 返回已返回：始终示例： `{"group": "match"}`
match_groups 列表 / 元素=字符串	包含匹配的所有子组的元组，由 https://docs.pythonlang.cn/3/library/re.html#re.MatchObject.groups 返回已返回：始终示例： `["match 1", "match 2"]`

作者

Jeroen Hoekx (@jhoekx)
John Jarvis (@jarv)
Andrii Radyk (@AnderEnder)