353 lines
13 KiB
ReStructuredText
353 lines
13 KiB
ReStructuredText
Playbook Roles and Include Statements
|
|
=====================================
|
|
|
|
.. contents:: Topics
|
|
|
|
Introduction
|
|
````````````
|
|
|
|
While it is possible to write a playbook in one very large file (and you might start out learning playbooks this way),
|
|
eventually you'll want to reuse files and start to organize things.
|
|
|
|
At a basic level, including task files allows you to break up bits of configuration policy into smaller files. Task includes
|
|
pull in tasks from other files. Since handlers are tasks too, you can also include handler files from the 'handlers:' section.
|
|
|
|
See :doc:`playbooks` if you need a review of these concepts.
|
|
|
|
Playbooks can also include plays from other playbook files. When that is done, the plays will be inserted into the playbook to form
|
|
a longer list of plays.
|
|
|
|
When you start to think about it -- tasks, handlers, variables, and so on -- begin to form larger concepts. You start to think about modeling
|
|
what something is, rather than how to make something look like something. It's no longer "apply this handful of THINGS to these hosts", you say "these hosts are dbservers" or "these hosts are webservers". In programming, we might call that "encapsulating" how things work. For instance,
|
|
you can drive a car without knowing how the engine works.
|
|
|
|
Roles in Ansible build on the idea of include files and combine them to form clean, reusable abstractions -- they allow you to focus
|
|
more on the big picture and only dive down into the details when needed.
|
|
|
|
We'll start with understanding includes so roles make more sense, but our ultimate goal should be understanding roles -- roles
|
|
are great and you should use them every time you write playbooks.
|
|
|
|
See the `ansible-examples <https://github.com/ansible/ansible-examples>`_ repository on GitHub for lots of examples of all of this
|
|
put together. You may wish to have this open in a separate tab as you dive in.
|
|
|
|
Task Include Files And Encouraging Reuse
|
|
````````````````````````````````````````
|
|
|
|
Suppose you want to reuse lists of tasks between plays or playbooks. You can use
|
|
include files to do this. Use of included task lists is a great way to define a role
|
|
that system is going to fulfill. Remember, the goal of a play in a playbook is to map
|
|
a group of systems into multiple roles. Let's see what this looks like...
|
|
|
|
A task include file simply contains a flat list of tasks, like so::
|
|
|
|
---
|
|
# possibly saved as tasks/foo.yml
|
|
- name: placeholder foo
|
|
command: /bin/foo
|
|
- name: placeholder bar
|
|
command: /bin/bar
|
|
|
|
Include directives look like this, and can be mixed in with regular tasks in a playbook::
|
|
|
|
tasks:
|
|
- include: tasks/foo.yml
|
|
|
|
You can also pass variables into includes. We call this a 'parameterized include'.
|
|
|
|
For instance, if deploying multiple wordpress instances, I could
|
|
contain all of my wordpress tasks in a single wordpress.yml file, and use it like so::
|
|
|
|
tasks:
|
|
- include: wordpress.yml user=timmy
|
|
- include: wordpress.yml user=alice
|
|
- include: wordpress.yml user=bob
|
|
|
|
If you are running Ansible 1.4 and later, include syntax is streamlined to match roles, and also allows passing list and dictionary parameters::
|
|
|
|
tasks:
|
|
- { include: wordpress.yml, user: timmy, ssh_keys: [ 'keys/one.txt', 'keys/two.txt' ] }
|
|
|
|
Using either syntax, variables passed in can then be used in the included files. We've already covered them a bit in :doc:`playbooks_variables`.
|
|
You can reference them like this::
|
|
|
|
{{ user }}
|
|
|
|
(In addition to the explicitly passed-in parameters, all variables from
|
|
the vars section are also available for use here as well.)
|
|
|
|
Starting in 1.0, variables can also be passed to include files using an alternative syntax,
|
|
which also supports structured variables::
|
|
|
|
tasks:
|
|
|
|
- include: wordpress.yml
|
|
vars:
|
|
remote_user: timmy
|
|
some_list_variable:
|
|
- alpha
|
|
- beta
|
|
- gamma
|
|
|
|
Playbooks can include other playbooks too, but that's mentioned in a later section.
|
|
|
|
.. note::
|
|
As of 1.0, task include statements can be used at arbitrary depth.
|
|
They were previously limited to a single level, so task includes
|
|
could not include other files containing task includes.
|
|
|
|
Includes can also be used in the 'handlers' section, for instance, if you
|
|
want to define how to restart apache, you only have to do that once for all
|
|
of your playbooks. You might make a handlers.yml that looks like::
|
|
|
|
---
|
|
# this might be in a file like handlers/handlers.yml
|
|
- name: restart apache
|
|
service: name=apache state=restarted
|
|
|
|
And in your main playbook file, just include it like so, at the bottom
|
|
of a play::
|
|
|
|
handlers:
|
|
- include: handlers/handlers.yml
|
|
|
|
You can mix in includes along with your regular non-included tasks and handlers.
|
|
|
|
Includes can also be used to import one playbook file into another. This allows
|
|
you to define a top-level playbook that is composed of other playbooks.
|
|
|
|
For example::
|
|
|
|
- name: this is a play at the top level of a file
|
|
hosts: all
|
|
remote_user: root
|
|
tasks:
|
|
- name: say hi
|
|
tags: foo
|
|
shell: echo "hi..."
|
|
|
|
- include: load_balancers.yml
|
|
- include: webservers.yml
|
|
- include: dbservers.yml
|
|
|
|
Note that you cannot do variable substitution when including one playbook
|
|
inside another.
|
|
|
|
.. note::
|
|
You can not conditionally path the location to an include file,
|
|
like you can with 'vars_files'. If you find yourself needing to do
|
|
this, consider how you can restructure your playbook to be more
|
|
class/role oriented. This is to say you cannot use a 'fact' to
|
|
decide what include file to use. All hosts contained within the
|
|
play are going to get the same tasks. ('*when*' provides some
|
|
ability for hosts to conditionally skip tasks).
|
|
|
|
.. _roles:
|
|
|
|
Roles
|
|
`````
|
|
|
|
.. versionadded:: 1.2
|
|
|
|
Now that you have learned about vars_files, tasks, and handlers, what is the best way to organize your playbooks?
|
|
The short answer is to use roles! Roles are ways of automatically loading certain vars_files, tasks, and
|
|
handlers based on a known file structure. Grouping content by roles also allows easy sharing of roles with other users.
|
|
|
|
Roles are just automation around 'include' directives as described above, and really don't contain much
|
|
additional magic beyond some improvements to search path handling for referenced files. However, that can be a big thing!
|
|
|
|
Example project structure::
|
|
|
|
site.yml
|
|
webservers.yml
|
|
fooservers.yml
|
|
roles/
|
|
common/
|
|
files/
|
|
templates/
|
|
tasks/
|
|
handlers/
|
|
vars/
|
|
meta/
|
|
webservers/
|
|
files/
|
|
templates/
|
|
tasks/
|
|
handlers/
|
|
vars/
|
|
meta/
|
|
|
|
In a playbook, it would look like this::
|
|
|
|
---
|
|
- hosts: webservers
|
|
roles:
|
|
- common
|
|
- webservers
|
|
|
|
This designates the following behaviors, for each role 'x':
|
|
|
|
- If roles/x/tasks/main.yml exists, tasks listed therein will be added to the play
|
|
- If roles/x/handlers/main.yml exists, handlers listed therein will be added to the play
|
|
- If roles/x/vars/main.yml exists, variables listed therein will be added to the play
|
|
- If roles/x/meta/main.yml exists, any role dependencies listed therein will be added to the list of roles (1.3 and later)
|
|
- Any copy tasks can reference files in roles/x/files/ without having to path them relatively or absolutely
|
|
- Any script tasks can reference scripts in roles/x/files/ without having to path them relatively or absolutely
|
|
- Any template tasks can reference files in roles/x/templates/ without having to path them relatively or absolutely
|
|
|
|
In Ansible 1.4 and later you can configure a roles_path to search for roles. Use this to check all of your common roles out to one location, and share
|
|
them easily between multiple playbook projects. See :doc:`intro_configuration` for details about how to set this up in ansible.cfg.
|
|
|
|
.. note::
|
|
Role dependencies are discussed below.
|
|
|
|
If any files are not present, they are just ignored. So it's ok to not have a 'vars/' subdirectory for the role,
|
|
for instance.
|
|
|
|
Note, you are still allowed to list tasks, vars_files, and handlers "loose" in playbooks without using roles,
|
|
but roles are a good organizational feature and are highly recommended. if there are loose things in the playbook,
|
|
the roles are evaluated first.
|
|
|
|
Also, should you wish to parameterize roles, by adding variables, you can do so, like this::
|
|
|
|
---
|
|
- hosts: webservers
|
|
roles:
|
|
- common
|
|
- { role: foo_app_instance, dir: '/opt/a', port: 5000 }
|
|
- { role: foo_app_instance, dir: '/opt/b', port: 5001 }
|
|
|
|
While it's probably not something you should do often, you can also conditionally apply roles like so::
|
|
|
|
---
|
|
- hosts: webservers
|
|
roles:
|
|
- { role: some_role, when: "ansible_os_family == 'RedHat'" }
|
|
|
|
This works by applying the conditional to every task in the role. Conditionals are covered later on in
|
|
the documentation.
|
|
|
|
Finally, you may wish to assign tags to the roles you specify. You can do so inline:::
|
|
|
|
---
|
|
- hosts: webservers
|
|
roles:
|
|
- { role: foo, tags: ["bar", "baz"] }
|
|
|
|
|
|
If the play still has a 'tasks' section, those tasks are executed after roles are applied.
|
|
|
|
If you want to define certain tasks to happen before AND after roles are applied, you can do this::
|
|
|
|
---
|
|
- hosts: webservers
|
|
pre_tasks:
|
|
- shell: echo 'hello'
|
|
roles:
|
|
- { role: some_role }
|
|
tasks:
|
|
- shell: echo 'still busy'
|
|
post_tasks:
|
|
- shell: echo 'goodbye'
|
|
|
|
.. note::
|
|
If using tags with tasks (described later as a means of only running part of a playbook),
|
|
be sure to also tag your pre_tasks and post_tasks and pass those along as well, especially if the pre
|
|
and post tasks are used for monitoring outage window control or load balancing.
|
|
|
|
Role Default Variables
|
|
``````````````````````
|
|
|
|
.. versionadded:: 1.3
|
|
|
|
Role default variables allow you to set default variables for included or dependent roles (see below). To create
|
|
defaults, simply add a `defaults/main.yml` file in your role directory. These variables will have the lowest priority
|
|
of any variables available, and can be easily overridden by any other variable, including inventory variables.
|
|
|
|
Role Dependencies
|
|
`````````````````
|
|
|
|
.. versionadded:: 1.3
|
|
|
|
Role dependencies allow you to automatically pull in other roles when using a role. Role dependencies are stored in the
|
|
`meta/main.yml` file contained within the role directory. This file should contain
|
|
a list of roles and parameters to insert before the specified role, such as the following in an example
|
|
`roles/myapp/meta/main.yml`::
|
|
|
|
---
|
|
dependencies:
|
|
- { role: common, some_parameter: 3 }
|
|
- { role: apache, port: 80 }
|
|
- { role: postgres, dbname: blarg, other_parameter: 12 }
|
|
|
|
Role dependencies can also be specified as a full path, just like top level roles::
|
|
|
|
---
|
|
dependencies:
|
|
- { role: '/path/to/common/roles/foo', x: 1 }
|
|
|
|
Roles dependencies are always executed before the role that includes them, and are recursive. By default,
|
|
roles can also only be added as a dependency once - if another role also lists it as a dependency it will
|
|
not be run again. This behavior can be overridden by adding `allow_duplicates: yes` to the `meta/main.yml` file.
|
|
For example, a role named 'car' could add a role named 'wheel' to its dependencies as follows::
|
|
|
|
---
|
|
dependencies:
|
|
- { role: wheel, n: 1 }
|
|
- { role: wheel, n: 2 }
|
|
- { role: wheel, n: 3 }
|
|
- { role: wheel, n: 4 }
|
|
|
|
And the `meta/main.yml` for wheel contained the following::
|
|
|
|
---
|
|
allow_duplicates: yes
|
|
dependencies:
|
|
- { role: tire }
|
|
- { role: brake }
|
|
|
|
The resulting order of execution would be as follows::
|
|
|
|
tire(n=1)
|
|
brake(n=1)
|
|
wheel(n=1)
|
|
tire(n=2)
|
|
brake(n=2)
|
|
wheel(n=2)
|
|
...
|
|
car
|
|
|
|
.. note::
|
|
Variable inheritance and scope are detailed in the :doc:`playbooks_variables`.
|
|
|
|
Ansible Galaxy
|
|
``````````````
|
|
|
|
`Ansible Galaxy <http://galaxy.ansible.com>`_, is a free site for finding, downloading, rating, and reviewing all kinds of community developed Ansible roles and can be a great way to get a jumpstart on your automation projects.
|
|
|
|
You can sign up with social auth, and the download client 'ansible-galaxy' is included in Ansible 1.4.2 and later.
|
|
|
|
Read the "About" page on the Galaxy site for more information.
|
|
|
|
.. seealso::
|
|
|
|
:doc:`YAMLSyntax`
|
|
Learn about YAML syntax
|
|
:doc:`playbooks`
|
|
Review the basic Playbook language features
|
|
:doc:`playbooks_best_practices`
|
|
Various tips about managing playbooks in the real world
|
|
:doc:`playbooks_variables`
|
|
All about variables in playbooks
|
|
:doc:`playbooks_conditionals`
|
|
Conditionals in playbooks
|
|
:doc:`playbooks_loops`
|
|
Loops in playbooks
|
|
:doc:`modules`
|
|
Learn about available modules
|
|
:doc:`developing_modules`
|
|
Learn how to extend Ansible by writing your own modules
|
|
`GitHub Ansible examples <https://github.com/ansible/ansible-examples>`_
|
|
Complete playbook files from the GitHub project source
|
|
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
|
Questions? Help? Ideas? Stop by the list on Google Groups
|
|
|