Ansible playbook --check --diff 怎么预览配置变更

我在上线一个配置模板前，最怕的不是 playbook 写错，而是不确定它会改哪台机器、改哪几行。这个场景里，--check 和 --diff 应该一起用：前者让 Ansible 尝试预测变更而不落地，后者让支持差异输出的模块展示 before/after。再配合 --limit 只看一台主机，审阅结果会更容易控制。

官方地址：https://docs.ansible.com/projects/ansible-core/devel/playbook_guide/playbooks_checkmode.html

推荐命令是 ansible-playbook site.yml --check --diff --limit app-01。它是预览，不是对所有任务都能做到完整仿真的保证；模块是否支持 check/diff、条件是否依赖前序结果，都会影响输出。

先把 check 和 diff 的职责分开

官方文档把 check mode 定义为模拟运行：支持它的模块会报告可能发生的变化，但不会在远端系统落地；不支持 check mode 的模块可能什么也不报告。diff mode 则负责给出前后对比，最常见于 template、lineinfile 等会改文件的模块，也可能由其他模块提供差异信息。

因此，先看“是否预测变更”，再看“差异是否足够详细”，不要把两个开关当成同一件事。命令中的 --limit app-01 只是收窄匹配到的主机，不能替代 playbook 自己的条件判断。

用一条受控命令预览配置文件变化

假设 playbook 里有一个模板任务，目标是把服务端口写入配置文件。预览时先把 inventory、playbook 和主机范围写清楚：

# 只在单台主机上模拟，不把模板变化写入远端
ansible-playbook -i inventory.ini site.yml \
  --check --diff --limit app-01

# 只列出会匹配的主机，避免 limit 拼写错误扩大范围
ansible-playbook -i inventory.ini site.yml \
  --list-hosts --limit app-01

输出里重点看任务名、目标主机和模块返回的 changed。如果模块给出 before/after，就能继续判断究竟是端口、权限、空白还是整段文件被替换；如果只有一行状态，先把它当作“模块已经判断出差异，但没有提供细节”，不要凭空猜哪一行会变。

为什么预览结果有时不完整

check mode 是模拟，不是完整的沙箱。官方文档特别提醒：依赖前序任务 register 变量的条件，可能在检查模式下没有可用的真实结果，所以后续任务的预测会缺少信息。另一个常见边界是任务显式写了 check_mode: false，它会在 --check 下仍按正常模式执行；这类任务必须单独审阅。

tasks:
  - name: 只有正式运行时才拉取远程仓库
    ansible.builtin.git:
      repo: "https://example.invalid/app.git"
      dest: /opt/app
    # 检查模式不执行有副作用的外部拉取
    when: not ansible_check_mode

  - name: 生产任务禁止暴露秘密差异
    ansible.builtin.template:
      src: secret.conf.j2
      dest: /etc/app/secret.conf
      mode: '0600'
    # diff 可能包含密码或令牌，显式关闭此任务的差异输出
    diff: false

还要留意不支持 check 或 diff 的模块：它们可能不报告变化，也不会给你想要的前后文本。预览缺口不是“命令失效”，而是任务能力和数据依赖没有提供足够信息。

把一次预览变成可复查的上线判断

我的做法是先单主机预览，再对照任务范围记录三件事：哪些任务显示 changed、哪些任务被跳过、哪些任务没有给出 diff。对文件类任务，差异里若出现整文件替换，要回头检查模板渲染、换行和权限；对没有差异的任务，不要直接推断“绝对不会改”。

确认预览符合预期后，才去掉 --check --diff 执行正式变更。若 playbook 包含秘密配置，审阅日志和 CI 输出也要按敏感信息处理；diff: false 只隐藏该任务的 diff，不会自动解决其他日志或变量泄露。

相关问题

--check 会完全不连接远端主机吗？

不会。它仍可能连接主机、读取事实或执行支持检查模式的只读动作；关键语义是尽量不落地变更，而不是完全离线模拟。

为什么加了 --diff 还是看不到文件差异？

目标模块可能不支持 diff，任务可能设置了 diff: false，也可能检查结果没有预测出变化。先区分这些边界，再判断 playbook 是否有问题。

应该一次对所有主机执行预览吗？

不建议把第一次审阅扩大到全量主机。先用 --limit 验证一台代表性主机，确认变量、条件和差异符合预期后，再决定是否扩大范围。

对我来说，--check --diff 最有价值的地方不是保证“绝不会出意外”，而是把一次高风险变更拆成可阅读的预测、差异和边界检查。只要把单主机范围、模块支持和敏感信息一起纳入判断，它就能成为正式部署前很实用的一道门。