meta - Execute Ansible ‘actions’

Synopsis

  • 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.
  • This module is also supported for Windows targets.

Parameters

Parameter Choices/Defaults Comments
free_form
required
    Choices:
  • noop
  • flush_handlers
  • refresh_inventory
  • clear_facts
  • clear_host_errors
  • end_play
  • reset_connection
This module takes a free form command, as a string. There's not an actual option named "free form". See the examples!
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).
refresh_inventory (added in 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."
noop (added in 2.0) This literally does 'nothing'. It is mainly used internally and not recommended for general use.
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.
clear_host_errors (added in 2.1) clears the failed state (if any) from hosts specified in the play's list of hosts.
end_play (added in 2.2) causes the play to end without failing the host(s). Note that this affects all hosts.
reset_connection (added in 2.3) interrupts a persistent connection (i.e. ssh + control persist)

Notes

Note

  • meta is not really a module nor action_plugin as such it cannot be overwritten.
  • This module is also supported for Windows targets.

Examples

- 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
  meta: flush_handlers

- 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 instaces exist in inventory
  meta: refresh_inventory

- name: Clear gathered facts from all currently targeted hosts
  meta: clear_facts

- name: bring host back to play after failure
  copy:
    src: file
    dest: /etc/file
  remote_user: imightnothavepermission

- meta: clear_host_errors

- user: name={{ansible_user}} groups=input
- name: reset ssh connection to allow user changes to affect 'current login user'
  meta: reset_connection

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Maintenance

This module is flagged as core which means that it is maintained by the Ansible Core Team. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Core Team, see here.

Support

For more information about Red Hat’s support of this module, please refer to this Knowledge Base article

Author

  • Ansible Core Team

Hint

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

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.6/modules/meta_module.html