基础设施即代码 / 系统课时
使用模块管理目标状态
使用模块管理目标状态
可重复执行的 Playbook 不应反复描述“执行某条命令”,而应描述“目标最终应该是什么样”。本课用 ansible.builtin.file 与 ansible.builtin.copy 写一个可重复运行的示例,并据此理解 FQCN、声明式参数和幂等结果。
学习目标
- 使用 Fully Qualified Collection Name 明确调用具体模块
- 用模块参数描述目录、文件、软件包和服务的期望状态
- 通过连续执行两次 Playbook 验证任务是否具备幂等性
从动作命令转成目标状态
FQCN 通常写成 namespace.collection.module,例如 ansible.builtin.copy。使用完整名称能明确模块来自哪个 collection,也能避免不同 collection 中出现同名模块时产生歧义。
声明式任务关注最终状态。例如“目录必须存在”写成 state: directory,“软件包必须安装”常写成 state: present,“服务必须运行”写成 state: started。模块先检查当前状态,只有不满足期望时才执行必要变更。
用 FQCN 写一个可重复任务
下面的 Playbook 只操作 /tmp,不要求远程主机或提权。第一条任务确保目录存在,第二条任务确保文件内容和权限与声明一致。
- name: Manage local demo state
hosts: localhost
connection: local
gather_facts: false
tasks:
- name: Ensure demo directory exists
ansible.builtin.file:
path: /tmp/ansible-managed-site
state: directory
mode: "0755"
- name: Ensure index content is correct
ansible.builtin.copy:
dest: /tmp/ansible-managed-site/index.txt
content: "managed by ansible\n"
mode: "0644"首次执行:
ansible-playbook desired-state.yml预期输出
假设目标目录和文件此前都不存在,两条任务都会造成变更:
TASK [Ensure demo directory exists] ********************************
changed: [localhost]
TASK [Ensure index content is correct] ******************************
changed: [localhost]
PLAY RECAP *********************************************************
localhost : ok=2 changed=2 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0再次执行同一个 Playbook:
ansible-playbook desired-state.yml预期输出
目标已经满足声明时,模块不需要再次修改系统,因此 changed=0:
TASK [Ensure demo directory exists] ********************************
ok: [localhost]
TASK [Ensure index content is correct] ******************************
ok: [localhost]
PLAY RECAP *********************************************************
localhost : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0第二次执行得到 changed=0,比“命令没有报错”更能说明 Playbook 是否真正可重复执行。
为不同资源选择对应模块
目标状态应该交给最了解该资源的模块管理。文件与目录可用 ansible.builtin.file,文件内容可用 ansible.builtin.copy 或模板模块,软件包可用 ansible.builtin.package,服务可用 ansible.builtin.service。这些模块会把“当前状态”和“期望状态”的比较逻辑封装起来。
例如 ansible.builtin.service 的 state: started 表示“如果没运行就启动,已经运行则不重复启动”;而 state: restarted 表示每次都执行重启,因此天然会产生动作。选择参数时要区分“保持某状态”和“每次触发一次操作”。
软件包名、服务名仍受目标操作系统影响。ansible.builtin.package 能抽象不同包管理器,但它不会替你统一发行版之间不同的软件包命名;ansible.builtin.service 也不会消除不同系统上的服务名称差异。
什么时候不要退回 shell
当已有专用模块能表达目标状态时,优先使用模块而不是 ansible.builtin.shell 或 ansible.builtin.command。直接执行命令通常无法自动判断“是否已经满足目标”,容易让每次运行都显示变化,甚至重复写配置或重复创建资源。
确实只能调用命令行工具时,应主动设计幂等条件,例如利用模块支持的 creates、removes,或根据返回值谨慎设置 changed_when。这些做法是在手工补回专用模块原本会提供的状态判断能力。
编写目标状态任务时,先问“系统最终必须满足什么条件”,再选择能表达这个条件的 FQCN 模块和参数。连续执行两次后,第二次应尽量稳定为 ok;只有确实需要每次触发的动作,才应该持续出现 changed。