Ansible Include and Import
Large playbooks grow messy. A single file with two hundred tasks is hard to read, test, and share. Splitting work into smaller files fixes the problem, and Ansible offers two families of keywords to pull those files back together: import and include. Imagine a cookbook that says "prepare the sauce, see page 12". The cook flips to page 12 and follows it. The keywords act as that page reference. The two families differ in when Ansible reads the referenced page.
Static Versus Dynamic
| Family | Keywords | Processing Time | Type |
|---|---|---|---|
| Import | import_tasks, import_playbook, import_role | Playbook parse time, before the run | Static |
| Include | include_tasks, include_role, include_vars | Run time, when execution reaches the line | Dynamic |
Diagram: Two Reading Styles
IMPORT (static) INCLUDE (dynamic)
site.yml site.yml
│ import_tasks: db.yml │ include_tasks: db.yml
▼ ▼
Ansible reads db.yml Ansible runs earlier tasks
BEFORE the run starts ...reaches the include line...
│ │
▼ ▼
One big merged task list Ansible loads db.yml NOW
is executed and runs it
Import Tasks
Store a group of tasks in a separate file. Keep the file free of play headers, since it holds only a task list.
# tasks/database.yml
- name: Install MariaDB
ansible.builtin.package:
name: mariadb-server
state: present
- name: Start MariaDB
ansible.builtin.service:
name: mariadb
state: started
enabled: true
# site.yml
- hosts: dbservers
become: true
tasks:
- ansible.builtin.import_tasks: tasks/database.yml
Include Tasks with a Loop or Condition
Dynamic includes support loops and conditions that depend on values created during the run.
- name: Configure each site
ansible.builtin.include_tasks: site.yml
loop:
- shop
- blog
- docs
loop_control:
loop_var: site_name
The file site.yml runs three times, and the variable site_name holds a different value on each pass.
- name: Pick tasks by operating system
ansible.builtin.include_tasks: "{{ ansible_os_family }}.yml"
This pattern loads Debian.yml or RedHat.yml based on a fact.
Import Playbook
The import_playbook keyword assembles a master playbook from smaller ones. Place the keyword at the top level, outside any play.
# site.yml
- import_playbook: webservers.yml
- import_playbook: dbservers.yml
- import_playbook: loadbalancers.yml
Run ansible-playbook site.yml to build the whole environment, or run webservers.yml alone for a targeted change.
Import Role and Include Role
tasks:
- ansible.builtin.import_role:
name: common
- ansible.builtin.include_role:
name: monitoring
when: enable_monitoring | default(false)
The include_role keyword allows a condition to decide whether the role runs at all.
Behavior Differences
- A condition on
import_tasksapplies to every imported task individually - A condition on
include_tasksapplies once to the include line - Tags on an import apply to all imported tasks, and tags on an include apply only to the include line
--list-tasksshows imported tasks but hides dynamically included ones--start-at-taskworks with imports and fails with includes
Choosing Between the Two
Choose imports for fixed structure that needs clear previews, tags, and predictable behavior. Choose includes when a loop, a fact, or a runtime variable decides what loads. Avoid mixing both styles for the same file inside one project, because the mixed behavior confuses readers.
Try This
Move two tasks from a playbook into tasks/common.yml and load them with import_tasks. Run ansible-playbook site.yml --list-tasks and notice the tasks appear. Switch to include_tasks, run the same command, and observe the include line without the inner tasks.
Summary
Import keywords load files during parsing and produce a predictable, previewable task list. Include keywords load files during execution and respond to loops, conditions, and runtime data. Use import_playbook to compose a master playbook. Pick the style that matches the need, and keep each project consistent.
