Ansible 如何忽略不可达主机 (ignore_unreachable)
Ansible 中不可达主机与任务失败的处理机制不同。本文详细介绍如何使用 ignore_unreachable 关键字,并结合 serial 和 max_fail_percentage 参数有效管理连接故障,确保在主机无法连接时 Playbook 仍能继续执行并准确记录缺失任务。
主机不可达并非任务失败
若要在 Ansible 中忽略不可达的主机,请设置 ignore_unreachable: true,该开关即可生效。关键在于明确何时使用它,因为 Ansible 以两种不同的方式处理两种不同的问题。在主机上运行并返回错误的任务属于失败。Ansible 完全无法连接的主机属于不可达。ignore_errors 仅涵盖前者。ignore_unreachable 仅涵盖后者。
以下是 Play 汇总中的区别。
PLAY RECAP *********************************************************************
web1 : ok=7 changed=2 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
web2 : ok=0 changed=0 unreachable=1 failed=0 skipped=0 rescued=0 ignored=0Ansible 已连接到 web1 并运行了 7 个任务。web2 显示了 unreachable=1 和 failed=0,这意味着该主机上未运行任何任务。Ansible 未能建立连接,因此将该主机从 Play 中移除并继续执行其余任务。如果该 Play 旨在安装安全更新,则意味着你的一台服务器尚未安装该更新。
主机无法访问的原因
无法访问意味着在任何模块连接到主机之前,连接就已经失败。此时没有模块输出可供读取,只有连接错误,且该错误会出现在第一个触及该机器的任务中。
fatal: [web2]: UNREACHABLE! => {"changed": false, "msg": "Failed to connect to the host via ssh: ssh: connect to host 203.0.113.20 port 22: Connection refused", "unreachable": true}msg 字段包含了根本原因。以下是你可能会遇到的情况:
Connection refused:TCP 连接被拒绝,说明该端口上没有服务在监听。sshd 已停止,或者 SSH 已迁移到其他端口,但你的清单文件仍指向 22 端口。Connection timed out:没有任何响应。防火墙丢弃了数据包,或者服务器已关机。每次尝试都会耗尽完整的连接超时时间,默认值为 10 秒。Host key verification failed.:~/.ssh/known_hosts中的密钥与服务器提供的密钥不匹配。重装后的 VPS 会保留 IP 地址但生成新的主机密钥,因此重装后出现此情况是正常的,但在其他任何时候出现则意味着严重问题。Permission denied (publickey):SSH 已响应但拒绝了你的密钥。端口正常,说明是身份验证问题,通常是ansible_user错误或密钥未加载。Timeout (12s) waiting for privilege escalation prompt:连接成功但become失败。sudo 正在等待密码,但始终未收到。
人们常认为缺少 Python 解释器是上述列表中的原因,但它并不属于此类。SSH 连接已建立,说明主机是可访问的。只是模块在目标机器上没有可运行的环境:
fatal: [db1]: FAILED! => {"changed": false, "module_stdout": "/bin/sh: 1: /usr/bin/python3: not found\r\n", "msg": "The module failed to execute correctly, you probably need to set the interpreter", "rc": 127}该行显示 FAILED!,且汇总信息将其计入 failed,因此 ignore_unreachable 永远不会处理它。请为该主机设置 ansible_python_interpreter,或在其上安装 python3。
如何在 Play 中忽略不可达主机
在任务级别,该关键字与模块并列:
- name: Read the package list, and do not stop if the host is down
ansible.builtin.command: dpkg -l
register: packages
changed_when: false
ignore_unreachable: true在 Play 级别,它会为 Play 中的每个任务设置默认值,单个任务可以将其改回:
- name: Opportunistic fleet maintenance
hosts: all
ignore_unreachable: true
tasks:
- name: This runs, cannot connect, and the play carries on
ansible.builtin.ping:
- name: This one still ends the play for a host that is down
ansible.builtin.ping:
ignore_unreachable: false了解底层发生的变化很有必要。设置 ignore_unreachable 后,主机不会从 Play 中移除,因此后续的每个任务都会尝试重新连接,并以同样的方式失败。每次尝试都会等待连接超时,除非你在 ansible.cfg 中修改了 timeout,否则默认超时时间为 10 秒。针对一台宕机服务器执行 20 个任务的 Play 会增加约 200 秒的运行时间,并在日志中产生 20 行红色错误。
因此,请检查一次,然后干净利落地停止该主机:
- name: Opportunistic fleet maintenance
hosts: all
gather_facts: false
tasks:
- name: Check that the host answers before doing any work
ansible.builtin.ping:
register: reachable
ignore_unreachable: true
- name: End the play for this host if it never answered
ansible.builtin.meta: end_host
when: reachable.unreachable | default(false)
- name: Gather facts now that the connection is known good
ansible.builtin.setup:
- name: Refresh the package index
ansible.builtin.apt:
update_cache: true
become: true这样每个宕机主机只会进行一次连接尝试,而不是每个任务尝试一次。Ansible 2.8 中引入的 end_host 会结束当前主机的 Play,且不会将其标记为失败。unreachable 键仅在连接失败时才会出现在注册结果中,因此 default(false) 确保了该条件在所有响应的主机上均有效。在 Play 级别关闭事实收集(Fact gathering)是因为隐式的 Gathering Facts 任务会成为遇到连接中断的任务,而你希望该任务是你自定义的 ping 任务。
ignore_unreachable 是一个 Play 关键字,也是一个任务关键字。请将其保留在 Playbook 中以便阅读者查看,而不是放在 Role 内部,因为它决定了运行过程中允许跳过哪些主机。Playbook 与 Role 的拆分 涵盖了哪一层应该负责此类设置。
为什么 ignore_errors 在此场景下不适用
Ansible 文档明确指出了该功能的局限性。ignore_errors “仅在任务能够运行并返回 'failed' 状态时生效。它无法让 Ansible 忽略未定义变量错误、连接失败、执行问题(例如缺少软件包)或语法错误。”
连接失败不会作为任务结果通过 failed: true 处理。它会以独立的标志形式出现,Ansible 会优先处理该标志:主机将被移入 unreachable 列表并退出当前 play。即使在 play 的全部 12 个任务上都加上 ignore_errors: true,如果主机的 SSH 端口关闭,执行依然会在第一个任务处停止。这是该领域最常见的误解,建议检查您旧有的 playbook,特别是那些在 学习编写第一个针对 VPS 的 playbook 时编写的代码。
在抑制报错前进行调试
如果抑制报错成为常态,会导致集群配置漂移,因为无法连接的主机往往也处于无人维护的状态。请优先按以下顺序排查。此处列出的所有命令均为只读操作。
ansible web2 -i inventory.ini -m ansible.builtin.ping -o针对单台主机运行单个模块,并输出一行结果。- 在同一命令中添加
-vvvv。Ansible 会打印其构建的完整 ssh 命令,包括目标用户、端口、私钥以及传递的选项。 - 使用
-v手动运行该 ssh 命令。如果普通的 ssh 无法连接,说明问题出在 Ansible 之下,任何 Playbook 关键字都无法解决。 - 读取
msg字符串并对照上述列表。Connection refused和Connection timed out指向两个不同的位置,前者指向 SSH 服务,后者指向网络路径。 - 对于
Host key verification failed.,查看ssh-keygen -F web2.example.com中存储的内容。如果服务器已重建,请使用ssh-keygen -R web2.example.com删除旧条目,并在通过服务商控制台核对后接受新密钥。在ansible.cfg中设置host_key_checking = False虽然能消除错误,但也移除了校验机制,导致无法发现是否有其他机器正在使用该地址响应。 - 对于
Permission denied (publickey),确认 Ansible 实际使用的配置。ansible-inventory -i inventory.ini --host web2会打印当前生效的变量,包括ansible_user和ansible_port。 - 如果 SSH 连接正常但模块无法运行,请使用
ansible web2 -m ansible.builtin.raw -a 'command -v python3 || echo none'检查解释器。raw模块通过 shell 执行命令,不需要目标主机安装 python。
只有完成上述步骤后,忽略主机才算是一个决策,而不是一种习惯。
汇总会单独统计 unreachable,而 CI 通常会漏报
ansible-playbook成功时退出码为 0;至少有一台主机 unreachable 时退出码为 4;至少有一台主机失败且没有主机 unreachable 时退出码为 2。这两个退出码不会合并。源代码注释称它们可安全作为位标志使用,但运行结束时,策略会先检查 unreachable 主机并返回单个退出码。因此,如果一次运行同时包含失败主机和 unreachable 主机,退出码为 4,而不是 6。检查 2 来发现任务失败的流水线,在某台主机同时不可用的运行中会漏报失败。ansible命令返回相同的退出码。上述行为已根据 2026-10-10 的 ansible-core 2.21 源代码核对。
现在设置 ignore_unreachable: true,并针对同一台不可用主机运行相同的七任务 play:
PLAY RECAP *********************************************************************
web1 : ok=7 changed=2 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
web2 : ok=7 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=7web2会报告 unreachable=0,七个任务显示为 ok,并且运行退出码为 0。设置该关键字后,Ansible 会为该主机递增 ok 和 ignored 计数器,而不是递增它称为 dark 的计数器;后者会填充 unreachable 列。红色的 UNREACHABLE! 行仍会打印,因此日志内容是准确的,但汇总和退出码不是。
只运行 playbook 并检查 $? 的 CI 作业会将此次运行判定为成功,而其摘要中不会显示某台机器从未被访问。应在 play 之前单独执行可达性检查:
ansible all -i inventory.ini -m ansible.builtin.ping -o该命令会为每台主机打印一行;如果任意主机 unreachable,则退出码为 4。这样流水线可以据此失败,日志中也会记录主机名。ping要求目标主机上有可用的 Python 解释器,因此验证内容不仅是连接本身,通常这正是你需要的结果。然后使用 ignore_unreachable 运行 playbook,使仍在线的主机继续应用变更。
any_errors_fatal 和 max_fail_percentage 在批次中的应用
这两个 Play 关键字决定了当集群部分节点出错后的行为,它们对不可达主机的处理方式不同。
any_errors_fatal: true 会对不可达主机做出反应。Ansible 会在批次中其余主机上完成当前任务,然后停止该批次中所有主机的 Play。当运行任务必须“要么全成功,要么全失败”(例如协调数据库模式变更)时,请使用此选项。
max_fail_percentage: 30 不会对不可达主机做出反应。该检查将失败主机数量除以批次大小,而不可达主机被归入单独列表,因此它们不会影响该比例。在 max_fail_percentage: 10 设置下,10 台主机中有 4 台不可达时任务会继续,而 2 台主机任务失败则会停止 Play。文档中还提到了一个陷阱:“必须超过设定的百分比,而不是等于。”若要使用 serial: 4 在 4 台主机中有 2 台失败时停止,必须设置为 49,而不是 50。
有一种情况是不可达主机也会导致运行停止。如果批次中的所有主机都处于失败或不可达状态,Ansible 将没有可操作的对象,并以 NO MORE HOSTS LEFT 结束 Play。
序列:在集群中滚动执行变更
- name: Rolling nginx config update
hosts: webservers
serial: 2
max_fail_percentage: 25
tasks:
- name: Deploy the site config
ansible.builtin.template:
src: site.conf.j2
dest: /etc/nginx/conf.d/site.conf
owner: root
mode: "0644"
become: true
notify: Reload nginx
handlers:
- name: Reload nginx
ansible.builtin.service:
name: nginx
state: reloaded
become: trueserial: 2 会针对两台主机运行整个剧本,执行完成后,再启动接下来的两台。serial: "25%" 会随组的大小进行扩展。列表 serial: [1, 5, 10] 是金丝雀部署的形态:先运行一台主机,接着是五台,然后是十台,剩余的主机将按最后一批的大小进行分批运行。max_fail_percentage 是按批次计算的,因此两者协同工作。如果第一台机器出现故障,运行会立即停止,从而避免影响到四十台机器。这就是 从一台控制机管理 Linux 服务器集群 能够通过单条命令安全执行的原因。
何时忽略不可达主机,何时不应忽略
对于机会性任务,可以忽略不可达主机。事实收集运行或每小时一次的配置漂移检查,跳过宕机主机并无损失,因为下一次轮询会将其补上。此时使用 Play 级别的 ignore_unreachable: true 是正确的做法,配合 ping 步骤,可以将跳过的主机名记录在案,以便运维人员查阅。
对于安全补丁运行,绝不能忽略不可达主机。此类运行的价值在于确保每台主机都已应用修复。如果抑制了不可达状态,会将“一台服务器仍存在漏洞”的警告掩盖为“运行成功”的绿色汇总。一台已经两周不可达的主机,极有可能是版本滞后最严重的主机。应让此类运行以 exit 4 状态退出,并由人工介入检查。
无论哪种情况,都应遵循一条原则:抑制停止运行,但绝不抑制记录。如果某台主机被跳过,必须在汇总信息、CI 日志或监控告警中有所体现。Ansible 仅在针对主机运行 Play 的几秒钟内感知其存在,因此它不是获知服务器自周二起宕机的理想工具。该任务属于监控系统的职责,通过 安装 Zabbix 的 Ansible playbook,可以在一个下午内实现对整个集群的监控。
FAQ
Ansible 中 ignore_errors 和 ignore_unreachable 有什么区别?
ignore_errors: true适用于已在主机上运行并返回失败的任务,例如命令以非零状态退出。ignore_unreachable: true适用于 Ansible 无法连接的主机,此时不会运行任何模块。它们读取任务结果中的不同字段,互不覆盖。Ansible 文档说明,ignore_errors“不会使 Ansible 忽略未定义变量错误、连接失败、执行问题(例如缺少软件包)或语法错误”;关闭的 SSH 端口属于连接失败。
ignore_unreachable 会将主机从 play 汇总中隐藏吗?
实际上会。设置该关键字后,Ansible 不再将该主机计入 unreachable,而是将其按每个任务计入 ok 和 ignored,运行随后退出码为 0。fatal: [host]: UNREACHABLE!行仍会打印,因此日志是准确的,但汇总和退出码不是。请关注 ignored 列,或将 ansible all -m ansible.builtin.ping -o作为单独步骤运行,以便 unreachable 主机仍能在某个环节产生非零退出码。
主机 unreachable 时,ansible-playbook 返回什么退出码?
返回 4。至少有一台主机失败时,只有在没有主机 unreachable 的情况下,运行才返回 2。如果同时存在失败主机和 unreachable 主机,运行也返回 4,因为会先检查 unreachable,两个退出码不会合并为 6。运行成功时返回 0。上述退出码已根据 2026-10-10 的 ansible-core 2.21 源代码核对。设置 ignore_unreachable: true会移除退出码 4,因此只检查退出码的流水线无法发现被跳过的机器。
如何跳过对从未响应的主机执行 play 的其余部分?
将第一个任务设为 ansible.builtin.ping,并使用 ignore_unreachable: true 和 register: reachable;然后在条件 when: reachable.unreachable | default(false) 下执行 ansible.builtin.meta: end_host。end_host会结束该主机的 play,但不会将其标记为失败。在 play 上设置 gather_facts: false,使 ping 任务处理断开的连接。没有这种模式时,不可用主机会继续留在 play 中,后续每个任务都会再次等待连接超时。
在执行安全补丁时,是否应忽略 unreachable 主机?
不应。执行补丁的价值在于确保每台主机都已安装更新;忽略 unreachable 主机会将这一保证替换为显示成功的汇总。让运行以 4 退出,读取未响应主机的名称,并修复这些主机。抑制错误只适用于重复执行的机会性运行,因为下一轮会处理本轮遗漏的主机。