ansible.builtin.url – return contents from URL

Note

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

New in version 1.9: of ansible.builtin

Synopsis
Parameters
Examples
Return Values

Synopsis

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

Parameters

Parameter	Choices/Defaults	Configuration	Comments
_terms string			urls to query
ca_path string added in 2.10 of ansible.builtin		ini entries: [url_lookup]ca_path = None env:ANSIBLE_LOOKUP_URL_CA_PATH var: ansible_lookup_url_ca_path	String of file system path to CA cert bundle to use
follow_redirects string added in 2.10 of ansible.builtin	Default: "urllib2"	ini entries: [url_lookup]follow_redirects = urllib2 env:ANSIBLE_LOOKUP_URL_FOLLOW_REDIRECTS var: ansible_lookup_url_follow_redirects	String of urllib2, all/yes, safe, none to determine how redirects are followed, see RedirectHandlerFactory for more information
force boolean added in 2.10 of ansible.builtin	no ← yes	ini entries: [url_lookup]force = no env:ANSIBLE_LOOKUP_URL_FORCE var: ansible_lookup_url_force	Whether or not to set "cache-control" header with value "no-cache"
force_basic_auth boolean added in 2.10 of ansible.builtin	no ← yes	ini entries: [url_lookup]agent = no env:ANSIBLE_LOOKUP_URL_AGENT var: ansible_lookup_url_agent	Force basic authentication
headers dictionary added in 2.9 of ansible.builtin	Default: {}		HTTP request headers
http_agent string added in 2.10 of ansible.builtin	Default: "ansible-httpget"	ini entries: [url_lookup]agent = ansible-httpget env:ANSIBLE_LOOKUP_URL_AGENT var: ansible_lookup_url_agent	User-Agent to use in the request. The default was changed in 2.11 to `ansible-httpget`.
password string added in 2.8 of ansible.builtin			Password to use for HTTP authentication.
split_lines boolean	no yes ←		Flag to control if content is returned as a list of lines or as a single text blob
timeout float added in 2.10 of ansible.builtin	Default: 10	ini entries: [url_lookup]timeout = 10 env:ANSIBLE_LOOKUP_URL_TIMEOUT var: ansible_lookup_url_timeout	How long to wait for the server to send data before giving up
unix_socket string added in 2.10 of ansible.builtin		ini entries: [url_lookup]unix_socket = None env:ANSIBLE_LOOKUP_URL_UNIX_SOCKET var: ansible_lookup_url_unix_socket	String of file system path to unix socket file to use when establishing connection to the provided url
unredirected_headers list / elements=string added in 2.10 of ansible.builtin		ini entries: [url_lookup]unredirected_headers = None env:ANSIBLE_LOOKUP_URL_UNREDIR_HEADERS var: ansible_lookup_url_unredir_headers	A list of headers to not attach on a redirected request
use_gssapi boolean added in 2.10 of ansible.builtin	no ← yes	ini entries: [url_lookup]use_gssapi = no env:ANSIBLE_LOOKUP_URL_USE_GSSAPI var: ansible_lookup_url_use_gssapi	Use GSSAPI handler of requests As of Ansible 2.11, GSSAPI credentials can be specified with username and password.
use_proxy boolean	no yes ←		Flag to control if the lookup will observe HTTP proxy environment variables when present.
username string added in 2.8 of ansible.builtin			Username to use for HTTP authentication.
validate_certs boolean	no yes ←		Flag to control SSL certificate validation

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	Returned	Description
_list list / elements=string	success	list of list of lines or content of url(s)

Authors

Brian Coca (@bcoca)

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