From db33ca8e1a8b9805eb0a074eee86aaa2237065cd Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Thu, 15 Sep 2022 11:12:48 -0400 Subject: [PATCH] faq legacy vs builtin (#78769) --- docs/docsite/rst/reference_appendices/faq.rst | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index 486fb5f09a2..feeb99bdac4 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -845,6 +845,35 @@ How do I submit a change to the documentation? Documentation for Ansible is kept in the main project git repository, and complete instructions for contributing can be found in the docs README `viewable on GitHub `_. Thanks! + +.. _legacy_vs_builtin: + +What is the difference between ``ansible.legacy`` and ``ansible.builtin`` collections? +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Neither is a real collection. They are virtually constructed by the core engine (synthetic collections). + +The ``ansible.builtin`` collection only refers to plugins that ship with ``ansible-core``. + +The ``ansible.legacy`` collection is a superset of ``ansible.builtin`` (you can reference the plugins from builtin through ``ansible.legacy``). You also get the ability to +add 'custom' plugins in the :ref:`configured paths and adjacent directories `, with the ability to override the builtin plugins that have the same name. + +Also, ``ansible.legacy`` is what you get by default when you do not specify an FQCN. +So this: + + .. code-block:: yaml + + - shell: echo hi + +Is really equivalent to: + + .. code-block:: yaml + + - ansible.legacy.shell: echo hi + +Though, if you do not override the ``shell`` module, you can also just write it as ``ansible.builtin.shell``, since legacy will resolve to the builtin collection. + + .. _i_dont_see_my_question: I don't see my question here