Ansible 角色 Roles：结构化复用

摘要：playbook 变长之后必须拆。本文讲清 role 的标准目录结构、用 ansible-galaxy init 生成骨架、defaults/vars 的区别，以及如何在多个 playbook 中复用同一个 role。

适用环境

• 已安装 ansible-core 或 ansible
• 已完成 inventory 与 SSH 免密配置
• 有一个想拆分的现成 playbook

操作步骤

1. 生成标准骨架

cd ~/ansible && ansible-galaxy init roles/nginx

roles/nginx/
├── defaults/main.yml   # 默认变量，优先级最低，最容易被覆盖
├── vars/main.yml       # role 内部变量，优先级高
├── tasks/main.yml      # 主任务入口
├── handlers/main.yml   # 处理器
├── templates/          # Jinja2 模板
└── meta/main.yml       # 依赖声明

目录都是可选的，只建需要的。

2. 填充内容

# defaults/main.yml
nginx_port: 80
# tasks/main.yml
- name: Install nginx
  ansible.builtin.package: { name: nginx, state: present }
- name: Deploy site config
  ansible.builtin.template:
    src: site.conf.j2
    dest: /etc/nginx/conf.d/site.conf
    validate: 'nginx -t -c %s'
  notify: reload nginx
# handlers/main.yml
- name: reload nginx
  ansible.builtin.service: { name: nginx, state: reloaded }

3. 调用并覆盖变量

- hosts: web
  become: true
  roles:
    - role: nginx
      nginx_port: 8080      # 覆盖 defaults 里的值
    - common

4. 声明依赖与跨项目复用

# meta/main.yml
dependencies:
  - role: nginx             # 执行本 role 之前先跑 nginx

cat > requirements.yml <<'EOF'
- src: https://github.com/geerlingguy/ansible-role-nginx
  name: nginx
  version: v1.1.0           # 必须固定版本
EOF
ansible-galaxy install -r requirements.yml

外部 role 未固定版本等于把生产交给上游

不指定 version 时上游一改你的生产就变了，且不可追溯。必须用 tag 或 commit 锁定。

验证

ansible-playbook -i inventory.ini site.yml --syntax-check
ansible-playbook -i inventory.ini site.yml --list-tasks

• [ ] 只改 playbook 里的变量就能改变 role 行为，无需改 role 代码
• [ ] 同一个 role 能被两个不同 playbook 同时引用

常见坑

defaults 与 vars 放反

想让调用方覆盖的放 defaults/main.yml；role 内部固定的放 vars/main.yml。放反会出现「传了变量却没生效」。

handler 同名冲突

多个 role 定义同名 handler 时只会执行其中一个。给 handler 名加前缀，如 nginx reload。

roles 总是先于 tasks 执行

想控制顺序就只用 tasks + include_role。

参考资料

• Ansible Roles 官方文档
• Ansible 变量优先级说明
• Ansible Galaxy 使用指南