ansible/docs/docsite/rst/user_guide/intro_patterns.rst

117 lines
4 KiB
ReStructuredText
Raw Normal View History

.. _intro_patterns:
Working with Patterns
=====================
.. contents:: Topics
Patterns in Ansible are how we decide which hosts to manage. This can mean what hosts to communicate with, but in terms
of :ref:`playbooks<playbooks_intro>` it actually means what hosts to apply a particular configuration or IT process to.
2012-03-09 20:39:29 +01:00
We'll go over how to use the command line in :ref:`intro_adhoc` section, however, basically it looks like this::
ansible <pattern_goes_here> -m <module_name> -a <arguments>
Such as::
ansible webservers -m service -a "name=httpd state=restarted"
2013-10-05 20:57:45 +02:00
A pattern usually refers to a set of groups (which are sets of hosts) -- in the above case, machines in the "webservers" group.
Anyway, to use Ansible, you'll first need to know how to tell Ansible which hosts in your inventory to talk to.
This is done by designating particular host names or groups of hosts.
2013-10-05 20:57:45 +02:00
The following patterns are equivalent and target all hosts in the inventory::
2012-03-08 19:53:48 +01:00
all
*
2012-03-08 19:36:47 +01:00
2013-10-05 20:57:45 +02:00
It is also possible to address a specific host or set of hosts by name::
2012-03-08 19:36:47 +01:00
one.example.com
one.example.com:two.example.com
192.0.2.50
192.0.2.*
The following patterns address one or more groups. Groups separated by a colon indicate an "OR" configuration.
This means the host may be in either one group or the other::
2012-03-08 19:36:47 +01:00
webservers
webservers:dbservers
2012-03-08 19:36:47 +01:00
You can exclude groups as well, for instance, all machines must be in the group webservers but not in the group phoenix::
2012-07-04 23:44:39 +02:00
webservers:!phoenix
2012-07-04 23:44:39 +02:00
You can also specify the intersection of two groups. This would mean the hosts must be in the group webservers and
the host must also be in the group staging::
webservers:&staging
You can do combinations::
webservers:dbservers:&staging:!phoenix
The above configuration means "all machines in the groups 'webservers' and 'dbservers' are to be managed if they are also in
the group 'staging', but the machines are not to be managed if they are in the group 'phoenix'." Whew!
You can also use variables if you want to pass some group specifiers via the ``-e`` argument to ansible-playbook, but this
is uncommonly used::
webservers:!{{excluded}}:&{{required}}
You also don't have to manage by strictly defined groups. Individual host names, IPs, and groups can also be referenced using
wildcards:
.. code-block:: none
2012-03-08 19:36:47 +01:00
2012-03-09 20:39:29 +01:00
*.example.com
*.com
2012-03-08 19:36:47 +01:00
2012-03-08 19:53:48 +01:00
It's also ok to mix wildcard patterns and groups at the same time::
2012-03-08 19:36:47 +01:00
one*.com:dbservers
2012-03-08 19:36:47 +01:00
You can select a host or subset of hosts from a group by their position. For example, given the following group::
[webservers]
cobweb
webbing
weber
2015-09-17 10:05:37 +02:00
You can refer to hosts within the group by adding a subscript to the group name::
webservers[0] # == cobweb
webservers[-1] # == weber
webservers[0:2] # == webservers[0],webservers[1]
# == cobweb,webbing
webservers[1:] # == webbing,weber
webservers[:3] # == cobweb,webbing,weber
Most people don't specify patterns as regular expressions, but you can. Just start the pattern with a ``~``::
2013-04-27 18:04:22 +02:00
~(web|db).*\.example\.com
While we're jumping a bit ahead, additionally, you can add an exclusion criteria just by supplying the ``--limit`` flag to /usr/bin/ansible or /usr/bin/ansible-playbook::
ansible-playbook site.yml --limit datacenter2
2012-04-18 01:54:23 +02:00
And if you want to read the list of hosts from a file, prefix the file name with ``@``::
ansible-playbook site.yml --limit @retry_hosts.txt
Easy enough. See :ref:`intro_adhoc` and then :ref:`playbooks_intro` for how to apply this knowledge.
2012-07-20 17:51:03 +02:00
.. note:: You can use a comma (``,``) as a host list separator instead of a colon (``:``). The comma is preferred when dealing with ranges and IPv6 addresses.
.. seealso::
:ref:`intro_adhoc`
Examples of basic commands
:ref:`working_with_playbooks`
Learning ansible's configuration management language
`Mailing List <https://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel