Update netconf_config module (#44379)

Fixes #40650
Fixes #40245
Fixes #41541

*  Refactor netconf_config module as per proposal #104
*  Update netconf_config module metadata to core network supported
*  Refactor local connection to use persistent connection framework
   for backward compatibility
*  Update netconf connection plugin configuration varaibles (Fixes #40245)
*  Add support for optional lock feature to Fixes #41541
*  Add integration test for netconf_config module
*  Documentation update
* Move deprecated options in netconf_config module

docs/docsite/rst/network/user_guide/platform_index.rst

@@ -20,6 +20,7 @@ Some Ansible Network platforms support multiple connection types, privilege esca
    platform_routeros
    platform_slxos
    platform_voss
+   platform_netconf_enabled
 
 .. _settings_by_platform:
 
@@ -63,5 +64,8 @@ Settings by Platform
 +-------------------+-------------------------+----------------------+----------------------+------------------+------------------+
 | VyOS*             | ``vyos``                | in v. >=2.5          | N/A                  | N/A              |  in v. >=2.4     |
 +-------------------+-------------------------+----------------------+----------------------+------------------+------------------+
+| OS that supports  | ``<network-os>``        | N/A                  | in v. >=2.6          | N/A              | in v. >=2.2      |
+| Netconf*          |                         |                      |                      |                  |                  |
++-------------------+-------------------------+----------------------+----------------------+------------------+------------------+
 
 `*` Maintained by Ansible Network Team

docs/docsite/rst/network/user_guide/platform_netconf_enabled.rst

@@ -0,0 +1,89 @@
+.. _netconf_enabled_platform_options:
+
+***************************************
+Netconf enabled Platform Options
+***************************************
+
+This page offers details on how the netconf connection works in Ansible 2.7 and how to use it.
+
+.. contents:: Topics
+
+Connections Available
+================================================================================
+
++----------------------------+----------------------------------------------------------------------------------------------------+
+| |                          | | NETCONF                                                                                          |
+| |                          | | * all modules except ``junos_netconf``, which enables NETCONF                                    |
++============================+====================================================================================================+
+| **Protocol**               | XML over SSH                                                                                       |
++----------------------------+----------------------------------------------------------------------------------------------------+
+| | **Credentials**          | | uses SSH keys / SSH-agent if present                                                             |
+| |                          | | accepts ``-u myuser -k`` if using password                                                       |
++----------------------------+----------------------------------------------------------------------------------------------------+
+| **Indirect Access**        | via a bastion (jump host)                                                                          |
++----------------------------+----------------------------------------------------------------------------------------------------+
+| **Connection Settings**    |   ``ansible_connection: netconf``                                                                  |
++----------------------------+----------------------------------------------------------------------------------------------------+
+
+For legacy playbooks, Ansible still supports ``ansible_connection=local`` for the netconf_config module only. We recommend modernizing to use ``ansible_connection=netconf`` as soon as possible.
+
+Using NETCONF in Ansible 2.6 onwards
+================================================================================
+
+Enabling NETCONF
+----------------
+
+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 Junos OS device(s)
+
+To enable NETCONF on a new switch via Ansible, use the platform specific module via the CLI connection or set it manually.
+For example 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
+     junos_netconf:
+     when: ansible_network_os == 'junos'
+
+Once NETCONF is enabled, change your variables to use the NETCONF connection.
+
+Example NETCONF inventory ``[junos:vars]``
+------------------------------------------
+
+.. code-block:: yaml
+
+   [junos:vars]
+   ansible_connection=netconf
+   ansible_network_os=junos
+   ansible_user=myuser
+   ansible_ssh_pass=!vault |
+
+
+Example NETCONF Task
+--------------------
+
+.. code-block:: yaml
+
+   - name: Backup current switch config
+     netconf_config:
+       backup: yes
+     register: backup_junos_location
+
+Example NETCONF Task with configurable variables
+------------------------------------------------
+
+.. code-block:: yaml
+
+   - name: configure interface while providing different private key file path
+     netconf_config:
+       backup: yes
+     register: backup_junos_location
+     vars:
+       ansible_private_key_file: /home/admin/.ssh/newprivatekeyfile
+
+Note: For nectonf connection plugin configurable variables .. _Refer: https://docs.ansible.com/ansible/latest/plugins/connection/netconf.html
+
+.. include:: shared_snippets/SSH_warning.txt