Modules in the main Ansible repo have a defined life cycle, from first introduction to final removal. The module life cycle is tied to the Ansible release cycle <release_cycle> and reflected in the ANSIBLE_METADATA block. A module may move through these four states:
preview. Modules in
previeware not stable. You may change the parameters or dependencies, expand or reduce the functionality of
previewmodules. Many modules remain
stableinterfaceand commit to maintaining its parameters, dependencies, and functionality. We support (though we cannot guarantee) backwards compatibility for
stableinterfacemodules, which means their parameters should be maintained with stable meanings.
deprecated. Modules that are
deprecatedare still available but they are reaching the end of their life cycle. We retain deprecated modules for 4 release cycles with deprecation warnings to help users update playbooks and roles that use them.
removed. Modules that are
removedare no longer shipped with Ansible. The stub file helps users find alternative modules.
To deprecate a module, you must:
_, for example, rename
_old_cloud.py. This keeps the module available and marks it as deprecated on the module index pages.
deprecated:to the documentation with the following sub-values:
string, such as
"2.9"; the version of Ansible where the module will be replaced with a docs-only module stub. Usually current release +4.
why: Optional string that used to detail why this has been removed. alternative: Inform users they should do instead, i.e.
Use M(whatmoduletouseinstead) instead..
You can also rename a module and keep an alias to the old name by using a symlink that starts with _.
This example allows the
stat module to be called with
fileinfo, making the following examples equivalent:
EXAMPLES = ''' ln -s stat.py _fileinfo.py ansible -m stat -a "path=/tmp" localhost ansible -m fileinfo -a "path=/tmp" localhost '''