cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

utilities: Clean up parameter types and add seealso (#53063)

Browse source 
* utilities: Clean up parameter types and add seealso

* Add inventory modules

* Add more references, clarify with-loops
This commit is contained in:
Dag Wieers 2019-03-07 00:25:59 +01:00 committed by GitHub
parent 77a03af394
commit f47191674e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
21 changed files with 468 additions and 321 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/docsite/rst/user_guide/playbooks_reuse_includes.rst
View file

@ -1,6 +1,8 @@
Including and Importing
=======================
.. _playbooks_reuse_includes:
.. contents:: Topics
Includes vs. Imports

78
lib/ansible/modules/inventory/add_host.py
View file

@ -1,81 +1,83 @@
# -*- mode: python -*-
#
# Copyright: (c) 2012, Seth Vidal (@skvidal)
# Copyright: Ansible Team
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['stableinterface'],
'supported_by': 'core'}
DOCUMENTATION = r'''
---
module: add_host
short_description: add a host (and alternatively a group) to the ansible-playbook in-memory inventory
short_description: Add a host (and alternatively a group) to the ansible-playbook in-memory inventory
description:
- Use variables to create new hosts and groups in inventory for use in later plays of the same playbook.
Takes variables so you can define the new hosts more fully.
- This module is also supported for Windows targets.
- Use variables to create new hosts and groups in inventory for use in later plays of the same playbook.
- Takes variables so you can define the new hosts more fully.
- This module is also supported for Windows targets.
version_added: "0.9"
options:
name:
aliases: [ 'hostname', 'host' ]
description:
- The hostname/ip of the host to add to the inventory, can include a colon and a port number.
type: str
required: true
aliases: [ host, hostname ]
groups:
aliases: [ 'groupname', 'group' ]
description:
- The groups to add the hostname to, comma separated.
required: false
- The groups to add the hostname to.
type: list
aliases: [ group, groupname ]
notes:
- This module bypasses the play host loop and only runs once for all the hosts in the play, if you need it
to iterate use a with\_ directive.
- Windows targets are supported by this module.
- The alias 'host' of the parameter 'name' is only available on >=2.4
- Since Ansible version 2.4, the ``inventory_dir`` variable is now set to ``None`` instead of the 'global inventory source',
because you can now have multiple sources. An example was added that shows how to partially restore the previous behaviour.
- This module bypasses the play host loop and only runs once for all the hosts in the play, if you need it
to iterate use a with-loop construct.
- The alias C(host) of the parameter C(name) is only available on Ansible 2.4 and newer.
- Since Ansible 2.4, the C(inventory_dir) variable is now set to C(None) instead of the 'global inventory source',
because you can now have multiple sources. An example was added that shows how to partially restore the previous behaviour.
- Windows targets are supported by this module.
seealso:
- module: group_by
author:
- "Ansible Core Team"
- "Seth Vidal (@skvidal)"
- Ansible Core Team
- Seth Vidal (@skvidal)
'''
EXAMPLES = '''
- name: add host to group 'just_created' with variable foo=42
EXAMPLES = r'''
- name: Add host to group 'just_created' with variable foo=42
add_host:
name: "{{ ip_from_ec2 }}"
name: '{{ ip_from_ec2 }}'
groups: just_created
foo: 42
- name: add host to multiple groups
- name: Add host to multiple groups
add_host:
hostname: "{{ new_ip }}"
hostname: '{{ new_ip }}'
groups:
- group1
- group2
- group1
- group2
- name: add a host with a non-standard port local to your machines
- name: Add a host with a non-standard port local to your machines
add_host:
name: "{{ new_ip }}:{{ new_port }}"
name: '{{ new_ip }}:{{ new_port }}'
- name: add a host alias that we reach through a tunnel (Ansible <= 1.9)
- name: Add a host alias that we reach through a tunnel (Ansible 1.9 and older)
add_host:
hostname: "{{ new_ip }}"
ansible_ssh_host: "{{ inventory_hostname }}"
ansible_ssh_port: "{{ new_port }}"
hostname: '{{ new_ip }}'
ansible_ssh_host: '{{ inventory_hostname }}'
ansible_ssh_port: '{{ new_port }}'
- name: add a host alias that we reach through a tunnel (Ansible >= 2.0)
- name: Add a host alias that we reach through a tunnel (Ansible 2.0 and newer)
add_host:
hostname: "{{ new_ip }}"
ansible_host: "{{ inventory_hostname }}"
ansible_port: "{{ new_port }}"
hostname: '{{ new_ip }}'
ansible_host: '{{ inventory_hostname }}'
ansible_port: '{{ new_port }}'
- name: Ensure inventory vars are set to the same value as the inventory_hostname has (close to pre 2.4 behaviour)
- name: Ensure inventory vars are set to the same value as the inventory_hostname has (close to pre Ansible 2.4 behaviour)
add_host:
hostname: charlie
inventory_dir: "{{inventory_dir}}"
inventory_dir: '{{ inventory_dir }}'
'''

32
lib/ansible/modules/inventory/group_by.py
View file

@ -1,43 +1,46 @@
# -*- mode: python -*-
#
# Copyright: (c) 2012, Jeroen Hoekx (@jhoekx)
# Copyright: Ansible Team
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['stableinterface'],
'supported_by': 'core'}
DOCUMENTATION = '''
DOCUMENTATION = r'''
---
module: group_by
short_description: Create Ansible groups based on facts
description:
- Use facts to create ad-hoc groups that can be used later in a playbook.
- This module is also supported for Windows targets.
- Use facts to create ad-hoc groups that can be used later in a playbook.
- This module is also supported for Windows targets.
version_added: "0.9"
options:
key:
description:
- The variables whose values will be used as groups
- The variables whose values will be used as groups.
type: str
required: true
parents:
description:
- The list of the parent groups
required: false
default: "all"
- The list of the parent groups.
type: list
default: all
version_added: "2.4"
author: "Jeroen Hoekx (@jhoekx)"
notes:
- Spaces in group names are converted to dashes '-'.
- This module is also supported for Windows targets.
- Spaces in group names are converted to dashes '-'.
- This module is also supported for Windows targets.
seealso:
- module: add_host
author:
- Jeroen Hoekx (@jhoekx)
'''
EXAMPLES = '''
EXAMPLES = r'''
# Create groups based on the machine architecture
- group_by:
key: machine_{{ ansible_machine }}
@ -51,5 +54,4 @@ EXAMPLES = '''
key: el{{ ansible_distribution_major_version }}-{{ ansible_architecture }}
parents:
- el{{ ansible_distribution_major_version }}
'''

2
lib/ansible/modules/utilities/helper/_accelerate.py
View file

@ -1,7 +1,7 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# (c) 2013, James Cammarata <jcammarata@ansible.com>
# Copyright: (c) 2013, James Cammarata <jcammarata@ansible.com>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function

77
lib/ansible/modules/utilities/helper/meta.py
View file

@ -1,74 +1,82 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# (c) 2016, Ansible, a Red Hat company
# Copyright: (c) 2016, Ansible, a Red Hat company
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'core'}
DOCUMENTATION = '''
DOCUMENTATION = r'''
module: meta
short_description: Execute Ansible 'actions'
version_added: "1.2"
version_added: '1.2'
description:
- Meta tasks are a special kind of task which can influence Ansible internal execution or state. Prior to Ansible 2.0,
the only meta option available was `flush_handlers`. As of 2.2, there are five meta tasks which can be used.
Meta tasks can be used anywhere within your playbook.
- Meta tasks are a special kind of task which can influence Ansible internal execution or state.
- Prior to Ansible 2.0, the only meta option available was C(flush_handlers).
- As of Ansible 2.2, there are five meta tasks which can be used.
- Meta tasks can be used anywhere within your playbook.
- This module is also supported for Windows targets.
options:
free_form:
description:
- This module takes a free form command, as a string. There's not an actual option named "free form". See the examples!
- >
C(flush_handlers) makes Ansible run any handler tasks which have thus far been notified. Ansible inserts these tasks internally at certain
- This module takes a free form command, as a string. There is not an actual option named "free form". See the examples!
- C(flush_handlers) makes Ansible run any handler tasks which have thus far been notified. Ansible inserts these tasks internally at certain
points to implicitly trigger handler runs (after pre/post tasks, the final role execution, and the main tasks section of your plays).
- >
C(refresh_inventory) (added in 2.0) forces the reload of the inventory, which in the case of dynamic inventory scripts means they will be
- C(refresh_inventory) (added in Ansible 2.0) forces the reload of the inventory, which in the case of dynamic inventory scripts means they will be
re-executed. If the dynamic inventory script is using a cache, Ansible cannot know this and has no way of refreshing it (you can disable the cache
or, if available for your specific inventory datasource (for es.: aws), you can use the an inventory plugin instead of an inventory script).
This is mainly useful when additional hosts are created and users wish to use them instead of using the `add_host` module."
- "C(noop) (added in 2.0) This literally does 'nothing'. It is mainly used internally and not recommended for general use."
- "C(clear_facts) (added in 2.1) causes the gathered facts for the hosts specified in the play's list of hosts to be cleared, including the fact cache."
- "C(clear_host_errors) (added in 2.1) clears the failed state (if any) from hosts specified in the play's list of hosts."
- "C(end_play) (added in 2.2) causes the play to end without failing the host(s). Note that this affects all hosts."
- "C(reset_connection) (added in 2.3) interrupts a persistent connection (i.e. ssh + control persist)"
- "C(end_host) (added in 2.8) is a per-host variation of C(end_play). Causes the play to end for the current host without failing it."
choices: ['flush_handlers', 'refresh_inventory', 'noop', 'clear_facts', 'clear_host_errors', 'end_play', 'reset_connection', 'end_host']
or, if available for your specific inventory datasource (e.g. aws), you can use the an inventory plugin instead of an inventory script).
This is mainly useful when additional hosts are created and users wish to use them instead of using the M(add_host) module.
- C(noop) (added in Ansible 2.0) This literally does 'nothing'. It is mainly used internally and not recommended for general use.
- C(clear_facts) (added in Ansible 2.1) causes the gathered facts for the hosts specified in the play's list of hosts to be cleared,
including the fact cache.
- C(clear_host_errors) (added in Ansible 2.1) clears the failed state (if any) from hosts specified in the play's list of hosts.
- C(end_play) (added in Ansible 2.2) causes the play to end without failing the host(s). Note that this affects all hosts.
- C(reset_connection) (added in Ansible 2.3) interrupts a persistent connection (i.e. ssh + control persist)
- C(end_host) (added in Ansible 2.8) is a per-host variation of C(end_play). Causes the play to end for the current host without failing it.
choices: [ clear_facts, clear_host_errors, end_host, end_play, flush_handlers, noop, refresh_inventory, reset_connection ]
required: true
notes:
- C(meta) is not really a module nor action_plugin as such it cannot be overwritten.
- C(clear_facts) will remove the persistent facts from M(set_fact) using C(cacheable=True),
but not the current host variable it creates for the current run.
- This module is also supported for Windows targets.
- "C(clear_facts) will remove the persistent facts from ``set_fact: cacheable=True``, but not the current host variable it creates for the current run."
seealso:
- module: assert
- module: fail
author:
- "Ansible Core Team"
- Ansible Core Team
'''
EXAMPLES = '''
EXAMPLES = r'''
# Example showing flushing handlers on demand, not at end of play
- template:
src: new.j2
dest: /etc/config.txt
notify: myhandler
- name: force all notified handlers to run at this point, not waiting for normal sync points
- name: Force all notified handlers to run at this point, not waiting for normal sync points
meta: flush_handlers
- name: reload inventory, useful with dynamic inventories when play makes changes to the existing hosts
# Example showing how to refresh inventory during play
- name: Reload inventory, useful with dynamic inventories when play makes changes to the existing hosts
cloud_guest: # this is fake module
name: newhost
state: present
- name: Refresh inventory to ensure new instances exist in inventory
meta: refresh_inventory
# Example showing how to clear all existing facts of targetted hosts
- name: Clear gathered facts from all currently targeted hosts
meta: clear_facts
- name: bring host back to play after failure
# Example showing how to continue using a failed target
- name: Bring host back to play after failure
copy:
src: file
dest: /etc/file
@ -76,13 +84,18 @@ EXAMPLES = '''
- meta: clear_host_errors
- user: name={{ansible_user}} groups=input
- name: reset ssh connection to allow user changes to affect 'current login user'
# Example showing how to reset an existing connection
- user:
name: '{{ ansible_user }}'
groups: input
- name: Reset ssh connection to allow user changes to affect 'current login user'
meta: reset_connection
# Example showing how to end the play for specific targets
- name: End the play for hosts that run CentOS 6
meta: end_host
when:
- ansible_distribution == 'CentOS'
- ansible_distribution_major_version == '6'
- ansible_distribution == 'CentOS'
- ansible_distribution_major_version == '6'
'''

59
lib/ansible/modules/utilities/logic/assert.py
View file

@ -1,19 +1,17 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright 2012 Dag Wieers <dag@wieers.com>
# Copyright: (c) 2012, Dag Wieers <dag@wieers.com>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['stableinterface'],
'supported_by': 'core'}
DOCUMENTATION = '''
DOCUMENTATION = r'''
---
module: assert
short_description: Asserts given expressions are true
@ -24,60 +22,65 @@ version_added: "1.5"
options:
that:
description:
- "A string expression of the same form that can be passed to the 'when' statement."
- "Alternatively, a list of string expressions."
- A list of string expressions of the same form that can be passed to the 'when' statement.
type: list
required: true
fail_msg:
version_added: "2.7"
description:
- "The customized message used for a failing assertion."
- "This argument was called 'msg' before version 2.7, now it's renamed to 'fail_msg' with alias 'msg'."
aliases:
- msg
- The customized message used for a failing assertion.
- This argument was called 'msg' before Ansible 2.7, now it is renamed to 'fail_msg' with alias 'msg'.
type: str
aliases: [ msg ]
version_added: "2.7"
success_msg:
description:
- The customized message used for a successful assertion.
type: str
version_added: "2.7"
description:
- "The customized message used for a successful assertion."
quiet:
version_added: "2.8"
description:
- "Set this to C(true) to avoid verbose output."
- Set this to C(yes) to avoid verbose output.
type: bool
default: false
default: no
version_added: "2.8"
notes:
- This module is also supported for Windows targets.
seealso:
- module: debug
- module: fail
- module: meta
author:
- "Ansible Core Team"
- "Michael DeHaan"
- Ansible Core Team
- Michael DeHaan
'''
EXAMPLES = '''
EXAMPLES = r'''
- assert: { that: "ansible_os_family != 'RedHat'" }
- assert:
that:
- "'foo' in some_command_result.stdout"
- "number_of_the_counting == 3"
- number_of_the_counting == 3
- name: after version 2.7 both 'msg' and 'fail_msg' can customize failing assertion message
- name: After version 2.7 both 'msg' and 'fail_msg' can customize failing assertion message
assert:
that:
- "my_param <= 100"
- "my_param >= 0"
- my_param <= 100
- my_param >= 0
fail_msg: "'my_param' must be between 0 and 100"
success_msg: "'my_param' is between 0 and 100"
- name: please use 'msg' when ansible version is smaller than 2.7
- name: Please use 'msg' when ansible version is smaller than 2.7
assert:
that:
- "my_param <= 100"
- "my_param >= 0"
- my_param <= 100
- my_param >= 0
msg: "'my_param' must be between 0 and 100"
- name: use quiet to avoid verbose output
assert:
that:
- "my_param <= 100"
- "my_param >= 0"
- my_param <= 100
- my_param >= 0
quiet: true
'''

76
lib/ansible/modules/utilities/logic/async_status.py
View file

@ -1,59 +1,99 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>, and others
# Copyright: (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>, and others
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['stableinterface'],
'supported_by': 'core'}
DOCUMENTATION = '''
DOCUMENTATION = r'''
---
module: async_status
short_description: Obtain status of asynchronous task
description:
- This module gets the status of an asynchronous task.
- This module is also supported for Windows targets.
- This module gets the status of an asynchronous task.
- This module is also supported for Windows targets.
version_added: "0.5"
options:
jid:
description:
- Job or task identifier
- Job or task identifier
type: str
required: true
mode:
description:
- if C(status), obtain the status; if C(cleanup), clean up the async job cache (by default in C(~/.ansible_async/)) for the specified job I(jid).
choices: [ "status", "cleanup" ]
default: "status"
- If C(status), obtain the status.
- If C(cleanup), clean up the async job cache (by default in C(~/.ansible_async/)) for the specified job I(jid).
type: str
choices: [ cleanup, status ]
default: status
notes:
- See also U(https://docs.ansible.com/playbooks_async.html)
- This module is also supported for Windows targets.
- This module is also supported for Windows targets.
seealso:
- module: async_wrapper
- ref: playbooks_async
description: Detailed information on how to use asynchronous actions and polling.
author:
- "Ansible Core Team"
- "Michael DeHaan"
- Ansible Core Team
- Michael DeHaan
'''
EXAMPLES = r'''
---
- name: Asynchronous yum task
yum:
name: docker-io
state: installed
async: 1000
poll: 0
register: yum_sleeper
- name: Wait for asynchronous job to end
async_status:
jid: '{{ yum_sleeper.ansible_job_id }}'
register: job_result
until: job_result.finished
retries: 30
'''
RETURN = r'''
ansible_job_id:
description: The asynchronous job id
returned: success
type: str
sample: '360874038559.4169'
finished:
description: Whether the asynchronous job has finished (C(1)) or not (C(0))
returned: success
type: int
sample: 1
started:
description: Whether the asynchronous job has started (C(1)) or not (C(0))
returned: success
type: int
sample: 1
'''
import json
import os
from ansible.module_utils._text import to_native
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.six import iteritems
from ansible.module_utils._text import to_native
def main():
module = AnsibleModule(argument_spec=dict(
jid=dict(required=True),
mode=dict(default='status', choices=['status', 'cleanup']),
jid=dict(type='str', required=True),
mode=dict(type='str', default='status', choices=['cleanup', 'status']),
# passed in from the async_status action plugin
_async_dir=dict(required=True, type='path'),
_async_dir=dict(type='path', required=True),
))
mode = module.params['mode']

2
lib/ansible/modules/utilities/logic/async_wrapper.py
View file

@ -1,7 +1,7 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>, and others
# Copyright: (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>, and others
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function

58
lib/ansible/modules/utilities/logic/debug.py
View file

@ -1,62 +1,66 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright 2012 Dag Wieers <dag@wieers.com>
# Copyright: (c) 2012 Dag Wieers <dag@wieers.com>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['stableinterface'],
'supported_by': 'core'}
DOCUMENTATION = '''
DOCUMENTATION = r'''
---
module: debug
short_description: Print statements during execution
description:
- This module prints statements during execution and can be useful
for debugging variables or expressions without necessarily halting
the playbook. Useful for debugging together with the 'when:' directive.
- This module is also supported for Windows targets.
version_added: "0.8"
- This module prints statements during execution and can be useful
for debugging variables or expressions without necessarily halting
the playbook.
- Useful for debugging together with the 'when:' directive.
- This module is also supported for Windows targets.
version_added: '0.8'
options:
msg:
description:
- The customized message that is printed. If omitted, prints a generic
message.
required: false
default: "Hello world!"
- The customized message that is printed. If omitted, prints a generic message.
type: str
default: 'Hello world!'
var:
description:
- A variable name to debug. Mutually exclusive with the 'msg' option.
- Be aware that this option already runs in Jinja2 context and has an implicit ``{{ }}`` wrapping,
so you should not be using Jinja2 delimiters unless you are looking for double interpolation.
- A variable name to debug.
- Mutually exclusive with the C(msg) option.
- Be aware that this option already runs in Jinja2 context and has an implicit C({{ }}) wrapping,
so you should not be using Jinja2 delimiters unless you are looking for double interpolation.
type: str
verbosity:
description:
- A number that controls when the debug is run, if you set to 3 it will only run debug when -vvv or above
required: False
- A number that controls when the debug is run, if you set to 3 it will only run debug when -vvv or above
type: int
default: 0
version_added: "2.1"
version_added: '2.1'
notes:
- This module is also supported for Windows targets.
seealso:
- module: assert
- module: fail
author:
- "Dag Wieers (@dagwieers)"
- "Michael DeHaan"
- Dag Wieers (@dagwieers)
- Michael DeHaan
'''
EXAMPLES = '''
EXAMPLES = r'''
# Example that prints the loopback address and gateway for each host
- debug:
msg: "System {{ inventory_hostname }} has uuid {{ ansible_product_uuid }}"
msg: System {{ inventory_hostname }} has uuid {{ ansible_product_uuid }}
- debug:
msg: "System {{ inventory_hostname }} has gateway {{ ansible_default_ipv4.gateway }}"
msg: System {{ inventory_hostname }} has gateway {{ ansible_default_ipv4.gateway }}
when: ansible_default_ipv4.gateway is defined
# Example that prints return information from the previous task
- shell: /usr/bin/uptime
register: result
@ -69,9 +73,9 @@ EXAMPLES = '''
var: hostvars[inventory_hostname]
verbosity: 4
# Example that prints two lines of messages, but only if there's an environment value set
# Example that prints two lines of messages, but only if there is an environment value set
- debug:
msg:
- "Provisioning based on YOUR_KEY which is: '{{ lookup('env', 'YOUR_KEY') }}"
- "These servers were built using the password of '{{ password_used }}'. Please retain this for later use."
- "Provisioning based on YOUR_KEY which is: {{ lookup('env', 'YOUR_KEY') }}"
- "These servers were built using the password of '{{ password_used }}'. Please retain this for later use."
'''

32
lib/ansible/modules/utilities/logic/fail.py
View file

@ -1,43 +1,45 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright 2012 Dag Wieers <dag@wieers.com>
# Copyright: (c) 2012, Dag Wieers <dag@wieers.com>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['stableinterface'],
'supported_by': 'core'}
DOCUMENTATION = '''
DOCUMENTATION = r'''
---
module: fail
short_description: Fail with custom message
description:
- This module fails the progress with a custom message. It can be
useful for bailing out when a certain condition is met using C(when).
- This module is also supported for Windows targets.
- This module fails the progress with a custom message.
- It can be useful for bailing out when a certain condition is met using C(when).
- This module is also supported for Windows targets.
version_added: "0.8"
options:
msg:
description:
- The customized message used for failing execution. If omitted,
fail will simply bail out with a generic message.
required: false
default: "'Failed as requested from task'"
- The customized message used for failing execution.
- If omitted, fail will simply bail out with a generic message.
type: str
default: Failed as requested from task
notes:
- This module is also supported for Windows targets.
author: "Dag Wieers (@dagwieers)"
seealso:
- module: assert
- module: debug
- module: meta
author:
- Dag Wieers (@dagwieers)
'''
EXAMPLES = '''
EXAMPLES = r'''
# Example playbook using fail and when together
- fail:
msg: "The system may not be provisioned according to the CMDB status."
msg: The system may not be provisioned according to the CMDB status.
when: cmdb_status != "to-be-staged"
'''

23
lib/ansible/modules/utilities/logic/import_playbook.py
View file

@ -1,27 +1,27 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright: Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {
'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'core'
}
DOCUMENTATION = '''
DOCUMENTATION = r'''
---
author: Ansible Core Team (@ansible)
module: import_playbook
short_description: Import a playbook
description:
- Includes a file with a list of plays to be executed.
- Files with a list of plays can only be included at the top level. You cannot use this action inside a play.
- Files with a list of plays can only be included at the top level.
- You cannot use this action inside a play.
version_added: "2.4"
options:
free-form:
@ -29,9 +29,16 @@ options:
- The name of the imported playbook is specified directly without any other option.
notes:
- This is a core feature of Ansible, rather than a module, and cannot be overridden like a module.
seealso:
- module: import_role
- module: import_tasks
- module: include_role
- module: include_tasks
- ref: playbooks_reuse_includes
description: More information related to including and importing playbooks, roles and tasks.
'''
EXAMPLES = """
EXAMPLES = r'''
- hosts: localhost
tasks:
- debug:
@ -49,8 +56,8 @@ EXAMPLES = """
- name: This fails because I'm inside a play already
import_playbook: stuff.yaml
"""
'''
RETURN = """
RETURN = r'''
# This module does not return anything except plays to execute.
"""
'''

41
lib/ansible/modules/utilities/logic/import_role.py
View file

@ -6,62 +6,71 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {
'metadata_version': '1.1',
'status': ['stableinterface'],
'supported_by': 'core'
}
DOCUMENTATION = '''
DOCUMENTATION = r'''
---
author: Ansible Core Team (@ansible)
module: import_role
short_description: Import a role into a play
description:
- Much like the `roles:` keyword, this task loads a role, but it allows you to control it when the role tasks run in
- Much like the C(roles:) keyword, this task loads a role, but it allows you to control it when the role tasks run in
between other tasks of the play.
- Most keywords, loops and conditionals will only be applied to the imported tasks, not to this statement itself. If
you want the opposite behavior, use M(include_role) instead. To better understand the difference you can read
the L(Including and Importing Guide,../user_guide/playbooks_reuse_includes.html).
version_added: "2.4"
you want the opposite behavior, use M(include_role) instead.
version_added: '2.4'
options:
name:
description:
- The name of the role to be executed.
required: True
type: str
required: true
tasks_from:
description:
- File to load from a role's C(tasks/) directory.
type: str
default: main
vars_from:
description:
- File to load from a role's C(vars/) directory.
type: str
default: main
defaults_from:
description:
- File to load from a role's C(defaults/) directory.
type: str
default: main
allow_duplicates:
description:
- Overrides the role's metadata setting to allow using a role more than once with the same parameters.
type: bool
default: 'yes'
default: yes
handlers_from:
description:
- File to load from a role's C(handlers/) directory.
type: str
default: main
version_added: '2.8'
notes:
- Handlers are made available to the whole play.
- "Since Ansible 2.7: variables defined in C(vars) and C(defaults) for the role are exposed at playbook parsing time.
- Since Ansible 2.7 variables defined in C(vars) and C(defaults) for the role are exposed at playbook parsing time.
Due to this, these variables will be accessible to roles and tasks executed before the location of the
C(import_role) task."
- Unlike C(include_role) variable exposure is not configurable, and will always be exposed.
M(import_role) task.
- Unlike M(include_role) variable exposure is not configurable, and will always be exposed.
seealso:
- module: import_playbook
- module: import_tasks
- module: include_role
- module: include_tasks
- ref: playbooks_reuse_includes
description: More information related to including and importing playbooks, roles and tasks.
'''
EXAMPLES = """
EXAMPLES = r'''
- hosts: all
tasks:
- import_role:
@ -82,8 +91,8 @@ EXAMPLES = """
import_role:
name: myrole
when: not idontwanttorun
"""
'''
RETURN = """
RETURN = r'''
# This module does not return anything except tasks to execute.
"""
'''

24
lib/ansible/modules/utilities/logic/import_tasks.py
View file

@ -1,20 +1,19 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright: Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {
'metadata_version': '1.1',
'status': ['stableinterface'],
'supported_by': 'core'
}
DOCUMENTATION = '''
DOCUMENTATION = r'''
---
author: Ansible Core Team (@ansible)
module: import_tasks
@ -26,13 +25,20 @@ options:
free-form:
description:
- The name of the imported file is specified directly without any other option.
- Most keywords, including loops and conditionals, only applied to the imported tasks, not to this statement
itself. If you need any of those to apply, use M(include_tasks) instead.
- Most keywords, including loops and conditionals, only applied to the imported tasks, not to this statement itself.
- If you need any of those to apply, use M(include_tasks) instead.
notes:
- This is a core feature of Ansible, rather than a module, and cannot be overridden like a module.
seealso:
- module: import_playbook
- module: import_role
- module: include_role
- module: include_tasks
- ref: playbooks_reuse_includes
description: More information related to including and importing playbooks, roles and tasks.
'''
EXAMPLES = """
EXAMPLES = r'''
- hosts: all
tasks:
- debug:
@ -52,8 +58,8 @@ EXAMPLES = """
- name: Apply conditional to all imported tasks
import_tasks: stuff.yaml
when: hostvar is defined
"""
'''
RETURN = """
RETURN = r'''
# This module does not return anything except tasks to execute.
"""
'''

27
lib/ansible/modules/utilities/logic/include.py
View file

@ -1,20 +1,19 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright: Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {
'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'core'
}
DOCUMENTATION = '''
DOCUMENTATION = r'''
---
author: Ansible Core Team (@ansible)
module: include
@ -23,11 +22,11 @@ description:
- Includes a file with a list of plays or tasks to be executed in the current playbook.
- Files with a list of plays can only be included at the top level. Lists of tasks can only be included where tasks
normally run (in play).
- Before Ansible version 2.0, all includes were 'static' and were executed when the play was compiled.
- Before Ansible 2.0, all includes were 'static' and were executed when the play was compiled.
- Static includes are not subject to most directives. For example, loops or conditionals are applied instead to each
inherited task.
- Since Ansible 2.0, task includes are dynamic and behave more like real tasks. This means they can be looped,
skipped and use variables from any source. Ansible tries to auto detect this, but you can use the `static`
skipped and use variables from any source. Ansible tries to auto detect this, but you can use the C(static)
directive (which was added in Ansible 2.1) to bypass autodetection.
- This module is also supported for Windows targets.
version_added: "0.6"
@ -40,10 +39,18 @@ notes:
- Include has some unintuitive behaviours depending on if it is running in a static or dynamic in play or in playbook context,
in an effort to clarify behaviours we are moving to a new set modules (M(include_tasks), M(include_role), M(import_playbook), M(import_tasks))
that have well established and clear behaviours.
This module will still be supported for some time but we are looking at deprecating it in the near future.
- B(This module will still be supported for some time but we are looking at deprecating it in the near future.)
seealso:
- module: import_playbook
- module: import_role
- module: import_tasks
- module: include_role
- module: include_tasks
- ref: playbooks_reuse_includes
description: More information related to including and importing playbooks, roles and tasks.
'''
EXAMPLES = """
EXAMPLES = r'''
- hosts: localhost
tasks:
- debug:
@ -73,8 +80,8 @@ EXAMPLES = """
include: "{{ hostvar }}.yaml"
static: no
when: hostvar is defined
"""
'''
RETURN = """
RETURN = r'''
# This module does not return anything except plays or tasks to execute.
"""
'''

39
lib/ansible/modules/utilities/logic/include_role.py
View file

@ -1,27 +1,26 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright: Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {
'metadata_version': '1.1',
'status': ['stableinterface'],
'supported_by': 'core'
}
DOCUMENTATION = '''
DOCUMENTATION = r'''
---
author: Ansible Core Team (@ansible)
module: include_role
short_description: Load and execute a role
description:
- Loads and executes a role as a task dynamically. This frees roles from the `roles:` directive and allows them to be
treated more as tasks.
- Loads and executes a role as a task dynamically.
- This frees roles from the C(roles:) directive and allows them to be treated more as tasks.
- Unlike M(import_role), most keywords, including loop, with_items, and conditionals, apply to this statement.
- The do until loop is not supported on M(include_role).
- This module is also supported for Windows targets.
@ -34,24 +33,28 @@ options:
name:
description:
- The name of the role to be executed.
type: str
required: True
tasks_from:
description:
- File to load from a role's C(tasks/) directory.
type: str
default: main
vars_from:
description:
- File to load from a role's C(vars/) directory.
type: str
default: main
defaults_from:
description:
- File to load from a role's C(defaults/) directory.
type: str
default: main
allow_duplicates:
description:
- Overrides the role's metadata setting to allow using a role more than once with the same parameters.
type: bool
default: 'yes'
default: yes
public:
description:
- This option dictates whether the role's C(vars) and C(defaults) are exposed to the playbook. If set to C(yes)
@ -59,22 +62,30 @@ options:
standard variable exposure for roles listed under the C(roles) header or C(import_role) as they are exposed at
playbook parsing time, and available to earlier roles and tasks as well.
type: bool
default: 'no'
default: no
version_added: '2.7'
handlers_from:
description:
- File to load from a role's C(handlers/) directory.
type: str
default: main
version_added: '2.8'
notes:
- Handlers are made available to the whole play.
- Before Ansible 2.4, as with C(include), this task could be static or dynamic, If static, it implied that it won't
need templating, loops or conditionals and will show included tasks in the `--list` options. Ansible would try to
autodetect what is needed, but you can set `static` to `yes` or `no` at task level to control this.
- After Ansible 2.4, you can use M(import_role) for 'static' behaviour and this action for 'dynamic' one.
need templating, loops or conditionals and will show included tasks in the C(--list) options. Ansible would try to
autodetect what is needed, but you can set C(static) to C(yes) or C(no) at task level to control this.
- After Ansible 2.4, you can use M(import_role) for C(static) behaviour and this action for C(dynamic) one.
seealso:
- module: import_playbook
- module: import_role
- module: import_tasks
- module: include_tasks
- ref: playbooks_reuse_includes
description: More information related to including and importing playbooks, roles and tasks.
'''
EXAMPLES = """
EXAMPLES = r'''
- include_role:
name: myrole
@ -111,8 +122,8 @@ EXAMPLES = """
- install
tags:
- always
"""
'''
RETURN = """
RETURN = r'''
# This module does not return anything except tasks to execute.
"""
'''

24
lib/ansible/modules/utilities/logic/include_tasks.py
View file

@ -1,37 +1,38 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright: Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {
'metadata_version': '1.1',
'status': ['stableinterface'],
'supported_by': 'core'
}
DOCUMENTATION = '''
DOCUMENTATION = r'''
---
author: Ansible Core Team (@ansible)
module: include_tasks
short_description: Dynamically include a task list
description:
- Includes a file with a list of tasks to be executed in the current playbook.
version_added: "2.4"
version_added: '2.4'
options:
file:
description:
- The name of the imported file is specified directly without any other option.
- Unlike M(import_tasks), most keywords, including loop, with_items, and conditionals, apply to this statement.
- The do until loop is not supported on M(include_tasks).
type: str
version_added: '2.7'
apply:
description:
- Accepts a hash of task keywords (e.g. C(tags), C(become)) that will be applied to the tasks within the include.
type: str
version_added: '2.7'
free-form:
description:
@ -40,9 +41,16 @@ options:
of specifying an argument of I(file).
notes:
- This is a core feature of the Ansible, rather than a module, and cannot be overridden like a module.
seealso:
- module: import_playbook
- module: import_role
- module: import_tasks
- module: include_role
- ref: playbooks_reuse_includes
description: More information related to including and importing playbooks, roles and tasks.
'''
EXAMPLES = """
EXAMPLES = r'''
- hosts: all
tasks:
- debug:
@ -80,8 +88,8 @@ EXAMPLES = """
- install
tags:
- always
"""
'''
RETURN = """
RETURN = r'''
# This module does not return anything except tasks to execute.
"""
'''

60
lib/ansible/modules/utilities/logic/include_vars.py
View file

@ -1,18 +1,18 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {
'metadata_version': '1.1',
'status': ['stableinterface'],
'supported_by': 'core'
}
DOCUMENTATION = '''
DOCUMENTATION = r'''
---
author: Allen Sanabria (@linuxdynasty)
module: include_vars
@ -22,58 +22,72 @@ description:
- If loading a directory, the files are sorted alphabetically before being loaded.
- This module is also supported for Windows targets.
- To assign included variables to a different host than C(inventory_hostname),
use C(delegate_to) and set L(delegate_facts=True,../user_guide/playbooks_delegate.html#delegated-facts).
use C(delegate_to) and set C(delegate_facts=yes).
version_added: "1.4"
options:
file:
version_added: "2.2"
description:
- The file name from which variables should be loaded.
- If the path is relative, it will look for the file in vars/ subdirectory of a role or relative to playbook.
dir:
type: path
version_added: "2.2"
dir:
description:
- The directory name from which the variables should be loaded.
- If the path is relative and the task is inside a role, it will look inside the role's vars/ subdirectory.
- If the path is relative and not inside a role, it will be parsed relative to the playbook.
type: path
version_added: "2.2"
name:
version_added: "2.2"
description:
- The name of a variable into which assign the included vars. If omitted (null) they will be made top level vars.
depth:
- The name of a variable into which assign the included vars.
- If omitted (null) they will be made top level vars.
type: str
version_added: "2.2"
depth:
description:
- When using C(dir), this module will, by default, recursively go through each sub directory and load up the
variables. By explicitly setting the depth, this module will only go as deep as the depth.
type: int
default: 0
files_matching:
version_added: "2.2"
files_matching:
description:
- Limit the files that are loaded within any directory to this regular expression.
ignore_files:
type: str
version_added: "2.2"
ignore_files:
description:
- List of file names to ignore.
type: list
version_added: "2.2"
extensions:
version_added: "2.3"
description:
- List of file extensions to read when using C(dir).
default: [yaml, yml, json]
type: list
default: [ json, yaml, yml ]
version_added: "2.3"
ignore_unknown_extensions:
version_added: "2.7"
description:
- Ignore unknown file extensions within the directory. This allows users to specify a directory containing vars files
that are intermingled with non vars files extension types (For example, a directory with a README in it and vars files)
default: False
- Ignore unknown file extensions within the directory.
- This allows users to specify a directory containing vars files that are intermingled with non-vars files extension types
(e.g. a directory with a README in it and vars files).
type: bool
default: no
version_added: "2.7"
free-form:
description:
- This module allows you to specify the 'file' option directly without any other options.
There is no 'free-form' option, this is just an indicator, see example below.
- There is no 'free-form' option, this is just an indicator, see example below.
notes:
- This module is also supported for Windows targets.
seealso:
- module: set_fact
- ref: playbooks_delegation
description: More information related to task delegation.
'''
EXAMPLES = """
EXAMPLES = r'''
- name: Include vars of stuff.yaml into the 'stuff' variable (2.2).
include_vars:
file: stuff.yaml
@ -129,9 +143,9 @@ EXAMPLES = """
dir: vars
ignore_unknown_extensions: True
extensions: ['', 'yaml', 'yml', 'json']
"""
'''
RETURN = '''
RETURN = r'''
ansible_facts:
description: Variables that were included and their values
returned: success
@ -141,6 +155,6 @@ ansible_included_var_files:
description: A list of files that were successfully included
returned: success
type: list
sample: [ '/path/to/file.yaml', '/path/to/file.json' ]
version_added: 2.4
sample: [ /path/to/file.json, /path/to/file.yaml ]
version_added: '2.4'
'''

38
lib/ansible/modules/utilities/logic/set_fact.py
View file

@ -7,25 +7,22 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['stableinterface'],
'supported_by': 'core'}
DOCUMENTATION = '''
DOCUMENTATION = r'''
---
author:
- Dag Wieers (@dagwieers)
module: set_fact
short_description: Set host facts from a task
version_added: "1.2"
description:
- This module allows setting new variables. Variables are set on a host-by-host basis just like facts discovered by the setup module.
- This module allows setting new variables.
- Variables are set on a host-by-host basis just like facts discovered by the setup module.
- These variables will be available to subsequent plays during an ansible-playbook run.
- Set C(cacheable) to C(yes) to save variables across executions
using a fact cache. Variables created with set_fact have different precedence depending on whether they are or are not cached.
- Per the standard Ansible variable precedence rules, many other types of variables have a higher priority, so this value may be overridden.
See L(Variable Precedence Guide,../user_guide/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable) for more information.
- This module is also supported for Windows targets.
options:
key_value:
@ -42,19 +39,24 @@ options:
https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable
- "This actually creates 2 copies of the variable, a normal 'set_fact' host variable with high precedence and
a lower 'ansible_fact' one that is available for persistance via the facts cache plugin.
This creates a possibly confusing interaction with ``meta: clear_facts`` as it will remove the 'ansible_fact' but not the host variable."
This creates a possibly confusing interaction with C(meta: clear_facts) as it will remove the 'ansible_fact' but not the host variable."
type: bool
default: 'no'
default: no
version_added: "2.4"
version_added: "1.2"
notes:
- "The `var=value` notation can only create strings or booleans.
If you want to create lists/arrays or dictionary/hashes use `var: [val1, val2]`"
- "The C(var=value) notation can only create strings or booleans.
If you want to create lists/arrays or dictionary/hashes use C(var: [val1, val2])."
- Since 'cacheable' is now a module param, 'cacheable' is no longer a valid fact name as of Ansible 2.4.
- This module is also supported for Windows targets.
- Since 'cacheable' is now a module param, 'cacheable' is no longer a valid fact name as of 2.4.
seealso:
- module: include_vars
- ref: ansible_variable_precedence
description: More information related to variable precedence and which type of variable wins over others.
author:
- Dag Wieers (@dagwieers)
'''
EXAMPLES = '''
EXAMPLES = r'''
# Example setting host facts using key=value pairs, note that this always creates strings or booleans
- set_fact: one_fact="something" other_fact="{{ local_var }}"
@ -68,13 +70,13 @@ EXAMPLES = '''
- set_fact:
one_fact: something
other_fact: "{{ local_var * 2 }}"
cacheable: true
cacheable: yes
# As of 1.8, Ansible will convert boolean strings ('true', 'false', 'yes', 'no')
# As of Ansible 1.8, Ansible will convert boolean strings ('true', 'false', 'yes', 'no')
# to proper boolean values when using the key=value syntax, however it is still
# recommended that booleans be set using the complex argument style:
- set_fact:
one_fact: true
other_fact: false
one_fact: yes
other_fact: no
'''

24
lib/ansible/modules/utilities/logic/set_stats.py
View file

@ -1,47 +1,47 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright 2016 Ansible RedHat, Inc
# Copyright: (c) 2016, Ansible RedHat, Inc
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'community'}
DOCUMENTATION = '''
DOCUMENTATION = r'''
---
author: "Brian Coca (@bcoca)"
module: set_stats
short_description: Set stats for the current ansible run
description:
- This module allows setting/accumulating stats on the current ansible run, either per host or for all hosts in the run.
- This module is also supported for Windows targets.
author: Brian Coca (@bcoca)
options:
data:
description:
- A dictionary of which each key represents a stat (or variable) you want to keep track of
- A dictionary of which each key represents a stat (or variable) you want to keep track of.
type: dict
required: true
per_host:
description:
- boolean that indicates if the stats is per host or for all hosts in the run.
required: no
- whether the stats are per host or for all hosts in the run.
type: bool
default: no
aggregate:
description:
- boolean that indicates if the provided value is aggregated to the existing stat C(yes) or will replace it C(no)
required: no
- Whether the provided value is aggregated to the existing stat C(yes) or will replace it C(no).
type: bool
default: yes
notes:
- In order for custom stats to be displayed, you must set C(show_custom_stats) in C(ansible.cfg) or C(ANSIBLE_SHOW_CUSTOM_STATS) to C(yes).
- This module is also supported for Windows targets.
- In order for custom stats to be displayed, you must set C(show_custom_stats) in C(ansible.cfg) or C(ANSIBLE_SHOW_CUSTOM_STATS) to C(true).
version_added: "2.3"
'''
EXAMPLES = '''
EXAMPLES = r'''
# Aggregating packages_installed stat per host
- set_stats:
data:

49
lib/ansible/modules/utilities/logic/wait_for.py
View file

@ -7,7 +7,6 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['stableinterface'],
'supported_by': 'core'}
@ -20,12 +19,12 @@ description:
- You can wait for a set amount of time C(timeout), this is the default if nothing is specified or just C(timeout) is specified.
This does not produce an error.
- Waiting for a port to become available is useful for when services are not immediately available after their init scripts return
which is true of certain Java application servers. It is also useful when starting guests with the M(virt) module and
needing to pause until they are ready.
which is true of certain Java application servers.
- It is also useful when starting guests with the M(virt) module and needing to pause until they are ready.
- This module can also be used to wait for a regex match a string to be present in a file.
- In 1.6 and later, this module can also be used to wait for a file to be available or
- In Ansible 1.6 and later, this module can also be used to wait for a file to be available or
absent on the filesystem.
- In 1.8 and later, this module can also be used to wait for active connections to be closed before continuing, useful if a node
- In Ansible 1.8 and later, this module can also be used to wait for active connections to be closed before continuing, useful if a node
is being rotated out of a load balancer pool.
- For Windows targets, use the M(win_wait_for) module instead.
version_added: "0.7"
@ -33,27 +32,33 @@ options:
host:
description:
- A resolvable hostname or IP address to wait for.
default: "127.0.0.1"
type: str
default: 127.0.0.1
timeout:
description:
- Maximum number of seconds to wait for, when used with another condition it will force an error.
- When used without other conditions it is equivalent of just sleeping.
type: int
default: 300
connect_timeout:
description:
- Maximum number of seconds to wait for a connection to happen before closing and retrying.
type: int
default: 5
delay:
description:
- Number of seconds to wait before starting to poll.
type: int
default: 0
port:
description:
- Port number to poll.
- C(path) and C(port) are mutually exclusive parameters.
type: int
active_connection_states:
description:
- The list of TCP connection states which are counted as active connections.
type: list
default: [ ESTABLISHED, FIN_WAIT1, FIN_WAIT2, SYN_RECV, SYN_SENT, TIME_WAIT ]
version_added: "2.3"
state:
@ -62,35 +67,42 @@ options:
- When checking a port C(started) will ensure the port is open, C(stopped) will check that it is closed, C(drained) will check for active connections.
- When checking for a file or a search string C(present) or C(started) will ensure that the file or string is present before continuing,
C(absent) will check that file is absent or removed.
type: str
choices: [ absent, drained, present, started, stopped ]
default: started
path:
version_added: "1.4"
description:
- Path to a file on the filesystem that must exist before continuing.
- C(path) and C(port) are mutually exclusive parameters.
search_regex:
type: path
version_added: "1.4"
search_regex:
description:
- Can be used to match a string in either a file or a socket connection.
- Defaults to a multiline regex.
type: str
version_added: "1.4"
exclude_hosts:
version_added: "1.8"
description:
- List of hosts or IPs to ignore when looking for active TCP connections for C(drained) state.
type: list
version_added: "1.8"
sleep:
version_added: "2.3"
default: 1
description:
- Number of seconds to sleep between checks, before 2.3 this was hardcoded to 1 second.
- Number of seconds to sleep between checks.
- Before Ansible 2.3 this was hardcoded to 1 second.
type: int
default: 1
version_added: "2.3"
msg:
version_added: "2.4"
description:
- This overrides the normal error message from a failure to meet the required conditions.
type: str
version_added: "2.4"
notes:
- The ability to use search_regex with a port connection was added in 1.7.
- Prior to 2.4, testing for the absence of a directory or UNIX socket did not work correctly.
- Prior to 2.4, testing for the presence of a file did not work correctly if the remote user did not have read access to that file.
- The ability to use search_regex with a port connection was added in Ansible 1.7.
- Prior to Ansible 2.4, testing for the absence of a directory or UNIX socket did not work correctly.
- Prior to Ansible 2.4, testing for the presence of a file did not work correctly if the remote user did not have read access to that file.
- Under some circumstances when using mandatory access control, a path may always be treated as being absent even if it exists, but
can't be modified or created by the remote user either.
- When waiting for a path, symbolic links will be followed. Many other modules that manipulate files do not follow symbolic links,
@ -107,7 +119,8 @@ author:
EXAMPLES = r'''
- name: sleep for 300 seconds and continue with play
wait_for: timeout=300
wait_for:
timeout: 300
delegate_to: localhost
- name: Wait for port 8000 to become open on the host, don't start checking for 10 seconds
@ -162,7 +175,7 @@ EXAMPLES = r'''
state: present
msg: Timeout to find file /tmp/foo
# Don't assume the inventory_hostname is resolvable and delay 10 seconds at start
# Do not assume the inventory_hostname is resolvable and delay 10 seconds at start
- name: Wait 300 seconds for port 22 to become open and contain "OpenSSH"
wait_for:
port: 22

22
lib/ansible/modules/utilities/logic/wait_for_connection.py
View file

@ -7,12 +7,10 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['stableinterface'],
'supported_by': 'core'}
DOCUMENTATION = r'''
---
module: wait_for_connection
@ -23,23 +21,27 @@ description:
- Tests the transport connection every C(sleep) seconds.
- This module makes use of internal ansible transport (and configuration) and the ping/win_ping module to guarantee correct end-to-end functioning.
- This module is also supported for Windows targets.
version_added: "2.3"
version_added: '2.3'
options:
connect_timeout:
description:
- Maximum number of seconds to wait for a connection to happen before closing and retrying.
- Maximum number of seconds to wait for a connection to happen before closing and retrying.
type: int
default: 5
delay:
description:
- Number of seconds to wait before starting to poll.
- Number of seconds to wait before starting to poll.
type: int
default: 0
sleep:
default: 1
description:
- Number of seconds to sleep between checks.
- Number of seconds to sleep between checks.
type: int
default: 1
timeout:
description:
- Maximum number of seconds to wait for.
- Maximum number of seconds to wait for.
type: int
default: 600
notes:
- This module is also supported for Windows targets.
@ -103,6 +105,6 @@ RETURN = r'''
elapsed:
description: The number of seconds that elapsed waiting for the connection to appear.
returned: always
type: int
sample: 23
type: float
sample: 23.1
'''