基础设施即代码 / 系统课时
设计 Role 目录与职责边界
设计 Role 目录与职责边界
当一个 Playbook 开始同时管理任务、配置文件和重启逻辑时,继续把所有内容堆在单个 YAML 文件里会迅速失控。本课把这些内容收拢成一个边界清晰的 Role,并用最小示例验证目录职责与调用方式。
学习目标
- 识别
tasks、handlers、templates、files、defaults、vars与meta的职责。 - 把“执行流程、配置素材、变化响应”分开,避免 Role 内部互相耦合。
- 设计可由 Playbook 直接调用、又不泄露环境细节的 Role 边界。
把 Role 当成可调用组件
Role 不是“按文件类型分类的目录集合”,而是一个具有入口、输入和副作用的可调用组件。tasks/main.yml 是默认执行入口;任务需要触发延迟动作时通知 handlers/main.yml;动态配置由 templates/ 提供,静态文件放入 files/。
变量也要按职责拆分:defaults/main.yml 放调用方通常允许覆盖的默认参数,vars/main.yml 只放不希望调用方依赖的实现变量;meta/ 则描述角色元数据、依赖或参数规格。不是每个 Role 都必须使用全部目录,空目录没有教学或工程价值时可以省略。

建立最小目录骨架
先创建一个只包含当前职责需要的目录。下面的命令不会自动写业务任务,只验证骨架是否按预期建立。
# 只创建本课需要验证的标准目录,不预填业务实现。
rm -rf role-demo
mkdir -p role-demo/roles/web_server/{tasks,handlers,templates,files,defaults,vars,meta}
test -d role-demo/roles/web_server/tasks && test -d role-demo/roles/web_server/templates && test -d role-demo/roles/web_server/handlers && printf 'role skeleton ok\n'预期输出:
role skeleton ok真实项目也可以用 ansible-galaxy role init 生成标准骨架,再删除不需要的空目录。关键不是目录越全越好,而是一个文件只能承担与目录语义一致的职责。
用一个配置变更串起目录职责
下面是一个完整的最小 Role。tasks/main.yml 只描述“生成配置”这个动作,并通过 notify 把变化后的响应交给 handler。
片段示例,保存为 roles/web_server/tasks/main.yml:
- name: Render web server configuration
ansible.builtin.template:
src: nginx.conf.j2
dest: /tmp/web-server.conf
mode: "0644"
# 只有模板真正改变时才触发后续响应。
notify: Record configuration change片段示例,保存为 roles/web_server/handlers/main.yml:
- name: Record configuration change
# 生产角色通常在这里执行 service reload 或 restart。
ansible.builtin.debug:
msg: "web_server configuration changed"片段示例,保存为 roles/web_server/templates/nginx.conf.j2:
worker_processes {{ web_server_workers | default(2) }};再用一个 Playbook 调用这个 Role。这里使用本机和 /tmp,避免依赖 root 权限。
- name: Verify web_server role
hosts: localhost
# 本机连接让示例不依赖额外测试主机。
connection: local
gather_facts: false
roles:
- role: web_server将它保存为 site.yml 后执行:
cd role-demo
# 先删除旧文件,确保本次执行能观察到一次真实变更。
rm -f /tmp/web-server.conf
ansible-playbook -i localhost, site.yml >/dev/null
cat /tmp/web-server.conf预期输出:
worker_processes 2;第一次生成文件时 task 状态会发生变化,因此 handler 会被通知;再次执行且模板内容不变时,template 保持幂等,handler 也不会再次触发。实际的 Ansible 任务统计会因环境而不同,所以这里用最终文件内容作为稳定的验收结果。
划清 Role 的职责边界
一个 Role 最好只对一个稳定能力负责,例如“配置 Nginx”“部署 node_exporter”或“创建应用系统用户”。如果同一个 Role 同时安装数据库、创建业务账号、部署应用并修改防火墙,它实际上包含了多个独立生命周期,复用和测试都会变得困难。
环境差异也不应写死在 Role 内部。主机地址、端口、实例数量、证书路径等应通过变量接口传入;密钥和密码更不应放进 vars/main.yml。files/ 与 templates/ 只保存该 Role 自己拥有的素材,不要让调用方直接依赖它们的内部路径。
当调用方只需要知道“这个 Role 能做什么、需要哪些输入”,而不需要理解内部 task 文件如何拆分时,职责边界才算设计成功。