基础设施即代码 / 系统课时
理解变量优先级
理解变量优先级
Ansible 允许同一个变量从 Inventory、group_vars、Play、Role、任务甚至命令行进入运行时。真正容易出错的不是“变量能不能定义”,而是同名变量最终取哪一个值。本课用一组最小实验建立可预测的覆盖模型,并给出定位冲突的方法。
学习目标
- 识别常见变量来源及其大致优先级关系
- 预测同名变量在一次 Play 执行中的最终取值
- 用最小实验验证变量覆盖,而不是靠猜测排查
先建立覆盖模型
变量优先级不是简单的“配置文件越靠后越高”。Ansible 会先按变量来源类别决定优先级,再结合变量作用域和具体加载位置合并数据。实践中可以先记住这条主线:Role 默认值适合提供兜底,Inventory 负责环境和主机差异,Play 与任务变量表达当前自动化意图,而 --extra-vars 用于显式覆盖。
常见来源从低到高可按下面的实用顺序理解。它不是把 Ansible 所有细分类别压成一条完整规范表,而是用于日常排错的主干:
| 常见来源 | 典型用途 | 覆盖特征 |
|---|---|---|
Role defaults |
可被用户覆盖的默认值 | 很低,适合兜底 |
Inventory / group_vars |
环境级、组级配置 | 可覆盖 Role 默认值 |
host_vars |
单主机差异 | 通常高于组级变量 |
| Facts | 主机运行时信息 | 可被更高层显式变量覆盖 |
Play vars、vars_files、Role vars |
当前 Play 或 Role 的强约束 | 高于多数 Inventory 变量 |
Block / Task 变量、include_vars、set_fact、注册变量 |
当前执行路径中的动态值 | 优先级较高 |
| Role / include 参数 | 调用 Role 或 include 时传入 | 用于调用点覆盖 |
--extra-vars |
人工或流水线强制注入 | 变量来源中最高 |

用最小实验观察覆盖
下面让同一个 app_port 同时出现在 Inventory、group_vars 和 Play 中。Inventory 文件:
[web]
web01 ansible_connection=local app_port=8000group_vars/all.yml:
app_port: 8080Playbook precedence.yml:
- name: Check variable precedence
hosts: web
gather_facts: false
vars:
# Play 变量用于表达这次运行的期望值。
app_port: 9000
tasks:
- name: Show effective port
ansible.builtin.debug:
msg: "app_port={{ app_port }}"先不传额外变量运行:
ansible-playbook -i inventory.ini precedence.yml预期输出中,回调格式可能随 Ansible 配置不同,但最终值应为:
ok: [web01] => {
"msg": "app_port=9000"
}这里 Play 变量覆盖了 Inventory 与 group_vars 中的同名值。再用 --extra-vars 强制覆盖:
ansible-playbook -i inventory.ini precedence.yml -e 'app_port=10000'预期输出:
ok: [web01] => {
"msg": "app_port=10000"
}这次 --extra-vars 获胜。重点不是记住示例中的三个数字,而是确认“同名变量从多个来源进入时,最终值由来源优先级决定”。
排查同名变量冲突
遇到“明明改了变量却没生效”,先缩小变量来源范围。ansible-inventory 适合查看 Inventory 合并后的主机变量,但它看不到之后在 Play、任务或 --extra-vars 中发生的全部覆盖。
ansible-inventory -i inventory.ini --host web01预期输出至少会包含 Inventory 阶段可见的变量;具体字段顺序可能不同:
{
"ansible_connection": "local",
"app_port": 8000
}这里能看到主机级 Inventory 变量 8000 高于 group_vars/all.yml 的组级值 8080。如果运行 Playbook 时又变成 9000,覆盖就发生在 Inventory 之后的来源。继续检查 Play vars、vars_files、Role 变量、任务级变量、set_fact 和运行命令中的 -e,通常能很快找到覆盖点。
变量优先级的真正价值,是让自动化结果可预测:默认值负责兜底,Inventory 描述环境,Play 和任务表达本次执行意图,--extra-vars 只承担明确的最终覆盖。