diff --git a/docs/docsite/Makefile b/docs/docsite/Makefile index 97a07af104e..c97936bc70d 100644 --- a/docs/docsite/Makefile +++ b/docs/docsite/Makefile @@ -26,7 +26,7 @@ ifdef PLUGINS PLUGIN_ARGS = -l $(PLUGINS) endif -DOC_PLUGINS ?= cache callback connection inventory lookup shell strategy vars +DOC_PLUGINS ?= cache callback cliconf connection httpapi inventory lookup shell strategy vars assertrst: ifndef rst diff --git a/docs/docsite/rst/plugins/cliconf.rst b/docs/docsite/rst/plugins/cliconf.rst new file mode 100644 index 00000000000..f6b83d80d6a --- /dev/null +++ b/docs/docsite/rst/plugins/cliconf.rst @@ -0,0 +1,57 @@ +.. _cliconf_plugins: + +Cliconf Plugins +=============== + +.. contents:: + :local: + :depth: 2 + +Cliconf plugins are abstactions over the CLI interface to network devices. They provide a standard interface +for Ansible to execute tasks on those network devices. + +These plugins generally correspond one-to-one to network device platforms. The appropriate cliconf plugin will +thus be automatically loaded based on the ``ansible_network_os`` variable. + +.. _enabling_cliconf: + +Adding cliconf plugins +------------------------- + +You can extend Ansible to support other network devices by dropping a custom plugin into the ``cliconf_plugins`` directory. + +.. _using_cliconf: + +Using cliconf plugins +------------------------ + +The cliconf plugin to use is determined automatically from the ``ansible_network_os`` variable. There should be no reason to override this functionality. + +Most cliconf plugins can operate without configuration. A few have additional options that can be set to impact how +tasks are translated into CLI commands. + +Plugins are self-documenting. Each plugin should document its configuration options. + +.. _cliconf_plugin_list: + +Plugin list +----------- + +You can use ``ansible-doc -t cliconf -l`` to see the list of available plugins. +Use ``ansible-doc -t cliconf `` to see detailed documentation and examples. + + +.. toctree:: :maxdepth: 1 + :glob: + + cliconf/* + + +.. seealso:: + + :ref:`Ansible for Network Automation` + An overview of using Ansible to automate networking devices. + `User Mailing List `_ + Have a question? Stop by the google group! + `irc.freenode.net `_ + #ansible-network IRC chat channel diff --git a/docs/docsite/rst/plugins/httpapi.rst b/docs/docsite/rst/plugins/httpapi.rst new file mode 100644 index 00000000000..bd934128027 --- /dev/null +++ b/docs/docsite/rst/plugins/httpapi.rst @@ -0,0 +1,57 @@ +.. _httpapi_plugins: + +Httpapi Plugins +=============== + +.. contents:: + :local: + :depth: 2 + +Httpapi plugins tell Ansible how to interact with a remote device's HTTP-based API and execute tasks on the +device. + +Each plugin represents a particular dialect of API. Some are platform-specific (Arista eAPI, Cisco NXAPI), while +others might be usable on a variety of platforms (RESTCONF). + +.. _enabling_httpapi: + +Adding httpapi plugins +------------------------- + +You can extend Ansible to support other APIs by dropping a custom plugin into the ``httpapi_plugins`` directory. + +.. _using_httpapi: + +Using httpapi plugins +------------------------ + +The httpapi plugin to use is determined automatically from the ``ansible_network_os`` variable. + +Most httpapi plugins can operate without configuration. Additional options may be defined by each plugin. + +Plugins are self-documenting. Each plugin should document its configuration options. + + +.. _httpapi_plugin_list: + +Plugin List +----------- + +You can use ``ansible-doc -t httpapi -l`` to see the list of available plugins. +Use ``ansible-doc -t httpapi `` to see detailed documentation and examples. + + +.. toctree:: :maxdepth: 1 + :glob: + + httpapi/* + + +.. seealso:: + + :ref:`Ansible for Network Automation` + An overview of using Ansible to automate networking devices. + `User Mailing List `_ + Have a question? Stop by the google group! + `irc.freenode.net `_ + #ansible-network IRC chat channel diff --git a/docs/docsite/rst/plugins/plugins.rst b/docs/docsite/rst/plugins/plugins.rst index 2a7d3c2feaf..fc55d93a92c 100644 --- a/docs/docsite/rst/plugins/plugins.rst +++ b/docs/docsite/rst/plugins/plugins.rst @@ -16,7 +16,9 @@ This section covers the various types of plugins that are included with Ansible: action cache callback + cliconf connection + httpapi inventory lookup shell diff --git a/lib/ansible/plugins/cliconf/aireos.py b/lib/ansible/plugins/cliconf/aireos.py index bad7f503393..453683f4492 100644 --- a/lib/ansible/plugins/cliconf/aireos.py +++ b/lib/ansible/plugins/cliconf/aireos.py @@ -19,6 +19,16 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +cliconf: aireos +short_description: Use aireos cliconf to run command on Cisco WLC platform +description: + - This aireos plugin provides low level abstraction apis for + sending and receiving CLI commands from Cisco WLC network devices. +version_added: 2.4 +""" + import re import json diff --git a/lib/ansible/plugins/cliconf/aruba.py b/lib/ansible/plugins/cliconf/aruba.py index c8c3045ac7a..e8e0674336e 100644 --- a/lib/ansible/plugins/cliconf/aruba.py +++ b/lib/ansible/plugins/cliconf/aruba.py @@ -19,6 +19,16 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +cliconf: aruba +short_description: Use aruba cliconf to run command on Aruba platform +description: + - This aruba plugin provides low level abstraction apis for + sending and receiving CLI commands from Aruba network devices. +version_added: 2.4 +""" + import re import json diff --git a/lib/ansible/plugins/cliconf/asa.py b/lib/ansible/plugins/cliconf/asa.py index d0d23cad436..2c12fcff30c 100644 --- a/lib/ansible/plugins/cliconf/asa.py +++ b/lib/ansible/plugins/cliconf/asa.py @@ -19,6 +19,16 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +cliconf: asa +short_description: Use asa cliconf to run command on Cisco ASA platform +description: + - This asa plugin provides low level abstraction apis for + sending and receiving CLI commands from Cisco ASA network devices. +version_added: 2.4 +""" + import re import json diff --git a/lib/ansible/plugins/cliconf/ce.py b/lib/ansible/plugins/cliconf/ce.py index 6790860c8de..d10c30cbc30 100644 --- a/lib/ansible/plugins/cliconf/ce.py +++ b/lib/ansible/plugins/cliconf/ce.py @@ -19,6 +19,16 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +cliconf: ce +short_description: Use ce cliconf to run command on HUAWEI CloudEngine platform +description: + - This ce plugin provides low level abstraction apis for + sending and receiving CLI commands from HUAWEI CloudEngine network devices. +version_added: 2.7 +""" + import re import json diff --git a/lib/ansible/plugins/cliconf/cnos.py b/lib/ansible/plugins/cliconf/cnos.py index 187e49f00ef..52fa83abd02 100644 --- a/lib/ansible/plugins/cliconf/cnos.py +++ b/lib/ansible/plugins/cliconf/cnos.py @@ -16,6 +16,16 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +cliconf: cnos +short_description: Use cnos cliconf to run command on Lenovo CNOS platform +description: + - This cnos plugin provides low level abstraction apis for + sending and receiving CLI commands from Lenovo CNOS network devices. +version_added: 2.6 +""" + import re import json diff --git a/lib/ansible/plugins/cliconf/dellos10.py b/lib/ansible/plugins/cliconf/dellos10.py index 2ed9982bbe8..032d463323c 100644 --- a/lib/ansible/plugins/cliconf/dellos10.py +++ b/lib/ansible/plugins/cliconf/dellos10.py @@ -21,6 +21,16 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +cliconf: dellos10 +short_description: Use dellos10 cliconf to run command on Dell OS10 platform +description: + - This dellos10 plugin provides low level abstraction apis for + sending and receiving CLI commands from Dell OS10 network devices. +version_added: 2.5 +""" + import re import json diff --git a/lib/ansible/plugins/cliconf/dellos6.py b/lib/ansible/plugins/cliconf/dellos6.py index 746f2530569..8bfe713905a 100644 --- a/lib/ansible/plugins/cliconf/dellos6.py +++ b/lib/ansible/plugins/cliconf/dellos6.py @@ -21,6 +21,16 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +cliconf: dellos6 +short_description: Use dellos6 cliconf to run command on Dell OS6 platform +description: + - This dellos6 plugin provides low level abstraction apis for + sending and receiving CLI commands from Dell OS6 network devices. +version_added: 2.5 +""" + import re import json diff --git a/lib/ansible/plugins/cliconf/dellos9.py b/lib/ansible/plugins/cliconf/dellos9.py index 2ea9d1fdf94..ee72acf1a85 100644 --- a/lib/ansible/plugins/cliconf/dellos9.py +++ b/lib/ansible/plugins/cliconf/dellos9.py @@ -21,6 +21,16 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +cliconf: dellos9 +short_description: Use dellos9 cliconf to run command on Dell OS9 platform +description: + - This dellos9 plugin provides low level abstraction apis for + sending and receiving CLI commands from Dell OS9 network devices. +version_added: 2.5 +""" + import re import json diff --git a/lib/ansible/plugins/cliconf/edgeos.py b/lib/ansible/plugins/cliconf/edgeos.py index 970de0e33e6..af23df9a6ad 100644 --- a/lib/ansible/plugins/cliconf/edgeos.py +++ b/lib/ansible/plugins/cliconf/edgeos.py @@ -5,6 +5,16 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +cliconf: edgeos +short_description: Use edgeos cliconf to run command on EdgeOS platform +description: + - This edgeos plugin provides low level abstraction apis for + sending and receiving CLI commands from Ubiquiti EdgeOS network devices. +version_added: "2.5" +""" + import re import json diff --git a/lib/ansible/plugins/cliconf/edgeswitch.py b/lib/ansible/plugins/cliconf/edgeswitch.py index 44903ccbf6a..c080a2470b3 100644 --- a/lib/ansible/plugins/cliconf/edgeswitch.py +++ b/lib/ansible/plugins/cliconf/edgeswitch.py @@ -19,6 +19,16 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +cliconf: edgeswitch +short_description: Use edgeswitch cliconf to run command on EdgeSwitch platform +description: + - This edgeswitch plugin provides low level abstraction apis for + sending and receiving CLI commands from Ubiquiti EdgeSwitch network devices. +version_added: "2.8" +""" + import re import time import json diff --git a/lib/ansible/plugins/cliconf/enos.py b/lib/ansible/plugins/cliconf/enos.py index 3c9267f3ef8..272743f1c5e 100644 --- a/lib/ansible/plugins/cliconf/enos.py +++ b/lib/ansible/plugins/cliconf/enos.py @@ -16,6 +16,16 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +cliconf: enos +short_description: Use enos cliconf to run command on Lenovo ENOS platform +description: + - This enos plugin provides low level abstraction apis for + sending and receiving CLI commands from Lenovo ENOS network devices. +version_added: "2.5" +""" + import re import json diff --git a/lib/ansible/plugins/cliconf/eos.py b/lib/ansible/plugins/cliconf/eos.py index d5b18240865..f878a843ec1 100644 --- a/lib/ansible/plugins/cliconf/eos.py +++ b/lib/ansible/plugins/cliconf/eos.py @@ -23,11 +23,11 @@ DOCUMENTATION = """ --- author: Ansible Networking Team cliconf: eos -short_description: Use eos cliconf to run command on eos platform +short_description: Use eos cliconf to run command on Arista EOS platform description: - - This eos plugin provides low level abstraction api's for - sending and receiving CLI commands from eos network devices. -version_added: "2.7" + - This eos plugin provides low level abstraction apis for + sending and receiving CLI commands from Arista EOS network devices. +version_added: "2.4" options: eos_use_sessions: type: int diff --git a/lib/ansible/plugins/cliconf/exos.py b/lib/ansible/plugins/cliconf/exos.py index e87189f92ef..72bc527d7d2 100644 --- a/lib/ansible/plugins/cliconf/exos.py +++ b/lib/ansible/plugins/cliconf/exos.py @@ -19,6 +19,16 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +cliconf: exos +short_description: Use exos cliconf to run command on Extreme EXOS platform +description: + - This exos plugin provides low level abstraction apis for + sending and receiving CLI commands from Extreme EXOS network devices. +version_added: "2.6" +""" + import re import json diff --git a/lib/ansible/plugins/cliconf/frr.py b/lib/ansible/plugins/cliconf/frr.py index e3201de7dd0..be80b04aec0 100644 --- a/lib/ansible/plugins/cliconf/frr.py +++ b/lib/ansible/plugins/cliconf/frr.py @@ -25,8 +25,8 @@ author: Ansible Networking Team cliconf: frr short_description: Use frr cliconf to run command on Free Range Routing platform description: - - This frr plugin provides low level abstraction api's for - sending and receiving CLI commands from devices running frr. + - This frr plugin provides low level abstraction apis for + sending and receiving CLI commands from FRR network devices. version_added: "2.8" """ diff --git a/lib/ansible/plugins/cliconf/ios.py b/lib/ansible/plugins/cliconf/ios.py index a90b829c67b..de1b6face2e 100644 --- a/lib/ansible/plugins/cliconf/ios.py +++ b/lib/ansible/plugins/cliconf/ios.py @@ -19,6 +19,17 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +author: Ansible Networking Team +cliconf: ios +short_description: Use ios cliconf to run command on Cisco IOS platform +description: + - This ios plugin provides low level abstraction apis for + sending and receiving CLI commands from Cisco IOS network devices. +version_added: "2.4" +""" + import re import time import json diff --git a/lib/ansible/plugins/cliconf/iosxr.py b/lib/ansible/plugins/cliconf/iosxr.py index d78e52f0780..1e791c4b0c7 100644 --- a/lib/ansible/plugins/cliconf/iosxr.py +++ b/lib/ansible/plugins/cliconf/iosxr.py @@ -19,6 +19,17 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +author: Ansible Networking Team +cliconf: iosxr +short_description: Use iosxr cliconf to run command on Cisco IOS XR platform +description: + - This iosxr plugin provides low level abstraction apis for + sending and receiving CLI commands from Cisco IOS XR network devices. +version_added: "2.4" +""" + import re import json diff --git a/lib/ansible/plugins/cliconf/ironware.py b/lib/ansible/plugins/cliconf/ironware.py index ebf24601f85..ecf35e8e481 100644 --- a/lib/ansible/plugins/cliconf/ironware.py +++ b/lib/ansible/plugins/cliconf/ironware.py @@ -19,6 +19,16 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +cliconf: ironware +short_description: Use ironware cliconf to run command on Extreme Ironware platform +description: + - This ironware plugin provides low level abstraction apis for + sending and receiving CLI commands from Extreme Ironware network devices. +version_added: "2.5" +""" + import re import json diff --git a/lib/ansible/plugins/cliconf/junos.py b/lib/ansible/plugins/cliconf/junos.py index 548b1b37c32..a928fe8d1fc 100644 --- a/lib/ansible/plugins/cliconf/junos.py +++ b/lib/ansible/plugins/cliconf/junos.py @@ -19,6 +19,17 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +author: Ansible Networking Team +cliconf: junos +short_description: Use junos cliconf to run command on Juniper Junos OS platform +description: + - This junos plugin provides low level abstraction apis for + sending and receiving CLI commands from Juniper Junos OS network devices. +version_added: "2.4" +""" + import json import re diff --git a/lib/ansible/plugins/cliconf/nos.py b/lib/ansible/plugins/cliconf/nos.py index f5e07ae7cd4..558f60ae8b9 100644 --- a/lib/ansible/plugins/cliconf/nos.py +++ b/lib/ansible/plugins/cliconf/nos.py @@ -19,6 +19,16 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +cliconf: nos +short_description: Use nos cliconf to run command on Extreme NOS platform +description: + - This nos plugin provides low level abstraction apis for + sending and receiving CLI commands from Extreme NOS network devices. +version_added: "2.7" +""" + import re import json diff --git a/lib/ansible/plugins/cliconf/nxos.py b/lib/ansible/plugins/cliconf/nxos.py index b3b24800006..dac95a22af3 100644 --- a/lib/ansible/plugins/cliconf/nxos.py +++ b/lib/ansible/plugins/cliconf/nxos.py @@ -19,6 +19,17 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +author: Ansible Networking Team +cliconf: nxos +short_description: Use nxos cliconf to run command on Cisco NX-OS platform +description: + - This nxos plugin provides low level abstraction apis for + sending and receiving CLI commands from Cicso NX-OS network devices. +version_added: "2.4" +""" + import json import re diff --git a/lib/ansible/plugins/cliconf/onyx.py b/lib/ansible/plugins/cliconf/onyx.py index 4d66bdaad79..8195634b65f 100644 --- a/lib/ansible/plugins/cliconf/onyx.py +++ b/lib/ansible/plugins/cliconf/onyx.py @@ -19,6 +19,16 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +cliconf: onyx +short_description: Use onyx cliconf to run command on Mellanox ONYX platform +description: + - This onyx plugin provides low level abstraction apis for + sending and receiving CLI commands from Mellanox ONYX network devices. +version_added: "2.5" +""" + import json from itertools import chain diff --git a/lib/ansible/plugins/cliconf/routeros.py b/lib/ansible/plugins/cliconf/routeros.py index 2c5a9227664..38b73fe5b04 100644 --- a/lib/ansible/plugins/cliconf/routeros.py +++ b/lib/ansible/plugins/cliconf/routeros.py @@ -19,6 +19,16 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +cliconf: routeros +short_description: Use routeros cliconf to run command on MikroTik RouterOS platform +description: + - This routeros plugin provides low level abstraction apis for + sending and receiving CLI commands from MikroTik RouterOS network devices. +version_added: "2.7" +""" + import re import json diff --git a/lib/ansible/plugins/cliconf/slxos.py b/lib/ansible/plugins/cliconf/slxos.py index 4cdbaedc7ec..5c71e2d23a1 100644 --- a/lib/ansible/plugins/cliconf/slxos.py +++ b/lib/ansible/plugins/cliconf/slxos.py @@ -19,6 +19,16 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +cliconf: slxos +short_description: Use slxos cliconf to run command on Extreme SLX-OS platform +description: + - This slxos plugin provides low level abstraction apis for + sending and receiving CLI commands from Extreme SLX-OS network devices. +version_added: "2.6" +""" + import re import json diff --git a/lib/ansible/plugins/cliconf/voss.py b/lib/ansible/plugins/cliconf/voss.py index f1052668194..7cf832d5fff 100644 --- a/lib/ansible/plugins/cliconf/voss.py +++ b/lib/ansible/plugins/cliconf/voss.py @@ -19,6 +19,16 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +cliconf: voss +short_description: Use voss cliconf to run command on Extreme VOSS platform +description: + - This voss plugin provides low level abstraction apis for + sending and receiving CLI commands from Extreme VOSS network devices. +version_added: "2.7" +""" + import re import json diff --git a/lib/ansible/plugins/cliconf/vyos.py b/lib/ansible/plugins/cliconf/vyos.py index a5b9f42f9ce..340849e0c6d 100644 --- a/lib/ansible/plugins/cliconf/vyos.py +++ b/lib/ansible/plugins/cliconf/vyos.py @@ -19,6 +19,17 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type +DOCUMENTATION = """ +--- +author: Ansible Networking Team +cliconf: vyos +short_description: Use vyos cliconf to run command on VyOS platform +description: + - This vyos plugin provides low level abstraction apis for + sending and receiving CLI commands from VyOS network devices. +version_added: "2.4" +""" + import re import json diff --git a/lib/ansible/plugins/loader.py b/lib/ansible/plugins/loader.py index 7e1236318af..6d1ae7d3e83 100644 --- a/lib/ansible/plugins/loader.py +++ b/lib/ansible/plugins/loader.py @@ -772,4 +772,5 @@ httpapi_loader = PluginLoader( 'ansible.plugins.httpapi', C.DEFAULT_HTTPAPI_PLUGIN_PATH, 'httpapi_plugins', + required_base_class='HttpApiBase', )