2013-09-30 01:10:28 +02:00
Using Lookups
=============
2012-05-13 17:00:02 +02:00
2014-04-29 22:49:15 +02:00
Lookup plugins allow access of data in Ansible from outside sources. These plugins are evaluated on the Ansible control
2015-02-20 00:15:10 +01:00
machine, and can include reading the filesystem but also contacting external datastores and services.
2014-04-29 22:49:15 +02:00
These values are then made available using the standard templating system
2013-10-03 04:06:56 +02:00
in Ansible, and are typically used to load variables or templates with information from those systems.
2012-05-13 17:00:02 +02:00
2015-02-20 00:15:10 +01:00
.. note :: This is considered an advanced feature, and many users will probably not rely on these features.
2012-08-28 21:41:10 +02:00
2014-03-16 01:43:10 +01:00
.. note :: Lookups occur on the local computer, not on the remote computer.
2015-02-20 00:15:10 +01:00
.. note :: Since 1.9 you can pass wantlist=True to lookups to use in jinja2 template "for" loops.
2013-12-26 20:32:01 +01:00
.. contents :: Topics
2013-10-05 00:41:14 +02:00
.. _getting_file_contents:
2013-09-30 00:44:46 +02:00
Intro to Lookups: Getting File Contents
`` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ``
2012-08-01 04:19:04 +02:00
2013-09-30 00:44:46 +02:00
The file lookup is the most basic lookup type.
2012-05-13 17:00:02 +02:00
2013-09-30 00:44:46 +02:00
Contents can be read off the filesystem as follows::
2012-05-13 17:00:02 +02:00
- hosts: all
vars:
2013-09-30 00:44:46 +02:00
contents: "{{ lookup('file', '/etc/foo.txt') }}"
2014-02-28 20:18:44 +01:00
2012-08-01 04:19:04 +02:00
tasks:
2014-02-28 20:18:44 +01:00
2013-09-30 00:44:46 +02:00
- debug: msg="the value of foo.txt is {{ contents }}"
2013-05-31 22:07:40 +02:00
2013-10-05 00:41:14 +02:00
.. _password_lookup:
2013-09-30 00:44:46 +02:00
The Password Lookup
2012-08-03 04:08:00 +02:00
`` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ``
2012-05-13 17:00:02 +02:00
2014-02-27 23:44:21 +01:00
.. note ::
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.
`` password `` generates a random plaintext password and stores it in
a file at a given filepath.
(Docs about crypted save modes are pending)
If 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
2013-09-30 00:44:46 +02:00
up random passwords per host (what simplifies password management in 'host_vars' variables).
2012-05-13 17:00:02 +02:00
2013-09-30 00:44:46 +02:00
Generated passwords contain a random mix of upper and lowercase ASCII letters, the
2013-11-07 22:45:52 +01:00
numbers 0-9 and punctuation (". , : - _"). The default length of a generated password is 20 characters.
2013-09-30 00:44:46 +02:00
This length can be changed by passing an extra parameter::
2012-05-13 17:00:02 +02:00
---
- hosts: all
2013-09-30 00:44:46 +02:00
tasks:
2012-05-13 17:00:02 +02:00
2013-09-30 00:44:46 +02:00
# create a mysql user with a random password:
- mysql_user: name={{ client }}
password="{{ lookup('password', 'credentials/' + client + '/' + tier + '/' + role + '/mysqlpassword length=15') }}"
priv={{ client }}_{{ tier }}_{{ role }}.*:ALL
2012-05-13 17:00:02 +02:00
2013-09-30 00:44:46 +02:00
(...)
2012-10-17 00:58:31 +02:00
2013-11-07 22:45:52 +01:00
.. 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
2013-11-11 20:54:11 +01:00
Starting 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::
---
- hosts: all
tasks:
# create a mysql user with a random password using only ascii letters:
- mysql_user: name={{ client }}
2014-06-17 12:57:29 +02:00
password="{{ lookup('password', '/tmp/passwordfile chars=ascii_letters') }}"
2013-11-11 20:54:11 +01:00
priv={{ client }}_{{ tier }}_{{ role }}.*:ALL
# create a mysql user with a random password using only digits:
- mysql_user: name={{ client }}
2013-11-12 14:54:19 +01:00
password="{{ lookup('password', '/tmp/passwordfile chars=digits') }}"
2013-11-11 20:54:11 +01:00
priv={{ client }}_{{ tier }}_{{ role }}.*:ALL
# create a mysql user with a random password using many different char sets:
- mysql_user: name={{ client }}
2014-06-17 12:58:07 +02:00
password="{{ lookup('password', '/tmp/passwordfile chars=ascii_letters,digits,hexdigits,punctuation') }}"
2013-11-11 20:54:11 +01:00
priv={{ client }}_{{ tier }}_{{ role }}.*:ALL
(...)
2013-11-16 23:01:26 +01:00
To enter comma use two commas ',,' somewhere - preferably at the end. Quotes and double quotes are not supported.
2013-11-11 20:54:11 +01:00
2013-10-05 00:41:14 +02:00
.. _more_lookups:
2012-10-17 00:58:31 +02:00
2013-09-30 00:44:46 +02:00
More Lookups
2013-07-15 06:28:02 +02:00
`` ` ` ` ` ` ` ` ` ``
2013-12-08 22:05:42 +01:00
Various *lookup plugins* allow additional ways to iterate over data. In :doc: `Loops <playbooks_loops>` you will learn
2013-09-30 00:44:46 +02:00
how to use them to walk over collections of numerous types. However, they can also be used to pull in data
from remote sources, such as shell commands or even key value stores. This section will cover lookup
plugins in this capacity.
2013-06-14 17:13:38 +02:00
2013-09-30 00:44:46 +02:00
Here are some examples::
2013-02-02 17:51:25 +01:00
---
- hosts: all
tasks:
2013-07-15 19:50:48 +02:00
- debug: msg="{{ lookup('env','HOME') }} is an environment variable"
2013-02-02 17:51:25 +01:00
2013-07-15 19:50:48 +02:00
- debug: msg="{{ item }} is a line from the result of this command"
2013-02-02 17:51:25 +01:00
with_lines:
- cat /etc/motd
2013-07-15 19:50:48 +02:00
- debug: msg="{{ lookup('pipe','date') }} is the raw result of running this command"
2013-02-02 17:51:25 +01:00
2015-02-16 04:37:58 +01:00
# redis_kv lookup requires the Python redis package
2013-07-15 19:50:48 +02:00
- debug: msg="{{ lookup('redis_kv', 'redis://localhost:6379,somekey') }} is value in Redis for somekey"
2013-02-02 17:51:25 +01:00
2015-01-25 21:20:49 +01:00
# dnstxt lookup requires the Python dnspython package
2013-07-15 19:50:48 +02:00
- debug: msg="{{ lookup('dnstxt', 'example.com') }} is a DNS TXT record for example.com"
2013-02-02 17:51:25 +01:00
2013-07-15 19:50:48 +02:00
- debug: msg="{{ lookup('template', './some_template.j2') }} is a value from evaluation of this template"
2012-10-17 00:51:10 +02:00
2014-10-02 22:45:46 +02:00
- debug: msg="{{ lookup('etcd', 'foo') }} is a value from a locally running etcd"
2015-02-20 15:06:17 +01:00
# The following lookups were added in 1.9
2015-01-27 23:48:39 +01:00
- debug: msg="{{item}}"
2015-01-27 23:25:55 +01:00
with_url:
- 'http://github.com/gremlin.keys'
2015-02-20 15:06:17 +01:00
# outputs the cartesian product of the supplied lists
- debug: msg="{{item}}"
with_cartesian:
- list1
- list2
- list3
2013-04-05 19:00:23 +02:00
As an alternative you can also assign lookup plugins to variables or use them
elsewhere. This macros are evaluated each time they are used in a task (or
2013-04-21 04:48:20 +02:00
template)::
2013-02-02 18:19:21 +01:00
vars:
2013-04-13 00:21:09 +02:00
motd_value: "{{ lookup('file', '/etc/motd') }}"
2013-02-02 18:56:56 +01:00
2013-02-02 18:19:21 +01:00
tasks:
2014-02-28 20:18:44 +01:00
2013-04-13 00:21:09 +02:00
- debug: msg="motd value is {{ motd_value }}"
2013-02-02 18:19:21 +01:00
2013-10-05 18:31:16 +02:00
.. seealso ::
:doc: `playbooks`
An introduction to playbooks
:doc: `playbooks_conditionals`
Conditional statements in playbooks
:doc: `playbooks_variables`
All about variables
:doc: `playbooks_loops`
Looping in playbooks
`User Mailing List <http://groups.google.com/group/ansible-devel> `_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net> `_
#ansible IRC chat channel