include_vars – Load variables from files, dynamically within a task
include_vars – Load variables from files, dynamically within a task
New in version 1.4.
Synopsis
- Loads variables from a YAML/JSON files dynamically from within a file or from a 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.
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
depth - added in 2.2 |
Default: 0 |
When using |
dir - added in 2.2 |
The directory name from which the 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. | |
extensions - added in 2.3 |
Default: ["yaml", "yml", "json"] |
List of file extensions to read when using |
file - 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 - 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 - added in 2.2 |
List of file names to ignore. | |
ignore_unknown_extensions - added in 2.7 |
Default: "no" |
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 (For example, a directory with a README in it and vars files) |
name - 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.
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: "{{ item }}"
with_first_found:
- "{{ 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]
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.yaml', '/path/to/file.json'] |
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.7/modules/include_vars_module.html