From e9af4195bee12dba5cae682fb6f8ec9bffaa0883 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Wed, 26 Jan 2022 12:17:18 -0500 Subject: [PATCH] update ansible.legacy docs (#76839) * update ansible.legacy docs * correct role description * Update docs/docsite/rst/dev_guide/developing_locally.rst * Update docs/docsite/rst/dev_guide/developing_locally.rst --- docs/docsite/rst/dev_guide/developing_locally.rst | 7 +++++++ docs/docsite/rst/dev_guide/migrating_roles.rst | 13 +------------ 2 files changed, 8 insertions(+), 12 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_locally.rst b/docs/docsite/rst/dev_guide/developing_locally.rst index 4c1423abe49..338c73b743f 100644 --- a/docs/docsite/rst/dev_guide/developing_locally.rst +++ b/docs/docsite/rst/dev_guide/developing_locally.rst @@ -133,3 +133,10 @@ Ansible automatically loads all plugins from certain directories adjacent to you .. warning:: Roles contained in collections cannot contain any plugins. All plugins in a collection must live in the collection ``plugins`` directory tree. All plugins in that tree are accessible to all roles in the collection. If you are developing new plugins, we recommend distributing them in :ref:`collections `, not in roles. + +.. _ansible.legacy.custom: + +Using ``ansible.legacy`` to access custom versions of an ``ansible.builtin`` module +=================================================================================== + +If you need to override one of the ``ansible.builtin`` modules and are using FQCN, you need to use ``ansible.legacy`` as part of the fully-qualified collection name (FQCN). For example, if you had your own ``copy`` module, you would access it as ``ansible.legacy.copy``. See :ref:`using_ansible_legacy` for details on how to use custom modules with roles within a collection. diff --git a/docs/docsite/rst/dev_guide/migrating_roles.rst b/docs/docsite/rst/dev_guide/migrating_roles.rst index 5ca134e558f..ddf79c954ba 100644 --- a/docs/docsite/rst/dev_guide/migrating_roles.rst +++ b/docs/docsite/rst/dev_guide/migrating_roles.rst @@ -413,15 +413,4 @@ The following is an example RPM spec file that accomplishes this using this exam Using ``ansible.legacy`` to access local custom modules from collections-based roles ===================================================================================== -Some roles use :ref:`local custom modules ` 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``. +Some roles within a collection use :ref:`local custom modules ` that are not part of the collection itself. If there is a conflict between the custom module short name and the collection module name, you need to specify which module your tasks call. You can update the tasks to change ``local_module_name`` to ``ansible.legacy.local_module_name`` to ensure you are using the custom module.