基础设施即代码 / 系统课时
理解幂等性与 changed 状态
理解幂等性与 changed 状态
Ansible 的可重复执行依赖两个判断:目标当前是什么状态,以及任务是否真的把它改成了期望状态。理解幂等性和 changed 后,你才能判断一次 Playbook 重跑是安全收敛,还是在重复制造副作用。
学习目标
- 判断一个任务是否具备幂等性,而不是只看它能否成功执行。
- 读懂
ok、changed与failed对重复执行和审计的含义。 - 为必要的命令式任务补上
creates、removes或changed_when等边界。
幂等性看的是目标状态
幂等任务描述的是“系统最终应该是什么样”,而不是“每次都执行同一个动作”。以 copy、file、package、user 等模块为例,模块会先读取当前状态;已经满足期望时返回 changed: false,存在差异时才修改并返回 changed: true。

changed 因而不是“任务成功”的同义词。成功且无需修改通常是 ok;成功并修改了受管状态才是 changed;执行失败则是 failed。理想的幂等 Playbook 在环境已经收敛后再次运行,变化数应降到 0 或只剩明确允许的例外。
用重复执行验证 changed
下面的 Playbook 同时演示两个可重复执行的任务:copy 只在文件内容或属性不匹配时写入,command 则通过 creates 把一次性动作变成“文件不存在才执行”。
- name: Verify idempotent execution
hosts: localhost
connection: local
gather_facts: false
tasks:
- name: Converge managed configuration
ansible.builtin.copy:
dest: /tmp/ansible-idempotent.conf
content: "mode=managed\n"
mode: "0644"
- name: Run bootstrap only once
ansible.builtin.command:
cmd: /usr/bin/touch /tmp/ansible-bootstrap.done
creates: /tmp/ansible-bootstrap.done把内容保存为 idempotence.yml,连续执行两次:
ansible-playbook -i localhost, -c local idempotence.yml
ansible-playbook -i localhost, -c local idempotence.yml预期输出如下,省略任务明细,只保留两次 PLAY RECAP:
localhost : ok=2 changed=2 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
localhost : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0第一次运行需要创建两个文件,所以有两项变化;第二次运行时配置已经一致,标记文件也已经存在,因此没有新的变化。若第二次仍持续出现 changed,就应继续检查任务是否真的具备收敛条件。
把 changed 当成审计信号
changed 会进入控制台回顾、回调插件、日志平台和自动化审计,也会决定 Handler 是否收到通知。它必须尽量反映“受管状态发生了有意义的变化”,否则不仅报表会失真,还可能触发不必要的服务重启。
读日志时应把状态分开理解:ok 说明任务成功且无需修改;changed 说明任务成功并声明发生了变化;failed 说明任务没有按预期完成。仅凭返回码为 0,不能推断任务是否幂等,也不能推断 changed 是否准确。
命令式任务如何补足幂等性
command 和 shell 的职责是执行命令,它们通常不知道命令前后的业务状态。优先选择能描述目标状态的专用模块;确实必须执行命令时,再显式补充判定条件。
creates 适合“目标文件已存在就不再执行”,removes 适合“前置文件不存在就不执行”。对于只读检查类命令,可以用 changed_when: false 告诉 Ansible 成功执行并不代表系统发生变化;若变化条件取决于返回内容,也应让 changed_when 根据可靠输出判断,而不是无条件写死。
判断一段自动化是否足够安全,最有效的验收不是“第一次跑通”,而是让它连续运行两次:第二次没有无意义的变化、没有重复副作用,changed 又能准确标记真实修改,这才是可重复执行的 Playbook。