基础设施即代码 / 系统课时

设计 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 都必须使用全部目录,空目录没有教学或工程价值时可以省略。

Role 目录与职责分工

建立最小目录骨架

先创建一个只包含当前职责需要的目录。下面的命令不会自动写业务任务,只验证骨架是否按预期建立。

bash
# 只创建本课需要验证的标准目录,不预填业务实现。
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'

预期输出:

text
role skeleton ok

真实项目也可以用 ansible-galaxy role init 生成标准骨架,再删除不需要的空目录。关键不是目录越全越好,而是一个文件只能承担与目录语义一致的职责。

用一个配置变更串起目录职责

下面是一个完整的最小 Role。tasks/main.yml 只描述“生成配置”这个动作,并通过 notify 把变化后的响应交给 handler。

片段示例,保存为 roles/web_server/tasks/main.yml:

yaml
- 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:

yaml
- name: Record configuration change
  # 生产角色通常在这里执行 service reload 或 restart。
  ansible.builtin.debug:
    msg: "web_server configuration changed"

片段示例,保存为 roles/web_server/templates/nginx.conf.j2:

text
worker_processes {{ web_server_workers | default(2) }};

再用一个 Playbook 调用这个 Role。这里使用本机和 /tmp,避免依赖 root 权限。

yaml
- name: Verify web_server role
  hosts: localhost
  # 本机连接让示例不依赖额外测试主机。
  connection: local
  gather_facts: false
  roles:
    - role: web_server

将它保存为 site.yml 后执行:

bash
cd role-demo
# 先删除旧文件,确保本次执行能观察到一次真实变更。
rm -f /tmp/web-server.conf
ansible-playbook -i localhost, site.yml >/dev/null
cat /tmp/web-server.conf

预期输出:

text
worker_processes 2;

第一次生成文件时 task 状态会发生变化,因此 handler 会被通知;再次执行且模板内容不变时,template 保持幂等,handler 也不会再次触发。实际的 Ansible 任务统计会因环境而不同,所以这里用最终文件内容作为稳定的验收结果。

划清 Role 的职责边界

一个 Role 最好只对一个稳定能力负责,例如“配置 Nginx”“部署 node_exporter”或“创建应用系统用户”。如果同一个 Role 同时安装数据库、创建业务账号、部署应用并修改防火墙,它实际上包含了多个独立生命周期,复用和测试都会变得困难。

环境差异也不应写死在 Role 内部。主机地址、端口、实例数量、证书路径等应通过变量接口传入;密钥和密码更不应放进 vars/main.yml。files/ 与 templates/ 只保存该 Role 自己拥有的素材,不要让调用方直接依赖它们的内部路径。

当调用方只需要知道“这个 Role 能做什么、需要哪些输入”,而不需要理解内部 task 文件如何拆分时,职责边界才算设计成功。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计 Role 目录与职责边界

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通