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。

注意

此模块具有相应的操作插件。

参数 

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

属性 

属性	支持	描述
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	支持: 无	在差异模式下，将返回有关已更改内容（或在 check_mode 中可能需要更改的内容）的详细信息
ignore_conditional	支持: 无	该操作不受条件执行的约束，因此它会忽略 `when:` 关键字
platform	平台: 全部	可以对其进行操作的目标操作系统/系列
tags	支持: 完全	允许使用“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 list / elements=string	成功包含的文件列表返回：成功示例： `["/path/to/file.json", "/path/to/file.yaml"]`

作者

Allen Sanabria (@linuxdynasty)