/docsite/rst/playbooks_lookups.rst

  1Using Lookups
  2=============
  3
  4Lookup plugins allow access of data in Ansible from outside sources.  These plugins are evaluated on the Ansible control
  5machine, and can include reading the filesystem but also contacting external datastores and services.  
  6These values are then made available using the standard templating system
  7in Ansible, and are typically used to load variables or templates with information from those systems.
  8
  9.. note:: This is considered an advanced feature, and many users will probably not rely on these features.  
 10
 11.. note:: Lookups occur on the local computer, not on the remote computer.
 12
 13.. contents:: Topics
 14
 15.. _getting_file_contents:
 16
 17Intro to Lookups: Getting File Contents
 18```````````````````````````````````````
 19
 20The file lookup is the most basic lookup type.
 21
 22Contents can be read off the filesystem as follows::
 23
 24    - hosts: all
 25      vars:
 26         contents: "{{ lookup('file', '/etc/foo.txt') }}"
 27
 28      tasks:
 29
 30         - debug: msg="the value of foo.txt is {{ contents }}"
 31
 32.. _password_lookup:
 33
 34The Password Lookup
 35```````````````````
 36
 37.. note::
 38
 39    A great alternative to the password lookup plugin, if you don't need to generate random passwords on a per-host basis, would be to use :doc:`playbooks_vault`.  Read the documentation there and consider using it first, it will be more desirable for most applications.
 40
 41``password`` generates a random plaintext password and stores it in
 42a file at a given filepath.  
 43
 44(Docs about crypted save modes are pending)
 45 
 46If the file exists previously, it will retrieve its contents, behaving just like with_file. Usage of variables like "{{ inventory_hostname }}" in the filepath can be used to set
 47up random passwords per host (what simplifies password management in 'host_vars' variables).
 48
 49Generated passwords contain a random mix of upper and lowercase ASCII letters, the
 50numbers 0-9 and punctuation (". , : - _"). The default length of a generated password is 20 characters.
 51This length can be changed by passing an extra parameter::
 52
 53    ---
 54    - hosts: all
 55
 56      tasks:
 57
 58        # create a mysql user with a random password:
 59        - mysql_user: name={{ client }}
 60                      password="{{ lookup('password', 'credentials/' + client + '/' + tier + '/' + role + '/mysqlpassword length=15') }}"
 61                      priv={{ client }}_{{ tier }}_{{ role }}.*:ALL
 62
 63        (...)
 64
 65.. note:: If the file already exists, no data will be written to it. If the file has contents, those contents will be read in as the password. Empty files cause the password to return as an empty string        
 66
 67Starting in version 1.4, password accepts a "chars" parameter to allow defining a custom character set in the generated passwords. It accepts comma separated list of names that are either string module attributes (ascii_letters,digits, etc) or are used literally::
 68
 69    ---
 70    - hosts: all
 71
 72      tasks:
 73
 74        # create a mysql user with a random password using only ascii letters:
 75        - mysql_user: name={{ client }}
 76                      password="{{ lookup('password', '/tmp/passwordfile chars=ascii_letters') }}"
 77                      priv={{ client }}_{{ tier }}_{{ role }}.*:ALL
 78
 79        # create a mysql user with a random password using only digits:
 80        - mysql_user: name={{ client }}
 81                      password="{{ lookup('password', '/tmp/passwordfile chars=digits') }}"
 82                      priv={{ client }}_{{ tier }}_{{ role }}.*:ALL
 83
 84        # create a mysql user with a random password using many different char sets:
 85        - mysql_user: name={{ client }}
 86                      password="{{ lookup('password', '/tmp/passwordfile chars=ascii_letters,digits,hexdigits,punctuation') }}"
 87                      priv={{ client }}_{{ tier }}_{{ role }}.*:ALL
 88
 89        (...)
 90
 91To enter comma use two commas ',,' somewhere - preferably at the end. Quotes and double quotes are not supported.
 92
 93.. _more_lookups:
 94
 95More Lookups
 96````````````
 97
 98.. note:: This feature is very infrequently used in Ansible.  You may wish to skip this section.
 99
100.. versionadded:: 0.8
101
102Various *lookup plugins* allow additional ways to iterate over data.  In :doc:`Loops <playbooks_loops>` you will learn
103how to use them to walk over collections of numerous types.  However, they can also be used to pull in data
104from remote sources, such as shell commands or even key value stores. This section will cover lookup
105plugins in this capacity.
106
107Here are some examples::
108
109    ---
110    - hosts: all
111
112      tasks:
113
114         - debug: msg="{{ lookup('env','HOME') }} is an environment variable"
115
116         - debug: msg="{{ item }} is a line from the result of this command"
117           with_lines:
118             - cat /etc/motd
119
120         - debug: msg="{{ lookup('pipe','date') }} is the raw result of running this command"
121
122         - debug: msg="{{ lookup('redis_kv', 'redis://localhost:6379,somekey') }} is value in Redis for somekey"
123
124         - debug: msg="{{ lookup('dnstxt', 'example.com') }} is a DNS TXT record for example.com"
125
126         - debug: msg="{{ lookup('template', './some_template.j2') }} is a value from evaluation of this template"
127
128As an alternative you can also assign lookup plugins to variables or use them
129elsewhere.  This macros are evaluated each time they are used in a task (or
130template)::
131
132    vars:
133      motd_value: "{{ lookup('file', '/etc/motd') }}"
134
135    tasks:
136
137      - debug: msg="motd value is {{ motd_value }}"
138
139.. seealso::
140
141   :doc:`playbooks`
142       An introduction to playbooks
143   :doc:`playbooks_conditionals`
144       Conditional statements in playbooks
145   :doc:`playbooks_variables`
146       All about variables
147   :doc:`playbooks_loops`
148       Looping in playbooks
149   `User Mailing List <http://groups.google.com/group/ansible-devel>`_
150       Have a question?  Stop by the google group!
151   `irc.freenode.net <http://irc.freenode.net>`_
152       #ansible IRC chat channel
153
154
155