Working with Lookup Plugins

1. Understanding Lookup Plugins

Property	Description	Usage
lookup	Plugin to retrieve data from external sources	`lookup('file', '/path/to/file')`
plugin	Name of the lookup plugin to use	`lookup('env', 'HOME')`
args	Arguments passed to the lookup plugin	`lookup('template', 'vars.j2')`

Example: Using lookup plugin to read a file

- name: Read file content
  set_fact:
    file_content: "{{ lookup('file', '/etc/passwd') }}"

Example: Using lookup plugin to get environment variable

- name: Get environment variable
  set_fact:
    home_dir: "{{ lookup('env', 'HOME') }}"

Note: Lookup plugins are used to fetch data from external sources like files, environment variables, databases, or APIs.

2. Reading Files

Option	Values	Description
ansible.builtin.lookup	`file`	Plugin to read file contents into a variable
file_path	`path/to/file.txt`	Path to the file to read

Example: Reading a File

- name: Read contents of a file
  debug:
    msg: "{{ lookup('file', '/etc/passwd') }}"

Example: Reading a File with Line-by-Line Processing

- name: Read file line by line
  debug:
    msg: "Line: {{ item }}"
  loop: "{{ lookup('file', '/etc/hosts').splitlines() }}"

Note: The file lookup plugin reads the entire file content into memory. For large files, consider using slurp or template plugins.

3. Using Environment Variables

Variable	Description	Usage
ansible_env	Dictionary of environment variables available to Ansible	`ansible_env.HOME`
env	Lookup plugin to get environment variables	`{{ lookup('env', 'PATH') }}`

Example: Retrieving Environment Variables

- name: "Get PATH from environment"
  debug:
    msg: "PATH is {{ lookup('env', 'PATH') }}"

Note: Environment variables are read-only and cannot be modified directly in Ansible playbooks.

4. Reading Templates

Property	Description	Example
lookup('template')	Reads a template file and renders it with Jinja2	`lookup('template', 'my_template.j2')`
template	Path to the template file (relative to `templates/` directory)	`template: user_config.j2`

Example: Reading a Jinja2 Template

- name: Read rendered template
  set_fact:
    config_content: "{{ lookup('template', 'config.j2') }}"

Note: Template files must be placed in the templates/ directory of your Ansible project.

Example: Using Template Variables

- name: Render template with variables
  set_fact:
    rendered_output: "{{ lookup('template', 'app_config.j2') }}"
  vars:
    app_name: "myapp"
    version: "1.0.0"

5. Querying Passwords

Lookup Plugin	Parameters	Description
passwordstore	`path`, `key`	Retrieve passwords from a password store (e.g., GNU Pass). NEW in Ansible 2.15
vault	`key`, `backend`	Retrieve values from Ansible Vault. Supports multiple backends like `hashivault`.

Example: Using passwordstore lookup

- name: Retrieve password from pass
  debug:
    msg: "Password is {{ lookup('passwordstore', 'user/password') }}"

Example: Using vault lookup

- name: Retrieve secret from vault
  debug:
    msg: "Secret is {{ lookup('vault', 'secret_key') }}"

Note: The passwordstore lookup requires the pass command-line tool to be installed and configured.

Warning: Never store passwords in plain text within your playbooks or inventories. Always use secure lookup plugins or vaults.

6. Using Key-Value Stores

Plugin	Description	Usage Example	Notes
lookup('kv')	Retrieves values from a key-value store (e.g., Consul, etcd, Vault)	`- name: Retrieve secret from Vault debug: msg: "{{ lookup('kv', 'secret/myapp/password') }}"`	Requires Vault or compatible backend configured in Ansible inventory
lookup('consul')	Fetches data from Consul KV store	`- name: Fetch config from Consul debug: msg: "{{ lookup('consul', 'config/app/setting') }}"`	Supports token-based authentication and TLS
lookup('etcd')	Retrieves values from etcd key-value store	`- name: Get value from etcd debug: msg: "{{ lookup('etcd', 'service/config') }}"`	Supports secure connections via TLS and authentication

Example: Using Vault Lookup Plugin

- name: Fetch sensitive data from HashiCorp Vault
  set_fact:
    api_key: "{{ lookup('hashi_vault', 'secret/data/api_keys key=api_key') }}"
  vars:
    ansible_hashi_vault_url: "https://vault.example.com"
    ansible_hashi_vault_token: "{{ vault_token }}"

Note: Ensure that the Vault token or authentication method is properly configured in inventory or environment variables.

Warning: Never hardcode secrets in playbooks. Use Vault or similar tools for secure secret management.

7. Reading URLs

Option	Values	Description
url	`https://example.com/data.json`	The URL to read data from
method	`GET`	HTTP method to use (GET, POST, etc.)
headers	`{"Authorization": "Bearer token123"}`	HTTP headers to include in the request
timeout	`30`	Timeout in seconds for the request

Example: Fetching JSON from a URL

- name: Fetch JSON from URL
  set_fact:
    api_data: "{{ lookup('url', 'https://api.example.com/data.json', headers={'Authorization': 'Bearer token123'}, timeout=30) }}"

Note: The url lookup plugin supports both HTTP and HTTPS protocols. It can be used to fetch data from REST APIs, configuration files, or any other resource accessible via a URL.

8. Using Pipe Lookup

The pipe lookup plugin in Ansible allows you to execute shell commands and capture their output directly within your playbooks. It's particularly useful for retrieving dynamic information or executing one-off commands that return structured data.

Parameter	Description	Default
cmd	The shell command to execute. This must be a valid command that can be run in the local shell.	None
shell	Whether to use the shell (e.g., `sh`, `bash`) to execute the command. If set to `false`, the command is executed directly.	`true`

Example: Using Pipe Lookup to Get Hostname

- name: Get hostname using pipe lookup
  hosts: localhost
  tasks:
    - name: Capture hostname from shell command
      debug:
        msg: "Hostname is {{ lookup('pipe', 'hostname') }}"

Example: Using Pipe Lookup with Complex Command

- name: Execute complex command using pipe lookup
  hosts: localhost
  tasks:
    - name: Get system uptime and parse it
      debug:
        msg: "System Uptime: {{ lookup('pipe', 'uptime | awk -F, \'{print $1}\'') }}"

Note: The pipe lookup executes commands on the Ansible control node, so ensure that any command you run is safe and does not pose a security risk.

9. Querying DNS

Lookup	Description	Parameters	Example
dns	Queries DNS records for a given hostname or IP address.	`record`, `type`, `server`	`{{ lookup('dns', 'example.com', type='A') }}`
dig	Uses the `dig` command-line tool to query DNS records.	`record`, `type`, `server`	`{{ lookup('dig', 'example.com', type='MX') }}`

Example: Querying A Records

- name: Get IP address of example.com
  set_fact:
    ip_address: "{{ lookup('dns', 'example.com', type='A') }}"

Example: Querying MX Records

- name: Get MX records for example.com
  set_fact:
    mx_records: "{{ lookup('dig', 'example.com', type='MX') }}"

10. Reading CSV Files

Option	Values	Description
file	`data.csv`	Path to the CSV file to read
delimiter	`,`	Delimiter used in the CSV file (default is comma)
quotechar	`"`	Character used to quote fields (default is double quote)
fieldnames	`name,age,city`	List of column names to use as keys (optional)

Example: Reading CSV Data

- name: Read CSV file
  set_fact:
    csv_data: "{{ lookup('csvfile', 'name=city file=data.csv delimiter=,') }}"

Example: Using CSV Data in a Loop

- name: Loop through CSV entries
  debug:
    msg: "City: {{ item.city }}, Age: {{ item.age }}"
  loop: "{{ lookup('csvfile', 'file=data.csv delimiter=,') }}"

11. Using Sequence Lookup

Option	Values	Notes
seq	`1,2,3,4,5`	Comma-separated sequence of numbers or strings
start	`0`	Starting value of the sequence (default: 0)
end	`10`	Ending value of the sequence (inclusive)
step	`1`	Increment between values (default: 1)

Example: Basic sequence usage

- name: "Print sequence from 1 to 5"
  debug:
    msg: "{{ lookup('sequence', '1,2,3,4,5') }}"

Example: Generate a range of numbers

- name: "Generate a list of numbers from 0 to 10"
  debug:
    msg: "{{ lookup('sequence', 'start=0, end=10') }}"

Example: Create a sequence with custom step

- name: "Create a sequence with step 2"
  debug:
    msg: "{{ lookup('sequence', 'start=0, end=10, step=2') }}"

12. Using ini Lookup

Option	Values	Notes
ini_file	`config.ini`	Path to the INI file to read from
section	`database`	Name of the section to read from
key	`host`	Name of the key to retrieve

Example: Reading a database host from an INI file

- name: Read database host from INI
  hosts: localhost
  tasks:
    - name: Get database host
      set_fact:
        db_host: "{{ lookup('ini', 'host section=database file=config.ini') }}"