运行上下文变量
Ansible 会自动提供一组描述运行上下文的特殊变量，俗称魔法变量：当前主机名、清单分组、主机变量字典、本 play 涉及的主机列表、当前批次等。它们不需要定义就能引用，是编排逻辑的骨架，做条件判断、生成集群配置、在模板里取别的主机信息都要用。使用前提是清楚它们按什么范围求值，否则在批处理与委派场景里会拿到意料之外的值。
基本信息
| 常用变量 | inventory_hostname、hostvars、groups、group_names、ansible_play_hosts、ansible_play_batch |
|---|---|
| 其他常用 | ansible_host、ansible_facts、ansible_check_mode、role_path |
| 求值范围 | 多数按主机求值，play 级列表在整个 play 内一致 |
| 覆盖限制 | 普通赋值不会覆盖魔法变量 |
典型使用场景
- 生成集群成员清单：模板里遍历本 play 的主机列表，而不是把成员写死在变量里
- 生成含其他节点地址的配置：用主机变量字典取目标主机的连接地址或事实
- 滚动发布时区分当前批次：引用批次变量决定跳过还是执行
- 演练模式下给出提示或跳过不可预演的任务：引用检查模式标志
- 角色内部引用自身目录下的文件路径：用角色路径变量拼接
常见用法
常见用法
- name: 列出本 play 中的全部主机 # 运行时按清单求值
ansible.builtin.debug:
msg: "{{ ansible_play_hosts }}"
- name: 取另一台主机的变量 # 主机变量字典按主机名索引
ansible.builtin.debug:
msg: "{{ hostvars[groups['db'][0]].ansible_host }}"
- name: 只在演练模式打印提示 # 检查模式标志
ansible.builtin.debug:
msg: "check mode"
when: ansible_check_mode变量与常见误用
| 变量 | 含义 | 常见误用 |
|---|---|---|
| inventory_hostname | 清单中的主机名 | 当成可路由地址，实际地址在 ansible_host |
| hostvars | 各主机的变量与事实 | 取未采集主机的事实得到未定义值 |
| groups | 分组到主机名的映射 | 分组名拼错时不报错，只在引用处失败 |
| ansible_play_hosts | 本 play 当前仍可执行的主机 | 与整个清单的主机混为一谈 |
| ansible_play_batch | 当前批次的主机 | 非滚动执行时误以为有多个批次 |
魔法变量在运行时计算，没法在变量文件里预先定义一份固定值。要一份稳定的集群成员清单，就用显式变量或运行期赋值，别依赖瞬时求值的结果。
主机变量字典里其他主机的事实，要在那台主机执行过采集之后才存在。只对部分主机执行 play 时引用未采集主机的事实会报未定义，需要先补采集或改用显式变量。
配合限定与委派
用限定参数圈定主机后，play 主机列表只包含被圈定的机器，而分组映射仍反映清单全貌，两者含义不同：前者是这次要操作的集合，后者是清单里定义的集合。在委派任务里，当前主机名仍指向被委派的那台机器，生成本机地址这类内容前先确认需要的是哪一边。