基础设施即代码 / 系统课时
控制失败传播与主机退出
控制失败传播与主机退出
Ansible 默认按主机隔离任务失败:一台主机失败后通常退出后续任务,其他主机继续执行。本课比较 ignore_errors、any_errors_fatal 与 max_fail_percentage,并用批次示例确定何时该容忍、全局中止或按失败比例停止。
学习目标
- 区分单任务忽略、全局致命失败和批次失败阈值的作用范围
- 结合
serial正确计算max_fail_percentage的停止条件 - 避免把“忽略错误”误当成“错误已经解决”
先确定失败应该传播到哪里
默认行为适合主机彼此独立的任务:某台主机的任务失败后,该主机不再执行后续普通任务,仍然健康的主机继续。需要改变这个边界时,应先决定业务要求,再选择指令,而不是习惯性加 ignore_errors: true。
| 机制 | 典型放置位置 | 失败后的效果 | 适合场景 |
|---|---|---|---|
ignore_errors |
单个任务 | 当前任务仍显示失败/被忽略,但该主机继续后续任务 | 可选探测、允许降级的非关键步骤 |
any_errors_fatal |
play 或 block | 任一未处理失败传播到全部主机并终止 play | 必须全体成功才能继续的全局前置条件 |
max_fail_percentage |
play | 当前批次失败比例超过阈值后终止 play | 滚动发布允许少量失败但必须限制损失面 |

三者控制的是不同层级:ignore_errors 改变单个任务失败后该主机是否继续,any_errors_fatal 扩大未处理失败的传播范围,max_fail_percentage 则根据一批主机的累计失败比例决定是否停止。
用批次阈值限制滚动发布
下面创建四个逻辑主机并全部在控制节点本地执行。前两个主机被故意标记为失败,serial: 4 表示这一批有四台主机,max_fail_percentage: 49 表示失败比例必须超过 49% 才会中止。
---
- name: Stop a batch when failure ratio is too high
hosts: all
connection: local
gather_facts: false
serial: 4
max_fail_percentage: 49
tasks:
- name: Fail two hosts deliberately
ansible.builtin.fail:
msg: "simulated failure"
when: inventory_hostname in ["host1", "host2"]
- name: Continue only when threshold is not exceeded
ansible.builtin.debug:
msg: "continuing on {{ inventory_hostname }}"保存为 failure-threshold.yml 后执行:
ansible-playbook -i 'host1,host2,host3,host4,' failure-threshold.yml预期结果:
失败主机:host1、host2
当前批次:4 台主机
失败比例:2 / 4 = 50%
阈值:49%
结果:50% > 49%,play 在该批次后终止,后续 debug 任务不执行这里最容易算错的是边界条件。阈值是“超过”才停止,因此四台主机中若希望第二台失败时就中止,应设置 49,而不是 50。配合 serial 时,比例针对当前批次计算,不是拿整个 inventory 的主机数做分母。
理解三个机制的适用边界
ignore_errors: true 只适用于任务已经正常发起并返回 failed 的情况。连接不可达、语法错误、未定义变量等问题不能靠它统一吞掉。即使错误被忽略,也应保留 register、日志或后续判断,否则自动化会继续推进,却没有证据说明系统是否仍满足前置条件。
any_errors_fatal: true 适合“一个失败,全体都不该继续”的场景,例如必须先从负载均衡摘除全部节点,再执行维护。它针对未被处理的失败;如果失败位于带 rescue 的 block 中且补救成功,该失败不会按普通未处理错误继续传播。
max_fail_percentage 更适合滚动发布,因为它允许有限故障。默认线性执行策略下,它常与 serial 一起使用,把停止条件限定在当前批次,避免一个坏版本继续扩散到后续批次。
选择停止策略而不是掩盖失败
判断顺序可以保持简单:非关键任务允许降级时才用 ignore_errors;任何单机失败都会破坏全局安全条件时用 any_errors_fatal;允许少数失败但要限制故障面时用 serial 加 max_fail_percentage。如果失败已经可以通过 rescue 恢复到已知状态,应优先补救,而不是一边忽略错误一边继续执行未知状态的主机。