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
Terms
Keyword parameters
Notes
Examples
Return Value

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: INI entry: [url_lookup] ca_path = VALUE Environment variable: `ANSIBLE_LOOKUP_URL_CA_PATH` Variable: ansible_lookup_url_ca_path
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: INI entry: [url_lookup] ciphers = VALUE Environment variable: `ANSIBLE_LOOKUP_URL_CIPHERS` Variable: ansible_lookup_url_ciphers
follow_redirects string added in ansible-base 2.10	String of urllib2, all/yes, safe, none to determine how redirects are followed Choices: `"all"`: Will follow all redirects. `"no"`: (DEPRECATED, will be removed in the future version) alias of `none`. `"none"`: Will not follow any redirects. `"safe"`: Only redirects doing GET or HEAD requests will be followed. `"urllib2"` (default): Defer to urllib2 behavior (As of writing this follows HTTP redirects). `"yes"`: (DEPRECATED, will be removed in the future version) alias of `all`. 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 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: INI entry: [url_lookup] force_basic_auth = false Environment variable: `ANSIBLE_LOOKUP_URL_FORCE_BASIC_AUTH` Variable: ansible_lookup_url_force_basic_auth
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: INI entry: [url_lookup] timeout = 10.0 Environment variable: `ANSIBLE_LOOKUP_URL_TIMEOUT` Variable: ansible_lookup_url_timeout
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: INI entry: [url_lookup] unix_socket = VALUE Environment variable: `ANSIBLE_LOOKUP_URL_UNIX_SOCKET` Variable: ansible_lookup_url_unix_socket
unredirected_headers list / elements=string added in ansible-base 2.10	A list of headers to not attach on a redirected request Configuration: INI entry: [url_lookup] unredirected_headers = VALUE Environment variable: `ANSIBLE_LOOKUP_URL_UNREDIR_HEADERS` Variable: ansible_lookup_url_unredir_headers
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: INI entry: [url_lookup] use_gssapi = false Environment variable: `ANSIBLE_LOOKUP_URL_USE_GSSAPI` Variable: ansible_lookup_url_use_gssapi
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: INI entry: [url_lookup] use_netrc = true Environment variable: `ANSIBLE_LOOKUP_URL_USE_NETRC` Variable: ansible_lookup_url_use_netrc
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.

Collection links

© 2012–2018 Michael DeHaan
© 2018–2024 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/ansible/builtin/url_lookup.html