Ansible如何实现幂等执行,怎样验证重复运行不会造成配置漂移?

发布人:A5数据发布时间:2026-11-05 09:26阅读量:57

同一份 Ansible Playbook 连续执行两次,第二次仍然出现 changed=1,并不一定代表 Ansible 失效;反过来,第二次显示 changed=0,也不能单独证明服务器没有配置漂移。真正的幂等执行,是在目标状态、输入变量和外部依赖保持一致时,第一次执行完成收敛,后续重复执行不再产生新的状态变化。

验证这一点需要同时观察控制端结果和被管理主机的实际状态:先在干净或已知状态的服务器上执行,再使用完全相同的清单、变量和权限重复执行;随后可以在测试环境中人为修改受管配置,确认 Playbook 能重新修正漂移,并再次运行确认恢复到 changed=0。--check 和 --diff 可以辅助判断,但不能替代真实执行和状态核对。

开篇:原理结合验证配图

先明确幂等执行的边界

幂等不是“每次都不做任何事”

Ansible 的目标是让服务器从当前状态收敛到声明的目标状态。第一次部署时,创建目录、写入配置、安装软件或创建定时任务都属于正常变更,因此可能出现多个任务 changed=1。

例如,下面的状态变化是符合预期的:

执行次数服务器状态典型结果
第一次配置文件不存在,服务未启动创建文件、启动服务,出现 changed
第二次配置已符合定义,服务已运行changed=0
人为修改配置后配置偏离定义修正配置,出现 changed
修正后的下一次配置再次符合定义changed=0

因此,幂等性关注的是“目标状态是否稳定”,而不是“任务是否从未执行”。

幂等、重复执行与配置漂移不是同一个概念

可以将三者区分为:

  • 重复执行:同一个 Playbook 被运行多次。
  • 幂等执行:在相同输入和相同目标约束下,重复执行不会继续改变资源状态。
  • 配置漂移:服务器实际状态被人工操作、其他程序或环境变化改变,导致其偏离 Ansible 声明的目标状态。

幂等 Playbook 并不阻止管理员临时修改文件,也不能阻止应用程序自行重写配置。它的作用是:下一次执行时识别差异,并将状态重新拉回定义。

此外,幂等也不等于事务回滚。一个 Playbook 可能已经成功修改了前几个主机,随后在某台服务器上失败。Ansible 默认不会把已经完成的所有操作自动撤销,因此还需要单独设计发布批次、备份和回滚机制。

Ansible如何把服务器收敛到目标状态

模块通过状态比较决定是否变更

Ansible 模块通常会读取远程状态,再与任务参数比较。例如:

  • file 比较路径、类型、权限、属主和属组;
  • copy、template 比较文件内容及文件属性;
  • package 根据软件是否存在或版本是否满足要求决定是否安装;
  • service 根据服务是否运行或是否启用决定是否操作;
  • user 和 group 根据账户属性进行调整;
  • cron 根据任务名称、时间表达式和命令维护定时任务。

下面的示例同时管理一个应用配置、服务状态和定时任务:

---
- name: Converge application host
  hosts: app
  become: true
  gather_facts: true

  tasks:
    - name: Ensure application configuration directory exists
      ansible.builtin.file:
        path: /etc/myapp
        state: directory
        owner: root
        group: root
        mode: "0755"

    - name: Manage application configuration
      ansible.builtin.copy:
        content: |
          listen = 8080
          log_level = info
          data_dir = /var/lib/myapp
        dest: /etc/myapp/app.conf
        owner: root
        group: root
        mode: "0644"
        backup: true
      notify: Restart myapp

    - name: Ensure myapp is running
      ansible.builtin.service:
        name: myapp
        state: started
        enabled: true

    - name: Manage cleanup cron job
      ansible.builtin.cron:
        name: "myapp log cleanup"
        user: root
        minute: "17"
        hour: "2"
        job: "/usr/local/sbin/myapp-cleanup --days 7"

  handlers:
    - name: Restart myapp
      ansible.builtin.service:
        name: myapp
        state: restarted

这个示例的前提是目标主机已经存在名为 myapp 的服务和清理脚本。配置内容、服务名、路径以及命令需要替换成实际环境中的值,不能直接假定所有发行版都采用相同目录结构。

配置文件只有在内容或属性发生变化时才会触发 Restart myapp。服务任务使用 state: started,只保证服务处于运行状态,不会在每次 Playbook 执行时主动重启。相反,如果任务直接写成 state: restarted,它通常会在每次执行时产生动作,这种写法就不适合作为普通的幂等状态声明。

changed是模块对变更的判断

Playbook 运行结果中的 changed 来自模块返回值。它反映的是模块认为自己是否修改了目标状态,而不是 Ansible 对整台服务器进行的独立审计。

这会带来两个重要判断:

  1. 使用成熟的状态模块时,changed=0 通常具有较好的参考价值。
  2. 使用 shell 或 command 时,必须额外定义“何时算发生变更”,否则输出可能无法代表实际状态。

例如,下面的命令每次都可能被执行:

- name: Run a maintenance command
  ansible.builtin.command: /usr/local/sbin/myapp-maintenance

如果该命令只是检查状态,或者只有在特定条件下才需要运行,应优先改成有明确状态语义的模块。确实只能调用外部命令时,可以使用 creates、removes,或根据命令输出设置 changed_when:

- name: Create initial data marker once
  ansible.builtin.command:
    cmd: /usr/local/sbin/myapp-init
    creates: /var/lib/myapp/.initialized

另一个例子是检查性命令:

- name: Check application configuration
  ansible.builtin.command: /usr/local/bin/myapp --check-config /etc/myapp/app.conf
  register: config_check
  changed_when: false
  failed_when: config_check.rc != 0

changed_when: false 只适用于确认该命令不会改变服务器状态的场景。不能为了让第二次执行显示 changed=0,把真正会修改文件或服务的命令强行标记为未变更。

Handler是控制副作用的重要机制

配置文件变化后重启服务,是常见的“状态变化触发副作用”场景。使用 notify 和 handler 的好处是:

合并动作”

  • 配置没有变化时,不重复重启;
  • 同一轮执行中多个任务通知同一个 handler 时,可以合并动作;
  • 变更逻辑与重启逻辑分离,便于审计和回滚。

如果服务必须在后续任务前立即重启,可以使用 meta: flush_handlers,但需要评估失败影响。handler 默认在合适的阶段执行,如果后续任务失败,之前已通知的 handler 可能尚未执行。对关键服务进行发布时,应明确安排健康检查和失败处理,而不是只依赖 handler 的默认时机。

哪些因素会破坏幂等性

把命令执行当成状态管理

shell、command 和 raw 适合调用没有对应模块的工具,但它们本身通常不知道目标状态。以下写法容易产生重复内容:

- name: Append a setting
  ansible.builtin.shell: echo "worker_processes=4" >> /etc/myapp/app.conf

每次执行都有追加风险,最终可能出现多行重复配置。更合适的选择是:

  • 用 copy 或 template 管理完整文件;
  • 用 lineinfile 管理明确的一行;
  • 用 blockinfile 管理有边界的配置块;
  • 使用应用提供的配置管理命令,并根据结果准确设置 changed_when。

使用 lineinfile 时,正则表达式应覆盖同一配置项的完整形式,并考虑注释、空白和已有重复行。例如:

- name: Ensure worker count is defined once
  ansible.builtin.lineinfile:
    path: /etc/myapp/app.conf
    regexp: '^\s*worker_processes\s*='
    line: 'worker_processes=4'
    create: true
    owner: root
    group: root
    mode: "0644"

如果文件存在多个旧配置项,仅靠一条规则不一定能清理所有重复内容。对于结构稳定、由 Ansible 完整拥有的文件,使用模板整体生成通常更容易验证。

模板内容包含不稳定输入

同样的模板如果每次渲染都得到不同内容,就不可能稳定收敛。常见来源包括:

  • 当前时间、随机数或随机密码;
  • 未排序的集合、字典或外部 API 返回数据;
  • 每次运行都重新生成的临时路径;
  • 依赖主机本地环境的命令输出;
  • 由应用自身自动写入的时间戳或格式化内容。

需要将这些输入固定、排序或隔离。例如,模板中使用列表时可以先排序:

- name: Render allowlist in stable order
  ansible.builtin.template:
    src: allowlist.conf.j2
    dest: /etc/myapp/allowlist.conf
    owner: root
    group: root
    mode: "0644"

模板文件中应尽量基于确定的变量生成内容:

{% for address in allowed_addresses | sort %}
allow = {{ address }}
{% endfor %}

如果确实需要生成一次性值,应先将该值持久化到受控的变量、密钥系统或事实存储中,而不是在每次运行时重新随机生成。

版本策略不明确

state: present 通常表示软件存在即可;state: latest 则可能因为软件仓库产生新版本,在不同时间执行时再次发生升级。对于需要可重复部署的环境,应明确区分:

  • 只要求软件存在:使用 present;
  • 允许跟随仓库更新:使用 latest,但接受其输入会变化;
  • 需要可审计的发布:指定固定版本,并固定软件源或仓库快照。

即使 Playbook 没有变化,仓库内容、DNS、证书、外部 API 和操作系统软件源也可能变化。验证幂等性时,不能只比较 YAML 文件是否相同,还要记录关键外部输入。

定时任务缺少稳定标识

定时任务特别容易出现重复项。使用 cron 模块时,name 应保持稳定,任务内容也应明确:

- name: Maintain one stable backup cron entry
  ansible.builtin.cron:
    name: "myapp daily backup"
    user: root
    minute: "30"
    hour: "1"
    job: "/usr/local/sbin/myapp-backup --retention 7"

如果每次运行都把日期拼进 job,或者动态修改任务名称,Ansible 会将其视为不同条目,可能不断新增任务。手工维护的同类任务也可能与 Ansible 管理的条目并存,因此上线前应检查实际 crontab,并约定哪些条目由 Playbook 完整负责。

外部程序会反向修改配置

Ansible 写入的文件可能随后被应用、代理程序或系统服务重写。例如,程序启动时自动补充默认值,或者管理工具把配置重新格式化。此时即使 Playbook 本身是幂等的,服务器也可能在两次运行之间持续漂移。

处理方式通常有三类:

  1. 将该文件交给单一管理者,避免 Ansible 与应用同时写入;
  2. 让 Ansible 管理应用认可的源配置,再由应用生成派生文件;
  3. 将自动生成内容排除在人工管理范围之外,只验证关键结果。

如果无法确定谁拥有文件的最终控制权,changed=0 不能作为合规结论。

一套可执行的重复运行验证方法

第一步:固定输入并完成静态检查

验证应在独立测试主机、快照或可恢复的环境进行。先固定以下内容:

  • Inventory 文件和目标主机分组;
  • Ansible 配置文件;
  • 角色、Playbook 和模板的 Git 提交;
  • 变量文件和必要的额外参数;
  • 执行用户、提权方式以及软件源;
  • 测试时是否允许访问外部服务。

先进行语法检查:

ansible-playbook -i inventory/hosts.yml site.yml --syntax-check

再检查目标主机是否可连接,并确认权限:

ansible -i inventory/hosts.yml app -m ansible.builtin.ping
ansible -i inventory/hosts.yml app -b -m ansible.builtin.command -a 'id'

如果使用了 become,验证结果应与实际发布时一致。普通用户能连接,不代表该用户有权限写入配置目录或管理服务。

第二步:执行第一次并保留结果

第一次执行的输出应保存下来,用于和第二次对比:

ansible-playbook \
  -i inventory/hosts.yml \
  site.yml \
  --diff \
  | tee run-1.log

--diff 可以显示文件内容变化,适合检查模板是否产生了预期结果。但配置中如果包含密码、令牌、证书私钥或其他敏感信息,不应直接输出差异。敏感任务可以使用 no_log: true,同时通过文件校验和、服务健康状态等方式保留必要审计证据。

第一次执行需要记录:

  • 哪些任务为 changed;
  • 是否有失败或不可达主机;
  • handler 是否执行;
  • 配置文件的实际路径、权限和属主;
  • 服务是否处于运行和启用状态;
  • 定时任务是否只有一条预期记录。

第三步:使用相同输入重复执行

不要在两次运行之间修改变量、切换 Inventory 或更新软件源。直接重复执行:

ansible-playbook \
  -i inventory/hosts.yml \
  site.yml \
  --diff \
  | tee run-2.log

在目标已经收敛、外部依赖没有变化的前提下,常见预期是:

ok=4    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

数字仅表示示例。实际任务数量会随 Playbook 变化,重点是每台目标主机的 changed=0、failed=0 和 unreachable=0。如果第二次仍然有 changed,应先定位具体任务,而不是直接修改 changed_when。

排查顺序可以是:

  1. 查看是哪个模块返回 changed;
  2. 比较第一次和第二次的 diff;
  3. 检查模板是否包含时间、随机数或不稳定排序;
  4. 检查外部程序是否在两次运行之间改写了文件;
  5. 检查任务是否使用了 shell、command 或 state: restarted;
  6. 检查事实、变量、软件仓库和执行权限是否发生变化。

第四步:使用检查模式预测变更

在不修改服务器的情况下,可以运行:

ansible-playbook \
  -i inventory/hosts.yml \
  site.yml \
  --check \
  --diff

当服务器已经收敛时,检查模式通常应预测没有待处理变更;如果人为修改了配置,检查模式通常会报告相关任务将发生变化。

但检查模式不是完整证明,原因包括:

  • 某些模块无法完全模拟远程操作;
  • command 和 shell 的检查能力有限;
  • 外部 API 的真实返回值可能与预测不同;
  • handler、服务启动和应用健康状态无法仅靠 diff 证明;
  • 模块可能只比较部分属性。

因此,检查模式适合作为发布前预览和变更审批依据,不应取代至少一次真实执行和后续状态核对。

第五步:在测试环境制造漂移

要验证“能否修复漂移”,不能只做两次无变化运行。可以在隔离测试主机上备份受管文件后,进行一次可恢复的人工修改:

sudo cp -a /etc/myapp/app.conf /tmp/app.conf.before-drift
sudo sed -i 's/^log_level = info$/log_level = debug/' /etc/myapp/app.conf

上述操作只适用于明确知道文件内容、并且能够恢复的测试环境。修改前应确认服务影响范围,必要时先停止流量或使用快照。测试完成后,如果 Playbook 本身没有修复成功,应使用备份文件恢复,并重新验证服务配置。

再次执行 Playbook,合理的结果应类似于:

  • 配置任务出现 changed=1;
  • 配置变更触发 handler;
  • 服务恢复到预期状态;
  • 再次执行时变为 changed=0。

如果手工修改后 Playbook 仍然显示 changed=0,可能说明任务没有真正管理该文件、比较范围不完整,或者 changed_when 掩盖了真实变更。此时应直接检查文件内容、权限、属主和服务实际加载的配置路径。

第六步:核对服务器实际状态

控制端输出之外,还应对关键状态进行断言。例如,验证配置文件中存在预期内容:

- name: Read managed configuration
  ansible.builtin.slurp:
    src: /etc/myapp/app.conf
  register: app_config
  changed_when: false

- name: Assert required configuration
  ansible.builtin.assert:
    that:
      - "'listen = 8080' in (app_config.content | b64decode)"
      - "'log_level = info' in (app_config.content | b64decode)"
    fail_msg: "The application configuration is not in the expected state"

验证服务状态时,可以使用服务事实:

- name: Gather service facts
  ansible.builtin.service_facts:

- name: Assert myapp is running
  ansible.builtin.assert:
    that:
      - "'myapp.service' in ansible_facts.services
      - ansible_facts.services['myapp.service'].state == 'running'

如果应用提供本地健康检查接口,还应在服务重启后进行业务层验证。仅仅看到 systemd 状态为 running,并不能证明端口已监听、配置已被加载或依赖服务可用。

Ansible 的重复部署与漂移修复,需要稳定的服务器资源承载业务环境。A5idc数据提供中国香港、美国、日本、韩国、中国台湾、新加坡和马来西亚等地区的物理服务器,涵盖常规建站、AMD计算、存储及多IP等产品方向;不同CPU、内存、磁盘和线路配置,可对应业务后台、数据库、接口服务及跨地区部署等场景,为服务器配置管理提供多样化的基础资源。

定时执行、审计与失败回滚

定时运行不能替代首次验证

将 Playbook 放到定时任务中,可以持续纠正配置漂移,但应先完成一次人工验证。定时执行还需要考虑:

  • 避免多个调度实例同时运行;
  • 记录每次执行使用的 Git 提交和变量版本;
  • 对失败、不可达和部分成功分别告警;
  • 控制并发,避免同时重启同一批服务;
  • 对输出中的密码、令牌和私钥进行脱敏;
  • 区分“没有变更”和“任务没有执行”。

Ansible 控制端可以通过 log_path 或外部作业系统保存运行日志,但日志保存本身不等于合规审计。较完整的审计记录至少应包含执行时间、目标主机、Playbook 版本、操作者或调度任务、变更任务、失败原因以及回滚结果。

失败回滚需要提前设计

配置文件任务中的 backup: true 可以在发生覆盖时生成远程备份,适合处理单个文件的临时恢复:

- name: Deploy application configuration with backup
  ansible.builtin.copy:
    src: files/app.conf
    dest: /etc/myapp/app.conf
    owner: root
    group: root
    mode: "0644"
    backup: true
  register: app_config_deploy
  notify: Restart myapp

但这个备份通常只是一次变更产生的文件副本,不等于长期版本库,也不一定覆盖数据库、软件包、证书和多台主机之间的关联状态。生产发布更适合采用以下方式:

  • 配置文件和模板进入版本控制;
  • 每次发布记录对应提交;
  • 使用版本化目录或发布包;
  • 先在少量主机上执行,再扩大批次;
  • 保留上一版本配置和应用包;
  • 回滚时重新执行上一版本的声明,而不是手工拼接文件。

如果需要在同一 Playbook 中处理失败,可以使用 block 和 rescue,但恢复动作本身也必须经过测试。Ansible 没有跨主机的自动事务机制,不能仅凭 rescue 就认为所有已完成操作都会回退。

什么时候不能简单宣称“已经幂等”

需要区分资源状态和业务结果

一个任务连续两次返回 changed=0,只说明该模块认为目标资源没有变化。它不一定说明:

  • 应用实际读取了这份配置;
  • 端口能够正常提供服务;
  • 数据库迁移没有重复执行;
  • 定时任务确实被调度器执行;
  • 外部系统已经接受配置;
  • 所有主机具有相同的版本和依赖。

因此,验证层级可以分为:

验证层级关注内容常用方式
任务层模块是否重复报告变更Playbook recap、changed_when
文件层内容、权限、属主、校验和stat、slurp、diff
服务层进程、监听、启用状态service_facts、端口检查
应用层配置是否成功加载、接口是否健康应用自带检查命令、健康接口
运行层漂移是否被发现和修复定时执行、日志、告警、人工修改测试

不同资源应使用对应的验证方式。不能用一个配置文件的 changed=0,推断数据库、定时任务和服务健康状态都没有问题。

多主机和外部依赖会改变结果

在多主机部署中,执行顺序、批次大小和服务依赖会影响结果。可以使用 serial 分批发布,先验证少量主机,再处理剩余节点:

---
- name: Rolling configuration deployment
  hosts: app
  become: true
  serial: 2

  tasks:
    - name: Deploy configuration
      ansible.builtin.template:
        src: app.conf.j2
        dest: /etc/myapp/app.conf
        owner: root
        group: root
        mode: "0644"
      notify: Restart myapp

    - name: Verify local application health
      ansible.builtin.command: /usr/local/bin/myapp-healthcheck
      changed_when: false

  handlers:
    - name: Restart myapp
      ansible.builtin.service:
        name: myapp
        state: restarted

这里的健康检查命令必须是只读检查,并且能够以非零退出码准确表示失败。若应用启动耗时较长,还需要加入适当的等待和重试逻辑,否则可能把正常启动延迟误判为发布失败。

外部 API、软件仓库、DNS、时间同步和证书有效期也会影响重复运行。如果这些因素没有固定,第二次执行发生变化并不一定是 Playbook 非幂等,而可能是输入环境已经变化。验证报告中应记录这些条件,避免把环境波动误判为模块问题。

幂等性是有条件的工程属性

可以用下面的判断标准确认一个 Playbook 是否达到可接受的幂等水平:

  1. 在相同 Inventory、变量、权限和依赖版本下,第一次执行能够完成目标状态收敛。
  2. 使用完全相同输入重复执行,受管资源不再产生新的变更。
  3. 在测试环境制造可控漂移后,Playbook 能识别并修正。
  4. 修正后的下一次执行再次达到 changed=0。
  5. 服务、定时任务和应用健康状态与文件层结果一致。
  6. 失败时能够识别已完成的部分,并按照预先定义的版本或备份恢复。
  7. 对不支持检查模式、不可逆或外部副作用明显的任务,单独标注验证方法和风险边界。

达到这些条件时,才可以较有把握地说 Playbook 具备可重复部署能力。若只看到第二次运行的 changed=0,却没有核对实际文件、服务、定时任务和外部副作用,最多只能说明一次执行结果看起来稳定,不能据此排除配置漂移。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/7606.html

相关推荐