include_vars – Load variables from files, dynamically within a task
include_vars – Load variables from files, dynamically within a task
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
.
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
depth integer added in 2.2 |
Default: 0 |
When using |
dir path added in 2.2 |
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. | |
extensions list added in 2.3 |
Default: ["json", "yaml", "yml"] |
List of file extensions to read when using |
file path added in 2.2 |
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. | |
files_matching string added in 2.2 |
Limit the files that are loaded within any directory to this regular expression. | |
free-form - |
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. | |
ignore_files list added in 2.2 |
List of file names to ignore. | |
ignore_unknown_extensions boolean added in 2.7 |
|
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). |
name string added in 2.2 |
The name of a variable into which assign the included vars. If omitted (null) they will be made top level vars. |
Notes
Note
- This module is also supported for Windows targets.
See Also
See also
- set_fact – Set host facts from a task
- The official documentation on the set_fact module.
- Delegation, Rolling Updates, 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', possible_files) }}"
vars:
possible_files:
- "{{ ansible_distribution }}.yaml"
- "{{ ansible_os_family }}.yaml"
- default.yaml
- 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 | Returned | Description |
---|---|---|
ansible_included_var_files list added in 2.4 |
success |
A list of files that were successfully included
Sample: ['/path/to/file.json', '/path/to/file.yaml'] |
Status
- This module is guaranteed to have no backward incompatible interface changes going forward. [stableinterface]
- This module is maintained by the Ansible Core Team. [core]
Red Hat Support
More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.
Authors
- Allen Sanabria (@linuxdynasty)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/include_vars_module.html