documents the use of ansible.legacy (#73942)

pull/74040/head
Alicia Cozine 4 years ago committed by GitHub
parent 5dbcaa4c01
commit c66cff444c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -110,11 +110,10 @@ This creates the collection directory structure.
5. Update the collection README.md file to add links to any role README.md files. 5. Update the collection README.md file to add links to any role README.md files.
.. _complex_roles_in_collections: .. _complex_roles_in_collections:
Migrating a role with plugins to a collection Migrating a role that contains plugins to a collection
============================================== ======================================================
To migrate from a standalone role that has plugins to a collection role: To migrate from a standalone role that has plugins to a collection role:
@ -408,3 +407,21 @@ The following is an example RPM spec file that accomplishes this using this exam
%doc %{collection_dir}/roles/*/README.md %doc %{collection_dir}/roles/*/README.md
%license %{_pkgdocdir}/*/COPYING %license %{_pkgdocdir}/*/COPYING
%license %{_pkgdocdir}/*/LICENSE %license %{_pkgdocdir}/*/LICENSE
.. _using_ansible_legacy:
Using ``ansible.legacy`` to access local custom modules from collections-based roles
=====================================================================================
Some roles use :ref:`local custom modules <developing_locally>` that are not part of the role itself. When you move these roles into collections, they can no longer find those custom plugins. You can add the synthetic collection ``ansible.legacy`` to enable legacy behavior and find those custom plugins. Adding ``ansible.legacy`` configures your role to search the pre-collections default paths for modules and plugins.
To enable a role hosted in a collection to find legacy custom modules and other plugins hosted locally:
Edit the role's ``meta/main.yml`` and add the ``ansible.legacy`` collection to your collection-hosted role to enable the use of legacy custom modules and plugins for all tasks:
.. code-block:: yaml
collections:
- ansible.legacy
Alternatively, you can update the tasks directly by changing ``local_module_name`` to ``ansible.legacy.local_module_name``.

Loading…
Cancel
Save