← Back to branch summary

~canonical-ci-engineering/ubuntu-ci-services-itself/ansible

« back to all changes in this revision

Viewing changes to docsite/rst/patterns.rst

  • Committer: Package Import Robot
  • Author(s): Michael Vogt, Harlan Lieberman-Berg, Michael Vogt
  • Date: 2013-11-01 09:40:59 UTC
  • mfrom: (1.1.2)
  • Revision ID: package-import@ubuntu.com-20131101094059-6w580ocxzqyqzuu3
Tags: 1.3.4+dfsg-1
http://bugs.debian.org/717777
http://bugs.debian.org/714822
http://bugs.debian.org/721766
[ Harlan Lieberman-Berg ]
* New upstream release (Closes: #717777).
  Fixes CVE-2013-2233 (Closes: #714822).
  Fixes CVE-2013-4259 (Closes: #721766).
* Drop fix-ansible-cfg patch.
* Change docsite generation to not expect docs as part of a wordpress install.
* Add trivial patch to fix lintian error with rpm-key script.
* Add patch header information to fix-html-makefile.

[ Michael Vogt ]
* add myself to uploader
* build/ship the module manpages for ansible in the ansible package

Show diffs side-by-side

added added

removed removed

Lines of Context:
docsite/rst/patterns.rst
1
 
.. _patterns:
2
 
 
3
 
Inventory & Patterns
4
 
====================
5
 
 
6
 
 
7
 
Ansible works against multiple systems in your infrastructure at the
8
 
same time.  It does this by selecting portions of systems listed in
9
 
Ansible's inventory file, which defaults to /etc/ansible/hosts.
10
 
 
11
 
.. contents:: `Table of contents`
12
 
   :depth: 2
13
 
   :backlinks: top
14
 
 
15
 
.. _inventoryformat:
16
 
 
17
 
Hosts and Groups
18
 
++++++++++++++++
19
 
 
20
 
The format for /etc/ansible/hosts is an INI format and looks like this::
21
 
 
22
 
    mail.example.com
23
 
 
24
 
    [webservers]
25
 
    foo.example.com
26
 
    bar.example.com
27
 
 
28
 
    [dbservers]
29
 
    one.example.com
30
 
    two.example.com
31
 
    three.example.com
32
 
 
33
 
The things in brackets are group names. You don't have to have them,
34
 
but they are useful.
35
 
 
36
 
If you have hosts that run on non-standard SSH ports you can put the port number
37
 
after the hostname with a colon.  Ports listed in any SSH config file won't be read,
38
 
so it is important that you set them if things are not running on the default port::
39
 
 
40
 
    badwolf.example.com:5309
41
 
 
42
 
Suppose you have just static IPs and want to set up some aliases that don't live in your host file, or you are connecting through tunnels.  You can do things like this::
43
 
 
44
 
    jumper ansible_ssh_port=5555 ansible_ssh_host=192.168.1.50
45
 
 
46
 
In the above example, trying to ansible against the host alias "jumper" (which may not even be a real hostname) will contact 192.168.1.50 on port 5555.
47
 
 
48
 
Adding a lot of hosts?  In 0.6 and later, if you have a lot of hosts following similar patterns you can do this rather than listing each hostname::
49
 
 
50
 
    [webservers]
51
 
    www[01:50].example.com
52
 
 
53
 
 
54
 
In 1.0 and later, you can also do this for alphabetic ranges::
55
 
 
56
 
    [databases]
57
 
    db-[a:f].example.com
58
 
 
59
 
For numeric patterns, leading zeros can be included or removed, as desired. Ranges are inclusive.
60
 
 
61
 
In 1.1 and later, you can also select the connection type and user on a per host basis::
62
 
 
63
 
   [targets]
64
 
 
65
 
   localhost              ansible_connection=local
66
 
   other1.example.com     ansible_connection=ssh        ansible_ssh_user=mpdehaan
67
 
   other2.example.com     ansible_connection=ssh        ansible_ssh_user=mdehaan
68
 
 
69
 
All of these variables can of course also be set outside of the inventory file, in 'host_vars' if you wish
70
 
to keep your inventory file simple.
71
 
 
72
 
Selecting Targets
73
 
+++++++++++++++++
74
 
 
75
 
We'll go over how to use the command line in :doc:`examples` section, however, basically it looks like this::
76
 
 
77
 
    ansible <pattern_goes_here> -m <module_name> -a <arguments>
78
 
 
79
 
Such as::
80
 
 
81
 
    ansible webservers -m service -a "name=httpd state=restarted"
82
 
 
83
 
Within :doc:`playbooks`, these patterns can be used for even greater purposes.
84
 
 
85
 
Anyway, to use Ansible, you'll first need to know how to tell Ansible which hosts in your inventory file to talk to.
86
 
This is done by designating particular host names or groups of hosts.
87
 
 
88
 
The following patterns target all hosts in the inventory file::
89
 
 
90
 
    all
91
 
    *
92
 
 
93
 
Basically 'all' is an alias for '*'.  It is also possible to address a specific host or hosts::
94
 
 
95
 
    one.example.com
96
 
    one.example.com:two.example.com
97
 
    192.168.1.50
98
 
    192.168.1.*
99
 
 
100
 
The following patterns address one or more groups, which are denoted
101
 
with the aforementioned bracket headers in the inventory file::
102
 
 
103
 
    webservers
104
 
    webservers:dbservers
105
 
 
106
 
You can exclude groups as well, for instance, all webservers not in Phoenix::
107
 
 
108
 
    webservers:!phoenix
109
 
 
110
 
You can also specify the intersection of two groups::
111
 
 
112
 
    webservers:&staging
113
 
 
114
 
You can do combinations::
115
 
 
116
 
    webservers:dbservers:!phoenix:&staging
117
 
 
118
 
You can also use variables::
119
 
 
120
 
    webservers:!$excluded:&$required
121
 
 
122
 
Individual host names, IPs and groups, can also be referenced using
123
 
wildcards::
124
 
 
125
 
    *.example.com
126
 
    *.com
127
 
 
128
 
It's also ok to mix wildcard patterns and groups at the same time::
129
 
 
130
 
    one*.com:dbservers
131
 
 
132
 
 
133
 
Easy enough.  See :doc:`examples` and then :doc:`playbooks` for how to do things to selected hosts.
134
 
 
135
 
Host Variables
136
 
++++++++++++++
137
 
 
138
 
It is easy to assign variables to hosts that will be used later in playbooks::
139
 
 
140
 
   [atlanta]
141
 
   host1 http_port=80 maxRequestsPerChild=808
142
 
   host2 http_port=303 maxRequestsPerChild=909
143
 
 
144
 
 
145
 
Group Variables
146
 
+++++++++++++++
147
 
 
148
 
Variables can also be applied to an entire group at once::
149
 
 
150
 
   [atlanta]
151
 
   host1
152
 
   host2
153
 
 
154
 
   [atlanta:vars]
155
 
   ntp_server=ntp.atlanta.example.com
156
 
   proxy=proxy.atlanta.example.com
157
 
 
158
 
Groups of Groups, and Group Variables
159
 
+++++++++++++++++++++++++++++++++++++
160
 
 
161
 
It is also possible to make groups of groups and assign
162
 
variables to groups.  These variables can be used by /usr/bin/ansible-playbook, but not
163
 
/usr/bin/ansible::
164
 
 
165
 
   [atlanta]
166
 
   host1
167
 
   host2
168
 
 
169
 
   [raleigh]
170
 
   host2
171
 
   host3
172
 
 
173
 
   [southeast:children]
174
 
   atlanta
175
 
   raleigh
176
 
 
177
 
   [southeast:vars]
178
 
   some_server=foo.southeast.example.com
179
 
   halon_system_timeout=30
180
 
   self_destruct_countdown=60
181
 
   escape_pods=2
182
 
 
183
 
   [usa:children]
184
 
   southeast
185
 
   northeast
186
 
   southwest
187
 
   southeast
188
 
 
189
 
If you need to store lists or hash data, or prefer to keep host and group specific variables
190
 
separate from the inventory file, see the next section.
191
 
 
192
 
Splitting Out Host and Group Specific Data
193
 
++++++++++++++++++++++++++++++++++++++++++
194
 
 
195
 
.. versionadded:: 0.6
196
 
 
197
 
In addition to the storing variables directly in the INI file, host
198
 
and group variables can be stored in individual files relative to the
199
 
inventory file.  These variable files are in YAML format.
200
 
 
201
 
Assuming the inventory file path is::
202
 
 
203
 
    /etc/ansible/hosts
204
 
 
205
 
If the host is named 'foosball', and in groups 'raleigh' and 'webservers', variables
206
 
in YAML files at the following locations will be made available to the host::
207
 
 
208
 
    /etc/ansible/group_vars/raleigh
209
 
    /etc/ansible/group_vars/webservers
210
 
    /etc/ansible/host_vars/foosball
211
 
 
212
 
For instance, suppose you have hosts grouped by datacenter, and each datacenter
213
 
uses some different servers.  The data in the groupfile '/etc/ansible/group_vars/raleigh' for
214
 
the 'raleigh' group might look like::
215
 
 
216
 
    ---
217
 
    ntp_server: acme.example.org
218
 
    database_server: storage.example.org
219
 
 
220
 
It is ok if these files do not exist, this is an optional feature.
221
 
 
222
 
Tip: Keeping your inventory file and variables in a git repo (or other version control)
223
 
is an excellent way to track changes to your inventory and host variables.
224
 
 
225
 
.. versionadded:: 0.5
226
 
   If you ever have two python interpreters on a system, or your Python version 2 interpreter is not found
227
 
   at /usr/bin/python, set an inventory variable called 'ansible_python_interpreter' to the Python
228
 
   interpreter path you would like to use.
229
 
 
230
 
.. seealso::
231
 
 
232
 
   :doc:`examples`
233
 
       Examples of basic commands
234
 
   :doc:`playbooks`
235
 
       Learning ansible's configuration management language
236
 
   `Mailing List <http://groups.google.com/group/ansible-project>`_
237
 
       Questions? Help? Ideas?  Stop by the list on Google Groups
238
 
   `irc.freenode.net <http://irc.freenode.net>`_
239
 
       #ansible IRC chat channel
240