Lookups ¶

Lookup plugins allow access of data in Ansible from outside sources. Like all templating, these plugins are evaluated on the Ansible control machine, and can include reading the filesystem but also contacting external datastores and services. These values are then made available using the standard templating system in Ansible, and are typically used to load variables or templates with information from those systems.

注解

This is considered an advanced feature, and many users will probably not rely on these features.

注解

Lookups occur on the local computer, not on the remote computer.

注解

Lookups are executed with a cwd relative to the role or play, as opposed to local tasks which are executed with the cwd of the executed script.

注解

Since 1.9 you can pass wantlist=True to lookups to use in jinja2 template “for” loops.

警告

Some lookups pass arguments to a shell. When using variables from a remote/untrusted source, use the |quote filter to ensure safe usage.

Topics

Lookups
Examples

Intro to Lookups: Getting File Contents ¶

The file lookup is the most basic lookup type.

Contents can be read off the filesystem as follows:

---
- hosts: all
  vars:
     contents: "{{ lookup('file', '/etc/foo.txt') }}"

  tasks:

     - debug: msg="the value of foo.txt is {{ contents }}"

The Password Lookup ¶

注解

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 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 up random passwords per host (which simplifies password management in ‘host_vars’ variables).

A special case is using /dev/null as a path. The password lookup will generate a new random password each time, but will not write it to /dev/null. This can be used when you need a password without storing it on the controller.

Generated passwords contain a random mix of upper and lowercase ASCII letters, the numbers 0-9 and punctuation (”. , : - _”). The default length of a generated password is 20 characters. This length can be changed by passing an extra parameter:

---
- hosts: all

  tasks:

    - name: 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"

    # (...)

注解

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.

Caution: Since this runs on the ansible host as the user running the playbook, and “become” does not apply, the target file must be readable by the playbook user, or, if it does not exist, the playbook user must have sufficient privileges to create it. (So, for example, attempts to write into areas such as /etc will fail unless the entire playbook is being run as root).

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:

    - name: create a mysql user with a random password using only ascii letters
      mysql_user: name={{ client }} password="{{ lookup('password', '/tmp/passwordfile chars=ascii_letters') }}" priv={{ client }}_{{ tier }}_{{ role }}.*:ALL

    - name: create a mysql user with a random password using only digits
      mysql_user:
        name: "{{ client }}"
        password: "{{ lookup('password', '/tmp/passwordfile chars=digits') }}"
        priv: "{{ client }}_{{ tier }}_{{ role }}.*:ALL"

    - name: create a mysql user with a random password using many different char sets
      mysql_user:
        name: "{{ client }}"
        password" "{{ lookup('password', '/tmp/passwordfile chars=ascii_letters,digits,hexdigits,punctuation') }}"
        priv: "{{ client }}_{{ tier }}_{{ role }}.*:ALL"

    # (...)

To enter comma use two commas ‘,,’ somewhere - preferably at the end. Quotes and double quotes are not supported.

The Passwordstore Lookup ¶

2.3 新版功能.

The passwordstore lookup enables Ansible to retrieve, create or update passwords from the passwordstore.org pass utility. It also retrieves YAML style keys stored as multilines in the passwordfile.

Field	Default	Description
file	ansible.csv	Name of the file to load
col	1	The column to output, indexed by 0
delimiter	TAB	Delimiter used by CSV file. As a special case, tab can be specified as either TAB or t.
default	empty string	Default return value if the key is not in the csv file
encoding	utf-8	Encoding (character set) of the used CSV file (added in version 2.1)

Field	Default	Description
type	ini	Type of the file. Can be ini or properties (for java properties).
file	ansible.ini	Name of the file to load
section	global	Default section where to lookup for key.
re	False	The key is a regexp.
default	empty string	return value if the key is not in the ini file

Record	Fields
ALL	owner, ttl, type
A	address
AAAA	address
CNAME	target
DNAME	target
DLV	algorithm, digest_type, key_tag, digest
DNSKEY	flags, algorithm, protocol, key
DS	algorithm, digest_type, key_tag, digest
HINFO	cpu, os
LOC	latitude, longitude, altitude, size, horizontal_precision, vertical_precision
MX	preference, exchange
NAPTR	order, preference, flags, service, regexp, replacement
NS	target
NSEC3PARAM	algorithm, flags, iterations, salt
PTR	target
RP	mbox, txt
SOA	mname, rname, serial, refresh, retry, expire, minimum
SPF	strings
SRV	priority, weight, port, target
SSHFP	algorithm, fp_type, fingerprint
TLSA	usage, selector, mtype, cert
TXT	strings

Parameter	Mandatory	Type	Default Value	Comment
connection_string	no	string	mongodb://localhost/	Can be any valid MongoDB connection string, supporting authentication, replicasets, etc. More info at https://docs.mongodb.org/manual/reference/connection-string/
extra_connection_parameters	no	dict	{}	Dictionary with extra parameters like ssl, ssl_keyfile, maxPoolSize etc... Check the full list here: https://api.mongodb.org/python/current/api/pymongo/mongo_client.html#pymongo.mongo_client.MongoClient
database	yes	string		Name of the database which the query will be made
collection	yes	string		Name of the collection which the query will be made
filter	no	dict	[pymongo default]	Criteria of the output Example: { “hostname”: “batman” }
projection	no	dict	[pymongo default]	Fields you want returned. Example: { “pid”: True , “_id” : False , “hostname” : True }
skip	no	integer	[pymongo default]	How many results should be skept
limit	no	integer	[pymongo default]	How many results should be shown
sort	no	list	[pymongo default]	Sorting rules. Please notice the constats are replaced by strings. [ [ “startTime” , “ASCENDING” ] , [ “age”, “DESCENDING” ] ]
[any find() parameter]	no	[any]	[pymongo default]	Every parameter with exception to connection_string, database and collection are passed to pymongo directly.

Lookups ¶

Intro to Lookups: Getting File Contents ¶

The Password Lookup ¶

The Passwordstore Lookup ¶

Examples ¶

The CSV File Lookup ¶

The INI File Lookup ¶

The Credstash Lookup ¶

The DNS Lookup (dig)¶

MongoDB Lookup ¶

More Lookups ¶