ansible/docsite/latest/rst/playbooks_loops.rst

152 lines
4.6 KiB
ReStructuredText
Raw Normal View History

2013-09-29 23:02:53 +02:00
Loops
=====
2013-09-25 07:18:43 +02:00
2013-09-29 23:02:53 +02:00
All about how to use loops in playbooks.
2013-09-25 06:26:14 +02:00
2013-09-29 23:02:53 +02:00
Standard Loops
``````````````
2012-05-13 17:00:02 +02:00
To save some typing, repeated tasks can be written in short-hand like so::
- name: add several users
user: name={{ item }} state=present groups=wheel
2012-05-13 17:00:02 +02:00
with_items:
- testuser1
- testuser2
If you have defined a YAML list in a variables file, or the 'vars' section, you can also do::
with_items: somelist
2012-05-13 17:00:02 +02:00
The above would be the equivalent of::
- name: add user testuser1
user: name=testuser1 state=present groups=wheel
2012-05-13 17:00:02 +02:00
- name: add user testuser2
user: name=testuser2 state=present groups=wheel
2012-05-13 17:00:02 +02:00
The yum and apt modules use with_items to execute fewer package manager transactions.
2012-05-13 17:00:02 +02:00
2012-10-17 01:12:31 +02:00
Note that the types of items you iterate over with 'with_items' do not have to be simple lists of strings.
2012-10-17 00:58:31 +02:00
If you have a list of hashes, you can reference subkeys using things like::
- name: add several users
user: name={{ item.name }} state=present groups={{ item.groups }}
with_items:
- { name: 'testuser1', groups: 'wheel' }
- { name: 'testuser2', groups: 'root' }
2012-10-17 00:58:31 +02:00
2013-07-15 06:28:02 +02:00
Nested Loops
````````````
2013-07-19 15:31:50 +02:00
Loops can be nested as well::
2013-07-15 06:28:02 +02:00
2013-07-19 15:13:30 +02:00
- name: give users access to multiple databases
2013-09-22 14:17:28 +02:00
mysql_user: name={{ item[0] }} priv={{ item[1] }}.*:ALL password=foo
2013-07-15 06:28:02 +02:00
with_nested:
- [ 'alice', 'bob', 'eve' ]
- [ 'clientdb', 'employeedb', 'providerdb' ]
2013-09-22 14:17:28 +02:00
As with the case of 'with_items' above, you can use previously defined variables. Just specify the variable's name without templating it with '{{ }}'::
2013-07-15 06:28:02 +02:00
- name: here, 'users' contains the above list of employees
2013-09-22 14:17:28 +02:00
mysql_user: name={{ item[0] }} priv={{ item[1] }}.*:ALL password=foo
2013-07-15 06:28:02 +02:00
with_nested:
- users
- [ 'clientdb', 'employeedb', 'providerdb' ]
2013-09-29 23:02:53 +02:00
Looping over Fileglobs
``````````````````````
2012-10-17 00:51:10 +02:00
2013-04-05 19:00:23 +02:00
``with_fileglob`` matches all files in a single directory, non-recursively, that match a pattern. It can
2012-10-17 00:51:10 +02:00
be used like this::
---
2012-10-17 00:51:10 +02:00
- hosts: all
tasks:
# first ensure our target directory exists
2013-07-15 19:50:48 +02:00
- file: dest=/etc/fooapp state=directory
2012-10-17 00:51:10 +02:00
# copy each file over that matches the given pattern
2013-07-15 19:50:48 +02:00
- copy: src={{ item }} dest=/etc/fooapp/ owner=root mode=600
2013-02-17 18:47:51 +01:00
with_fileglob:
- /playbooks/files/fooapp/*
2013-09-29 23:02:53 +02:00
Looping over Parallel Sets of Data
``````````````````````````````````
2013-09-29 23:02:53 +02:00
Documentation for this feature is coming soon.
2013-09-29 23:02:53 +02:00
Looping over Subelements
````````````````````````
2013-09-29 23:02:53 +02:00
Documentation for this feature is coming soon.
2013-09-29 23:02:53 +02:00
Looping over Integer Sequences
``````````````````````````````
2013-04-05 19:00:23 +02:00
``with_sequence`` generates a sequence of items in ascending numerical order. You
can specify a start, end, and an optional step value.
Arguments should be specified in key=value pairs. If supplied, the 'format' is a printf style string.
2013-02-17 18:47:51 +01:00
Numerical values can be specified in decimal, hexadecimal (0x3f8) or octal (0600).
Negative numbers are not supported. This works as follows::
---
- hosts: all
tasks:
# create groups
- group: name=evens state=present
- group: name=odds state=present
# create some test users
- user: name={{ item }} state=present groups=evens
2013-04-17 02:41:42 +02:00
with_sequence: start=0 end=32 format=testuser%02x
# create a series of directories with even numbers for some reason
- file: dest=/var/stuff/{{ item }} state=directory
with_sequence: start=4 end=16 stride=2
# a simpler way to use the sequence plugin
# create 4 groups
- group: name=group{{ item }} state=present
with_sequence: count=4
2013-09-29 23:02:53 +02:00
Do-Until Loops
``````````````
2013-09-29 23:02:53 +02:00
Sometimes you would want to retry a task until a certain condition is met. Here's an example::
- action: shell /usr/bin/foo
register: result
until: register.stdout.find("all systems go") != -1
retries: 5
delay: 10
2013-08-12 15:49:34 +02:00
2013-09-29 23:02:53 +02:00
The above example run the shell module recursively till the module's result has "all systems go" in it's stdout or the task has
been retried for 5 times with a delay of 10 seconds. The default value for "retries" is 3 and "delay" is 5.
2013-09-29 23:02:53 +02:00
The task returns the results returned by the last task run. The results of individual retries can be viewed by -vv option.
The registered variable will also have a new key "attempts" which will have the number of the retries for the task.
2013-09-29 23:02:53 +02:00
The Do/Until feature does not take decision on whether to fail or pass the play when the maximum retries are completed, the user can
can do that in the next task as follows::
- action: shell /usr/bin/foo
register: result
until: register.stdout.find("all systems go") != -1
retries: 5
delay: 10
failed_when: result.attempts == 5
2012-05-13 17:00:02 +02:00