ansible.builtin.wait_for 模块 – 在继续之前等待条件

注意

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

概要 

您可以等待设定的时间量 timeout，如果未指定任何内容或只指定了 timeout，则这是默认值。这不会产生错误。
等待端口可用对于服务在 init 脚本返回后无法立即使用的情况很有用，这种情况在某些 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`
延迟整数	开始轮询之前等待的秒数。默认值： `0`
exclude_hosts 列表 / 元素=字符串	在为 `drained` 状态查找活动 TCP 连接时要忽略的主机或 IP 列表。
主机字符串	要等待的可解析主机名或 IP 地址。默认值： `"127.0.0.1"`
消息字符串	这会覆盖无法满足所需条件时出现的正常错误消息。
路径路径	文件系统上必须存在的文件的路径。 `path` 和 `port` 是相互排斥的参数。
端口整数	要轮询的端口号。 `path` 和 `port` 是相互排斥的参数。
search_regex 字符串	可用于在文件或套接字连接中匹配字符串。默认为多行正则表达式。
睡眠整数	检查之间要休眠的秒数。在 Ansible 2.3 之前，这被硬编码为 1 秒。默认值： `1`
状态字符串	为 `present`、`started` 或 `stopped`、`absent` 或 `drained`。在检查端口时，`started` 将确保端口处于打开状态，`stopped` 将检查它是否已关闭，`drained` 将检查活动连接。在检查文件或搜索字符串时，`present` 或 `started` 将确保文件或字符串存在，然后继续，`absent` 将检查文件是否不存在或已删除。选择 `"absent"` `"drained"` `"present"` `"started"` ← (默认) `"stopped"`
超时整数	等待的最大秒数，当与另一个条件一起使用时，它将强制出现错误。当不使用其他条件时，它等效于睡眠。默认值： `300`

属性 

属性	支持	描述
check_mode	支持：无	可以在 check_mode 下运行并返回已更改状态预测，而不会修改目标，如果不支持，则将跳过操作。
diff_mode	支持：无	将在 diff 模式下返回有关更改了什么（或可能需要在 check_mode 中更改）的详细信息
平台	平台： 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

返回值 

常见返回值在此处文档化，以下是此模块独有的字段

键	描述
经过的时间整数	等待时经过的秒数返回：始终示例： `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)