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. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.url for easy linking to the plugin documentation and to avoid conflicting with other collections that may have the same lookup plugin name.

Synopsis

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

Terms

Parameter

Comments

Terms

string

urls to query

Keyword parameters

This describes keyword parameters of the lookup. These are the values key1=value1, key2=value2 and so on in the following examples: lookup('ansible.builtin.url', key1=value1, key2=value2, ...) and query('ansible.builtin.url', key1=value1, key2=value2, ...)

Parameter

Comments

ca_path

string

added in ansible-base 2.10

String of file system path to CA cert bundle to use

Configuration:

ciphers

list / elements=string

added in ansible-core 2.14

SSL/TLS Ciphers to use for the request

When a list is provided, all ciphers are joined in order with :

See the OpenSSL Cipher List Format for more details.

The available ciphers is dependent on the Python and OpenSSL/LibreSSL versions

Configuration:

follow_redirects

string

added in ansible-base 2.10

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

Default: "urllib2"

Configuration:

force

boolean

added in ansible-base 2.10

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

Choices:

  • false ← (default)

  • true

Configuration:

  • INI entry:

    [url_lookup]
force = false

  • Environment variable: ANSIBLE_LOOKUP_URL_FORCE

  • Variable: ansible_lookup_url_force

force_basic_auth

boolean

added in ansible-base 2.10

Force basic authentication

Choices:

  • false ← (default)

  • true

Configuration:

headers

dictionary

added in Ansible 2.9

HTTP request headers

Default: {}

http_agent

string

added in ansible-base 2.10

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 Ansible 2.8

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:

  • false

  • true ← (default)

timeout

float

added in ansible-base 2.10

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

Default: 10.0

Configuration:

unix_socket

string

added in ansible-base 2.10

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

Configuration:

unredirected_headers

list / elements=string

added in ansible-base 2.10

A list of headers to not attach on a redirected request

Configuration:

use_gssapi

boolean

added in ansible-base 2.10

Use GSSAPI handler of requests

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

Choices:

  • false ← (default)

  • true

Configuration:

use_netrc

boolean

added in ansible-core 2.14

Determining whether to use credentials from ``~/.netrc`` file

By default .netrc is used with Basic authentication headers

When set to False, .netrc credentials are ignored

Choices:

  • false

  • true ← (default)

Configuration:

use_proxy

boolean

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

Choices:

  • false

  • true ← (default)

username

string

added in Ansible 2.8

Username to use for HTTP authentication.

validate_certs

boolean

Flag to control SSL certificate validation

Choices:

  • false

  • true ← (default)

Notes

Note

  • When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters: lookup('ansible.builtin.url', term1, term2, key1=value1, key2=value2) and query('ansible.builtin.url', term1, term2, key1=value1, key2=value2)

Examples

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

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

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

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

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

Return Value

Key

Description

Return value

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.