diff --git a/docs/docsite/rst/network/user_guide/platform_index.rst b/docs/docsite/rst/network/user_guide/platform_index.rst index 1cda93c7e3a..f3a80df42cf 100644 --- 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 diff --git a/docs/docsite/rst/network/user_guide/platform_iosxr.rst b/docs/docsite/rst/network/user_guide/platform_iosxr.rst new file mode 100644 index 00000000000..11062f26b92 --- /dev/null +++ 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 \ No newline at end of file diff --git a/lib/ansible/modules/network/iosxr/_iosxr_interface.py b/lib/ansible/modules/network/iosxr/_iosxr_interface.py index aa047b8f720..358ca3e1d31 100644 --- 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: diff --git a/lib/ansible/modules/network/iosxr/iosxr_banner.py b/lib/ansible/modules/network/iosxr/iosxr_banner.py index 06c80c196d6..bacba915238 100644 --- 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: diff --git a/lib/ansible/modules/network/iosxr/iosxr_bgp.py b/lib/ansible/modules/network/iosxr/iosxr_bgp.py index 45d96dea2ba..44d82378a3b 100644 --- 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: diff --git a/lib/ansible/modules/network/iosxr/iosxr_command.py b/lib/ansible/modules/network/iosxr/iosxr_command.py index e3d971a76a5..2270235cac5 100644 --- 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: diff --git a/lib/ansible/modules/network/iosxr/iosxr_config.py b/lib/ansible/modules/network/iosxr/iosxr_config.py index 1e610a27544..ad082418845 100644 --- 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. diff --git a/lib/ansible/modules/network/iosxr/iosxr_facts.py b/lib/ansible/modules/network/iosxr/iosxr_facts.py index aed32db0144..9f8f4d5e23e 100644 --- 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) diff --git a/lib/ansible/modules/network/iosxr/iosxr_interfaces.py b/lib/ansible/modules/network/iosxr/iosxr_interfaces.py index 94942867e98..e917df76355 100644 --- 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 diff --git a/lib/ansible/modules/network/iosxr/iosxr_lacp.py b/lib/ansible/modules/network/iosxr/iosxr_lacp.py index 3663a0e9d74..aa835f7f49e 100644 --- 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: diff --git a/lib/ansible/modules/network/iosxr/iosxr_lacp_interfaces.py b/lib/ansible/modules/network/iosxr/iosxr_lacp_interfaces.py index c57a8a7cea7..9120f992904 100644 --- 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: diff --git a/lib/ansible/modules/network/iosxr/iosxr_lldp_global.py b/lib/ansible/modules/network/iosxr/iosxr_lldp_global.py index eaa8f7e34d4..a46565f9f75 100644 --- 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: diff --git a/lib/ansible/modules/network/iosxr/iosxr_lldp_interfaces.py b/lib/ansible/modules/network/iosxr/iosxr_lldp_interfaces.py index 6599bfb9f80..ff975b95be6 100644 --- 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: diff --git a/lib/ansible/modules/network/iosxr/iosxr_logging.py b/lib/ansible/modules/network/iosxr/iosxr_logging.py index 254fcb1dc5b..6b13071e758 100644 --- 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: diff --git a/lib/ansible/modules/network/iosxr/iosxr_netconf.py b/lib/ansible/modules/network/iosxr/iosxr_netconf.py index d574241c1f8..3e52aef903f 100644 --- 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 = """ diff --git a/lib/ansible/modules/network/iosxr/iosxr_system.py b/lib/ansible/modules/network/iosxr/iosxr_system.py index 66b316c6964..1af1d3ad753 100644 --- 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 diff --git a/lib/ansible/modules/network/iosxr/iosxr_user.py b/lib/ansible/modules/network/iosxr/iosxr_user.py index c96b12fd4c8..a4b565ccdef 100644 --- 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) """ diff --git a/lib/ansible/plugins/doc_fragments/iosxr.py b/lib/ansible/plugins/doc_fragments/iosxr.py index 1457169b096..5c1b31aed09 100644 --- 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 ` - For more information on using Ansible to manage Cisco devices see the `Cisco integration page `_.