ansible.builtin.url – return contents from URL

Note

This module is part of ansible-core and included in all Ansible installations. In most cases, you can use the short module name url even without specifying the collections: keyword. However, 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

  • 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
    Choices:
  • 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
    Choices:
  • 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
    Choices:
  • 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
    Choices:
  • 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
    Choices:
  • 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
    Choices:
  • 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)