45

In Ansible 2.4, the include module is deprecated. In its place, it ships with two replacement modules, import_tasks and include_tasks. But they have very similar descriptions:

  • include_tasks: Includes a file with a list of tasks to be executed in the current playbook.
  • import_tasks: Imports a list of tasks to be added to the current playbook for subsequent execution.

When should I use the former, and when should I use the latter?

  • (Also: the deprecation warning refers to "dynamic" and "static" tasks. I read the docs but didn't understand them.) – Ben S Sep 24 '17 at 16:43
52

There's quite a bit about this topic in the documentation:

The main difference is:

All import* statements are pre-processed at the time playbooks are parsed.
All include* statements are processed as they encountered during the execution of the playbook.

So import is static, include is dynamic.

From my experience, you should use import when you deal with logical "units". For example, separate long list of tasks into subtask files:

main.yml:

- import_tasks: prepare_filesystem.yml
- import_tasks: install_prerequisites.yml
- import_tasks: install_application.yml

But you would use include to deal with different workflows and take decisions based on some dynamically gathered facts:

install_prerequisites:

- include_tasks: prerequisites_{{ ansible_os_family | lower }}.yml
  • 6
    I found this link very useful: docs.ansible.com/ansible/latest/… It calls out a case where import and include behave differently - a 'when' conditional where the tasks in the file may change the criteria used to determine the import. With import_tasks, each task checks the criteria, so the behavior changes when the criteria changes. With include_tasks, the tasks are either present or not based on whether or not the condition was evaluated as true when the include_tasks statement was executed. If I understand well... – Ethel Evans Dec 6 '17 at 20:28
  • What was the behavior of include? If we were using include would import_tasks be the equivalent? – Andy Shinn Jan 18 '18 at 20:27
  • include had static: yes (behaved like import_tasks), and static: no (like include_tasks). – Konstantin Suvorov Jan 19 '18 at 6:28
  • What is the default for static? – Andy Shinn May 30 '18 at 0:46
  • static is None by default: 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. – Konstantin Suvorov May 30 '18 at 7:48
4

Imports are static, includes are dynamic. Imports happen at parsing time, includes at runtime.

Imports basically replace the task with the tasks from the file. There's no import_task at runtime. So, attributes like tags, and when (and most likely other attributes) are copied to every imported task.

includes are indeed executed. tags and when of an included task apply only to the task itself.

Tagged tasks from an imported file get executed if import task is untagged. No tasks is executed from an included file if include task is untagged.

All tasks from an imported file get executed if import task is tagged. Only tagged tasks from an included file get executed if include task is tagged.

Limitations of imports:

  • can't be used with with_* or loop attributes
  • can't import a file, which name depends on a variable

Limitations of includes:

  • --list-tags doesn't show tags from included files
  • --list-tasks doesn't show tasks from included files
  • you cannot use notify to trigger a handler name which comes from inside a dynamic include
  • you cannot use --start-at-task to begin execution at a task inside a dynamic include

More on it here and here.

For me that basically comes down to the fact that imports can't be used with loop attributes.

import would certainly fail in cases like this:

# playbook.yml
- import_tasks: set-x.yml
  when: x is not defined

# set-x.yml
- set_fact
  x: foo
- debug:
  var: x

debug is not executed, since it inherits when from import_tasks task. So, no importing task files that change variables used in import's when attribute.

I had a policy to start with imports, but once I need an include make sure nothing is imported by that included file or the files it includes. But that's pretty damn hard to maintain. And it's still not clear if it'll protect me from troubles. Meaning, mixing includes and imports which they don't recommend.

I can't use only imports, since I occasionally need to loop include tasks. I could probably switch to only includes. But I decided to switch to imports everywhere except for the cases where the task is supposed to be run several times. I decided to experience all those tricky edge cases first-hand. Maybe there won't be any in my playbooks. Or hopefully I'll find a way to make it work.

UPD A possibly useful trick to create a task file that can be imported many times, but executed once:

- name: ...
  ...
  when: not _file_executed | default(False)

- name: ...
  ...
  when: not _file_executed | default(False)

...

- name: Set _file_executed
  set_fact:
    _file_executed: True

UPD One not really expected effect of mixing includes and imports is that include vars override import ones:

playbook.yml:

- hosts: all
  tasks:
    - import_tasks: 2.yml
      vars:
        v1: 1
    - include_tasks: 2.yml
      vars:
        v1: 1

2.yml:

- import_tasks: 3.yml
  vars:
    v1: 2

3.yml:

- debug:
    var: v1    # 2 then 1

Probably, because include_tasks first does all additional static imports, and then changes variables passed via its vars directive.

UPD Another case of mixing includes and imports.

playbook.yml:

- hosts: all
  tasks:
    # here you're bound to use include, some sort of loop
    - include_tasks: 2.yml
      vars:
        https: yes

2.yml:

- import_tasks: 3.yml
  when: https

3.yml:

- import_tasks: 4.yml
  vars:
    https: no  # here we're trying to temporarily override https var
- import_tasks: 4.yml

4.yml:

- debug:
    var: https

We get true and true, see the previous case (include vars take precedence over import vars). So we switch to includes in 3.yml. But then the first include in 3.yml is skipped. Since it inherites when: https from the parent task, and the latter supposedly takes https from the task's vars. The solution is to switch to includes in 2.yml as well. That prevents propagation of when: https to the child tasks.

  • 1
    Great answer!. I was frustrated with everyone on the internet just repeating what the documentation says. Thank you. – Sergio Acosta Jan 26 at 2:22

Your Answer

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

Not the answer you're looking for? Browse other questions tagged or ask your own question.