url – return contents from URL

Synopsis

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

Parameters

Parameter Choices/Defaults Configuration Comments
_terms
-
urls to query
ca_path
string
String of file system path to CA cert bundle to use
follow_redirects
string
Default:
"urllib2"
String of urllib2, all/yes, safe, none to determine how redirects are followed, see RedirectHandlerFactory for more information
force
boolean
Default:
"no"
Whether or not to set "cache-control" header with value "no-cache"
force_basic_auth
boolean
Default:
"no"
Force basic authentication
headers
dictionary
added in 2.9
Default:
{}
HTTP request headers
http_agent
string
User-Agent to use in the request
password
string
added in 2.8
Password to use for HTTP authentication.
split_lines
boolean
Default:
"yes"
Flag to control if content is returned as a list of lines or as a single text blob
timeout
float
Default:
10
How long to wait for the server to send data before giving up
unix_socket
string
String of file system path to unix socket file to use when establishing connection to the provided url
unredirected_headers
list
A list of headers to not attach on a redirected request
use_gssapi
boolean
Default:
"no"
Use GSSAPI handler of requests
use_proxy
boolean
Default:
"yes"
Flag to control if the lookup will observe HTTP proxy environment variables when present.
username
string
added in 2.8
Username to use for HTTP authentication.
validate_certs
boolean
Default:
"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 of list of lines or content of url(s)



Status

Authors

  • Brian Coca (@bcoca)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.

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.