基础设施即代码 / 系统课时
设计 Role 的变量接口
设计 Role 的变量接口
Role 能否复用,关键不在于变量数量,而在于调用方是否只依赖一组稳定、可覆盖的输入。本课用 defaults、vars 与参数规格设计一个小型变量接口,并验证调用方覆盖默认值时的实际效果。
学习目标
- 用
defaults/main.yml暴露可配置参数,并理解它为何适合作为 Role 的公共入口。 - 控制
vars/main.yml的使用范围,避免高优先级内部变量阻塞常见覆盖方式。 - 通过命名约定和参数校验减少调用方对 Role 内部实现的依赖。
先区分公共输入与内部实现
defaults/main.yml 的变量优先级很低,适合表达“没有外部输入时采用什么值”。调用方可以用 inventory、play 变量、Role 参数或更高优先级来源覆盖它,因此它天然适合做公共接口。
vars/main.yml 的优先级高于 Role defaults,也高于很多常见的 inventory 与 play 变量来源。把用户本应修改的端口、路径或开关放进这里,会导致调用方明明设置了变量却没有生效。它更适合保存内部实现细节,而且即使放在这里也不能把它当作绝对不可覆盖的常量。

设计一组最小公共参数
假设 Role 名为 app_banner,它只负责生成一个文本文件。公共变量统一加上 app_banner_ 前缀,既能降低与其他 Role 的变量冲突,也让调用方一眼看出变量归属。
片段示例,保存为 roles/app_banner/defaults/main.yml:
# 这两个变量构成调用方可依赖的公共输入。
app_banner_message: "managed by Ansible"
app_banner_path: "/tmp/app-banner.txt"内部实现变量放在 roles/app_banner/vars/main.yml,并且不把它写进对外文档:
# 仅服务当前实现,不作为公开调用契约。
app_banner_content_prefix: "[managed]"任务只消费最终解析后的变量,不关心它们来自 defaults、inventory 还是调用参数。保存为 roles/app_banner/tasks/main.yml:
- name: Write application banner
ansible.builtin.copy:
# task 只消费解析后的变量,不绑定变量来源。
content: "{{ app_banner_content_prefix }} {{ app_banner_message }}\n"
dest: "{{ app_banner_path }}"
mode: "0644"调用方只覆盖真正属于接口的 app_banner_message:
- name: Verify app_banner role
hosts: localhost
connection: local
gather_facts: false
roles:
# Role 参数覆盖 defaults 中的同名默认值。
- role: app_banner
app_banner_message: "production banner"给公共变量加参数规格
仅有命名约定还不够。Role 可以在 meta/argument_specs.yml 中声明公开参数的类型和说明,让错误输入在执行具体 task 之前更早暴露。
片段示例,保存为 roles/app_banner/meta/argument_specs.yml:
argument_specs:
main:
short_description: Create an application banner file
# 只声明稳定的公共输入,不暴露内部变量。
options:
app_banner_message:
type: str
required: false
app_banner_path:
type: str
required: false这里故意没有声明 app_banner_content_prefix,因为它是实现细节而不是调用契约。参数规格负责校验接口,不应该把所有内部变量都公开出去。
验证覆盖结果
把前面的调用 Playbook 保存为 site.yml,然后在包含 roles/app_banner 的项目目录执行:
# 删除旧结果后重新执行,便于稳定验收最终内容。
rm -f /tmp/app-banner.txt
ansible-playbook -i localhost, site.yml >/dev/null
cat /tmp/app-banner.txt预期输出:
[managed] production banner结果表明,Role 默认值 managed by Ansible 已被调用方提供的 production banner 覆盖,而内部前缀仍由 Role 自己维护。实际 Playbook 的任务统计会因环境和重复执行次数不同,因此验收应关注最终文件内容。
避免变量接口逐渐失控
公共变量应该描述业务意图,而不是泄露内部 task 结构。与其让调用方设置 app_banner_copy_task_mode、app_banner_template_src 这类实现细节,不如提供 app_banner_path、app_banner_message 这类稳定参数;内部换用 template 或 copy 时,调用方无需修改。
需要组合多个值时,也应优先在 Role 内部计算,而不是要求调用方同步维护多个彼此依赖的变量。若某个变量是秘密信息,应使用 Ansible Vault 或外部秘密管理系统,而不是因为它位于 vars/main.yml 就认为已经受保护。
稳定的 Role 变量接口应当具备三个特征:有合理默认值、名称清晰且可验证、内部实现可以变化而调用方式基本不变。