@@ -44,10 +44,14 @@

               <a href="{{ meta['github_url'] }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>

             {% else %}

               <!-- Ansible-specific additions for modules etc -->

-                {% if pagename.endswith('_module') %}

-                  <a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/{{ theme_vcs_pageview_mode|default("blob") }}/{{ github_module_version }}{{ meta.get('source', '') }}?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>

-                {% elif pagename.startswith('plugins') and meta.get('source', None) %}

-                  <a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/{{ theme_vcs_pageview_mode|default("blob") }}/{{ github_root_dir }}/{{ pagename }}.py?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>

+                {% if (pagename.endswith('_module')) or (pagename.endswith('_become'))

+                  or (pagename.endswith('_cache')) or (pagename.endswith('_callback'))

+                  or (pagename.endswith('_connection')) or (pagename.endswith('_inventory'))

+                  or (pagename.endswith('_lookup')) or (pagename.endswith('_shell'))

+                  or (pagename.endswith('_strategy')) or (pagename.endswith('_vars'))

+                 %}

+                <!--  <a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/{{ theme_vcs_pageview_mode|default("blob") }}/{{ github_module_version }}{{ meta.get('source', '') }}?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr" class="fa fa-github"> {{ _('Edit on GitHub') }}</a> -->

+                  <br>

                 {% elif pagename.startswith('cli') and meta.get('source', None) %}

                   <a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/{{ theme_vcs_pageview_mode|default("blob") }}/{{ github_cli_version }}{{ meta.get('source', '') }}?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>

                 {% elif (not 'list_of' in pagename) and (not 'category' in pagename) %}

@@ -43,7 +43,7 @@ Here's an overview of the PR lifecycle:

 Automated PR review: ansibullbot

 --------------------------------

-Because Ansible receives many pull requests, and because we love automating things, we've automated several steps of the process of reviewing and merging pull requests with a tool called Ansibullbot, or Ansibot for short.

+Because Ansible receives many pull requests, and because we love automating things, we have automated several steps of the process of reviewing and merging pull requests with a tool called Ansibullbot, or Ansibot for short.

 `Ansibullbot <https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md>`_ serves many functions:

@@ -139,11 +139,7 @@ We don't merge every PR. Here are some tips for making your PR useful, attractiv

 Changelogs

 ----------

-Changelogs help users and developers keep up with changes to Ansible.

-Ansible builds a changelog for each release from fragments.

-You **must** add a changelog fragment to any PR that changes functionality or fixes a bug in ansible-base.

-You don't have to add a changelog fragment for PRs that add new

-modules and plugins, because our tooling does that for you automatically.

+Changelogs help users and developers keep up with changes to Ansible. Ansible builds a changelog for each release from fragments. You **must** add a changelog fragment to any PR that changes functionality or fixes a bug in ansible-base. You do not have to add a changelog fragment for PRs that add new modules and plugins, because our tooling does that for you automatically.

 We build short summary changelogs for minor releases as well as for major releases. If you backport a bugfix, include a changelog fragment with the backport PR.

@@ -152,35 +148,29 @@ We build short summary changelogs for minor releases as well as for major releas

 Creating a changelog fragment

 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-A basic changelog fragment is a ``.yaml`` file placed in the

-``changelogs/fragments/`` directory.  Each file contains a yaml dict with

-keys like ``bugfixes`` or ``major_changes`` followed by a list of

-changelog entries of bugfixes or features.  Each changelog entry is

-rst embedded inside of the yaml file which means that certain

-constructs would need to be escaped so they can be interpreted by rst

-and not by yaml (or escaped for both yaml and rst if that's your

-desire).  Each PR **must** use a new fragment file rather than adding to

-an existing one, so we can trace the change back to the PR that introduced it.

+A basic changelog fragment is a ``.yaml`` file placed in the ``changelogs/fragments/`` directory.  Each file contains a yaml dict with keys like ``bugfixes`` or ``major_changes`` followed by a list of changelog entries of bugfixes or features.  Each changelog entry is rst embedded inside of the yaml file which means that certain constructs would need to be escaped so they can be interpreted by rst and not by yaml (or escaped for both yaml and rst if you prefer).  Each PR **must** use a new fragment file rather than adding to an existing one, so we can trace the change back to the PR that introduced it.

-To create a changelog entry, create a new file with a unique name in the ``changelogs/fragments/`` directory of corresponding repository.

-The file name should include the PR number and a description of the change.

-It must end with the file extension ``.yaml``. For example: ``40696-user-backup-shadow-file.yaml``

+To create a changelog entry, create a new file with a unique name in the ``changelogs/fragments/`` directory of the corresponding repository. The file name should include the PR number and a description of the change. It must end with the file extension ``.yaml``. For example: ``40696-user-backup-shadow-file.yaml``

-A single changelog fragment may contain multiple sections but most will only contain one section.

-The toplevel keys (bugfixes, major_changes, and so on) are defined in the

-`config file <https://github.com/ansible/ansible/blob/devel/changelogs/config.yaml>`_ for our release note tool. Here are the valid sections and a description of each:

+A single changelog fragment may contain multiple sections but most will only contain one section. The toplevel keys (bugfixes, major_changes, and so on) are defined in the `config file <https://github.com/ansible/ansible/blob/devel/changelogs/config.yaml>`_ for our `release note tool <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst>`_. Here are the valid sections and a description of each:

+

+**breaking_changes**

+  Changes that break existing playbooks or roles. This includes any change to existing behavior that forces users to update tasks. Displayed in both the changelogs and the :ref:`Porting Guides <porting_guides>`.

 **major_changes**

-  Major changes to Ansible itself. Generally does not include module or plugin changes.

+  Major changes to Ansible itself. Generally does not include module or plugin changes. Displayed in both the changelogs and the :ref:`Porting Guides <porting_guides>`.

 **minor_changes**

   Minor changes to Ansible, modules, or plugins. This includes new features, new parameters added to modules, or behavior changes to existing parameters.

 **deprecated_features**

-  Features that have been deprecated and are scheduled for removal in a future release.

+  Features that have been deprecated and are scheduled for removal in a future release. Displayed in both the changelogs and the :ref:`Porting Guides <porting_guides>`.

 **removed_features**

-  Features that were previously deprecated and are now removed.

+  Features that were previously deprecated and are now removed. Displayed in both the changelogs and the :ref:`Porting Guides <porting_guides>`.

+

+**security_fixes**

+  Fixes that address CVEs or resolve security concerns. Include links to CVE information.

 **bugfixes**

   Fixes that resolve issues.

@@ -188,8 +178,7 @@ The toplevel keys (bugfixes, major_changes, and so on) are defined in the

 **known_issues**

   Known issues that are currently not fixed or will not be fixed.

-Each changelog entry must contain a link to its issue between parentheses at the end.

-If there is no corresponding issue, the entry must contain a link to the PR itself.

+Each changelog entry must contain a link to its issue between parentheses at the end. If there is no corresponding issue, the entry must contain a link to the PR itself.

 Most changelog entries will be ``bugfixes`` or ``minor_changes``. When writing a changelog entry that pertains to a particular module, start the entry with ``- [module name] -`` and the following sentence with a lowercase letter.

@@ -222,9 +211,7 @@ Once you've written the changelog fragment for your PR, commit the file and incl

 Backporting merged PRs

 ======================

-All Ansible PRs must be merged to the ``devel`` branch first.

-After a pull request has been accepted and merged to the ``devel`` branch, the following instructions will help you create a

-pull request to backport the change to a previous stable branch.

+All Ansible PRs must be merged to the ``devel`` branch first. After a pull request has been accepted and merged to the ``devel`` branch, the following instructions will help you create a pull request to backport the change to a previous stable branch.

 We do **not** backport features.

@@ -6,7 +6,7 @@ Python API

 .. contents:: Topics

-.. note:: This API is intended for internal Ansible use. Ansible may make changes to this API at any time that could break backward compatibility with older versions of the API. Because of this, external use is not supported by Ansible.

+.. note:: This API is intended for internal Ansible use. Ansible may make changes to this API at any time that could break backward compatibility with older versions of the API. Because of this, external use is not supported by Ansible. If you want to use Python API only for executing playbooks or modules, consider `ansible-runner <https://ansible-runner.readthedocs.io/en/latest/>`_ first.

 There are several ways to use Ansible from an API perspective.   You can use

 the Ansible Python API to control nodes, you can extend Ansible to respond to various Python events, you can

@@ -25,6 +25,8 @@ Collections follow a simple data structure. None of the directories are required

     collection/

     ├── docs/

     ├── galaxy.yml

+    ├── meta/

+    │   └── runtime.yml

     ├── plugins/

     │   ├── modules/

     │   │   └── module1.py

@@ -194,6 +196,64 @@ command completion, or environment variables are presented throughout the

 Ansible Collection Testing because the act of installing the stable release of

 Ansible containing `ansible-test` is expected to setup those things for you.

+.. _meta_runtime_yml:

+

+meta directory

+--------------

+

+A collection can store some additional metadata in a ``runtime.yml`` file in the collection's ``meta`` directory. The ``runtime.yml`` file supports the top level keys:

+

+- *requires_ansible*:

+

+  The version of Ansible required to use the collection. Multiple versions can be separated with a comma.

+

+  .. code:: yaml

+

+     requires_ansible: ">=2.10,<2.11"

+

+  .. note:: although the version is a `PEP440 Version Specifier <https://www.python.org/dev/peps/pep-0440/#version-specifiers>`_ under the hood, Ansible deviates from PEP440 behavior by truncating prerelease segments from the Ansible version. This means that Ansible 2.11.0b1 is compatible with something that ``requires_ansible: ">=2.11"``.

+

+- *plugin_routing*:

+

+  Content in a collection that Ansible needs to load from another location or that has been deprecated/removed.

+  The top level keys of ``plugin_routing`` are types of plugins, with individual plugin names as subkeys.

+  To define a new location for a plugin, set the ``redirect`` field to another name.

+  To deprecate a plugin, use the ``deprecation`` field to provide a custom warning message and the removal date or version. If the plugin has been renamed or moved to a new location, the ``redirect`` field should also be provided. If a plugin is being removed entirely, ``tombstone`` can be used for the fatal error message and removal date or version.

+

+  .. code:: yaml

+

+     plugin_routing:

+       inventory:

+         kubevirt:

+           redirect: community.general.kubevirt

+         my_inventory:

+           tombstone:

+             removal_version: "2.0.0"

+             warning_text: my_inventory has been removed. Please use other_inventory instead.

+       modules:

+         my_module:

+           deprecation:

+             removal_date: "2021-11-30"

+             warning_text: my_module will be removed in a future release of this collection. Use another.collection.new_module instead.

+           redirect: another.collection.new_module

+         podman_image:

+           redirect: containers.podman.podman_image

+       module_utils:

+         ec2:

+           redirect: amazon.aws.ec2

+         util_dir.subdir.my_util:

+           redirect: namespace.name.my_util

+

+- *import_redirection*

+

+  A mapping of names for Python import statements and their redirected locations.

+

+  .. code:: yaml

+

+     import_redirection:

+       ansible.module_utils.old_utility:

+         redirect: ansible_collections.collection_name.plugins.module_utils.new_location

+

 .. _creating_collections_skeleton:

@@ -469,16 +529,63 @@ Collection versions use `Semantic Versioning <https://semver.org/>`_ for version

 .. _migrate_to_collection:

-Migrating Ansible content to a collection

-=========================================

+Migrating Ansible content to a different collection

+====================================================

+

+To migrate content from one collection to another, you need to create three PRs as follows:

+

+#. Create a PR against the old collection to remove the content.

+#. Create a PR against the new collection to add the files removed in step 1.

+#. Update the ``ansible/ansible:devel`` branch entries for all files moved.

+

+

+Removing the content from the old collection

+----------------------------------------------

+

+Create a PR against the old collection repo to remove the modules, module_utils, plugins, and docs_fragments related to this migration:

+

+#. If you are removing an action plugin, remove the corresponding module that contains the documentation.

+#. If you are removing a module, remove any corresponding action plugin that should stay with it.

+#. Remove any entries about removed plugins from ``meta/runtime.yml``. Ensure they are added into the new repo.

+#. Remove sanity ignore lines from ``tests/sanity/ignore\*.txt``

+#. Remove associated integration tests from ``tests/integrations/targets/`` and unit tests from ``tests/units/plugins/``.

+#. if you are removing from content from ``community.general`` or ``community.network``, remove entries from ``.github/BOTMETA.yml``.

+#. Carefully review ``meta/runtime.yml`` for any entries you may need to remove or update, in particular deprecated entries.

+#. Update ``meta/runtime.yml`` to contain redirects for EVERY PLUGIN, pointing to the new collection name.

+#. If possible, do not yet add deprecation warnings to the new ``meta/runtime.yml`` entries, but only for a later major release. So the order should be:

+    1. Remove content, add redirects in 3.0.0;

+    2. Deprecate redirects in 4.0.0;

+    3. Set removal version to 5.0.0 or later.

-You can experiment with migrating existing modules into a collection using the `content_collector tool <https://github.com/ansible/content_collector>`_. The ``content_collector`` is a playbook that helps you migrate content from an Ansible distribution into a collection.

 .. warning::

-	This tool is in active development and is provided only for experimentation and feedback at this point.

+	Maintainers for the old collection have to make sure that the PR is merged in a way that it does not break user experience and semantic versioning:

+

+	#. A new version containing the merged PR must not be released before the collection the content has been moved to has been released again, with that content contained in it. Otherwise the redirects cannot work and users relying on that content will experience breakage.

+	#. Once 1.0.0 of the collection from which the content has been removed has been released, such PRs can only be merged for a new **major** version (i.e. 2.0.0, 3.0.0, etc.).

+

+

+Adding the content to the new collection

+-----------------------------------------

+

+Create a PR in the new collection to:

+

+#. Add ALL the files removed in first PR (from the old collection).

+#. If it is an action plugin, include the corresponding module with documentation.

+#. If it is a module, check if it has a corresponding action plugin that should move with it.

+#. Check ``meta/ `` for relevant updates to ``action_groups.yml`` and ``runtime.yml`` if they exist.

+#. Carefully check the moved ``tests/integration`` and ``tests/units`` and update for FQCN.

+#. Review ``tests/sanity/ignore-\*.txt`` entries.

+#. Update ``meta/runtime.yml``.

+

+Updating ``ansible/ansible:devel`` branch entries for all files moved

+----------------------------------------------------------------------

+

+Create a third PR on ``ansible/ansible`` repository to:

-See the `content_collector README <https://github.com/ansible/content_collector>`_ for full details and usage guidelines.

+#. Update ``lib/ansible/config/ansible_builtin_runtime.yml`` (the redirect entry).

+#. Update ``.github/BOTMETA.yml`` (the migrated_to entry)

 BOTMETA.yml

 -----------

@@ -486,7 +593,6 @@ BOTMETA.yml

 The `BOTMETA.yml <https://github.com/ansible/ansible/blob/devel/.github/BOTMETA.yml>`_ in the ansible/ansible GitHub repository is the source of truth for:

 * ansibullbot

-* the docs build for collections-based modules

 Ansibulbot will know how to redirect existing issues and PRs to the new repo.

 The build process for docs.ansible.com will know where to find the module docs.

@@ -232,6 +232,10 @@ The preferred way to install Ansible on a Mac is with ``pip``.

 The instructions can be found in :ref:`from_pip`. If you are running macOS version 10.12 or older, then you should upgrade to the latest ``pip`` to connect to the Python Package Index securely. It should be noted that pip must be run as a module on macOS, and the linked ``pip`` instructions will show you how to do that.

+.. note::

+

+	If you have Ansible 2.9 or older installed, you need to use ``pip uninstall ansible`` first to remove older versions of Ansible before re-installing it.

+

 If you are installing on macOS Mavericks (10.9), you may encounter some noise from your compiler. A workaround is to do the following::

     $ CFLAGS=-Qunused-arguments CPPFLAGS=-Qunused-arguments pip install --user ansible

@@ -301,6 +305,10 @@ Ansible can be installed with ``pip``, the Python package manager. If ``pip`` is

     $ curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py

     $ python get-pip.py --user

+.. note::

+

+  	If you have Ansible 2.9 or older installed, you need to use ``pip uninstall ansible`` first to remove older versions of Ansible before re-installing it.

+

 Then install Ansible [1]_::

     $ python -m pip install --user ansible

@@ -324,6 +332,33 @@ If you wish to install Ansible globally, run the following commands::

     Please make sure you have the latest version of ``pip`` before installing Ansible.

     If you have an older version of ``pip`` installed, you can upgrade by following `pip's upgrade instructions <https://pip.pypa.io/en/stable/installing/#upgrading-pip>`_ .

+Upgrading Ansible from version 2.9 and older to version 2.10 or later

+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

+

+Starting in version 2.10, Ansible is made of two packages. You need to first uninstall the old Ansible version (2.9 or earlier) before upgrading.

+If you do not uninstall the older version of Ansible, you will see the following message, and no change will be performed:

+

+.. code-block:: console

+

+    Cannot install ansible-base with a pre-existing ansible==2.x installation.

+

+    Installing ansible-base with ansible-2.9 or older currently installed with

+    pip is known to cause problems. Please uninstall ansible and install the new

+    version:

+

+    pip uninstall ansible

+    pip install ansible-base

+

+    ...

+

+As explained by the message, to upgrade you must first remove the version of Ansible installed and then install it

+to the latest version.

+

+.. code-block:: console

+

+    $ pip uninstall ansible

+    $ pip install ansible

+

 .. _from_pip_devel:

 Installing the development version of Ansible

@@ -333,6 +368,10 @@ Installing the development version of Ansible

     You should only run Ansible from ``devel`` if you are modifying the Ansible engine, or trying out features under development. This is a rapidly changing source of code and can become unstable at any point.

+.. note::

+

+    If you have Ansible 2.9 or older installed, you need to use ``pip uninstall ansible`` first to remove older versions of Ansible before re-installing it.

+

 The development version of Ansible can be directly installed from GitHub with pip::

     $ python -m pip install --user https://github.com/ansible/ansible/archive/devel.tar.gz

@@ -348,6 +387,10 @@ See :ref:`from_source` for instructions on how to run Ansible directly from sour

 Virtual Environments

 ^^^^^^^^^^^^^^^^^^^^

+.. note::

+

+	If you have Ansible 2.9 or older installed, you need to use ``pip uninstall ansible`` first to remove older versions of Ansible before re-installing it.

+

 Ansible can also be installed inside a new or existing ``virtualenv``::

     $ python -m virtualenv ansible  # Create a virtualenv if one does not already exist

@@ -113,7 +113,9 @@ The ``handle_httperror(self, exception)`` method can deal with status codes retu

 * A value of ``true`` means that the request can be retried. This my be used to indicate a transient error, or one that has been resolved. For example, the default implementation will try to call ``login()`` when presented with a 401, and return ``true`` if successful.

-* A value of ``false`` means that the plugin is unable to recover from this response. The status code will be returned to the calling module as an exception. Any other value will be taken as a nonfatal response from the request. This may be useful if the server returns error messages in the body of the response. Returning the original exception is usually sufficient in this case, as HTTPError objects have the same interface as a successful response.

+* A value of ``false`` means that the plugin is unable to recover from this response. The status code will be raised as an exception to the calling module.

+

+* Any other value will be taken as a nonfatal response from the request. This may be useful if the server returns error messages in the body of the response. Returning the original exception is usually sufficient in this case, as HTTPError objects have the same interface as a successful response.

 For example httpapi plugins, see the `source code for the httpapi plugins <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/httpapi>`_ included with Ansible Core.

@@ -4,11 +4,12 @@

 CloudEngine OS Platform Options

 ***************************************

-CloudEngine CE OS supports multiple connections. This page offers details on how each connection works in Ansible and how to use it.

+CloudEngine CE OS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and supports multiple connections. This page offers details on how each connection works in Ansible and how to use it.

-.. contents:: Topics

+.. contents::

+  :local:

-Connections Available

+Connections available

 ================================================================================

 .. table::

@@ -27,7 +28,8 @@ Connections Available

     Indirect Access       via a bastion (jump host)                   via a bastion (jump host)

-    Connection Settings   ``ansible_connection: network_cli``         ``ansible_connection: netconf``

+    Connection Settings   ``ansible_connection:``                     ``ansible_connection:``

+                            ``ansible.netcommon.network_cli``           ``ansible.netcommon.netconf``

     |enable_mode|         not supported by ce OS                      not supported by ce OS

@@ -36,7 +38,7 @@ Connections Available

 .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation)

-For legacy playbooks, Ansible still supports ``ansible_connection=local`` on all CloudEngine modules. We recommend modernizing to use ``ansible_connection=netconf`` or ``ansible_connection=network_cli`` as soon as possible.

+The ``ansible_connection: local`` has been deprecated. Please use  ``ansible_connection: ansible.netcommon.netconf`` or ``ansible_connection=ansible.netcommon.network_cli`` instead.

 Using CLI in Ansible

 ====================

@@ -47,8 +49,8 @@ Example CLI inventory ``[ce:vars]``

 .. code-block:: yaml

    [ce:vars]

-   ansible_connection=network_cli

-   ansible_network_os=ce

+   ansible_connection=ansible.netcommon.network_cli

+   ansible_network_os=community.network.ce

    ansible_user=myuser

    ansible_password=!vault...

    ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"'

@@ -58,15 +60,15 @@ Example CLI inventory ``[ce:vars]``

 - If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration.

 - If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.

-Example CLI Task

+Example CLI task

 ----------------

 .. code-block:: yaml

    - name: Retrieve CE OS version

-     ce_command:

+     community.network.ce_command:

        commands: display version

-     when: ansible_network_os == 'ce'

+     when: ansible_network_os == 'community.network.ce'

 Using NETCONF in Ansible

@@ -80,16 +82,16 @@ Before you can use NETCONF to connect to a switch, you must:

 - install the ``ncclient`` python package on your control node(s) with ``pip install ncclient``

 - enable NETCONF on the CloudEngine OS device(s)

-To enable NETCONF on a new switch via Ansible, use the ``ce_config`` module via the CLI connection. Set up your platform-level variables just like in the CLI example above, then run a playbook task like this:

+To enable NETCONF on a new switch using Ansible, use the ``community.network.ce_config`` module with the CLI connection. Set up your platform-level variables just like in the CLI example above, then run a playbook task like this:

 .. code-block:: yaml

    - name: Enable NETCONF

-     connection: network_cli

-     ce_config:

+     connection: ansible.netcommon.network_cli

+     community.network.ce_config:

        lines:

          - snetconf server enable

-     when: ansible_network_os == 'ce'

+     when: ansible_network_os == 'community.network.ce'

 Once NETCONF is enabled, change your variables to use the NETCONF connection.

@@ -99,110 +101,110 @@ Example NETCONF inventory ``[ce:vars]``

 .. code-block:: yaml

    [ce:vars]

-   ansible_connection=netconf

-   ansible_network_os=ce

+   ansible_connection=ansible.netcommon.netconf

+   ansible_network_os=community.network.ce

    ansible_user=myuser

    ansible_password=!vault |

    ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"'

-Example NETCONF Task

+Example NETCONF task

 --------------------

 .. code-block:: yaml

    - name: Create a vlan, id is 50(ce)

-     ce_vlan:

+     community.network.ce_vlan:

        vlan_id: 50

        name: WEB

-     when: ansible_network_os == 'ce'

+     when: ansible_network_os == 'community.network.ce'

 Notes

 ========================

-Modules work with connection C(network_cli)

+Modules that work with ``ansible.netcommon.network_cli``

+---------------------------------------------------------

 .. code-block:: yaml

-   ce_acl_interface

-   ce_command

-   ce_config

-   ce_evpn_bgp

-   ce_evpn_bgp_rr

-   ce_evpn_global

-   ce_facts

-   ce_mlag_interface

-   ce_mtu

-   ce_netstream_aging

-   ce_netstream_export

-   ce_netstream_global

-   ce_netstream_template

-   ce_ntp_auth

-   ce_rollback

-   ce_snmp_contact

-   ce_snmp_location

-   ce_snmp_traps

-   ce_startup

-   ce_stp

-   ce_vxlan_arp

-   ce_vxlan_gateway

-   ce_vxlan_global

-

-

-Modules work with connection C(netconf)

+   community.network.ce_acl_interface

+   community.network.ce_command

+   community.network.ce_config

+   community.network.ce_evpn_bgp

+   community.network.ce_evpn_bgp_rr

+   community.network.ce_evpn_global

+   community.network.ce_facts

+   community.network.ce_mlag_interface

+   community.network.ce_mtu

+   community.network.ce_netstream_aging

+   community.network.ce_netstream_export

+   community.network.ce_netstream_global

+   community.network.ce_netstream_template

+   community.network.ce_ntp_auth

+   community.network.ce_rollback

+   community.network.ce_snmp_contact

+   community.network.ce_snmp_location

+   community.network.ce_snmp_traps

+   community.network.ce_startup

+   community.network.ce_stp

+   community.network.ce_vxlan_arp

+   community.network.ce_vxlan_gateway

+   community.network.ce_vxlan_global

+

+

+Modules that work with ``ansible.netcommon.netconf``

+-----------------------------------------------------

 .. code-block:: yaml

-   ce_aaa_server

-   ce_aaa_server_host

-   ce_acl

-   ce_acl_advance

-   ce_bfd_global

-   ce_bfd_session

-   ce_bfd_view

-   ce_bgp

-   ce_bgp_af

-   ce_bgp_neighbor

-   ce_bgp_neighbor_af

-   ce_dldp

-   ce_dldp_interface

-   ce_eth_trunk

-   ce_evpn_bd_vni

-   ce_file_copy

-   ce_info_center_debug

-   ce_info_center_global

-   ce_info_center_log

-   ce_info_center_trap

-   ce_interface

-   ce_interface_ospf

-   ce_ip_interface

-   ce_lacp

-   ce_link_status

-   ce_lldp

-   ce_lldp_interface

-   ce_mlag_config

-   ce_netconf

-   ce_ntp

-   ce_ospf

-   ce_ospf_vrf

-   ce_reboot

-   ce_sflow

-   ce_snmp_community

-   ce_snmp_target_host

-   ce_snmp_user

-   ce_static_route

-   ce_static_route_bfd

-   ce_switchport

-   ce_vlan

-   ce_vrf

-   ce_vrf_af

-   ce_vrf_interface

-   ce_vrrp

-   ce_vxlan_tunnel

-   ce_vxlan_vap

+   community.network.ce_aaa_server

+   community.network.ce_aaa_server_host

+   community.network.ce_acl

+   community.network.ce_acl_advance

+   community.network.ce_bfd_global

+   community.network.ce_bfd_session

+   community.network.ce_bfd_view

+   community.network.ce_bgp

+   community.network.ce_bgp_af

+   community.network.ce_bgp_neighbor

+   community.network.ce_bgp_neighbor_af

+   community.network.ce_dldp

+   community.network.ce_dldp_interface

+   community.network.ce_eth_trunk

+   community.network.ce_evpn_bd_vni

+   community.network.ce_file_copy

+   community.network.ce_info_center_debug

+   community.network.ce_info_center_global

+   community.network.ce_info_center_log

+   community.network.ce_info_center_trap

+   community.network.ce_interface

+   community.network.ce_interface_ospf

+   community.network.ce_ip_interface

+   community.network.ce_lacp

+   community.network.ce_link_status

+   community.network.ce_lldp

+   community.network.ce_lldp_interface

+   community.network.ce_mlag_config

+   community.network.ce_netconf

+   community.network.ce_ntp

+   community.network.ce_ospf

+   community.network.ce_ospf_vrf

+   community.network.ce_reboot

+   community.network.ce_sflow

+   community.network.ce_snmp_community

+   community.network.ce_snmp_target_host

+   community.network.ce_snmp_user

+   community.network.ce_static_route

+   community.network.ce_static_route_bfd

+   community.network.ce_switchport

+   community.network.ce_vlan

+   community.network.ce_vrf

+   community.network.ce_vrf_af

+   community.network.ce_vrf_interface

+   community.network.ce_vrrp

+   community.network.ce_vxlan_tunnel

+   community.network.ce_vxlan_vap

 .. include:: shared_snippets/SSH_warning.txt

@@ -4,11 +4,12 @@

 CNOS Platform Options

 ***************************************

-CNOS supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on CNOS in Ansible.

+CNOS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on CNOS in Ansible.

-.. contents:: Topics

+.. contents::

+  :local:

-Connections Available

+Connections available

 ================================================================================

 .. table::

@@ -25,7 +26,7 @@ Connections Available

     Indirect Access       via a bastion (jump host)

-    Connection Settings   ``ansible_connection: network_cli``

+    Connection Settings   ``ansible_connection: ansible.netcommon.network_cli``

     |enable_mode|         supported: use ``ansible_become: yes``

                           with ``ansible_become_method: enable``

@@ -36,7 +37,7 @@ Connections Available

 .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation)

-For legacy playbooks, CNOS still supports ``ansible_connection: local``. We recommend modernizing to use ``ansible_connection: network_cli`` as soon as possible.

+The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead.

 Using CLI in Ansible

 ================================================================================

@@ -46,8 +47,8 @@ Example CLI ``group_vars/cnos.yml``

 .. code-block:: yaml

-   ansible_connection: network_cli

-   ansible_network_os: cnos

+   ansible_connection: ansible.netcommon.network_cli

+   ansible_network_os: community.network.cnos

    ansible_user: myuser

    ansible_password: !vault...

    ansible_become: yes

@@ -60,15 +61,15 @@ Example CLI ``group_vars/cnos.yml``

 - If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration.

 - If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.

-Example CLI Task

+Example CLI task

 ----------------

 .. code-block:: yaml

    - name: Retrieve CNOS OS version

-     cnos_command:

+     community.network.cnos_command:

        commands: show version

-     when: ansible_network_os == 'cnos'

+     when: ansible_network_os == 'community.network.cnos'

 .. include:: shared_snippets/SSH_warning.txt

@@ -4,11 +4,12 @@

 Dell OS10 Platform Options

 ***************************************

-OS10 supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS10 in Ansible.

+The `dellemc.os10 <https://galaxy.ansible.com/dellemc_networking/os10>`_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS10 in Ansible.

-.. contents:: Topics

+.. contents::

+  :local:

-Connections Available

+Connections available

 ================================================================================

 .. table::

@@ -25,7 +26,7 @@ Connections Available

     Indirect Access       via a bastion (jump host)

-    Connection Settings   ``ansible_connection: network_cli``

+    Connection Settings   ``ansible_connection: ansible.netcommon.network_cli``

     |enable_mode|         supported: use ``ansible_become: yes``

                           with ``ansible_become_method: enable``

@@ -36,7 +37,8 @@ Connections Available

 .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation)

-For legacy playbooks, OS10 still supports ``ansible_connection: local``. We recommend modernizing to use ``ansible_connection: network_cli`` as soon as possible.

+The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead.

+

 Using CLI in Ansible

 ================================================================================

@@ -46,8 +48,8 @@ Example CLI ``group_vars/dellos10.yml``

 .. code-block:: yaml

-   ansible_connection: network_cli

-   ansible_network_os: dellos10

+   ansible_connection: ansible.netcommon.network_cli

+   ansible_network_os: dellemc.os10.os10

    ansible_user: myuser

    ansible_password: !vault...

    ansible_become: yes

@@ -60,16 +62,16 @@ Example CLI ``group_vars/dellos10.yml``

 - If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration.

 - If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.

-Example CLI Task

+Example CLI task

 ----------------

 .. code-block:: yaml

    - name: Backup current switch config (dellos10)

-     dellos10_config:

+     dellemc.os10.os10_config:

        backup: yes

      register: backup_dellos10_location

-     when: ansible_network_os == 'dellos10'

+     when: ansible_network_os == 'dellemc.os10.os10'

 .. include:: shared_snippets/SSH_warning.txt

@@ -4,11 +4,12 @@

 Dell OS6 Platform Options

 ***************************************

-OS6 supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS6 in Ansible.

+The `dellemc.os6 <https://github.com/ansible-collections/dellemc.os6>`_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS6 in Ansible.

-.. contents:: Topics

+.. contents::

+  :local:

-Connections Available

+Connections available

 ================================================================================

 .. table::

@@ -25,7 +26,7 @@ Connections Available

     Indirect Access       via a bastion (jump host)

-    Connection Settings   ``ansible_connection: network_cli``

+    Connection Settings   ``ansible_connection: ansible.netcommon.network_cli``

     |enable_mode|         supported: use ``ansible_become: yes``

                           with ``ansible_become_method: enable``

@@ -36,7 +37,7 @@ Connections Available

 .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation)

-For legacy playbooks, OS6 still supports ``ansible_connection: local``. We recommend modernizing to use ``ansible_connection: network_cli`` as soon as possible.

+The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead.

 Using CLI in Ansible

 ================================================================================

@@ -46,8 +47,8 @@ Example CLI ``group_vars/dellos6.yml``

 .. code-block:: yaml

-   ansible_connection: network_cli

-   ansible_network_os: dellos6

+   ansible_connection: ansible.netcommon.network_cli

+   ansible_network_os: dellemc.os6.os6

    ansible_user: myuser

    ansible_password: !vault...

    ansible_become: yes

@@ -60,16 +61,16 @@ Example CLI ``group_vars/dellos6.yml``

 - If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration.

 - If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.

-Example CLI Task

+Example CLI task

 ----------------

 .. code-block:: yaml

    - name: Backup current switch config (dellos6)

-     dellos6_config:

+     dellemc.os6.os6_config:

        backup: yes

      register: backup_dellso6_location

-     when: ansible_network_os == 'dellos6'

+     when: ansible_network_os == 'dellemc.os6.os6'

 .. include:: shared_snippets/SSH_warning.txt

@@ -4,11 +4,12 @@

 Dell OS9 Platform Options

 ***************************************

-OS9 supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS9 in Ansible.

+The `dellemc.os9 <https://github.com/ansible-collections/dellemc.os9>`_ collection  supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS9 in Ansible.

-.. contents:: Topics

+.. contents::

+  :local:

-Connections Available

+Connections available

 ================================================================================

 .. table::

@@ -25,7 +26,7 @@ Connections Available