Docs4dev
Docs
ansible / latest / collections / ansible / builtin / url_lookup.html

ansible.builtin.url – 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 even without specifying the collections: keyword. However, we recommend you use the FQCN for easy linking to the plugin documentation and to avoid conflicting with other collections that may have the same lookup plugin 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)

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