基础设施即代码 / 系统课时
理解 Playbook 执行结构
理解 Playbook 执行结构
Playbook 的难点不是 YAML 缩进本身,而是看清 Ansible 如何从一个 play 选中主机,再按顺序执行 tasks、调用模块并收集每台主机的结果。本课用一个可运行的本地示例拆开这条执行链,让你能独立阅读最小 Playbook。
学习目标
- 说清 Playbook、play、hosts、tasks 与 module 之间的层级关系
- 看懂模块参数如何传入,以及任务结果如何按主机返回
- 使用
register保存结果,并判断changed与failed的含义
从 Playbook 读到一次执行
一个 Playbook 的 YAML 顶层是 play 列表。每个 play 用 hosts 选择 inventory 中的一组目标主机,再按 tasks 从上到下组织任务。一个普通 task 通常调用一个模块,并把该模块需要的参数放在模块名之下。
执行时,Ansible 会先确定当前 play 匹配哪些主机,再针对这些主机推进任务。模块完成后会返回结构化结果;Ansible 根据其中的状态决定显示 ok、changed 或 failed,也可以把完整结果保存给后续任务使用。

name 只是可读标签,真正决定目标范围的是 hosts,决定动作的是任务中的模块。示例里关闭 gather_facts,是为了避免自动事实采集干扰我们观察这两条显式任务。
跑通一个最小 Playbook
保存下面内容为 playbook.yml。它在控制节点本机创建一个演示目录,并把第一条任务的返回结果注册为 demo_dir。
- name: Demonstrate playbook structure
hosts: localhost
connection: local
gather_facts: false
tasks:
- name: Ensure demo directory exists
ansible.builtin.file:
path: /tmp/ansible-playbook-structure
state: directory
mode: "0755"
register: demo_dir
- name: Show selected result fields
ansible.builtin.debug:
msg: "path={{ demo_dir.path }} changed={{ demo_dir.changed }}"执行 Playbook:
ansible-playbook playbook.yml预期输出
假设目录最初不存在,第一条任务会改变目标状态,第二条只是输出信息,因此结果类似:
TASK [Ensure demo directory exists] ********************************
changed: [localhost]
TASK [Show selected result fields] *********************************
ok: [localhost] => {
"msg": "path=/tmp/ansible-playbook-structure changed=True"
}
PLAY RECAP *********************************************************
localhost : ok=2 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0如果目录已经存在且权限正确,Ensure demo directory exists 会显示 ok,changed 也会变成 False。这正是目标状态模块可重复执行时应有的表现。
看懂模块参数与返回结果
ansible.builtin.file 是模块的 Fully Qualified Collection Name。它下面的 path、state、mode 是模块参数;Ansible 根据这些参数判断当前状态与期望状态是否一致,并在需要时执行变更。
模块返回值是一个映射。register: demo_dir 把当前主机上的返回值保存成变量,因此后续 task 可以读取 demo_dir.changed、demo_dir.path 等字段。常见状态字段中,changed 表示这次任务是否修改了目标状态,failed 表示任务是否失败;其他字段由具体模块定义,不能假设所有模块都返回同一组业务字段。
用执行顺序定位结构问题
阅读陌生 Playbook 时,可以按“play 选主机 → task 定义动作 → module 接收参数 → result 返回状态”的顺序检查。若 YAML 能解析但行为不符合预期,先确认 hosts 是否匹配正确主机,再确认任务顺序和模块参数,最后查看失败任务的返回字段,而不是只盯着任务名称。
还要区分“任务执行成功”和“目标发生变化”:ok 表示成功且无需改变,changed 表示成功且做了变更,failed 才表示执行失败。理解这三种结果后,Playbook 的层级结构就不再只是 YAML 缩进,而是一条可以逐段验证的执行链。