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

复用 Include 与 Import

复用 Include 与 Import

当任务文件或角色开始拆分后,真正容易踩坑的不是“怎么引用”,而是“什么时候展开”。本课用一个可运行实验对比动态 include 与静态 import,帮助你按运行时条件、循环需求和可预览性选择正确的复用方式。

学习目标

  • 解释 include_* 与 import_* 在展开时机上的根本差异。
  • 根据运行时变量、循环、标签和任务可见性选择合适方式。
  • 用最小 Playbook 验证静态导入与动态包含的实际执行结果。

先看两种复用的展开时机

ansible.builtin.include_tasks、ansible.builtin.include_role 属于动态复用:Ansible 执行到这条任务时,才决定要加载哪个任务文件或角色。因此,前面任务刚写入的事实、注册结果或循环项都可以参与选择。

ansible.builtin.import_tasks、ansible.builtin.import_role 属于静态复用:Ansible 在真正执行任务前先展开内容,后续执行看到的已经是导入后的任务。完整 Playbook 也只能通过 ansible.builtin.import_playbook 静态复用,没有对应的动态 include_playbook。

Include 与 Import 的展开时机

两者的核心差异可以压缩成下面几项:

关注点 include_* import_*
展开时机 执行到该任务时 Playbook 执行前
运行时选择文件 适合 不适合
循环复用 include_tasks、include_role 可配合循环 不用于循环导入
标签传播 默认只标记 include 本身;需要时用 apply 等方式传给内部任务 标签会应用到导入后的任务
--list-tasks / --list-tags 动态内容通常无法在预处理阶段完整列出 导入后的内容可提前看到

用同一变量观察静态与动态结果

下面的实验先把 task_file 定义为 one.yml,运行时再用 set_fact 改成 two.yml。静态 import 在运行前已经解析文件名,而动态 include 会读取运行到该位置时的最新变量值。

bash
mkdir -p /tmp/ansible-reuse
cd /tmp/ansible-reuse

cat > one.yml <<'YAML'
- name: Message from one
  ansible.builtin.debug:
    msg: "loaded one.yml"
YAML

cat > two.yml <<'YAML'
- name: Message from two
  ansible.builtin.debug:
    msg: "loaded two.yml"
YAML

cat > site.yml <<'YAML'
- name: Compare import and include timing
  hosts: localhost
  gather_facts: false
  vars:
    task_file: one.yml
  tasks:
    - name: Change task file at runtime
      ansible.builtin.set_fact:
        task_file: two.yml

    - name: Static import resolved before task execution
      ansible.builtin.import_tasks: "{{ task_file }}"

    - name: Dynamic include resolved when reached
      ansible.builtin.include_tasks: "{{ task_file }}"
YAML

ansible-playbook -i localhost, -c local site.yml

预期输出中,静态导入仍执行 one.yml,动态包含则加载 two.yml。不同 ansible-core 版本的任务横幅格式可能略有差异,但关键消息应一致:

text
TASK [Change task file at runtime] ********************************
ok: [localhost]

TASK [Message from one] *******************************************
ok: [localhost] => {
    "msg": "loaded one.yml"
}

TASK [Dynamic include resolved when reached] **********************
included: /tmp/ansible-reuse/two.yml for localhost

TASK [Message from two] *******************************************
ok: [localhost] => {
    "msg": "loaded two.yml"
}

这个结果说明:import 决定“任务图长什么样”,include 决定“运行到这里时再装入什么”。如果被引用文件名依赖前面任务产生的值,应优先考虑动态 include。

条件、循环与标签的边界

条件也会因展开方式不同而产生不同语义。条件写在 import_tasks 上时,会作用到导入后的各个任务;如果其中某个任务改变了条件依赖的变量,后续导入任务再次判断时可能得到不同结果。条件写在 include_tasks 上时,先决定这一刻是否执行包含动作,只有通过后才装入内部任务。

循环是动态 include 最典型的使用场景,例如按多个实例参数重复包含同一组任务。反过来,如果你希望 ansible-playbook --list-tasks、--list-tags 或 --start-at-task 尽可能看到稳定、完整的任务结构,静态 import 更合适。

按复用意图做选择

需要根据运行时事实、注册结果或循环项决定“加载什么”时,选择 include_tasks 或 include_role;被复用内容固定、希望任务在执行前完全展开时,选择 import_tasks 或 import_role;拆分完整 Playbook 时使用 import_playbook。

实际维护中,先问自己一句“这个引用目标能否在执行前确定”。能确定且希望任务结构透明,就偏向 import;必须等运行时才能决定,就使用 include。这样比记忆一长串语法差异更可靠。

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

目录与阅读设置

阅读设置

17

记录一个想法

复用 Include 与 Import

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

登录哪都通