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

注意

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

概要 

您可以等待设定的时间量 timeout，如果未指定任何内容或仅指定 timeout，则这是默认值。这不会产生错误。
等待端口可用对于某些 Java 应用程序服务器在它们的 init 脚本返回后服务并非立即可用时非常有用。
在使用 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)