ansible.builtin.include_vars – Load variables from files, dynamically within a task
Note
This module is part of ansible-core
and included in all Ansible
installations. In most cases, you can use the short
module name
include_vars
even without specifying the collections:
keyword.
However, we recommend you use the FQCN for easy linking to the
module documentation and to avoid conflicting with other collections that may have
the same module name.
New in version 1.4: of ansible.builtin
Synopsis
Loads YAML/JSON variables dynamically from a file or directory, recursively, during task runtime.
If loading a directory, the files are sorted alphabetically before being loaded.
This module is also supported for Windows targets.
To assign included variables to a different host than
inventory_hostname
, usedelegate_to
and setdelegate_facts=yes
.
Note
This module has a corresponding action plugin.
Parameters
Parameter |
Comments |
---|---|
When using Default: 0 |
|
The directory name from which the variables should be loaded. If the path is relative and the task is inside a role, it will look inside the role’s vars/ subdirectory. If the path is relative and not inside a role, it will be parsed relative to the playbook. |
|
List of file extensions to read when using Default: [“json”, “yaml”, “yml”] |
|
The file name from which variables should be loaded. If the path is relative, it will look for the file in vars/ subdirectory of a role or relative to playbook. |
|
Limit the files that are loaded within any directory to this regular expression. |
|
This module allows you to specify the ‘file’ option directly without any other options. There is no ‘free-form’ option, this is just an indicator, see example below. |
|
List of file names to ignore. |
|
Ignore unknown file extensions within the directory. This allows users to specify a directory containing vars files that are intermingled with non-vars files extension types (e.g. a directory with a README in it and vars files). Choices:
|
|
The name of a variable into which assign the included vars. If omitted (null) they will be made top level vars. |
See Also
See also
- ansible.builtin.set_fact
The official documentation on the ansible.builtin.set_fact module.
- Controlling where tasks run: delegation and local actions
More information related to task delegation.
Examples
- name: Include vars of stuff.yaml into the 'stuff' variable (2.2).
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)
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.
include_vars: "{{ lookup('first_found', params) }}"
vars:
params:
files:
- '{{ansible_distribution}}.yaml'
- '{{ansible_os_family}}.yaml'
- default.yaml
paths:
- 'vars'
- name: Bare include (free-form)
include_vars: myvars.yaml
- name: Include all .json and .jsn files in vars/all and all nested directories (2.3)
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)
include_vars:
dir: vars/all
name: test
- name: Include default extension files in vars/services (2.2)
include_vars:
dir: vars/services
depth: 1
- name: Include only files matching bastion.yaml (2.2)
include_vars:
dir: vars
files_matching: bastion.yaml
- name: Include all .yaml files except bastion.yaml (2.3)
include_vars:
dir: vars
ignore_files:
- 'bastion.yaml'
extensions:
- 'yaml'
- name: Ignore warnings raised for files with unknown extensions while loading (2.7)
include_vars:
dir: vars
ignore_unknown_extensions: True
extensions:
- ''
- 'yaml'
- 'yml'
- 'json'
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
---|---|
A list of files that were successfully included Returned: success Sample: [“/path/to/file.json”, “/path/to/file.yaml”] |
Authors
Allen Sanabria (@linuxdynasty)