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

设计 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 变量接口与覆盖关系

设计一组最小公共参数

假设 Role 名为 app_banner,它只负责生成一个文本文件。公共变量统一加上 app_banner_ 前缀,既能降低与其他 Role 的变量冲突,也让调用方一眼看出变量归属。

片段示例,保存为 roles/app_banner/defaults/main.yml:

yaml
# 这两个变量构成调用方可依赖的公共输入。
app_banner_message: "managed by Ansible"
app_banner_path: "/tmp/app-banner.txt"

内部实现变量放在 roles/app_banner/vars/main.yml,并且不把它写进对外文档:

yaml
# 仅服务当前实现,不作为公开调用契约。
app_banner_content_prefix: "[managed]"

任务只消费最终解析后的变量,不关心它们来自 defaults、inventory 还是调用参数。保存为 roles/app_banner/tasks/main.yml:

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

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

yaml
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 的项目目录执行:

bash
# 删除旧结果后重新执行,便于稳定验收最终内容。
rm -f /tmp/app-banner.txt
ansible-playbook -i localhost, site.yml >/dev/null
cat /tmp/app-banner.txt

预期输出:

text
[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 变量接口应当具备三个特征:有合理默认值、名称清晰且可验证、内部实现可以变化而调用方式基本不变。

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

目录与阅读设置

阅读设置

17

记录一个想法

设计 Role 的变量接口

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

登录哪都通