ansible.builtin.url lookup – return contents from URL

Note

This lookup plugin is part of ansible-core and included in all Ansible installations. In most cases, you can use the short plugin name url even without specifying the collections: keyword. However, we recommend you use the FQCN for easy linking to the plugin documentation and to avoid conflicting with other collections that may have the same lookup plugin name.

New in version 1.9: of ansible.builtin

Synopsis

  • Returns the content of the URL requested to be used as data in play.

Parameters

Parameter

Comments

_terms

string

urls to query

ca_path

string

added in 2.10 of ansible.builtin

String of file system path to CA cert bundle to use

Configuration:

  • INI entry:

    [url_lookup]
ca_path = None

  • Environment variable: ANSIBLE_LOOKUP_URL_CA_PATH

  • Variable: ansible_lookup_url_ca_path

follow_redirects

string

added in 2.10 of ansible.builtin

String of urllib2, all/yes, safe, none to determine how redirects are followed, see RedirectHandlerFactory for more information

Default: “urllib2”

Configuration:

  • INI entry:

    [url_lookup]
follow_redirects = urllib2

  • Environment variable: ANSIBLE_LOOKUP_URL_FOLLOW_REDIRECTS

  • Variable: ansible_lookup_url_follow_redirects

force

boolean

added in 2.10 of ansible.builtin

Whether or not to set “cache-control” header with value “no-cache”

Choices:

  • no ← (default)

  • yes

Configuration:

  • INI entry:

    [url_lookup]
force = no

  • Environment variable: ANSIBLE_LOOKUP_URL_FORCE

  • Variable: ansible_lookup_url_force

force_basic_auth

boolean

added in 2.10 of ansible.builtin

Force basic authentication

Choices:

  • no ← (default)

  • yes

Configuration:

  • INI entry:

    [url_lookup]
agent = no

  • Environment variable: ANSIBLE_LOOKUP_URL_AGENT

  • Variable: ansible_lookup_url_agent

headers

dictionary

added in 2.9 of ansible.builtin

HTTP request headers

Default: {}

http_agent

string

added in 2.10 of ansible.builtin

User-Agent to use in the request. The default was changed in 2.11 to ansible-httpget.

Default: “ansible-httpget”

Configuration:

  • INI entry:

    [url_lookup]
agent = ansible-httpget

  • Environment variable: ANSIBLE_LOOKUP_URL_AGENT

  • Variable: ansible_lookup_url_agent

password

string

added in 2.8 of ansible.builtin

Password to use for HTTP authentication.

split_lines

boolean

Flag to control if content is returned as a list of lines or as a single text blob

Choices:

  • no

  • yes ← (default)

timeout

float

added in 2.10 of ansible.builtin

How long to wait for the server to send data before giving up

Default: 10

Configuration:

  • INI entry:

    [url_lookup]
timeout = 10

  • Environment variable: ANSIBLE_LOOKUP_URL_TIMEOUT

  • Variable: ansible_lookup_url_timeout

unix_socket

string

added in 2.10 of ansible.builtin

String of file system path to unix socket file to use when establishing connection to the provided url

Configuration:

  • INI entry:

    [url_lookup]
unix_socket = None

  • Environment variable: ANSIBLE_LOOKUP_URL_UNIX_SOCKET

  • Variable: ansible_lookup_url_unix_socket

unredirected_headers

list / elements=string

added in 2.10 of ansible.builtin

A list of headers to not attach on a redirected request

Configuration:

  • INI entry:

    [url_lookup]
unredirected_headers = None

  • Environment variable: ANSIBLE_LOOKUP_URL_UNREDIR_HEADERS

  • Variable: ansible_lookup_url_unredir_headers

use_gssapi

boolean

added in 2.10 of ansible.builtin

Use GSSAPI handler of requests

As of Ansible 2.11, GSSAPI credentials can be specified with username and password.

Choices:

  • no ← (default)

  • yes

Configuration:

  • INI entry:

    [url_lookup]
use_gssapi = no

  • Environment variable: ANSIBLE_LOOKUP_URL_USE_GSSAPI

  • Variable: ansible_lookup_url_use_gssapi

use_proxy

boolean

Flag to control if the lookup will observe HTTP proxy environment variables when present.

Choices:

  • no

  • yes ← (default)

username

string

added in 2.8 of ansible.builtin

Username to use for HTTP authentication.

validate_certs

boolean

Flag to control SSL certificate validation

Choices:

  • no

  • yes ← (default)

Examples

- name: url lookup splits lines by default
  debug: msg="{{item}}"
  loop: "{{ lookup('url', 'https://github.com/gremlin.keys', wantlist=True) }}"

- name: display ip ranges
  debug: msg="{{ lookup('url', 'https://ip-ranges.amazonaws.com/ip-ranges.json', split_lines=False) }}"

- name: url lookup using authentication
  debug: msg="{{ lookup('url', 'https://some.private.site.com/file.txt', username='bob', password='hunter2') }}"

- name: url lookup using basic authentication
  debug: msg="{{ lookup('url', 'https://some.private.site.com/file.txt', username='bob', password='hunter2', force_basic_auth='True') }}"

- name: url lookup using headers
  debug: msg="{{ lookup('url', 'https://some.private.site.com/api/service', headers={'header1':'value1', 'header2':'value2'} ) }}"

Return Values

Common return values are documented here, the following are the fields unique to this lookup:

Key

Description

_list

list / elements=string

list of list of lines or content of url(s)

Returned: success

Authors

  • Brian Coca (@bcoca)

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.