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

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使不指定集合关键字，你也可以使用简短的模块名称 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`
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	支持：无	将返回有关更改内容（或可能需要在 check_mode 中更改的内容）的详细信息，当处于 diff 模式时
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)