Add iosxr platform guide (#60936)

Signed-off-by: NilashishC <nilashishchakraborty8@gmail.com>

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

@@ -20,6 +20,7 @@ Some Ansible Network platforms support multiple connection types, privilege esca
    platform_exos
    platform_icx
    platform_ios
+   platform_iosxr
    platform_ironware
    platform_junos
    platform_netvisor

docs/docsite/rst/network/user_guide/platform_iosxr.rst

@@ -0,0 +1,124 @@
+.. _iosxr_platform_options:
+
+***************************************
+IOS-XR Platform Options
+***************************************
+
+IOS-XR supports multiple connections. This page offers details on how each connection works in Ansible and how to use it.
+
+.. contents:: Topic
+
+Connections Available
+================================================================================
+
+.. table::
+    :class: documentation-table
+
+    ====================  ==========================================  =========================
+    ..                    CLI                                         NETCONF
+
+                                                                      only for modules ``iosxr_banner``, 
+                                                                      ``iosxr_interface``, ``iosxr_logging``, 
+                                                                      ``iosxr_system``, ``iosxr_user``
+    ====================  ==========================================  =========================
+    Protocol              SSH                                         XML over SSH
+
+    Credentials           uses SSH keys / SSH-agent if present        uses SSH keys / SSH-agent if present
+
+                          accepts ``-u myuser -k`` if using password  accepts ``-u myuser -k`` if using password
+
+    Indirect Access       via a bastion (jump host)                   via a bastion (jump host)
+
+    Connection Settings   ``ansible_connection: network_cli``         ``ansible_connection: netconf``
+
+    |enable_mode|         not supported                               not supported
+
+    Returned Data Format  Refer to individual module documentation    Refer to individual module documentation
+    ====================  ==========================================  =========================
+
+.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation)
+
+
+For legacy playbooks, Ansible still supports ``ansible_connection=local`` on all IOS-XR modules. We recommend modernizing to use ``ansible_connection=netconf`` or ``ansible_connection=network_cli`` as soon as possible.
+
+Using CLI in Ansible
+====================
+
+Example CLI inventory ``[iosxr:vars]``
+--------------------------------------
+
+.. code-block:: yaml
+
+   [iosxr:vars]
+   ansible_connection=network_cli
+   ansible_network_os=iosxr
+   ansible_user=myuser
+   ansible_password=!vault...
+   ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"'
+
+
+- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration.
+- 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
+----------------
+
+.. code-block:: yaml
+
+   - name: Retrieve IOS-XR version
+     iosxr_command:
+       commands: show version
+     when: ansible_network_os == 'iosxr'
+
+
+Using NETCONF in Ansible
+========================
+
+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 Cisco IOS-XR device(s)
+
+To enable NETCONF on a new switch via Ansible, use the ``iosxr_netconf`` 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:
+
+.. code-block:: yaml
+
+   - name: Enable NETCONF
+     connection: network_cli
+     iosxr_netconf:
+     when: ansible_network_os == 'iosxr'
+
+Once NETCONF is enabled, change your variables to use the NETCONF connection.
+
+Example NETCONF inventory ``[iosxr:vars]``
+------------------------------------------
+
+.. code-block:: yaml
+
+   [iosxr:vars]
+   ansible_connection=netconf
+   ansible_network_os=iosxr
+   ansible_user=myuser
+   ansible_password=!vault |
+   ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"'
+
+
+Example NETCONF Task
+--------------------
+
+.. code-block:: yaml
+
+   - name: Configure hostname and domain-name
+     iosxr_system:
+       hostname: iosxr01
+       domain_name: test.example.com
+       domain_search:
+         - ansible.com
+         - redhat.com
+         - cisco.com
+
+.. include:: shared_snippets/SSH_warning.txt

lib/ansible/modules/network/iosxr/_iosxr_interface.py

@@ -28,9 +28,13 @@ deprecated:
   removed_in: '2.13'
   alternative: iosxr_interfaces
   why: Newer and updated modules released with more functionality in Ansible 2.9
+requirements:
+    - ncclient >= 0.5.3 when using netconf
+    - lxml >= 4.1.1 when using netconf
 extends_documentation_fragment: iosxr
 notes:
-  - Tested against IOS XRv 6.1.2
+  - This module works with connection C(network_cli) and C(netconf). See L(the IOS-XR Platform Options,../network/user_guide/platform_iosxr.html).
+  - Tested against IOS XRv 6.1.3.
   - Preconfiguration of physical interfaces is not supported with C(netconf) transport.
 options:
   name:

lib/ansible/modules/network/iosxr/iosxr_banner.py

@@ -24,9 +24,13 @@ description:
   - This module will configure both exec and motd banners on remote device
     running Cisco IOS XR. It allows playbooks to add or remove
     banner text from the running configuration.
+requirements:
+    - ncclient >= 0.5.3 when using netconf
+    - lxml >= 4.1.1 when using netconf
 extends_documentation_fragment: iosxr
 notes:
-  - Tested against IOS XRv 6.1.2
+  - Tested against IOS XRv 6.1.3.
+  - This module works with connection C(network_cli) and C(netconf). See L(the IOS-XR Platform Options,../network/user_guide/platform_iosxr.html).
 options:
   banner:
     description:

lib/ansible/modules/network/iosxr/iosxr_bgp.py

@@ -25,7 +25,7 @@ description:
     on devices running Cisco IOS-XR
 notes:
   - Tested against Cisco IOS XR Software Version 6.1.3
-  - This module works with connection C(network_cli).
+  - This module works with connection C(network_cli). See L(the IOS-XR Platform Options,../network/user_guide/platform_iosxr.html).
 options:
   config:
     description:

lib/ansible/modules/network/iosxr/iosxr_command.py

@@ -27,8 +27,9 @@ description:
     Please use M(iosxr_config) to configure iosxr devices.
 extends_documentation_fragment: iosxr
 notes:
-  - This module does not support netconf connection
+  - This module works with C(network_cli). See L(the IOS-XR Platform Options,../network/user_guide/platform_iosxr.html).
-  - Tested against IOS XR 6.1.2
+  - This module does not support C(netconf) connection.
+  - Tested against IOS XR 6.1.3
 options:
   commands:
     description:

lib/ansible/modules/network/iosxr/iosxr_config.py

@@ -25,8 +25,9 @@ description:
     a deterministic way.
 extends_documentation_fragment: iosxr
 notes:
-  - Tested against IOS XRv 6.1.2
+  - This module works with connection C(network_cli). See L(the IOS-XR Platform Options,../network/user_guide/platform_iosxr.html).
-  - This module does not support netconf connection
+  - Tested against IOS XRv 6.1.3.
+  - This module does not support C(netconf) connection
   - Abbreviated commands are NOT idempotent, see
     L(Network FAQ,../network/user_guide/faq.html#why-do-the-config-modules-always-return-changed-true-with-abbreviated-commands).
   - Avoid service disrupting changes (viz. Management IP) from config replace.

lib/ansible/modules/network/iosxr/iosxr_facts.py

@@ -28,6 +28,9 @@ description:
     respective resource name.  The facts module will always collect a
     base set of facts from the device and can enable or disable
     collection of additional facts.
+notes:
+  - Tested against IOS-XR 6.1.3.
+  - This module works with connection C(network_cli). See L(the IOS-XR Platform Options,../network/user_guide/platform_iosxr.html).
 author:
   - Ricardo Carrillo Cruz (@rcarrillocruz)
   - Nilashish Chakraborty (@Nilashishc)

lib/ansible/modules/network/iosxr/iosxr_interfaces.py

@@ -41,7 +41,7 @@ description: This module manages the interface attributes on Cisco IOS-XR networ
 author: Sumit Jaiswal (@justjais)
 notes:
   - Tested against Cisco IOS-XRv Version 6.1.3 on VIRL.
-  - This module works with connection C(network_cli).
+  - This module works with connection C(network_cli). See L(the IOS-XR Platform Options,../network/user_guide/platform_iosxr.html).
 options:
   config:
     description: A dictionary of interface options

lib/ansible/modules/network/iosxr/iosxr_lacp.py

@@ -44,7 +44,7 @@ description:
   - This module manages Global Link Aggregation Control Protocol (LACP) on IOS-XR devices.
 notes:
   - Tested against IOS-XR 6.1.3.
-  - This module works with connection C(network_cli).
+  - This module works with connection C(network_cli). See L(the IOS-XR Platform Options,../network/user_guide/platform_iosxr.html).
 author: Nilashish Chakraborty (@nilashishc)
 options:
   config:

lib/ansible/modules/network/iosxr/iosxr_lacp_interfaces.py

@@ -44,7 +44,7 @@ description:
   - This module manages Link Aggregation Control Protocol (LACP) attributes of interfaces on IOS-XR devices.
 notes:
   - Tested against IOS-XR 6.1.3.
-  - This module works with connection C(network_cli).
+  - This module works with connection C(network_cli). See L(the IOS-XR Platform Options,../network/user_guide/platform_iosxr.html).
 author: Nilashish Chakraborty (@nilashishc)
 options:
   config:

lib/ansible/modules/network/iosxr/iosxr_lldp_global.py

@@ -44,7 +44,7 @@ description:
   - This module manages Global Link Layer Discovery Protocol (LLDP) settings on IOS-XR devices.
 notes:
   - Tested against IOS-XR 6.1.3.
-  - This module works with connection C(network_cli).
+  - This module works with connection C(network_cli). See L(the IOS-XR Platform Options,../network/user_guide/platform_iosxr.html).
 author: Nilashish Chakraborty (@NilashishC)
 options:
   config:

lib/ansible/modules/network/iosxr/iosxr_lldp_interfaces.py

@@ -44,7 +44,7 @@ description:
   - This module manages Link Layer Discovery Protocol (LLDP) attributes of interfaces on IOS-XR devices.
 notes:
   - Tested against IOS-XR 6.1.3.
-  - This module works with connection C(network_cli).
+  - This module works with connection C(network_cli). See L(the IOS-XR Platform Options,../network/user_guide/platform_iosxr.html).
 author: Nilashish Chakraborty (@nilashishc)
 options:
   config:

lib/ansible/modules/network/iosxr/iosxr_logging.py

@@ -23,8 +23,12 @@ short_description: Configuration management of system logging services on networ
 description:
   - This module provides declarative management configuration of system logging (syslog)
     on Cisco IOS XR devices.
+requirements:
+    - ncclient >= 0.5.3 when using netconf
+    - lxml >= 4.1.1 when using netconf
 notes:
-  - Tested against IOS XRv 6.1.2
+  - This module works with connection C(network_cli) and C(netconf). See L(the IOS-XR Platform Options,../network/user_guide/platform_iosxr.html).
+  - Tested against IOS XRv 6.1.3
 options:
   dest:
     description:

lib/ansible/modules/network/iosxr/iosxr_netconf.py

@@ -51,7 +51,8 @@ options:
     default: present
     choices: ['present', 'absent']
 notes:
-  - Tested against Cisco IOS XR Software, Version 6.1.2
+  - This module works with connection C(network_cli). See L(the IOS-XR Platform Options,../network/user_guide/platform_iosxr.html).
+  - Tested against Cisco IOS XR Software, Version 6.1.3
 """
 
 EXAMPLES = """

lib/ansible/modules/network/iosxr/iosxr_system.py

@@ -24,9 +24,13 @@ description:
     on Cisco IOS XR devices. It provides an option to configure host system
     parameters or remove those parameters from the device active
     configuration.
+requirements:
+    - ncclient >= 0.5.3 when using netconf
+    - lxml >= 4.1.1 when using netconf
 extends_documentation_fragment: iosxr
 notes:
-  - Tested against IOS XRv 6.1.2
+  - This module works with connection C(network_cli) and C(netconf). See L(the IOS-XR Platform Options,../network/user_guide/platform_iosxr.html).
+  - Tested against IOS XRv 6.1.3
   - name-servers I(state=absent) operation with C(netconf) transport is a success, but with rpc-error. This is
     due to XR platform issue. Recommended to use I(ignore_errors) option with the task as a workaround.
 options:
@@ -85,7 +89,7 @@ EXAMPLES = """
   iosxr_system:
     hostname: iosxr01
     domain_name: test.example.com
-    domain-search:
+    domain_search:
       - ansible.com
       - redhat.com
       - cisco.com
@@ -93,7 +97,7 @@ EXAMPLES = """
   iosxr_system:
     hostname: iosxr01
     domain_name: test.example.com
-    domain-search:
+    domain_search:
       - ansible.com
       - redhat.com
       - cisco.com
@@ -103,7 +107,7 @@ EXAMPLES = """
     hostname: iosxr01
     vrf: nondefault
     domain_name: test.example.com
-    domain-search:
+    domain_search:
       - ansible.com
       - redhat.com
       - cisco.com

lib/ansible/modules/network/iosxr/iosxr_user.py

@@ -29,7 +29,8 @@ description:
     configuration that are not explicitly defined.
 extends_documentation_fragment: iosxr
 notes:
-  - Tested against IOS XRv 6.1.2
+  - This module works with connection C(network_cli) and C(netconf). See L(the IOS-XR Platform Options,../network/user_guide/platform_iosxr.html).
+  - Tested against IOS XRv 6.1.3
 options:
   aggregate:
     description:
@@ -121,6 +122,8 @@ options:
         public_key.If used with multiple users in aggregates, then the
         same key file is used for all users.
 requirements:
+  - ncclient >= 0.5.3 when using netconf
+  - lxml >= 4.1.1 when using netconf
   - base64 when using I(public_key_contents) or I(public_key)
   - paramiko when using I(public_key_contents) or I(public_key)
 """

lib/ansible/plugins/doc_fragments/iosxr.py

@@ -59,9 +59,6 @@ options:
             in the task, the value of environment variable C(ANSIBLE_NET_SSH_KEYFILE)
             will be used instead.
         type: path
-requirements:
-    - ncclient >= 0.5.3 when using netconf
-    - lxml >= 4.1.1 when using netconf
 notes:
   - For more information on using Ansible to manage network devices see the :ref:`Ansible Network Guide <network_guide>`
   - For more information on using Ansible to manage Cisco devices see the `Cisco integration page <https://www.ansible.com/integrations/networks/cisco>`_.