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。

注意

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

参数 

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

属性 

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