From 9a26fbe58ee618861a0998f839f63cea26fb215e Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 20 Aug 2020 17:27:58 -0400 Subject: [PATCH] update Ansible-maintained platform guides with FQCN (#70369) (#71263) * update platform guides with FQCN * implemented feedback * fix remainin fqcn * Update docs/docsite/rst/network/user_guide/platform_netconf_enabled.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> (cherry picked from commit 172230d7b80c8565c4d9d6b6a8b301932b6785c0) --- .../rst/network/user_guide/platform_eos.rst | 92 +++++-------------- .../rst/network/user_guide/platform_frr.rst | 19 ++-- .../rst/network/user_guide/platform_ios.rst | 21 +++-- .../rst/network/user_guide/platform_iosxr.rst | 38 ++++---- .../rst/network/user_guide/platform_junos.rst | 40 ++++---- .../user_guide/platform_netconf_enabled.rst | 31 ++++--- .../rst/network/user_guide/platform_nxos.rst | 44 ++++----- .../rst/network/user_guide/platform_vyos.rst | 21 +++-- 8 files changed, 133 insertions(+), 173 deletions(-) diff --git a/docs/docsite/rst/network/user_guide/platform_eos.rst b/docs/docsite/rst/network/user_guide/platform_eos.rst index 86cb06581dd..065a7dc0627 100644 --- a/docs/docsite/rst/network/user_guide/platform_eos.rst +++ b/docs/docsite/rst/network/user_guide/platform_eos.rst @@ -4,19 +4,20 @@ EOS Platform Options *************************************** -Arista EOS supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. +The `Arista EOS `_ collection 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:: :class: documentation-table - ==================== ========================================== ========================= + ==================== ========================================== =========================== .. CLI eAPI - ==================== ========================================== ========================= + ==================== ========================================== =========================== Protocol SSH HTTP(S) Credentials uses SSH keys / SSH-agent if present uses HTTPS certificates if @@ -25,13 +26,9 @@ Connections Available Indirect Access via a bastion (jump host) via a web proxy - Connection Settings ``ansible_connection: network_cli`` ``ansible_connection: httpapi`` + Connection Settings ``ansible_connection:`` ``ansible_connection:`` + ``ansible.netcommon.network_cli`` ``ansible.netcommon.httpapi`` - OR - - ``ansible_connection: local`` - with ``transport: eapi`` - in the ``provider`` dictionary |enable_mode| supported: |br| supported: |br| @@ -39,18 +36,13 @@ Connections Available with ``ansible_become_method: enable`` uses ``ansible_become: yes`` with ``ansible_become_method: enable`` - * ``local`` - uses ``authorize: yes`` - and ``auth_pass:`` - in the ``provider`` dictionary - Returned Data Format ``stdout[0].`` ``stdout[0].messages[0].`` - ==================== ========================================== ========================= + ==================== ========================================== =========================== .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) -For legacy playbooks, EOS still supports ``ansible_connection: local``. We recommend modernizing to use ``ansible_connection: network_cli`` or ``ansible_connection: httpapi`` as soon as possible. +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` or ``ansible_connection: ansible.netcommon.httpapi`` instead. Using CLI in Ansible ==================== @@ -60,8 +52,8 @@ Example CLI ``group_vars/eos.yml`` .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: eos + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: arista.eos.eos ansible_user: myuser ansible_password: !vault... ansible_become: yes @@ -74,16 +66,16 @@ Example CLI ``group_vars/eos.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 (eos) - eos_config: + arista.eos.eos_config: backup: yes register: backup_eos_location - when: ansible_network_os == 'eos' + when: ansible_network_os == 'arista.eos.eos' @@ -93,19 +85,19 @@ Using eAPI in Ansible Enabling eAPI ------------- -Before you can use eAPI to connect to a switch, you must enable eAPI. To enable eAPI on a new switch via Ansible, use the ``eos_eapi`` module via the CLI connection. Set up group_vars/eos.yml just like in the CLI example above, then run a playbook task like this: +Before you can use eAPI to connect to a switch, you must enable eAPI. To enable eAPI on a new switch with Ansible, use the ``arista.eos.eos_eapi`` module through the CLI connection. Set up ``group_vars/eos.yml`` just like in the CLI example above, then run a playbook task like this: .. code-block:: yaml - name: Enable eAPI - eos_eapi: + arista.eos.eos_eapi: enable_http: yes enable_https: yes become: true become_method: enable - when: ansible_network_os == 'eos' + when: ansible_network_os == 'arista.eos.eos' -You can find more options for enabling HTTP/HTTPS connections in the :ref:`eos_eapi ` module documentation. +You can find more options for enabling HTTP/HTTPS connections in the :ref:`arista.eos.eos_eapi ` module documentation. Once eAPI is enabled, change your ``group_vars/eos.yml`` to use the eAPI connection. @@ -114,8 +106,8 @@ Example eAPI ``group_vars/eos.yml`` .. code-block:: yaml - ansible_connection: httpapi - ansible_network_os: eos + ansible_connection: ansible.netcommon.httpapi + ansible_network_os: arista.eos.eos ansible_user: myuser ansible_password: !vault... ansible_become: yes @@ -127,56 +119,20 @@ Example eAPI ``group_vars/eos.yml`` - If you are accessing your host through a web proxy using ``https``, change ``http_proxy`` to ``https_proxy``. -Example eAPI Task +Example eAPI task ----------------- .. code-block:: yaml - name: Backup current switch config (eos) - eos_config: + arista.eos.eos_config: backup: yes register: backup_eos_location environment: "{{ proxy_env }}" - when: ansible_network_os == 'eos' + when: ansible_network_os == 'arista.eos.eos' In this example the ``proxy_env`` variable defined in ``group_vars`` gets passed to the ``environment`` option of the module in the task. -eAPI examples with ``connection: local`` ------------------------------------------ - -``group_vars/eos.yml``: - -.. code-block:: yaml - - ansible_connection: local - ansible_network_os: eos - ansible_user: myuser - ansible_password: !vault... - eapi: - host: "{{ inventory_hostname }}" - transport: eapi - authorize: yes - auth_pass: !vault... - proxy_env: - http_proxy: http://proxy.example.com:8080 - -eAPI task: - -.. code-block:: yaml - - - name: Backup current switch config (eos) - eos_config: - backup: yes - provider: "{{ eapi }}" - register: backup_eos_location - environment: "{{ proxy_env }}" - when: ansible_network_os == 'eos' - -In this example two variables defined in ``group_vars`` get passed to the module of the task: - -- the ``eapi`` variable gets passed to the ``provider`` option of the module -- the ``proxy_env`` variable gets passed to the ``environment`` option of the module - .. include:: shared_snippets/SSH_warning.txt .. seealso:: diff --git a/docs/docsite/rst/network/user_guide/platform_frr.rst b/docs/docsite/rst/network/user_guide/platform_frr.rst index 0003204eb65..0d7bad14c03 100644 --- a/docs/docsite/rst/network/user_guide/platform_frr.rst +++ b/docs/docsite/rst/network/user_guide/platform_frr.rst @@ -4,11 +4,12 @@ FRR Platform Options *************************************** -This page offers details on connection options to manage FRR using Ansible. +The `FRR `_ collection supports the ``ansible.netcommon.network_cli`` connection. This section provides details on how to use this connection for Free Range Routing (FRR). -.. 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| not supported @@ -43,24 +44,24 @@ Example CLI ``group_vars/frr.yml`` .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: frr + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: frr.frr.frr ansible_user: frruser ansible_password: !vault... ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' -- The `ansible_user` should be a part of the `frrvty` group and should have the default shell set to `/bin/vtysh`. +- The ``ansible_user`` should be a part of the ``frrvty`` group and should have the default shell set to ``/bin/vtysh``. - 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 +Example CLI task ---------------- .. code-block:: yaml - name: Gather FRR facts - frr_facts: + frr.frr.frr_facts: gather_subset: - config - hardware diff --git a/docs/docsite/rst/network/user_guide/platform_ios.rst b/docs/docsite/rst/network/user_guide/platform_ios.rst index a92db971214..1c53a5ca013 100644 --- a/docs/docsite/rst/network/user_guide/platform_ios.rst +++ b/docs/docsite/rst/network/user_guide/platform_ios.rst @@ -4,11 +4,12 @@ IOS Platform Options *************************************** -IOS supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on IOS in Ansible. +The `Cisco IOS `_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on IOS 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`` and ``ansible_become_password:`` @@ -36,7 +37,7 @@ Connections Available .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) -For legacy playbooks, IOS 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/ios.yml`` .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: ios + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: cisco.ios.ios ansible_user: myuser ansible_password: !vault... ansible_become: yes @@ -60,16 +61,16 @@ Example CLI ``group_vars/ios.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 (ios) - ios_config: + cisco.ios.ios_config: backup: yes register: backup_ios_location - when: ansible_network_os == 'ios' + when: ansible_network_os == 'cisco.ios.ios' .. include:: shared_snippets/SSH_warning.txt diff --git a/docs/docsite/rst/network/user_guide/platform_iosxr.rst b/docs/docsite/rst/network/user_guide/platform_iosxr.rst index cad1cf6850a..1e1eab27a51 100644 --- a/docs/docsite/rst/network/user_guide/platform_iosxr.rst +++ b/docs/docsite/rst/network/user_guide/platform_iosxr.rst @@ -4,11 +4,12 @@ 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. +The `Cisco IOS-XR collection `_ supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. -.. contents:: Topic +.. contents:: + :local: -Connections Available +Connections available ================================================================================ .. table:: @@ -29,7 +30,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 not supported @@ -39,7 +41,7 @@ Connections Available .. |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. +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` or ``ansible_connection: ansible.netcommon.netconf`` instead. Using CLI in Ansible ==================== @@ -50,8 +52,8 @@ Example CLI inventory ``[iosxr:vars]`` .. code-block:: yaml [iosxr:vars] - ansible_connection=network_cli - ansible_network_os=iosxr + ansible_connection=ansible.netcommon.network_cli + ansible_network_os=cisco.iosxr.iosxr ansible_user=myuser ansible_password=!vault... ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"' @@ -61,15 +63,15 @@ Example CLI inventory ``[iosxr: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 IOS-XR version - iosxr_command: + cisco.iosxr.iosxr_command: commands: show version - when: ansible_network_os == 'iosxr' + when: ansible_network_os == 'cisco.iosxr.iosxr' Using NETCONF in Ansible @@ -83,14 +85,14 @@ 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: +To enable NETCONF on a new switch via Ansible, use the ``cisco.iosxr.iosxr_netconf`` module through 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' + connection: ansible.netcommon.network_cli + cisco.iosxr.iosxr_netconf: + when: ansible_network_os == 'cisco.iosxr.iosxr' Once NETCONF is enabled, change your variables to use the NETCONF connection. @@ -100,20 +102,20 @@ Example NETCONF inventory ``[iosxr:vars]`` .. code-block:: yaml [iosxr:vars] - ansible_connection=netconf - ansible_network_os=iosxr + ansible_connection=ansible.netcommon.netconf + ansible_network_os=cisco.iosxr.iosxr 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: Configure hostname and domain-name - iosxr_system: + cisco.iosxr.iosxr_system: hostname: iosxr01 domain_name: test.example.com domain_search: diff --git a/docs/docsite/rst/network/user_guide/platform_junos.rst b/docs/docsite/rst/network/user_guide/platform_junos.rst index ad624225e3a..3b83810344b 100644 --- a/docs/docsite/rst/network/user_guide/platform_junos.rst +++ b/docs/docsite/rst/network/user_guide/platform_junos.rst @@ -4,11 +4,12 @@ Junos OS Platform Options *************************************** -Juniper Junos OS supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. +The `Juniper Junos OS `_ 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:: @@ -28,7 +29,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 Junos OS not supported by Junos OS @@ -40,7 +42,7 @@ Connections Available .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) -For legacy playbooks, Ansible still supports ``ansible_connection=local`` on all JUNOS 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.network_cli`` or ``ansible_connection: ansible.netcommon.netconf`` instead. Using CLI in Ansible ==================== @@ -51,8 +53,8 @@ Example CLI inventory ``[junos:vars]`` .. code-block:: yaml [junos:vars] - ansible_connection=network_cli - ansible_network_os=junos + ansible_connection=ansible.netcommon.network_cli + ansible_network_os=junipernetworks.junos.junos ansible_user=myuser ansible_password=!vault... ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"' @@ -62,15 +64,15 @@ Example CLI inventory ``[junos: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 Junos OS version - junos_command: + junipernetworks.junos.junos_command: commands: show version - when: ansible_network_os == 'junos' + when: ansible_network_os == 'junipernetworks.junos.junos' Using NETCONF in Ansible @@ -84,14 +86,14 @@ 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 ``junos_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: +To enable NETCONF on a new switch via Ansible, use the ``junipernetworks.junos.junos_netconf`` module through 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 - junos_netconf: - when: ansible_network_os == 'junos' + connection: ansible.netcommon.network_cli + junipernetworks.junos.junos_netconf: + when: ansible_network_os == 'junipernetworks.junos.junos' Once NETCONF is enabled, change your variables to use the NETCONF connection. @@ -101,23 +103,23 @@ Example NETCONF inventory ``[junos:vars]`` .. code-block:: yaml [junos:vars] - ansible_connection=netconf - ansible_network_os=junos + ansible_connection=ansible.netcommon.netconf + ansible_network_os=junipernetworks.junos.junos 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: Backup current switch config (junos) - junos_config: + junipernetworks.junos.junos_config: backup: yes register: backup_junos_location - when: ansible_network_os == 'junos' + when: ansible_network_os == 'junipernetworks.junos.junos' .. include:: shared_snippets/SSH_warning.txt diff --git a/docs/docsite/rst/network/user_guide/platform_netconf_enabled.rst b/docs/docsite/rst/network/user_guide/platform_netconf_enabled.rst index ac305ac0df9..6169b076096 100644 --- a/docs/docsite/rst/network/user_guide/platform_netconf_enabled.rst +++ b/docs/docsite/rst/network/user_guide/platform_netconf_enabled.rst @@ -6,9 +6,10 @@ Netconf enabled Platform Options This page offers details on how the netconf connection works in Ansible and how to use it. -.. contents:: Topics +.. contents:: + :local: -Connections Available +Connections available ================================================================================ .. table:: :class: documentation-table @@ -27,11 +28,11 @@ Connections Available Indirect Access via a bastion (jump host) - Connection Settings ``ansible_connection: netconf`` + Connection Settings ``ansible_connection: ansible.netcommon.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. +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.netconf`` instead. Using NETCONF in Ansible ======================== @@ -50,9 +51,9 @@ For example set up your platform-level variables just like in the CLI example ab .. code-block:: yaml - name: Enable NETCONF - connection: network_cli - junos_netconf: - when: ansible_network_os == 'junos' + connection: ansible.netcommon.network_cli + junipernetworks.junos.junos_netconf: + when: ansible_network_os == 'junipernetworks.junos.junos' Once NETCONF is enabled, change your variables to use the NETCONF connection. @@ -62,37 +63,37 @@ Example NETCONF inventory ``[junos:vars]`` .. code-block:: yaml [junos:vars] - ansible_connection=netconf - ansible_network_os=junos + ansible_connection=ansible.netcommon.netconf + ansible_network_os=junipernetworks.junos.junos ansible_user=myuser ansible_password=!vault | -Example NETCONF Task +Example NETCONF task -------------------- .. code-block:: yaml - name: Backup current switch config - netconf_config: + junipernetworks.junos.netconf_config: backup: yes register: backup_junos_location -Example NETCONF Task with configurable variables +Example NETCONF task with configurable variables ------------------------------------------------ .. code-block:: yaml - name: configure interface while providing different private key file path - netconf_config: + junipernetworks.junos.netconf_config: backup: yes register: backup_junos_location vars: ansible_private_key_file: /home/admin/.ssh/newprivatekeyfile -Note: For netconf connection plugin configurable variables see :ref:`netconf `. +Note: For netconf connection plugin configurable variables see :ref:`ansible.netcommon.netconf `. -Bastion/Jumphost Configuration +Bastion/Jumphost configuration ------------------------------ To use a jump host to connect to a NETCONF enabled device you must set the ``ANSIBLE_NETCONF_SSH_CONFIG`` environment variable. diff --git a/docs/docsite/rst/network/user_guide/platform_nxos.rst b/docs/docsite/rst/network/user_guide/platform_nxos.rst index 437359962b5..e698b2d9798 100644 --- a/docs/docsite/rst/network/user_guide/platform_nxos.rst +++ b/docs/docsite/rst/network/user_guide/platform_nxos.rst @@ -4,11 +4,12 @@ NXOS Platform Options *************************************** -Cisco NXOS supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. +The `Cisco NXOS `_ 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:: @@ -25,13 +26,8 @@ Connections Available Indirect Access via a bastion (jump host) via a web proxy - Connection Settings ``ansible_connection: network_cli`` ``ansible_connection: httpapi`` - - OR - - ``ansible_connection: local`` - with ``transport: nxapi`` - in the ``provider`` dictionary + Connection Settings ``ansible_connection:`` ``ansible_connection:`` + ``ansible.netcommon.network_cli`` ``ansible.netcommon.httpapi`` |enable_mode| supported: use ``ansible_become: yes`` not supported by NX-API with ``ansible_become_method: enable`` @@ -43,7 +39,7 @@ Connections Available .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) |br| supported as of 2.5.3 -For legacy playbooks, NXOS still supports ``ansible_connection: local``. We recommend modernizing to use ``ansible_connection: network_cli`` or ``ansible_connection: httpapi`` as soon as possible. +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` or ``ansible_connection: ansible.netcommon.httpapi`` instead. Using CLI in Ansible ==================== @@ -53,8 +49,8 @@ Example CLI ``group_vars/nxos.yml`` .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: nxos + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: cisco.nxos.nxos ansible_user: myuser ansible_password: !vault... ansible_become: yes @@ -67,16 +63,16 @@ Example CLI ``group_vars/nxos.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 (nxos) - nxos_config: + cisco.nxos.nxos_config: backup: yes register: backup_nxos_location - when: ansible_network_os == 'nxos' + when: ansible_network_os == 'cisco.nxos.nxos' @@ -91,10 +87,10 @@ Before you can use NX-API to connect to a switch, you must enable NX-API. To ena .. code-block:: yaml - name: Enable NX-API - nxos_nxapi: + cisco.nxos.nxos_nxapi: enable_http: yes enable_https: yes - when: ansible_network_os == 'nxos' + when: ansible_network_os == 'cisco.nxos.nxos' To find out more about the options for enabling HTTP/HTTPS and local http see the :ref:`nxos_nxapi ` module documentation. @@ -105,8 +101,8 @@ Example NX-API ``group_vars/nxos.yml`` .. code-block:: yaml - ansible_connection: httpapi - ansible_network_os: nxos + ansible_connection: ansible.netcommon.httpapi + ansible_network_os: cisco.nxos.nxos ansible_user: myuser ansible_password: !vault... proxy_env: @@ -116,23 +112,23 @@ Example NX-API ``group_vars/nxos.yml`` - If you are accessing your host through a web proxy using ``https``, change ``http_proxy`` to ``https_proxy``. -Example NX-API Task +Example NX-API task ------------------- .. code-block:: yaml - name: Backup current switch config (nxos) - nxos_config: + cisco.nxos.nxos_config: backup: yes register: backup_nxos_location environment: "{{ proxy_env }}" - when: ansible_network_os == 'nxos' + when: ansible_network_os == 'cisco.nxos.nxos' In this example the ``proxy_env`` variable defined in ``group_vars`` gets passed to the ``environment`` option of the module used in the task. .. include:: shared_snippets/SSH_warning.txt -Cisco Nexus Platform Support Matrix +Cisco Nexus platform support matrix =================================== The following platforms and software versions have been certified by Cisco to work with this version of Ansible. diff --git a/docs/docsite/rst/network/user_guide/platform_vyos.rst b/docs/docsite/rst/network/user_guide/platform_vyos.rst index f3bb5a9a432..5ec00f7bea0 100644 --- a/docs/docsite/rst/network/user_guide/platform_vyos.rst +++ b/docs/docsite/rst/network/user_guide/platform_vyos.rst @@ -4,11 +4,12 @@ VyOS Platform Options *************************************** -This page offers details on connection options to manage VyOS using Ansible. +The `VyOS `_ collection supports the ``ansible.netcommon.network_cli`` connection type. This page offers details on connection options to manage VyOS using 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| not supported @@ -35,7 +36,7 @@ Connections Available .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) -For legacy playbooks, VyOS 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 ==================== @@ -45,8 +46,8 @@ Example CLI ``group_vars/vyos.yml`` .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: vyos + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: vyos.vyos.vyos ansible_user: myuser ansible_password: !vault... ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' @@ -56,15 +57,15 @@ Example CLI ``group_vars/vyos.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 VyOS version info - vyos_command: + vyos.vyos.vyos_command: commands: show version - when: ansible_network_os == 'vyos' + when: ansible_network_os == 'vyos.vyos.vyos' .. include:: shared_snippets/SSH_warning.txt