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 list / elements=string	作为活动连接计算的 TCP 连接状态列表。默认值： `["ESTABLISHED", "FIN_WAIT1", "FIN_WAIT2", "SYN_RECV", "SYN_SENT", "TIME_WAIT"]`
connect_timeout integer	在关闭并重试之前等待连接发生的秒数上限。默认值： `5`
delay integer	开始轮询之前等待的秒数。默认值： `0`
exclude_hosts list / elements=string	在查找 `drained` 状态的活动 TCP 连接时要忽略的主机或 IP 列表。
host string	要等待的可解析主机名或 IP 地址。默认值： `"127.0.0.1"`
msg string	这将覆盖无法满足所需条件的失败的正常错误消息。
path path	文件系统上必须存在的文件的路径。 `path` 和 `port` 是互斥的参数。
port integer	要轮询的端口号。 `path` 和 `port` 是互斥的参数。
search_regex string	可用于匹配文件或套接字连接中的字符串。默认为多行正则表达式。
sleep integer	检查之间睡眠的秒数。在 Ansible 2.3 之前，这被硬编码为 1 秒。默认值： `1`
state string	可以是 `present`、`started` 或 `stopped`、`absent` 或 `drained`。在检查端口时，`started` 将确保端口已打开，`stopped` 将检查端口已关闭，`drained` 将检查活动连接。在检查文件或搜索字符串时，`present` 或 `started` 将确保文件或字符串存在后再继续，`absent` 将检查文件不存在或已删除。选择 `"absent"` `"drained"` `"present"` `"started"` ← (默认值) `"stopped"`
timeout integer	要等待的最大秒数，当与其他条件一起使用时，它将强制出错。当不使用其他条件时，它等同于只睡眠。默认值： `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 integer	等待时经过的秒数已返回：始终示例： `23`
match_groupdict dictionary	包含所有匹配的命名子组的字典，以子组名称为键，如 https://docs.pythonlang.cn/3/library/re.html#re.MatchObject.groupdict 所返回。已返回：始终示例： `{"group": "match"}`
match_groups list / elements=string	包含所有匹配的子组的元组，如 https://docs.pythonlang.cn/3/library/re.html#re.MatchObject.groups 所返回。已返回：始终示例： `["match 1", "match 2"]`

作者

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