ansible.builtin.include_vars 模块 – 在任务中动态加载文件中的变量

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使没有指定 collections 关键字，您也可以使用简短的模块名称 include_vars。但是，我们建议您使用完全限定的集合名称 (FQCN) ansible.builtin.include_vars，以便轻松链接到模块文档并避免与可能具有相同模块名称的其他集合发生冲突。

摘要 

在任务运行时，从文件或目录（递归）中动态加载 YAML/JSON 变量。
如果加载目录，则在加载之前按字母顺序对文件进行排序。
此模块也支持 Windows 目标。
要将包含的变量分配给与 inventory_hostname 不同的主机，请使用 delegate_to 并设置 delegate_facts=yes。

注意

此模块具有相应的 action 插件。

参数 

参数	注释
depth 整数	使用 `dir` 时，此模块默认情况下会递归遍历每个子目录并加载变量。通过显式设置深度，此模块只会深入到指定的深度。默认值： `0`
dir 路径	应从中加载变量的目录名称。如果路径是相对路径并且任务位于角色内部，它将在角色的 `vars/` 子目录中查找。如果路径是相对路径且不在角色内部，则将相对于 playbook 进行解析。
extensions 列表 / 元素=字符串	使用 `dir` 时要读取的文件扩展名列表。默认值： `["json", "yaml", "yml"]`
file 路径	应从中加载变量的文件名。如果路径是相对路径，它将在角色的 `vars/` 子目录中或相对于 playbook 查找文件。
files_matching 字符串	将任何目录中加载的文件限制为此正则表达式。
自由格式字符串	此模块允许您直接指定 `file` 选项，而无需任何其他选项。没有 `free-form` 选项，这只是一个指示器，请参见下面的示例。
hash_behaviour 字符串在 ansible-core 2.12 中添加	如果设置为 `merge`，则合并现有的哈希变量，而不是覆盖它们。如果省略（`null`），则行为将回退到全局 `hash_behaviour` 配置。此选项是独立的，不适用于 `dir` 中的单个文件。您可以使用循环为每个文件应用 `hash_behaviour`。选择 `"replace"` `"merge"`
ignore_files 列表 / 元素=字符串	要忽略的文件名列表。
ignore_unknown_extensions 布尔值在 Ansible 2.7 中添加	忽略目录中未知的文件扩展名。这允许用户指定一个包含变量文件的目录，这些变量文件与非变量文件扩展名类型混合在一起（例如，包含自述文件和变量文件的目录）。选择 `false` ← (默认) `true`
name 字符串	要将包含的变量分配到的变量的名称。如果省略（`null`），则它们将成为顶级变量。

属性 

属性	支持	描述
action	支持：部分虽然 action 插件确实执行了一些工作，但它依赖于核心引擎来实际创建变量，这部分无法被覆盖	指示这有一个对应的 action 插件，因此某些选项部分可以在控制器上执行
async	支持：不支持	支持与 `async` 关键字一起使用
become	支持：不支持	可与 become 关键字一起使用
bypass_host_loop	支持：不支持	强制执行不按主机执行的“全局”任务，这绕过按主机模板化以及序列、节流和其他循环考虑因素条件将按使用 `run_once` 的方式工作，使用的变量将来自第一个可用的主机此操作在非锁步策略之外无法正常工作
bypass_task_loop	支持：不支持	这些任务会忽略 `loop` 和 `with_` 关键字
check_mode	支持：完全	可以在 check_mode 下运行并返回更改状态预测，而无需修改目标，如果不支持，则操作将被跳过。
connection	支持：不支持	使用目标的配置连接信息在其上执行代码
core	支持：部分虽然此操作的部分内容是在核心代码中实现的，但其他部分仍然可以作为正常的插件使用，并且可以被部分覆盖	这是一个“核心引擎”功能，其实现方式与大多数任务操作不同，因此无法通过插件系统以任何方式覆盖。
delegation	支持：部分虽然变量分配可以委托给不同的主机，但执行上下文始终是当前的 inventory_hostname 连接变量（如果设置）将反映它将定位的主机，即使在这种情况下我们根本没有连接	可以与 delegate_to 和相关关键字结合使用
diff_mode	支持：不支持	在 diff 模式下，将返回有关已更改内容（或可能需要在 check_mode 下更改的内容）的详细信息
ignore_conditional	支持：不支持	操作不受条件执行的影响，因此它将忽略 `when:` 关键字
平台	支持的平台：所有	可以操作的目标操作系统/系列
标签	支持：完全	允许使用“tags”关键字控制此操作的选择以执行
until	支持：完全	表示此操作是否服从 until/retry/poll 关键字

另请参见 

另请参阅

ansible.builtin.set_fact: 设置主机变量和事实。
控制任务运行的位置：委托和本地操作: 与任务委托相关的更多信息。

示例 

- name: Include vars of stuff.yaml into the 'stuff' variable (2.2).
  ansible.builtin.include_vars:
    file: stuff.yaml
    name: stuff

- name: Conditionally decide to load in variables into 'plans' when x is 0, otherwise do not. (2.2)
  ansible.builtin.include_vars:
    file: contingency_plan.yaml
    name: plans
  when: x == 0

- name: Load a variable file based on the OS type, or a default if not found. Using free-form to specify the file.
  ansible.builtin.include_vars: "{{ lookup('ansible.builtin.first_found', params) }}"
  vars:
    params:
      files:
        - '{{ansible_distribution}}.yaml'
        - '{{ansible_os_family}}.yaml'
        - default.yaml
      paths:
        - 'vars'

- name: Bare include (free-form)
  ansible.builtin.include_vars: myvars.yaml

- name: Include all .json and .jsn files in vars/all and all nested directories (2.3)
  ansible.builtin.include_vars:
    dir: vars/all
    extensions:
      - 'json'
      - 'jsn'

- name: Include all default extension files in vars/all and all nested directories and save the output in test. (2.2)
  ansible.builtin.include_vars:
    dir: vars/all
    name: test

- name: Include default extension files in vars/services (2.2)
  ansible.builtin.include_vars:
    dir: vars/services
    depth: 1

- name: Include only files matching bastion.yaml (2.2)
  ansible.builtin.include_vars:
    dir: vars
    files_matching: bastion.yaml

- name: Include all .yaml files except bastion.yaml (2.3)
  ansible.builtin.include_vars:
    dir: vars
    ignore_files:
      - 'bastion.yaml'
    extensions:
      - 'yaml'

- name: Ignore warnings raised for files with unknown extensions while loading (2.7)
  ansible.builtin.include_vars:
    dir: vars
    ignore_unknown_extensions: True
    extensions:
      - ''
      - 'yaml'
      - 'yml'
      - 'json'

返回值 

常见的返回值已记录在此处，以下是此模块特有的字段

键	描述
ansible_included_var_files 列表 / 元素=字符串	成功包含的文件列表返回值：成功示例： `["/path/to/file.json", "/path/to/file.yaml"]`

作者

Allen Sanabria (@linuxdynasty)