From 11ba2a965d79d67124edba3b2ee20b86cc77a7b7 Mon Sep 17 00:00:00 2001 From: Rohit Date: Fri, 23 Aug 2019 20:23:50 +0530 Subject: [PATCH] platform guide updates (#61121) * platform guide updates Signed-off-by: rohitthakur2590 * sanity fix Signed-off-by: rohitthakur2590 --- .../rst/network/user_guide/platform_index.rst | 1 + .../rst/network/user_guide/platform_vyos.rst | 69 +++++++++++++++++++ .../modules/network/vyos/vyos_banner.py | 3 +- .../modules/network/vyos/vyos_command.py | 3 +- .../modules/network/vyos/vyos_config.py | 5 +- .../modules/network/vyos/vyos_facts.py | 3 +- .../modules/network/vyos/vyos_interfaces.py | 3 + .../network/vyos/vyos_l3_interfaces.py | 3 + .../network/vyos/vyos_lag_interfaces.py | 2 +- .../modules/network/vyos/vyos_lldp_global.py | 2 +- .../network/vyos/vyos_lldp_interfaces.py | 2 +- .../modules/network/vyos/vyos_logging.py | 3 +- lib/ansible/modules/network/vyos/vyos_ping.py | 2 + .../modules/network/vyos/vyos_static_route.py | 3 +- .../modules/network/vyos/vyos_system.py | 3 +- lib/ansible/modules/network/vyos/vyos_user.py | 3 +- lib/ansible/modules/network/vyos/vyos_vlan.py | 3 +- 17 files changed, 99 insertions(+), 14 deletions(-) create mode 100644 docs/docsite/rst/network/user_guide/platform_vyos.rst diff --git a/docs/docsite/rst/network/user_guide/platform_index.rst b/docs/docsite/rst/network/user_guide/platform_index.rst index f3a80df42cf..0dde9d8495a 100644 --- a/docs/docsite/rst/network/user_guide/platform_index.rst +++ b/docs/docsite/rst/network/user_guide/platform_index.rst @@ -29,6 +29,7 @@ Some Ansible Network platforms support multiple connection types, privilege esca platform_routeros platform_slxos platform_voss + platform_vyos platform_netconf_enabled .. _settings_by_platform: diff --git a/docs/docsite/rst/network/user_guide/platform_vyos.rst b/docs/docsite/rst/network/user_guide/platform_vyos.rst new file mode 100644 index 00000000000..5d9af25ab57 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_vyos.rst @@ -0,0 +1,69 @@ +.. _vyos_platform_options: + +*************************************** +VyOS Platform Options +*************************************** + +VyOS supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on VyOS in Ansible. + +.. contents:: Topics + +Connections Available +================================================================================ + +.. table:: + :class: documentation-table + + ==================== ========================================== + .. CLI + ==================== ========================================== + Protocol 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: network_cli`` + + |enable_mode| not supported + + Returned Data Format Refer to individual module documentation + ==================== ========================================== + +.. |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. + +Using CLI in Ansible +==================== + +Example CLI ``group_vars/vyos.yml`` +----------------------------------- + +.. code-block:: yaml + + ansible_connection: network_cli + ansible_network_os: vyos + 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 VyOS version info + vyos_command: + commands: show version + when: ansible_network_os == 'vyos' + +.. include:: shared_snippets/SSH_warning.txt diff --git a/lib/ansible/modules/network/vyos/vyos_banner.py b/lib/ansible/modules/network/vyos/vyos_banner.py index d2151c5f9dc..6abd797fb17 100644 --- a/lib/ansible/modules/network/vyos/vyos_banner.py +++ b/lib/ansible/modules/network/vyos/vyos_banner.py @@ -34,7 +34,8 @@ description: devices running VyOS. It allows playbooks to add or remote banner text from the active running configuration. notes: - - Tested against VYOS 1.1.7 + - Tested against VyOS 1.1.8 (helium). + - This module works with connection C(network_cli). See L(the VyOS OS Platform Options,../network/user_guide/platform_vyos.html). options: banner: description: diff --git a/lib/ansible/modules/network/vyos/vyos_command.py b/lib/ansible/modules/network/vyos/vyos_command.py index 71201a88cd4..d53e401bd04 100644 --- a/lib/ansible/modules/network/vyos/vyos_command.py +++ b/lib/ansible/modules/network/vyos/vyos_command.py @@ -81,11 +81,12 @@ options: default: 1 notes: - - Tested against VYOS 1.1.7 + - Tested against VyOS 1.1.8 (helium). - Running C(show system boot-messages all) will cause the module to hang since VyOS is using a custom pager setting to display the output of that command. - If a command sent to the device requires answering a prompt, it is possible to pass a dict containing I(command), I(answer) and I(prompt). See examples. + - This module works with connection C(network_cli). See L(the VyOS OS Platform Options,../network/user_guide/platform_vyos.html). """ EXAMPLES = """ diff --git a/lib/ansible/modules/network/vyos/vyos_config.py b/lib/ansible/modules/network/vyos/vyos_config.py index cd4e66409f4..25711a0cc43 100644 --- a/lib/ansible/modules/network/vyos/vyos_config.py +++ b/lib/ansible/modules/network/vyos/vyos_config.py @@ -35,9 +35,8 @@ description: in the device configuration. extends_documentation_fragment: vyos notes: - - Tested against VYOS 1.1.7 - - 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). + - Tested against VyOS 1.1.8 (helium). + - This module works with connection C(network_cli). See L(the VyOS OS Platform Options,../network/user_guide/platform_vyos.html). options: lines: description: diff --git a/lib/ansible/modules/network/vyos/vyos_facts.py b/lib/ansible/modules/network/vyos/vyos_facts.py index 0dbd91cdee4..73a8c52e8d5 100644 --- a/lib/ansible/modules/network/vyos/vyos_facts.py +++ b/lib/ansible/modules/network/vyos/vyos_facts.py @@ -30,7 +30,8 @@ author: - Rohit Thakur (@rohitthakur2590) extends_documentation_fragment: vyos notes: - - Tested against VyOS 1.1.8 + - Tested against VyOS 1.1.8 (helium). + - This module works with connection C(network_cli). See L(the VyOS OS Platform Options,../network/user_guide/platform_vyos.html). options: gather_subset: description: diff --git a/lib/ansible/modules/network/vyos/vyos_interfaces.py b/lib/ansible/modules/network/vyos/vyos_interfaces.py index c8733fdaf98..692595f02ee 100644 --- a/lib/ansible/modules/network/vyos/vyos_interfaces.py +++ b/lib/ansible/modules/network/vyos/vyos_interfaces.py @@ -44,6 +44,9 @@ description: - This module manages the interface attributes on VyOS network devices. - This module supports managing base attributes of Ethernet, Bonding, VXLAN, Loopback and Virtual Tunnel Interfaces. +notes: + - Tested against VyOS 1.1.8 (helium). + - This module works with connection C(network_cli). See L(the VyOS OS Platform Options,../network/user_guide/platform_vyos.html). author: Nilashish Chakraborty (@nilashishc) options: config: diff --git a/lib/ansible/modules/network/vyos/vyos_l3_interfaces.py b/lib/ansible/modules/network/vyos/vyos_l3_interfaces.py index d2f4c2ae135..1d33b864c98 100644 --- a/lib/ansible/modules/network/vyos/vyos_l3_interfaces.py +++ b/lib/ansible/modules/network/vyos/vyos_l3_interfaces.py @@ -41,6 +41,9 @@ module: vyos_l3_interfaces version_added: 2.9 short_description: Manages L3 interface attributes of VyOS network devices. description: This module manages the L3 interface attributes on VyOS network devices. +notes: + - Tested against VyOS 1.1.8 (helium). + - This module works with connection C(network_cli). See L(the VyOS OS Platform Options,../network/user_guide/platform_vyos.html). author: Nilashish Chakraborty (@NilashishC) options: config: diff --git a/lib/ansible/modules/network/vyos/vyos_lag_interfaces.py b/lib/ansible/modules/network/vyos/vyos_lag_interfaces.py index 1daefb9959c..73aee564645 100644 --- a/lib/ansible/modules/network/vyos/vyos_lag_interfaces.py +++ b/lib/ansible/modules/network/vyos/vyos_lag_interfaces.py @@ -43,7 +43,7 @@ short_description: Manages attributes of link aggregation groups on VyOS network description: This module manages attributes of link aggregation groups on VyOS network devices. notes: - Tested against VyOS 1.1.8 (helium). - - This module works with connection C(network_cli). + - This module works with connection C(network_cli). See L(the VyOS OS Platform Options,../network/user_guide/platform_vyos.html). author: Rohit Thakur (@rohitthakur2590) options: config: diff --git a/lib/ansible/modules/network/vyos/vyos_lldp_global.py b/lib/ansible/modules/network/vyos/vyos_lldp_global.py index 73b83d9f979..08fe2453428 100644 --- a/lib/ansible/modules/network/vyos/vyos_lldp_global.py +++ b/lib/ansible/modules/network/vyos/vyos_lldp_global.py @@ -43,7 +43,7 @@ short_description: Manage link layer discovery protocol (LLDP) attributes on VyO description: This module manages link layer discovery protocol (LLDP) attributes on VyOS devices. notes: - Tested against VyOS 1.1.8 (helium). - - This module works with connection C(network_cli). + - This module works with connection C(network_cli). See L(the VyOS OS Platform Options,../network/user_guide/platform_vyos.html). author: - Rohit Thakur (@rohitthakur2590) options: diff --git a/lib/ansible/modules/network/vyos/vyos_lldp_interfaces.py b/lib/ansible/modules/network/vyos/vyos_lldp_interfaces.py index 8797a4eba15..f451fa0591e 100644 --- a/lib/ansible/modules/network/vyos/vyos_lldp_interfaces.py +++ b/lib/ansible/modules/network/vyos/vyos_lldp_interfaces.py @@ -43,7 +43,7 @@ short_description: Manages attributes of lldp interfaces on VyOS devices. description: This module manages attributes of lldp interfaces on VyOS network devices. notes: - Tested against VyOS 1.1.8 (helium). - - This module works with connection C(network_cli) + - This module works with connection C(network_cli). See L(the VyOS OS Platform Options,../network/user_guide/platform_vyos.html). author: - Rohit Thakur (@rohitthakur2590) options: diff --git a/lib/ansible/modules/network/vyos/vyos_logging.py b/lib/ansible/modules/network/vyos/vyos_logging.py index 6f4361d25bf..6d9911da079 100644 --- a/lib/ansible/modules/network/vyos/vyos_logging.py +++ b/lib/ansible/modules/network/vyos/vyos_logging.py @@ -33,7 +33,8 @@ description: - This module provides declarative management of logging on Vyatta Vyos devices. notes: - - Tested against VYOS 1.1.7 + - Tested against VyOS 1.1.8 (helium). + - This module works with connection C(network_cli). See L(the VyOS OS Platform Options,../network/user_guide/platform_vyos.html). options: dest: description: diff --git a/lib/ansible/modules/network/vyos/vyos_ping.py b/lib/ansible/modules/network/vyos/vyos_ping.py index e3960872294..4364e3d393e 100644 --- a/lib/ansible/modules/network/vyos/vyos_ping.py +++ b/lib/ansible/modules/network/vyos/vyos_ping.py @@ -70,9 +70,11 @@ options: choices: [ absent, present ] default: present notes: + - Tested against VyOS 1.1.8 (helium). - For a general purpose network module, see the M(net_ping) module. - For Windows targets, use the M(win_ping) module instead. - For targets running Python, use the M(ping) module instead. + - This module works with connection C(network_cli). See L(the VyOS OS Platform Options,../network/user_guide/platform_vyos.html). extends_documentation_fragment: vyos """ diff --git a/lib/ansible/modules/network/vyos/vyos_static_route.py b/lib/ansible/modules/network/vyos/vyos_static_route.py index a41b0491faa..58b52837e06 100644 --- a/lib/ansible/modules/network/vyos/vyos_static_route.py +++ b/lib/ansible/modules/network/vyos/vyos_static_route.py @@ -34,7 +34,8 @@ description: - This module provides declarative management of static IP routes on Vyatta VyOS network devices. notes: - - Tested against VYOS 1.1.7 + - Tested against VyOS 1.1.8 (helium). + - This module works with connection C(network_cli). See L(the VyOS OS Platform Options,../network/user_guide/platform_vyos.html). options: prefix: description: diff --git a/lib/ansible/modules/network/vyos/vyos_system.py b/lib/ansible/modules/network/vyos/vyos_system.py index fd9a0498b34..0d59e4580d2 100644 --- a/lib/ansible/modules/network/vyos/vyos_system.py +++ b/lib/ansible/modules/network/vyos/vyos_system.py @@ -34,7 +34,8 @@ description: returning successfully. extends_documentation_fragment: vyos notes: - - Tested against VYOS 1.1.7 + - Tested against VyOS 1.1.8 (helium). + - This module works with connection C(network_cli). See L(the VyOS OS Platform Options,../network/user_guide/platform_vyos.html). options: host_name: description: diff --git a/lib/ansible/modules/network/vyos/vyos_user.py b/lib/ansible/modules/network/vyos/vyos_user.py index 9a12318a44a..cbe72c5c877 100644 --- a/lib/ansible/modules/network/vyos/vyos_user.py +++ b/lib/ansible/modules/network/vyos/vyos_user.py @@ -36,7 +36,8 @@ description: current running config. It also supports purging usernames from the configuration that are not explicitly defined. notes: - - Tested against VYOS 1.1.7 + - Tested against VyOS 1.1.8 (helium). + - This module works with connection C(network_cli). See L(the VyOS OS Platform Options,../network/user_guide/platform_vyos.html). options: aggregate: description: diff --git a/lib/ansible/modules/network/vyos/vyos_vlan.py b/lib/ansible/modules/network/vyos/vyos_vlan.py index 66c1e4b6b95..0bf191f3f9a 100644 --- a/lib/ansible/modules/network/vyos/vyos_vlan.py +++ b/lib/ansible/modules/network/vyos/vyos_vlan.py @@ -22,7 +22,8 @@ description: - This module provides declarative management of VLANs on VyOS network devices. notes: - - Tested against VYOS 1.1.7 + - Tested against VyOS 1.1.8 (helium). + - This module works with connection C(network_cli). See L(the VyOS OS Platform Options,../network/user_guide/platform_vyos.html). options: name: description: