diff options
| author | Alicia Cozine <879121+acozine@users.noreply.github.com> | 2021-03-25 21:36:46 +0100 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-03-25 21:36:46 +0100 |
| commit | c66cff444c88b1f7b8d3f01cb6fec07fffe3d52e (patch) | |
| tree | 1f60349b0976e9096efdeb0a49161bc5c4f412f8 | |
| parent | Update version on FreeBSD (#73664) (diff) | |
| download | ansible-c66cff444c88b1f7b8d3f01cb6fec07fffe3d52e.tar.xz ansible-c66cff444c88b1f7b8d3f01cb6fec07fffe3d52e.zip | |
documents the use of ansible.legacy (#73942)
| -rw-r--r-- | docs/docsite/rst/dev_guide/migrating_roles.rst | 23 |
1 files changed, 20 insertions, 3 deletions
diff --git a/docs/docsite/rst/dev_guide/migrating_roles.rst b/docs/docsite/rst/dev_guide/migrating_roles.rst index d7d8b57115..2ed5f53e84 100644 --- a/docs/docsite/rst/dev_guide/migrating_roles.rst +++ b/docs/docsite/rst/dev_guide/migrating_roles.rst @@ -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``. |