Shirone

template：天然幂等，内容比对#

单独讲一下template：典型幂等模块。Ansible 用 Jinja2 渲染模板，然后和目标文件做 checksum/内容比较：一致就 ok，不一致才复制并 changed。 owner、group、mode 等属性不一致也会触发变更。 变更后通过 notify 通知 handler，handler 只在 changed 时触发，而且同一个 handler 在一个 play 中通常只跑一次，避免重复重启服务。

1
- name: 部署配置
2
  template:
3
    src: app.conf.j2
4
    dest: /etc/app/app.conf
5
    owner: root
6
    group: root
7
    mode: '0644'
8
  notify: restart app
9

10
handlers:
11
  - name: restart app
12
    service:
13
      name: app
14
      state: restarted

两点值得记住：

• 模板里不要放天然变化的东西。ansible_date_time、随机数、递增版本号会让渲染结果每次都不同，于是每次都 changed。需要时间戳就自己定义稳定变量，或在确实需要时才引入；
• validate 能在落地前兜底。例如 validate: 'nginx -t -c %s'，Ansible 会先把渲染结果写到临时文件校验，失败就不替换——避免把语法错误的配置推上去，再把服务搞挂。

copy 的思路相同，区别只在于它是”源文件原样复制”，不经过 Jinja2 渲染。

1. creates / removes#

command、shell、raw 默认非幂等，每次跑都 changed，要用 creates、removes 或 when + register 兜底：

1
- name: 解压应用包（已解压则跳过）
2
  ansible.builtin.command:
3
    cmd: tar -xzf /tmp/app.tar.gz -C /opt/app
4
    creates: /opt/app/bin/app

creates / removes 是文件级判定，简单有效；一旦判断条件涉及”内容”（例如配置文件里有没有某一行），就只能退回 register + when。

2. when + register#

总有些操作无法用声明式表达：自定义安装脚本、一次性数据迁移、数据库初始化、节点加入集群。这类操作的统一解法是三段式：

flowchart LR
    A["检查任务：只读探测"] --> B{"期望状态已满足？"}
    B -- 是 --> C["ok：不执行变更"]
    B -- 否 --> D["变更任务：执行"]
    D --> E["changed：必要时 notify handler"]

写成任务就是”检查任务 + register + 变更任务 + when”，要点有三个：

1. 检查任务必须只读且无副作用，并显式写 changed_when: false。否则每次运行都报 changed，还会误触发 handler；
2. 检查任务要能区分”尚未初始化”和”真失败”。很多检查脚本用非 0 返回码表示”还没初始化”，直接用默认失败判定会让 playbook 在第一次运行时中断，需要用 failed_when 放行预期内的返回码；
3. 检查本身也有成本。如果检查要连远程服务、扫大表，注意加超时与重试，别把一个只读探测做成新的故障点。

register 把任务返回存成变量，里面有 rc、stdout、stderr、changed 等：

when 根据 facts、变量、register 结果决定要不要执行。 黄金模式：检查任务 + register + changed_when: false，变更任务 + when 条件。 比如：

1
- name: 检查是否初始化
2
  command: /usr/local/bin/check_init
3
  register: init_check
4
  changed_when: false
5
  failed_when: init_check.rc not in [0, 1]
6

7
- name: 初始化
8
  command: /usr/local/bin/init
9
  when: init_check.rc == 1

这样已初始化就不执行，实现幂等。

when 不只能看 register，也可以直接判断 facts 与变量，把”不该在这台机器上执行”的任务提前摘掉：

1
- name: 仅在 RedHat 系安装
2
  ansible.builtin.package:
3
    name: nginx
4
    state: present
5
  when: ansible_facts['os_family'] == 'RedHat'

1. changed_when / failed_when：修正状态报告#

changed_when 用来告诉 Ansible 这次到底算不算变更。 只读检查命令常写 changed_when: false，避免污染 changed 状态、误触发 handler。 也可以按输出判断：changed_when: "'already' not in result.stdout"。 failed_when 用来自定义失败条件，避免 rc != 0 但其实是正常情况被误判失败。

常见写法：

注意：这俩只影响结果判定和 handler 触发，不会让非幂等命令本身变幂等，真正幂等还得靠 when、creates/removes 控制执行。换句话说，changed_when: false 是”把报告改好看”，不是”把系统改正确”——它让第二次运行的 changed 消失，却让真正的重复执行继续发生。

2. notify + handler：变更收敛的去重器#

handler 是”只在被通知时才执行”的任务，而通知只发生在任务 changed 时。它存在的意义就是让”多个任务改了多个文件”收敛成”一次重启服务”：

1
handlers:
2
  - name: reload nginx
3
    service:
4
      name: nginx
5
      state: reloaded

几条关键语义：

• 同一个 handler 在一个 play 中默认只执行一次，无论被 notify 多少次。改了三个配置文件，nginx 也只重启一次；
• handler 默认在该 play 的所有普通任务执行完后统一运行。需要”先重启服务、再执行后续任务”时，用 meta: flush_handlers 显式提前触发；
• 触发条件是 changed：被 when 跳过的任务不会触发，写了 changed_when: false 的任务也不会触发——这既是保护，也是坑（真变更被标成 false 时，handler 就哑了）；
• 执行顺序是定义顺序，不是通知顺序；多个 handler 想响应同一个事件时用 listen 订阅同一主题；
• handler 里同样要写幂等语义的模块。service: state=restarted 放在 handler 里是合理的（由 changed 驱动），但把 command/shell 这种每次都 changed 的操作放进 handler，会形成”变更 → 执行命令 → 又变更”的连锁。

关于 handler 的更多细节（通知去重、执行时机、listen 主题），可参考 深入理解 Ansible Handler | Will’s Blog，讲的比较详尽。