/docsite/rst/playbooks_loops.rst

https://github.com/ajanthanm/ansible · ReStructuredText · 432 lines · 312 code · 120 blank · 0 comment · 0 complexity · 52f6cd65883bd50797db6bfc71b90416 MD5 · raw file

  1. Loops
  2. =====
  3. Often you'll want to do many things in one task, such as create a lot of users, install a lot of packages, or
  4. repeat a polling step until a certain result is reached.
  5. This chapter is all about how to use loops in playbooks.
  6. .. contents:: Topics
  7. .. _standard_loops:
  8. Standard Loops
  9. ``````````````
  10. To save some typing, repeated tasks can be written in short-hand like so::
  11. - name: add several users
  12. user: name={{ item }} state=present groups=wheel
  13. with_items:
  14. - testuser1
  15. - testuser2
  16. If you have defined a YAML list in a variables file, or the 'vars' section, you can also do::
  17. with_items: somelist
  18. The above would be the equivalent of::
  19. - name: add user testuser1
  20. user: name=testuser1 state=present groups=wheel
  21. - name: add user testuser2
  22. user: name=testuser2 state=present groups=wheel
  23. The yum and apt modules use with_items to execute fewer package manager transactions.
  24. Note that the types of items you iterate over with 'with_items' do not have to be simple lists of strings.
  25. If you have a list of hashes, you can reference subkeys using things like::
  26. - name: add several users
  27. user: name={{ item.name }} state=present groups={{ item.groups }}
  28. with_items:
  29. - { name: 'testuser1', groups: 'wheel' }
  30. - { name: 'testuser2', groups: 'root' }
  31. .. _nested_loops:
  32. Nested Loops
  33. ````````````
  34. Loops can be nested as well::
  35. - name: give users access to multiple databases
  36. mysql_user: name={{ item[0] }} priv={{ item[1] }}.*:ALL append_privs=yes password=foo
  37. with_nested:
  38. - [ 'alice', 'bob' ]
  39. - [ 'clientdb', 'employeedb', 'providerdb' ]
  40. As with the case of 'with_items' above, you can use previously defined variables. Just specify the variable's name without templating it with '{{ }}'::
  41. - name: here, 'users' contains the above list of employees
  42. mysql_user: name={{ item[0] }} priv={{ item[1] }}.*:ALL append_privs=yes password=foo
  43. with_nested:
  44. - users
  45. - [ 'clientdb', 'employeedb', 'providerdb' ]
  46. .. _looping_over_hashes:
  47. Looping over Hashes
  48. ```````````````````
  49. .. versionadded:: 1.5
  50. Suppose you have the following variable::
  51. ---
  52. users:
  53. alice:
  54. name: Alice Appleworth
  55. telephone: 123-456-7890
  56. bob:
  57. name: Bob Bananarama
  58. telephone: 987-654-3210
  59. And you want to print every user's name and phone number. You can loop through the elements of a hash using ``with_dict`` like this::
  60. tasks:
  61. - name: Print phone records
  62. debug: msg="User {{ item.key }} is {{ item.value.name }} ({{ item.value.telephone }})"
  63. with_dict: users
  64. .. _looping_over_fileglobs:
  65. Looping over Fileglobs
  66. ``````````````````````
  67. ``with_fileglob`` matches all files in a single directory, non-recursively, that match a pattern. It can
  68. be used like this::
  69. ---
  70. - hosts: all
  71. tasks:
  72. # first ensure our target directory exists
  73. - file: dest=/etc/fooapp state=directory
  74. # copy each file over that matches the given pattern
  75. - copy: src={{ item }} dest=/etc/fooapp/ owner=root mode=600
  76. with_fileglob:
  77. - /playbooks/files/fooapp/*
  78. .. note:: When using a relative path with ``with_fileglob`` in a role, Ansible resolves the path relative to the `roles/<rolename>/files` directory.
  79. Looping over Parallel Sets of Data
  80. ``````````````````````````````````
  81. .. note:: This is an uncommon thing to want to do, but we're documenting it for completeness. You probably won't be reaching for this one often.
  82. Suppose you have the following variable data was loaded in via somewhere::
  83. ---
  84. alpha: [ 'a', 'b', 'c', 'd' ]
  85. numbers: [ 1, 2, 3, 4 ]
  86. And you want the set of '(a, 1)' and '(b, 2)' and so on. Use 'with_together' to get this::
  87. tasks:
  88. - debug: msg="{{ item.0 }} and {{ item.1 }}"
  89. with_together:
  90. - alpha
  91. - numbers
  92. Looping over Subelements
  93. ````````````````````````
  94. Suppose you want to do something like loop over a list of users, creating them, and allowing them to login by a certain set of
  95. SSH keys.
  96. How might that be accomplished? Let's assume you had the following defined and loaded in via "vars_files" or maybe a "group_vars/all" file::
  97. ---
  98. users:
  99. - name: alice
  100. authorized:
  101. - /tmp/alice/onekey.pub
  102. - /tmp/alice/twokey.pub
  103. - name: bob
  104. authorized:
  105. - /tmp/bob/id_rsa.pub
  106. It might happen like so::
  107. - user: name={{ item.name }} state=present generate_ssh_key=yes
  108. with_items: users
  109. - authorized_key: "user={{ item.0.name }} key='{{ lookup('file', item.1) }}'"
  110. with_subelements:
  111. - users
  112. - authorized
  113. Subelements walks a list of hashes (aka dictionaries) and then traverses a list with a given key inside of those
  114. records.
  115. The authorized_key pattern is exactly where it comes up most.
  116. .. _looping_over_integer_sequences:
  117. Looping over Integer Sequences
  118. ``````````````````````````````
  119. ``with_sequence`` generates a sequence of items in ascending numerical order. You
  120. can specify a start, end, and an optional step value.
  121. Arguments should be specified in key=value pairs. If supplied, the 'format' is a printf style string.
  122. Numerical values can be specified in decimal, hexadecimal (0x3f8) or octal (0600).
  123. Negative numbers are not supported. This works as follows::
  124. ---
  125. - hosts: all
  126. tasks:
  127. # create groups
  128. - group: name=evens state=present
  129. - group: name=odds state=present
  130. # create some test users
  131. - user: name={{ item }} state=present groups=evens
  132. with_sequence: start=0 end=32 format=testuser%02x
  133. # create a series of directories with even numbers for some reason
  134. - file: dest=/var/stuff/{{ item }} state=directory
  135. with_sequence: start=4 end=16 stride=2
  136. # a simpler way to use the sequence plugin
  137. # create 4 groups
  138. - group: name=group{{ item }} state=present
  139. with_sequence: count=4
  140. .. _random_choice:
  141. Random Choices
  142. ``````````````
  143. The 'random_choice' feature can be used to pick something at random. While it's not a load balancer (there are modules
  144. for those), it can somewhat be used as a poor man's loadbalancer in a MacGyver like situation::
  145. - debug: msg={{ item }}
  146. with_random_choice:
  147. - "go through the door"
  148. - "drink from the goblet"
  149. - "press the red button"
  150. - "do nothing"
  151. One of the provided strings will be selected at random.
  152. At a more basic level, they can be used to add chaos and excitement to otherwise predictable automation environments.
  153. .. _do_until_loops:
  154. Do-Until Loops
  155. ``````````````
  156. .. versionadded: 1.4
  157. Sometimes you would want to retry a task until a certain condition is met. Here's an example::
  158. - action: shell /usr/bin/foo
  159. register: result
  160. until: result.stdout.find("all systems go") != -1
  161. retries: 5
  162. delay: 10
  163. The above example run the shell module recursively till the module's result has "all systems go" in its stdout or the task has
  164. been retried for 5 times with a delay of 10 seconds. The default value for "retries" is 3 and "delay" is 5.
  165. The task returns the results returned by the last task run. The results of individual retries can be viewed by -vv option.
  166. The registered variable will also have a new key "attempts" which will have the number of the retries for the task.
  167. .. _with_first_found:
  168. Finding First Matched Files
  169. ```````````````````````````
  170. .. note:: This is an uncommon thing to want to do, but we're documenting it for completeness. You probably won't be reaching for this one often.
  171. This isn't exactly a loop, but it's close. What if you want to use a reference to a file based on the first file found
  172. that matches a given criteria, and some of the filenames are determined by variable names? Yes, you can do that as follows::
  173. - name: INTERFACES | Create Ansible header for /etc/network/interfaces
  174. template: src={{ item }} dest=/etc/foo.conf
  175. with_first_found:
  176. - "{{ansible_virtualization_type}}_foo.conf"
  177. - "default_foo.conf"
  178. This tool also has a long form version that allows for configurable search paths. Here's an example::
  179. - name: some configuration template
  180. template: src={{ item }} dest=/etc/file.cfg mode=0444 owner=root group=root
  181. with_first_found:
  182. - files:
  183. - "{{inventory_hostname}}/etc/file.cfg"
  184. paths:
  185. - ../../../templates.overwrites
  186. - ../../../templates
  187. - files:
  188. - etc/file.cfg
  189. paths:
  190. - templates
  191. .. _looping_over_the_results_of_a_program_execution:
  192. Iterating Over The Results of a Program Execution
  193. `````````````````````````````````````````````````
  194. .. note:: This is an uncommon thing to want to do, but we're documenting it for completeness. You probably won't be reaching for this one often.
  195. Sometimes you might want to execute a program, and based on the output of that program, loop over the results of that line by line.
  196. Ansible provides a neat way to do that, though you should remember, this is always executed on the control machine, not the local
  197. machine::
  198. - name: Example of looping over a command result
  199. shell: /usr/bin/frobnicate {{ item }}
  200. with_lines: /usr/bin/frobnications_per_host --param {{ inventory_hostname }}
  201. Ok, that was a bit arbitrary. In fact, if you're doing something that is inventory related you might just want to write a dynamic
  202. inventory source instead (see :doc:`intro_dynamic_inventory`), but this can be occasionally useful in quick-and-dirty implementations.
  203. Should you ever need to execute a command remotely, you would not use the above method. Instead do this::
  204. - name: Example of looping over a REMOTE command result
  205. shell: /usr/bin/something
  206. register: command_result
  207. - name: Do something with each result
  208. shell: /usr/bin/something_else --param {{ item }}
  209. with_items: command_result.stdout_lines
  210. .. _indexed_lists:
  211. Looping Over A List With An Index
  212. `````````````````````````````````
  213. .. note:: This is an uncommon thing to want to do, but we're documenting it for completeness. You probably won't be reaching for this one often.
  214. .. versionadded: 1.3
  215. If you want to loop over an array and also get the numeric index of where you are in the array as you go, you can also do that.
  216. It's uncommonly used::
  217. - name: indexed loop demo
  218. debug: msg="at array position {{ item.0 }} there is a value {{ item.1 }}"
  219. with_indexed_items: some_list
  220. .. _flattening_a_list:
  221. Flattening A List
  222. `````````````````
  223. .. note:: This is an uncommon thing to want to do, but we're documenting it for completeness. You probably won't be reaching for this one often.
  224. In rare instances you might have several lists of lists, and you just want to iterate over every item in all of those lists. Assume
  225. a really crazy hypothetical datastructure::
  226. ----
  227. # file: roles/foo/vars/main.yml
  228. packages_base:
  229. - [ 'foo-package', 'bar-package' ]
  230. packages_apps:
  231. - [ ['one-package', 'two-package' ]]
  232. - [ ['red-package'], ['blue-package']]
  233. As you can see the formatting of packages in these lists is all over the place. How can we install all of the packages in both lists?::
  234. - name: flattened loop demo
  235. yum: name={{ item }} state=installed
  236. with_flattened:
  237. - packages_base
  238. - packages_apps
  239. That's how!
  240. .. _using_register_with_a_loop:
  241. Using register with a loop
  242. ``````````````````````````
  243. When using ``register`` with a loop the data structure placed in the variable during a loop, will contain a ``results`` attribute, that is a list of all responses from the module.
  244. Here is an example of using ``register`` with ``with_items``::
  245. - shell: echo "{{ item }}"
  246. with_items:
  247. - one
  248. - two
  249. register: echo
  250. This differs from the data structure returned when using ``register`` without a loop::
  251. {
  252. "changed": true,
  253. "msg": "All items completed",
  254. "results": [
  255. {
  256. "changed": true,
  257. "cmd": "echo \"one\" ",
  258. "delta": "0:00:00.003110",
  259. "end": "2013-12-19 12:00:05.187153",
  260. "invocation": {
  261. "module_args": "echo \"one\"",
  262. "module_name": "shell"
  263. },
  264. "item": "one",
  265. "rc": 0,
  266. "start": "2013-12-19 12:00:05.184043",
  267. "stderr": "",
  268. "stdout": "one"
  269. },
  270. {
  271. "changed": true,
  272. "cmd": "echo \"two\" ",
  273. "delta": "0:00:00.002920",
  274. "end": "2013-12-19 12:00:05.245502",
  275. "invocation": {
  276. "module_args": "echo \"two\"",
  277. "module_name": "shell"
  278. },
  279. "item": "two",
  280. "rc": 0,
  281. "start": "2013-12-19 12:00:05.242582",
  282. "stderr": "",
  283. "stdout": "two"
  284. }
  285. ]
  286. }
  287. Subsequent loops over the registered variable to inspect the results may look like::
  288. - name: Fail if return code is not 0
  289. fail:
  290. msg: "The command ({{ item.cmd }}) did not have a 0 return code"
  291. when: item.rc != 0
  292. with_items: echo.results
  293. .. _writing_your_own_iterators:
  294. Writing Your Own Iterators
  295. ``````````````````````````
  296. While you ordinarily shouldn't have to, should you wish to write your own ways to loop over arbitrary datastructures, you can read :doc:`developing_plugins` for some starter
  297. information. Each of the above features are implemented as plugins in ansible, so there are many implementations to reference.
  298. .. seealso::
  299. :doc:`playbooks`
  300. An introduction to playbooks
  301. :doc:`playbooks_roles`
  302. Playbook organization by roles
  303. :doc:`playbooks_best_practices`
  304. Best practices in playbooks
  305. :doc:`playbooks_conditionals`
  306. Conditional statements in playbooks
  307. :doc:`playbooks_variables`
  308. All about variables
  309. `User Mailing List <http://groups.google.com/group/ansible-devel>`_
  310. Have a question? Stop by the google group!
  311. `irc.freenode.net <http://irc.freenode.net>`_
  312. #ansible IRC chat channel