internet/community.general
3
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2026-05-06 13:22:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

HTTP(S) API connection plugin (#39224)

Browse Source 
* HTTPAPI connection

* Punt run_commands to cliconf or httpapi

* Fake enable_mode on eapi

* Pull changes to nxos

* Move load_config to edit_config for future-preparedness

* Don't fail on lldp disabled

* Re-enable check_rc on nxos' run_commands

* Reorganize nxos httpapi plugin for compatibility

* draft docs for connection: httpapi

* restores docs for connection:local for eapi

* Add _remote_is_local to httpapi
This commit is contained in:
Nathaniel Case
2018-05-17 18:47:15 -04:00
committed by GitHub
parent cc61c86049
commit e9d7fa0418
277 changed files with 1325 additions and 1676 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
docs/docsite/rst/network/getting_started/network_differences.rst
View File

@@ -11,11 +11,7 @@ Execution on the Control Node
Unlike most Ansible modules, network modules do not run on the managed nodes. From a user's point of view, network modules work like any other modules. They work with ad-hoc commands, playbooks, and roles. Behind the scenes, however, network modules use a different methodology than the other (Linux/Unix and Windows) modules use. Ansible is written and executed in Python. Because the majority of network devices can not run Python, the Ansible network modules are executed on the Ansible control node, where ``ansible`` or ``ansible-playbook`` runs.
Execution on the control node shapes two other differences in how network modules function:
- Network modules do not run every task in a playbook. They request current config first, compare current config to the state described by the task or playbook, and execute a task only if it changes the state of the managed node.
- Network modules that offer a backup option write the backup files onto the control node. With Linux/Unix modules, where a configuration file already exists on the managed node(s), the backup file gets written by default in the same directory as the new, changed file. Network modules do not update configuration files on the managed nodes, because network configuration is not written in files. Network modules write backup files on the control node, in the `backup` directory under the playbook root directory.
Network modules also use the control node as a destination for backup files, for those modules that offer a ``backup`` option. With Linux/Unix modules, where a configuration file already exists on the managed node(s), the backup file gets written by default in the same directory as the new, changed file. Network modules do not update configuration files on the managed nodes, because network configuration is not written in files. Network modules write backup files on the control node, usually in the `backup` directory under the playbook root directory.
Multiple Communication Protocols
================================================================================
@@ -23,14 +19,15 @@ Multiple Communication Protocols
Because network modules execute on the control node instead of on the managed nodes, they can support multiple communication protocols. The communication protocol (XML over SSH, CLI over SSH, API over HTTPS) selected for each network module depends on the platform and the purpose of the module. Some network modules support only one protocol; some offer a choice. The most common protocol is CLI over SSH. You set the communication protocol with the ``ansible_connection`` variable:
.. csv-table::
:header: "Value of ansible_connection", "Protocol", "Requires"
:widths: 30, 10, 10
:header: "Value of ansible_connection", "Protocol", "Requires", "Persistent?"
:widths: 30, 10, 10, 10
"network_cli", "CLI over SSH", "network_os setting"
"netconf", "XML over SSH", "network_os setting"
"local", "depends on provider", "provider setting"
"network_cli", "CLI over SSH", "network_os setting", "yes"
"netconf", "XML over SSH", "network_os setting", "yes"
"httpapi", "API over HTTP/HTTPS", "network_os setting", "yes"
"local", "depends on provider", "provider setting", "no"
Beginning with Ansible 2.5, we recommend using ``network_cli`` or ``netconf`` for ``ansible_connection`` whenever possible. For details on using API over HTTPS connections, see the :ref:`platform-specific <platform_options>` pages.
Beginning with Ansible 2.6, we recommend using one of the persistent connection types listed above instead of ``local``. With persistent connections, you can define the hosts and credentials only once, rather than in every task. For more details on using each connection type on various platforms, see the :ref:`platform-specific <platform_options>` pages.
Modules Organized by Network Platform
@@ -46,12 +43,15 @@ A network platform is a set of network devices with a common operating system th
All modules within a network platform share certain requirements. Some network platforms have specific differences - see the :ref:`platform-specific <platform_options>` documentation for details.
Privilege Escalation: `authorize` and `become`
Privilege Escalation: ``enable`` mode, ``become``, and ``authorize``
================================================================================
Several network platforms support privilege escalation, where certain tasks must be done by a privileged user. This is generally known as ``enable`` mode (the equivalent of ``sudo`` in \*nix administration). Ansible network modules offer privilege escalation for those network devices that support it. However, different platforms use privilege escalation in different ways.
Several network platforms support privilege escalation, where certain tasks must be done by a privileged user. On network devices this is called ``enable`` mode (the equivalent of ``sudo`` in \*nix administration). Ansible network modules offer privilege escalation for those network devices that support it. For details of which platforms support ``enable`` mode, with examples of how to use it, see the :ref:`platform-specific <platform_options>` documentation.
Network platforms that support ``connection: network_cli`` and privilege escalation use the top-level Ansible parameter ``become: yes`` with ``become_method: enable``. For modules in these platforms, a ``group_vars`` file would look like:
Using ``become`` for privilege escalation
-----------------------------------------
As of Ansible 2.6, you can use the top-level Ansible parameter ``become: yes`` with ``become_method: enable`` to run a task, play, or playbook with escalated privileges on any network platform that supports privilege escalation. You must use either ``connection: network_cli`` or ``connection: httpapi`` with ``become: yes`` with ``become_method: enable``. If you are using ``network_cli`` to connect Ansible to your network devices, a ``group_vars`` file would look like:
.. code-block:: yaml
@@ -60,9 +60,10 @@ Network platforms that support ``connection: network_cli`` and privilege escalat
ansible_become: yes
ansible_become_method: enable
We recommend using ``network_cli`` connections whenever possible.
Legacy playbooks: ``authorize`` for privilege escalation
-----------------------------------------------------------------
Some network platforms support privilege escalation but cannot use ``network_cli`` connections yet. This includes all platforms in older versions of Ansible (< 2.5) and HTTPS connections using ``eapi`` in version 2.5. With these connections, you must use a ``provider`` dictionary and include ``authorize: yes`` and ``auth_pass: my_enable_password``. For that use case, a ``group_vars`` file looks like:
If you are running Ansible 2.5 or older, some network platforms support privilege escalation but not ``network_cli`` or ``httpapi`` connections. This includes all platforms in versions 2.4 and older, and HTTPS connections using ``eapi`` in version 2.5. With a ``local`` connection, you must use a ``provider`` dictionary and include ``authorize: yes`` and ``auth_pass: my_enable_password``. For that use case, a ``group_vars`` file looks like:
.. code-block:: yaml
@@ -76,7 +77,7 @@ Some network platforms support privilege escalation but cannot use ``network_cli
transport: eapi
use_ssl: no
And you use the ``eapi`` variable in your play(s) or task(s):
And you use the ``eapi`` variable in your task(s):
.. code-block:: yaml
@@ -91,4 +92,6 @@ And you use the ``eapi`` variable in your play(s) or task(s):
state: present
provider: "{{ eapi }}"
Note that while Ansible 2.6 supports the use of ``connection: local`` with ``provider`` dictionaries, this usage will be deprecated in future and eventually removed.
For more information, see :ref:`Become and Networks<become-network>`

92
docs/docsite/rst/network/user_guide/platform_eos.rst
View File

@@ -11,27 +11,35 @@ Arista EOS supports multiple connections. This page offers details on how each c
Connections Available
================================================================================
+---------------------------+-----------------------------------------------+-----------------------------------------+
|.. | CLI | eAPI |
+===========================+===============================================+=========================================+
| **Protocol** | SSH | HTTP(S) |
+---------------------------+-----------------------------------------------+-----------------------------------------+
| | **Credentials** | | uses SSH keys / SSH-agent if present | | uses HTTPS certificates if present |
| | | | accepts ``-u myuser -k`` if using password | | |
+---------------------------+-----------------------------------------------+-----------------------------------------+
| **Indirect Access** | via a bastion (jump host) | via a web proxy |
+---------------------------+-----------------------------------------------+-----------------------------------------+
| | **Connection Settings** | | ``ansible_connection: network_cli`` | | ``ansible_connection: local`` |
| | | | | | Requires ``transport: eapi`` |
| | | | | | in the ``provider`` dictionary |
+---------------------------+-----------------------------------------------+-----------------------------------------+
| | **Enable Mode** | | supported - use ``ansible_become: yes`` | | supported - use ``authorize: yes`` |
| | (Privilege Escalation) | | with ``ansible_become_method: enable`` | | and ``auth_pass:`` in the |
| | | | and ``ansible_become_pass:`` | | ``provider`` dictionary |
+---------------------------+-----------------------------------------------+-----------------------------------------+
| **Returned Data Format** | ``stdout[0].`` | ``stdout[0].messages[0].`` |
+---------------------------+-----------------------------------------------+-----------------------------------------+
+---------------------------+-----------------------------------------------+---------------------------------------------+
|.. | CLI | eAPI |
+===========================+===============================================+=============================================+
| **Protocol** | SSH | HTTP(S) |
+---------------------------+-----------------------------------------------+---------------------------------------------+
| | **Credentials** | | uses SSH keys / SSH-agent if present | | uses HTTPS certificates if present |
| | | | accepts ``-u myuser -k`` if using password | | |
+---------------------------+-----------------------------------------------+---------------------------------------------+
| **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: eapi`` |
| | | | | | in the ``provider`` dictionary |
+---------------------------+-----------------------------------------------+---------------------------------------------+
| | **Enable Mode** | | supported - use ``ansible_become: yes`` | | supported: |
| | (Privilege Escalation) | | with ``ansible_become_method: enable`` | | ``httpapi`` |
| | | | | | 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].`` |
+---------------------------+-----------------------------------------------+---------------------------------------------+
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.
Using CLI in Ansible 2.5
================================================================================
@@ -86,13 +94,47 @@ Before you can use eAPI to connect to a switch, you must enable eAPI. To enable
become_method: enable
when: ansible_network_os == 'eos'
You can find more options for enabling HTTP/HTTPS and local http in the :ref:`eos_eapi <eos_eapi_module>` module documentation.
You can find more options for enabling HTTP/HTTPS connections in the :ref:`eos_eapi <eos_eapi_module>` module documentation.
Once eAPI is enabled, change your ``group_vars/eos.yml`` to use the eAPI connection.
Example eAPI ``group_vars/eos.yml``
-----------------------------------
.. code-block:: yaml
ansible_connection: httpapi
ansible_network_os: eos
ansible_user: myuser
ansible_ssh_pass: !vault...
become: yes
become_method: enable
proxy_env:
http_proxy: http://proxy.example.com:8080
- If you are accessing your host directly (not through a web proxy) you can remove the ``proxy_env`` configuration.
- If you are accessing your host through a web proxy using ``https``, change ``http_proxy`` to ``https_proxy``.
Example eAPI Task
-----------------
.. code-block:: yaml
- name: Backup current switch config (eos)
eos_config:
backup: yes
register: backup_eos_location
environment: "{{ proxy_env }}"
when: ansible_network_os == '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
@@ -107,12 +149,7 @@ Example eAPI ``group_vars/eos.yml``
proxy_env:
http_proxy: http://proxy.example.com:8080
- If you are accessing your host directly (not through a web proxy) you can remove the ``proxy_env`` configuration.
- If you are accessing your host through a web proxy using ``https``, change ``http_proxy`` to ``https_proxy``.
Example eAPI Task
-----------------
eAPI task:
.. code-block:: yaml
@@ -129,5 +166,4 @@ In this example two variables defined in ``group_vars`` get passed to the module
- 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.rst

2
docs/docsite/rst/network/user_guide/platform_index.rst
View File

@@ -4,7 +4,7 @@
Platform Options
****************
Some Ansible Network platforms support multiple connection types, privilege escalation, or other options. The pages in this section offer standardized guides to understanding available options on each network platform. We welcome contributions from community-maintained platforms to this section.
Some Ansible Network platforms support multiple connection types, privilege escalation (``enable`` mode), or other options. The pages in this section offer standardized guides to understanding available options on each network platform. We welcome contributions from community-maintained platforms to this section.
.. toctree::
:maxdepth: 2

17
docs/docsite/rst/network/user_guide/platform_nxos.rst
View File

@@ -21,9 +21,7 @@ Connections Available
+---------------------------+-----------------------------------------------+-----------------------------------------+
| **Indirect Access** | via a bastion (jump host) | via a web proxy |
+---------------------------+-----------------------------------------------+-----------------------------------------+
| | **Connection Settings** | | ``ansible_connection: network_cli`` | | ``ansible_connection: local`` |
| | | | | | Requires ``transport: nxapi`` |
| | | | | | in the ``provider`` dictionary |
| | **Connection Settings** | | ``ansible_connection: network_cli`` | | ``ansible_connection: httpapi`` |
+---------------------------+-----------------------------------------------+-----------------------------------------+
| | **Enable Mode** | | supported - use ``ansible_become: yes`` | | not supported by NX-API |
| | (Privilege Escalation) | | with ``ansible_become_method: enable`` | | |
@@ -32,6 +30,7 @@ Connections Available
| **Returned Data Format** | ``stdout[0].`` | ``stdout[0].messages[0].`` |
+---------------------------+-----------------------------------------------+-----------------------------------------+
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.
Using CLI in Ansible 2.5
================================================================================
@@ -93,13 +92,10 @@ Example NX-API ``group_vars/nxos.yml``
.. code-block:: yaml
ansible_connection: local
ansible_connection: httpapi
ansible_network_os: nxos
ansible_user: myuser
ansible_ssh_pass: !vault...
nxapi:
host: "{{ inventory_hostname }}"
transport: nxapi
proxy_env:
http_proxy: http://proxy.example.com:8080
@@ -115,15 +111,10 @@ Example NX-API Task
- name: Backup current switch config (nxos)
nxos_config:
backup: yes
provider: "{{ nxapi }}"
register: backup_nxos_location
environment: "{{ proxy_env }}"
when: ansible_network_os == 'nxos'
In this example two variables defined in ``group_vars`` get passed to the module of the task:
- the ``nxapi`` variable gets passed to the ``provider`` option of the module
- the ``proxy_env`` variable gets passed to the ``environment`` option of the module
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.rst

17
docs/docsite/rst/user_guide/become.rst
View File

@@ -213,15 +213,11 @@ module.
Become and Networks
===================
As of version 2.6, Ansible supports ``become`` for privilege escalation (entering ``enable`` mode or privileged EXEC mode) on all :ref:`Ansible-maintained platforms<network_supported>` that support ``enable`` mode: `eos``, ``ios``, and ``nxos``. Using ``become`` replaces the ``authorize`` and ``auth_pass`` options in a ``provider`` dictionary.
network_cli and become
----------------------
You must set the connection type to either ``connection: network_cli`` or ``connection: httpapi`` to use ``become`` for privilege escalation on network devices. Check the :ref:`platform_options` and :ref:`network_modules` documentation for details.
Ansible 2.5 added support for ``become`` to be used to enter ``enable`` mode (Privileged EXEC mode) on network devices that support it. This replaces the previous ``authorize`` and ``auth_pass`` options in ``provider``.
You must set the host connection type to ``connection: network_cli`` to use ``become`` for privilege escalation on network devices. Ansible 2.5.3 supports ``become`` for privilege escalation on ``eos``, ``ios``, and ``nxos``.
You can use escalated privileges on only the specific tasks that need them, on an entire play, or on all plays. Adding ``become: yes`` and ``become_method: enable`` instructs Ansible to enter ``enable`` mode before executing the task, play, or playbook.
You can use escalated privileges on only the specific tasks that need them, on an entire play, or on all plays. Adding ``become: yes`` and ``become_method: enable`` instructs Ansible to enter ``enable`` mode before executing the task, play, or playbook where those parameters are set.
If you see this error message, the task that generated it requires ``enable`` mode to succeed:
@@ -281,13 +277,10 @@ If you need a password to enter ``enable`` mode, you can specify it in one of tw
As a reminder passwords should never be stored in plain text. For information on encrypting your passwords and other secrets with Ansible Vault, see :doc:`playbooks_vault`.
.. _become-network-auth-and-auth-password:
authorize and auth_pass
-----------------------
For HTTPS connections that cannot use ``connection: network_cli``, you can enter ``enable`` mode using the module options ``authorize`` and ``auth_pass``:
Ansible still supports ``enable`` mode with ``connection: local`` for legacy playbooks. To enter ``enable`` mode with ``connection: local``, use the module options ``authorize`` and ``auth_pass``:
.. code-block:: yaml
@@ -302,7 +295,7 @@ For HTTPS connections that cannot use ``connection: network_cli``, you can enter
authorize: yes
auth_pass: " {{ secret_auth_pass }}"
Note that over time more platforms and connections will support ``become``. As this happens, the use of ``authorize`` and of ``provider`` dictionaries will be deprecated. Check the :ref:`platform_options` and :ref:`network_modules` documentation for details.
We recommend updating your playbooks to use ``become`` for network-device ``enable`` mode consistently. The use of ``authorize`` and of ``provider`` dictionaries will be deprecated in future. Check the :ref:`platform_options` and :ref:`network_modules` documentation for details.
.. _become-windows: