Ansible 任务验证：检查模式与差异模式-未完纪

Ansible 提供两种用于验证任务的执行模式：检查模式（check mode）和差异模式（diff mode）。它们可以分别使用，也可以结合使用。在编写或修改 playbook、role，并希望了解它们将执行什么操作时，这两种模式都很有用。

在检查模式下，Ansible 模拟执行，不改动远程系统。支持检查模式的模块会报告它们原本会产生的变更；不支持检查模式的模块不会报告结果，也不会执行操作。在差异模式下，Ansible 会比较变更前后的内容；支持差异模式的模块会展示详细信息。将两种模式结合，可以更细致地验证 playbook 或 role。

使用检查模式

检查模式只是模拟。对于根据注册变量（先前任务的结果）设置条件的任务，它可能无法生成相应输出。不过，对于一次管理一个节点的配置管理 playbook，检查模式很适合用于验证。要以检查模式运行 playbook：

ansible-playbook foo.yml --check

在任务中强制启用或禁用检查模式

此功能从 Ansible 2.2 开始提供。

如果希望某些任务始终在检查模式下执行，或者始终正常执行，而不受调用 playbook 时是否使用 --check 的影响，可以为这些任务添加 check_mode 选项：

设置 check_mode: true，即使调用 playbook 时没有使用 --check，也会强制该任务以检查模式执行。
设置 check_mode: false，即使调用 playbook 时使用了 --check，也会强制该任务正常执行，并实际改动系统。

例如：

tasks:
  - name: This task will always make changes to the system
    ansible.builtin.command: /something/to/run --even-in-check-mode
    check_mode: false

  - name: This task will never make changes to the system
    ansible.builtin.lineinfile:
      line: "important config"
      dest: /path/to/myconfig.conf
      state: present
    check_mode: true
    register: changes_to_important_config

对单个任务设置 check_mode: true，既可以测试 Ansible 模块本身，也可以测试模块在什么条件下会产生变更。还可以在这些任务中注册变量，以了解潜在变更的更多细节。

旧版本说明：在 2.2 之前，只有与 check_mode: false 等效的功能，当时的写法是 always_run: true。

在检查模式下跳过任务或忽略错误

此功能从 Ansible 2.1 开始提供。

如果希望 Ansible 在检查模式下跳过某个任务，或者忽略某个任务的错误，可以使用布尔类型的魔术变量 ansible_check_mode。Ansible 在检查模式下运行时，该变量的值为 True。例如：

tasks:

  - name: This task will be skipped in check mode
    ansible.builtin.git:
      repo: ssh://git@github.com/mylogin/hello.git
      dest: /home/mylogin/hello
    when: not ansible_check_mode

  - name: This task will ignore errors in check mode
    ansible.builtin.git:
      repo: ssh://git@github.com/mylogin/hello.git
      dest: /home/mylogin/hello
    ignore_errors: "{{ ansible_check_mode }}"

使用差异模式

ansible-playbook 的 --diff 选项可以单独使用，也可以与 --check 结合使用。在差异模式下，支持该模式的模块会报告已经产生的变更；如果同时使用 --check，则报告原本会产生的变更。差异模式常见于操作文件的模块，例如 template；其他模块也可能展示变更前后的信息，例如 user 模块。

差异模式会产生大量输出，因此最好一次只检查一台主机。例如：

ansible-playbook foo.yml --check --diff --limit foo.example.com

在任务中禁用差异输出

此功能从 Ansible 2.4 开始提供。

--diff 可能暴露敏感信息。可以为任务设置 diff: false，禁用该任务的差异输出。例如：

tasks:
  - name: This task will not report a diff when the file changes
    ansible.builtin.template:
      src: secret.conf.j2
      dest: /etc/secret.conf
      owner: root
      group: root
      mode: '0600'
    diff: false

来源：Ansible Community Documentation — Validating tasks: check mode and diff mode。Copyright © Ansible project contributors。中文改编日期：2026-10-03；正文已翻译，命令与 YAML 示例保持原文。原始文档及本改编按 GNU GPL v3 分发，不提供担保。可编辑 HTML、原文与完整许可证随离线稿一并保存。

文章版权归作者所有，未经允许请勿转载。

THE END