Add iosxr platform guide (#60936)

Signed-off-by: NilashishC <nilashishchakraborty8@gmail.com>
2019-08-22 23:35:15 +05:30 · 2019-08-22 23:35:15 +05:30 · d06930d6f6
commit d06930d6f6
parent cedc012e30
18 changed files with 169 additions and 22 deletions
--- a/docs/docsite/rst/network/user_guide/platform_index.rst
+++ b/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
--- a/docs/docsite/rst/network/user_guide/platform_iosxr.rst
+++ b/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
--- a/lib/ansible/modules/network/iosxr/_iosxr_interface.py
+++ b/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:
--- a/lib/ansible/modules/network/iosxr/iosxr_banner.py
+++ b/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:
--- a/lib/ansible/modules/network/iosxr/iosxr_bgp.py
+++ b/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:
--- a/lib/ansible/modules/network/iosxr/iosxr_command.py
+++ b/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
-  - Tested against IOS XR 6.1.2
+  - This module works with C(network_cli). See L(the IOS-XR Platform Options,../network/user_guide/platform_iosxr.html).
+  - This module does not support C(netconf) connection.
+  - Tested against IOS XR 6.1.3
 options:
  commands:
    description:
--- a/lib/ansible/modules/network/iosxr/iosxr_config.py
+++ b/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 does not support netconf connection
+  - This module works with connection C(network_cli). See L(the IOS-XR Platform Options,../network/user_guide/platform_iosxr.html).
+  - 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.
--- a/lib/ansible/modules/network/iosxr/iosxr_facts.py
+++ b/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)
--- a/lib/ansible/modules/network/iosxr/iosxr_interfaces.py
+++ b/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
--- a/lib/ansible/modules/network/iosxr/iosxr_lacp.py
+++ b/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:
--- a/lib/ansible/modules/network/iosxr/iosxr_lacp_interfaces.py
+++ b/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:
--- a/lib/ansible/modules/network/iosxr/iosxr_lldp_global.py
+++ b/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:
--- a/lib/ansible/modules/network/iosxr/iosxr_lldp_interfaces.py
+++ b/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:
--- a/lib/ansible/modules/network/iosxr/iosxr_logging.py
+++ b/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:
--- a/lib/ansible/modules/network/iosxr/iosxr_netconf.py
+++ b/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 = """
--- a/lib/ansible/modules/network/iosxr/iosxr_system.py
+++ b/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
--- a/lib/ansible/modules/network/iosxr/iosxr_user.py
+++ b/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)
 """
--- a/lib/ansible/plugins/doc_fragments/iosxr.py
+++ b/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>`_.