1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
# -*- coding: utf-8 -*-
# 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 annotations
DOCUMENTATION = r"""
module: meta
short_description: Execute Ansible 'actions'
version_added: '1.2'
description:
- Meta tasks are a special kind of task which can influence Ansible internal execution or state.
- 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 is not an actual option named "free form". See the examples!
- V(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).
- V(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 example P(amazon.aws.aws_ec2#inventory)), 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(ansible.builtin.add_host) module.
- Note that neither V(refresh_inventory) nor the M(ansible.builtin.add_host) add hosts to the hosts the current play iterates over.
However, if needed, you can explicitly delegate tasks to new hosts with C(delegate_to). Generally,
C(delegate_to) can be used against hosts regardless of whether they are in the inventory or not, as long as
the value supplied is sufficient for the connection plugin to access the host.
- V(noop) (added in Ansible 2.0) This literally does 'nothing'. It is mainly used internally and not recommended for general use.
- V(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.
- V(clear_host_errors) (added in Ansible 2.1) clears the failed state (if any) from hosts specified in the play's list of hosts.
- V(end_play) (added in Ansible 2.2) causes the play to end without failing the host(s). Note that this affects all hosts.
- V(reset_connection) (added in Ansible 2.3) interrupts a persistent connection (i.e. ssh + control persist)
- V(end_host) (added in Ansible 2.8) is a per-host variation of V(end_play). Causes the play to end for the current host without failing it.
- V(end_batch) (added in Ansible 2.12) causes the current batch (see C(serial)) to end without failing the host(s).
Note that with C(serial=0) or undefined this behaves the same as V(end_play).
- V(end_role) (added in Ansible 2.18) causes the currently executing role to end without failing the host(s).
Effectively all tasks from within a role after V(end_role) is executed are ignored. Since handlers live in a global,
play scope, all handlers added via the role are unaffected and are still executed if notified. It is an error
to call V(end_role) from outside of a role or from a handler. Note that V(end_role) does not have an effect to
the parent roles or roles that depend (via dependencies in meta/main.yml) on a role executing V(end_role).
choices: [ clear_facts, clear_host_errors, end_host, end_play, flush_handlers, noop, refresh_inventory, reset_connection, end_batch, end_role ]
required: true
extends_documentation_fragment:
- action_common_attributes
- action_common_attributes.conn
- action_common_attributes.flow
- action_core
attributes:
action:
support: none
bypass_host_loop:
details: Some of the subactions ignore the host loop, see the description above for each specific action for the exceptions
support: partial
bypass_task_loop:
details: Most of the subactions ignore the task loop, see the description above for each specific action for the exceptions
support: partial
check_mode:
details: While these actions don't modify the targets directly they do change possible states of the target within the run
support: partial
delegation:
support: none
diff_mode:
support: none
ignore_conditional:
details: Only some options support conditionals and when they do they act 'bypassing the host loop', taking the values from first available host
support: partial
connection:
details: Most options in this action do not use a connection, except V(reset_connection) which still does not connect to the remote
support: partial
until:
support: none
notes:
- V(clear_facts) will remove the persistent facts from M(ansible.builtin.set_fact) using O(ansible.builtin.set_fact#module:cacheable=True),
but not the current host variable it creates for the current run.
- Skipping M(ansible.builtin.meta) tasks with tags is not supported before Ansible 2.11.
seealso:
- module: ansible.builtin.assert
- module: ansible.builtin.fail
author:
- Ansible Core Team
"""
EXAMPLES = r"""
# Example showing flushing handlers on demand, not at end of play
- ansible.builtin.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
ansible.builtin.meta: flush_handlers
# 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
ansible.builtin.meta: refresh_inventory
# Example showing how to clear all existing facts of targeted hosts
- name: Clear gathered facts from all currently targeted hosts
ansible.builtin.meta: clear_facts
# Example showing how to continue using a failed target
- name: Bring host back to play after failure
ansible.builtin.copy:
src: file
dest: /etc/file
remote_user: imightnothavepermission
- ansible.builtin.meta: clear_host_errors
# Example showing how to reset an existing connection
- ansible.builtin.user:
name: '{{ ansible_user }}'
groups: input
- name: Reset ssh connection to allow user changes to affect 'current login user'
ansible.builtin.meta: reset_connection
# Example showing how to end the play for specific targets
- name: End the play for hosts that run CentOS 6
ansible.builtin.meta: end_host
when:
- ansible_distribution == 'CentOS'
- ansible_distribution_major_version == '6'
"""
|
