ansible.builtin.include module – Include a play or task list

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 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 0.6: of ansible.builtin

DEPRECATED

Removed in

version 2.16

Why

it has too many conflicting behaviours depending on keyword combinations and it was unclear how it should behave in each case. new actions were developed that were specific about each case and related behaviours.

Alternative

include_tasks, import_tasks, import_playbook

Synopsis

  • Includes a file with a list of plays or tasks to be executed in the current playbook.

  • Files with a list of plays can only be included at the top level. Lists of tasks can only be included where tasks normally run (in play).

  • Before Ansible 2.0, all includes were ‘static’ and were executed when the play was compiled.

  • Static includes are not subject to most directives. For example, loops or conditionals are applied instead to each inherited task.

  • Since Ansible 2.0, task includes are dynamic and behave more like real tasks. This means they can be looped, skipped and use variables from any source. Ansible tries to auto detect this, but you can use the static directive (which was added in Ansible 2.1) to bypass autodetection.

  • This module is also supported for Windows targets.

Parameters

Parameter

Comments

free-form

string

This module allows you to specify the name of the file directly without any other options.

Notes

Note

See Also

See also

ansible.builtin.import_playbook

The official documentation on the ansible.builtin.import_playbook module.

ansible.builtin.import_role

The official documentation on the ansible.builtin.import_role module.

ansible.builtin.import_tasks

The official documentation on the ansible.builtin.import_tasks module.

ansible.builtin.include_role

The official documentation on the ansible.builtin.include_role module.

ansible.builtin.include_tasks

The official documentation on the ansible.builtin.include_tasks module.

Including and importing

More information related to including and importing playbooks, roles and tasks.

Examples

- hosts: localhost
  tasks:
    - debug:
        msg: play1

- name: Include a play after another play
  include: otherplays.yaml


- hosts: all
  tasks:
    - debug:
        msg: task1

    - name: Include task list in play
      include: stuff.yaml

    - debug:
        msg: task10

- hosts: all
  tasks:
    - debug:
        msg: task1

    - name: Include task list in play only if the condition is true
      include: "{{ hostvar }}.yaml"
      static: no
      when: hostvar is defined

Status

  • This module will be removed in version 2.16. [deprecated]

  • For more information see DEPRECATED.

Authors

  • Ansible Core Team (@ansible)