documents the use of ansible.legacy (#73942)

This commit is contained in:
Alicia Cozine 2021-03-25 15:36:46 -05:00 committed by GitHub
parent 5dbcaa4c01
commit c66cff444c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -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.
.. _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:
@ -408,3 +407,21 @@ The following is an example RPM spec file that accomplishes this using this exam
%doc %{collection_dir}/roles/*/README.md
%license %{_pkgdocdir}/*/COPYING
%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``.