Merge pull request #42236 from cloudflare/napalm-provider

New option for napalm proxy/minion: provider

salt/proxy/napalm.py

@@ -23,37 +23,77 @@ Please check Installation_ for complete details.
 Pillar
 ------
 
-The napalm proxy configuration requires four mandatory parameters in order to connect to the network device:
+The napalm proxy configuration requires the following parameters in order to connect to the network device:
 
-* driver: specifies the network device operating system. For a complete list of the supported operating systems \
-please refer to the `NAPALM Read the Docs page`_.
-* host: hostname
-* username: username to be used when connecting to the device
-* passwd: the password needed to establish the connection
-* optional_args: dictionary with the optional arguments. Check the complete list of supported `optional arguments`_
+driver
+    Specifies the network device operating system.
+    For a complete list of the supported operating systems please refer to the
+    `NAPALM Read the Docs page`_.
 
-.. _`NAPALM Read the Docs page`: https://napalm.readthedocs.io/en/latest/#supported-network-operating-systems
-.. _`optional arguments`: http://napalm.readthedocs.io/en/latest/support/index.html#list-of-supported-optional-arguments
+host
+    The IP Address or FQDN to use when connecting to the device. Alternatively,
+    the following field names can be used instead: ``hostname``, ``fqdn``, ``ip``.
 
-.. versionadded:: 2017.7.0
+username
+    The username to be used when connecting to the device.
 
-* always_alive: in certain less dynamic environments, maintaining the remote connection permanently
+passwd
+    The password needed to establish the connection.
+
+    .. note::
+
+        This field may not be mandatory when working with SSH-based drivers, and
+        the username has a SSH key properly configured on the device targeted to
+        be managed.
+
+optional_args
+    Dictionary with the optional arguments.
+    Check the complete list of supported `optional arguments`_.
+
+always_alive: ``True``
+    In certain less dynamic environments, maintaining the remote connection permanently
     open with the network device is not always beneficial. In that case, the user can
     select to initialize the connection only when needed, by specifying this field to ``false``.
     Default: ``true`` (maintains the connection with the remote network device).
 
-Example:
+    .. versionadded:: 2017.7.0
+
+provider: ``napalm_base``
+    The module that provides the ``get_network_device`` function.
+    This option is useful when the user has more specific needs and requires
+    to extend the NAPALM capabilities using a private library implementation.
+    The only constraint is that the alternative library needs to have the
+    ``get_network_device`` function available.
+
+    .. versionadded:: 2017.7.1
+
+.. _`NAPALM Read the Docs page`: https://napalm.readthedocs.io/en/latest/#supported-network-operating-systems
+.. _`optional arguments`: http://napalm.readthedocs.io/en/latest/support/index.html#list-of-supported-optional-arguments
+
+Proxy pillar file example:
 
 .. code-block:: yaml
 
     proxy:
-        proxytype: napalm
-        driver: junos
-        host: core05.nrt02
-        username: my_username
-        passwd: my_password
-        optional_args:
-            port: 12201
+      proxytype: napalm
+      driver: junos
+      host: core05.nrt02
+      username: my_username
+      passwd: my_password
+      optional_args:
+        port: 12201
+
+Example using a user-specific library, extending NAPALM's capabilities, e.g. ``custom_napalm_base``:
+
+.. code-block:: yaml
+
+    proxy:
+      proxytype: napalm
+      driver: ios
+      fqdn: cr1.th2.par.as1234.net
+      username: salt
+      password: ''
+      provider: custom_napalm_base
 
 .. seealso::
 

salt/utils/napalm.py

@@ -19,6 +19,7 @@ from __future__ import absolute_import
 
 import traceback
 import logging
+import importlib
 from functools import wraps
 log = logging.getLogger(__file__)
 
@@ -264,6 +265,7 @@ def get_device_opts(opts, salt_obj=None):
     network_device['TIMEOUT'] = device_dict.get('timeout', 60)
     network_device['OPTIONAL_ARGS'] = device_dict.get('optional_args', {})
     network_device['ALWAYS_ALIVE'] = device_dict.get('always_alive', True)
+    network_device['PROVIDER'] = device_dict.get('provider')
     network_device['UP'] = False
     # get driver object form NAPALM
     if 'config_lock' not in network_device['OPTIONAL_ARGS']:
@@ -281,7 +283,24 @@ def get_device(opts, salt_obj=None):
     '''
     log.debug('Setting up NAPALM connection')
     network_device = get_device_opts(opts, salt_obj=salt_obj)
-    _driver_ = napalm_base.get_network_driver(network_device.get('DRIVER_NAME'))
+    provider_lib = napalm_base
+    if network_device.get('PROVIDER'):
+        # In case the user requires a different provider library,
+        #   other than napalm-base.
+        # For example, if napalm-base does not satisfy the requirements
+        #   and needs to be enahanced with more specific features,
+        #   we may need to define a custom library on top of napalm-base
+        #   with the constraint that it still needs to provide the
+        #   `get_network_driver` function. However, even this can be
+        #   extended later, if really needed.
+        # Configuration example:
+        #   provider: napalm_base_example
+        try:
+            provider_lib = importlib.import_module(network_device.get('PROVIDER'))
+        except ImportError as ierr:
+            log.error('Unable to import {0}'.format(network_device.get('PROVIDER')), exc_info=True)
+            log.error('Falling back to napalm-base')
+    _driver_ = provider_lib.get_network_driver(network_device.get('DRIVER_NAME'))
     try:
         network_device['DRIVER'] = _driver_(
             network_device.get('HOSTNAME', ''),