Doc - network device configuration capabilities

Add documentation for the device configuration capabilities.
The driver plug-in interface and the `netconf-openconfig`
reference driver implementation.

Story: 2009961
Task: 45994
Change-Id: I465b310b5e30904a484e4056446ea19778157544

doc/source/conf.py

@@ -51,8 +51,15 @@ master_doc = 'index'
 # General information about the project.
 copyright = u'2017, The Networking Baremetal team'
 
-config_generator_config_file = '../../tools/config/networking-baremetal-config-generator.conf'
-sample_config_basename = '_static/ironic_neutron_agent.ini'
+config_generator_config_file = [
+    ('../../tools/config/networking-baremetal-ironic-neutron-agent.conf',
+     '_static/ironic_neutron_agent.ini'),
+    ('../../tools/config/networking-baremetal-common-device-driver-opts.conf',
+     '_static/common_device_driver_opts'),
+    ('../../tools/config/networking-baremetal-netconf-openconfig-driver-opts.conf',
+     '_static/netconf_openconfig_device_driver')
+]
+# sample_config_basename = '_static/ironic_neutron_agent.ini'
 
 # A list of ignored prefixes for module index sorting.
 modindex_common_prefix = ['networking_baremetal.']

doc/source/configuration/config.rst

@@ -1,10 +0,0 @@
-=====================
-Configuration Options
-=====================
-
-The following is an overview of all available configuration options in
-networking-baremetal. For a sample configuration file, refer to
-:doc:`sample-config`.
-
-.. show-options::
-   :config-file: tools/config/networking-baremetal-config-generator.conf

doc/source/configuration/index.rst

@@ -1,12 +1,9 @@
-=======================
-Configuration Reference
-=======================
-
-The following pages describe configuration options that can be used to adjust
-the service to your particular situation.
+=====================
+Configuration Options
+=====================
 
 .. toctree::
-  :maxdepth: 1
+   :maxdepth: 3
 
-  Configuration Options <config>
-  Sample Config File <sample-config>
+   Ironic Neutron agent <ironic-neutron-agent/index>
+   ML2 <ml2/index>

doc/source/configuration/ironic-neutron-agent/config.rst

@@ -0,0 +1,10 @@
+============================================
+ironic-neutron-agent - Configuration Options
+============================================
+
+The following is an overview of all available configuration options in
+networking-baremetal. For a sample configuration file, refer to
+:doc:`sample-config`.
+
+.. show-options::
+   :config-file: tools/config/networking-baremetal-ironic-neutron-agent.conf

doc/source/configuration/ironic-neutron-agent/index.rst

@@ -0,0 +1,12 @@
+=======================
+Configuration Reference
+=======================
+
+The following pages describe configuration options that can be used to adjust
+the ``ironic-neutron-agent`` service to your particular situation.
+
+.. toctree::
+  :maxdepth: 1
+
+  Configuration Options <config>
+  Sample Config File <sample-config>

doc/source/configuration/ml2/device_drivers/common_config.rst

@@ -0,0 +1,31 @@
+===================================================
+Common configuration options for all device drivers
+===================================================
+
+This page describes configuration options that is common to all networking-
+baremetal device drivers. Individual drivers may have independent configuration
+requirements depending on the implementation, refer to the device driver
+specific documentation.
+
+Configuration options
+^^^^^^^^^^^^^^^^^^^^^
+
+.. show-options::
+   :config-file: tools/config/networking-baremetal-common-device-driver-opts.conf
+
+Sample Configuration File
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following is a sample configuration section that would be added to
+``/etc/neutron/plugins/ml2/ml2_conf.ini``.
+
+The sample configuration can also be viewed in :download:`file form
+</_static/netconf_openconfig_device_driver.conf.sample>`.
+
+.. important::
+
+   The sample configuration file is auto-generated from networking-baremetal
+   when this documentation is built. You must ensure your version of
+   networking-baremetal matches the version of this documentation.
+
+.. literalinclude:: /_static/common_device_driver_opts.conf.sample

doc/source/configuration/ml2/device_drivers/index.rst

@@ -0,0 +1,28 @@
+==============
+Device drivers
+==============
+
+The baremetal mechanism ML2 plug-in provides a device driver plug-in interface,
+this interface can be used to add device (switch) configuration capabilities.
+The interface uses `stevedore <https://opendev.org/openstack/stevedore/>`__ for
+dynamic loading.
+
+Individual drivers may have independent configuration requirements depending on
+the implementation. :ref:`Driver specific options <device_drivers>` are
+documented separately.
+
+.. toctree::
+   :maxdepth: 2
+
+   Common configuration options <common_config>
+
+
+.. _device_drivers:
+
+Available device drivers
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 3
+
+   netconf-openconfig <netconf-openconfig>

doc/source/configuration/ml2/device_drivers/netconf-openconfig.rst

@@ -0,0 +1,67 @@
+Device driver - netconf-openconfig
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``netconf-openconfig`` device driver uses the Network Configuration
+Protocol (`NETCONF <https://datatracker.ietf.org/group/netconf/about/>`__)
+and open source vendor-neutral  `OpenConfig <http://openconfig.net/>`__ YANG
+models.
+
+This driver has been tested with the following switch vendor/operating systems:
+
+* Cisco NXOS
+* Arista vEOS
+
+**Example configuration for Cisco NXOS device**:
+
+.. code-block:: ini
+
+  [networking_baremetal]
+  enabled_devices = nexus.example.net
+
+  [nexus.example.net]
+  driver = netconf-openconfig
+  device_params = name:nexus
+  switch_info = nexus
+  switch_id = 00:53:00:0a:0a:0a
+  host = nexus.example.net
+  username = user
+  key_filename = /etc/neutron/ssh_keys/nexus_sshkey
+
+**Example configuration for Arista EOS device**:
+
+.. code-block:: ini
+
+  [networking_baremetal]
+  enabled_devices = arista.example.net
+
+  [arista.example.net]
+  driver = netconf-openconfig
+  device_params = name:default
+  switch_info = arista
+  switch_id = 00:53:00:0b:0b:0b
+  host = arista.example.net
+  username = user
+  key_filename = /etc/neutron/ssh_keys/arista_sshkey
+
+Configuration options
+^^^^^^^^^^^^^^^^^^^^^
+
+.. show-options::
+   :config-file: tools/config/networking-baremetal-netconf-openconfig-driver-opts.conf
+
+Sample Configuration File
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following is a sample configuration section that would be added to
+``/etc/neutron/plugins/ml2/ml2_conf.ini``.
+
+The sample configuration can also be viewed in :download:`file form
+</_static/netconf_openconfig_device_driver.conf.sample>`.
+
+.. important::
+
+   The sample configuration file is auto-generated from networking-baremetal
+   when this documentation is built. You must ensure your version of
+   networking-baremetal matches the version of this documentation.
+
+.. literalinclude:: /_static/netconf_openconfig_device_driver.conf.sample

doc/source/configuration/ml2/index.rst

@@ -0,0 +1,32 @@
+=======================
+Configuration Reference
+=======================
+
+The following pages describe configuration options that can be used to adjust
+the neutron ML2 configuration and the baremetal ML2 plug-in and device drivers
+to your particular situation.
+
+To enable mechanism drivers in the ML2 plug-in, edit the
+``/etc/neutron/plugins/ml2/ml2_conf.ini`` configuration file. For example, this
+enables the ``openvswitch`` and ``baremetal`` mechanism drivers:
+
+.. code-block:: ini
+
+  [ml2]
+  mechanism_drivers = openvswitch,baremetal
+
+To add a device to manage, edit the ``/etc/neutron/plugins/ml2/ml2_conf.ini``
+configuration file. The example below enables devices: ``device_a.example.net``
+and ``device_b.example.net``. For each device a separate section in the same
+configuration file defines the device and driver specific configuration. Please
+refer to :doc:`device_drivers/index` for details.
+
+.. code-block:: ini
+
+  [networking_baremetal]
+  enabled_device = device_a.example.net,device_b.example.net
+
+.. toctree::
+   :maxdepth: 4
+
+   Device Drivers <device_drivers/index>

doc/source/contributor/index.rst

@@ -65,6 +65,7 @@ code reviews to an OpenStack project.
 
    Deploying networking-baremetal with DevStack <quickstart>
    Deploying networking-baremetal and multi-tenant networking with DevStack <quickstart-multitenant>
+   Virtual lab with virtual switch and netconf-openconfig Device Driver <quickstart-netconf-openconfig>
 
 Full networking-baremetal python API reference
 ==============================================

doc/source/contributor/quickstart-netconf-openconfig.rst

@@ -0,0 +1,6 @@
+Virtual lab with virtual switch and netconf-openconfig Device Driver
+####################################################################
+
+Ansible playbooks that can be used to set up a lab for developing networking-
+baremetal network device integration is hosted on `GitHub
+<https://github.com/hjensas/net-bm-lab>`_.

doc/source/index.rst

@@ -23,7 +23,7 @@ Configuration Guide
 ===================
 
 .. toctree::
-  :maxdepth: 2
+  :maxdepth: 3
 
   configuration/index
 

doc/source/install/index.rst

@@ -45,6 +45,44 @@ enables the ``openvswitch`` and ``baremetal`` mechanism drivers:
   [ml2]
   mechanism_drivers = openvswitch,baremetal
 
+Add devices (switches) to manage
+--------------------------------
+
+The baremetal mechanism ML2 plug-in provides a device driver plug-in interface.
+If a device driver for the switch model exist the baremetal ML2 plug-in can be
+configured to manage switch configuration, adding tenant VLANs and setting
+switch port VLAN configuration etc.
+
+To add a device to manage, edit the ``/etc/neutron/plugins/ml2/ml2_conf.ini``
+configuration file. The example below enables devices: ``device_a.example.net``
+and ``device_b.example.net``. Both devices in the example is using the
+``netconf-openconfig`` device driver. For each device a separate section in
+configuration defines the device and driver specific configuration.
+
+.. code-block:: ini
+
+  [networking_baremetal]
+  enabled_devices = device_a.example.net,device_b.example.net
+
+  [device_a.example.net]
+  driver = netconf-openconfig
+  switch_info = device_a
+  switch_id = 00:53:00:0a:0a:0a
+  host = device_a.example.net
+  username = user
+  key_filename = /etc/neutron/ssh_keys/device_a_sshkey
+  hostkey_verify = false
+
+  [device_b.example.net]
+  driver = netconf-openconfig
+  switch_info = device_b
+  switch_id = 00:53:00:0b:0b:0b
+  host = device_a.example.net
+  username = user
+  key_filename = /etc/neutron/ssh_keys/device_a_sshkey
+  hostkey_verify = false
+
+
 Configure ironic-neutron-agent
 ------------------------------
 

networking_baremetal/config.py

@@ -13,7 +13,6 @@
 from oslo_config import cfg
 from oslo_log import log as logging
 
-import networking_baremetal.drivers.netconf.openconfig as netconf_openconfig
 
 CONF = cfg.CONF
 LOG = logging.getLogger(__name__)
@@ -21,8 +20,8 @@ LOG = logging.getLogger(__name__)
 _opts = [
     cfg.ListOpt('enabled_devices',
                 default=[],
-                sample_default=['generic.example.com',
-                                'netconf-openconfig.example.com'],
+                sample_default=['common-example',
+                                'netconf-openconfig-example'],
                 help=('Enabled devices for which the plugin should manage'
                       'configuration. Driver specific configuration for each '
                       'device must be added in separate sections.')),
@@ -45,7 +44,6 @@ _device_opts = [
                       'be create and deleted on the device.')),
     ]
 
-
 networking_baremetal_group = cfg.OptGroup(
     name='networking_baremetal',
     title='ML2 networking-baremetal options')
@@ -60,11 +58,12 @@ for device in CONF.networking_baremetal.enabled_devices:
 
 
 def list_opts():
+    return [('networking_baremetal', _opts)]
+
+
+def list_common_device_driver_opts():
     return [('networking_baremetal', _opts),
-            ('generic.example.com', _device_opts),
-            ('netconf-openconfig.example.com',
-             _device_opts + netconf_openconfig._DEVICE_OPTS
-             + netconf_openconfig._NCCLIENT_OPTS)]
+            ('common-example', _device_opts)]
 
 
 def get_devices():

networking_baremetal/drivers/netconf/openconfig.py

@@ -31,6 +31,7 @@ from oslo_log import log as logging
 import tenacity
 
 from networking_baremetal import common
+from networking_baremetal import config
 from networking_baremetal import constants
 from networking_baremetal.constants import NetconfEditConfigOperation as nc_op
 from networking_baremetal.drivers import base
@@ -129,6 +130,12 @@ _NCCLIENT_OPTS = [
 ]
 
 
+def list_driver_opts():
+    return [('networking_baremetal', config._opts),
+            ('netconf-openconfig-example',
+             config._device_opts + _DEVICE_OPTS + _NCCLIENT_OPTS)]
+
+
 class NetconfLockDenied(n_exec.NeutronException):
     message = ('Access to the requested lock is denied because the'
                'lock is currently held by another entity.')

setup.cfg

@@ -29,6 +29,8 @@ oslo.config.opts =
     ironic-neutron-agent = networking_baremetal.agent.ironic_neutron_agent:list_opts
     ironic-client = networking_baremetal.ironic_client:list_opts
     baremetal = networking_baremetal.config:list_opts
+    common-device-driver-opts = networking_baremetal.config:list_common_device_driver_opts
+    netconf-openconfig-driver-opts = networking_baremetal.drivers.netconf.openconfig:list_driver_opts
 
 console_scripts =
     ironic-neutron-agent = networking_baremetal.agent.ironic_neutron_agent:main

tools/config/networking-baremetal-common-device-driver-opts.conf

@@ -0,0 +1,4 @@
+[DEFAULT]
+output_file = etc/neutron/plugins/ml2/common_device_driver.ini.sample
+wrap_width = 79
+namespace = common-device-driver-opts

tools/config/networking-baremetal-ironic-neutron-agent.conf

@@ -4,4 +4,3 @@ wrap_width = 79
 namespace = ironic-neutron-agent
 namespace = oslo.log
 namespace = ironic-client
-namespace = baremetal

tools/config/networking-baremetal-netconf-openconfig-driver-opts.conf

@@ -0,0 +1,4 @@
+[DEFAULT]
+output_file = etc/neutron/plugins/ml2/netconf_openconfig_device_driver.ini.sample
+wrap_width = 79
+namespace = netconf-openconfig-driver-opts

tox.ini

@@ -74,7 +74,9 @@ deps =
    -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
    -r{toxinidir}/test-requirements.txt
 commands =
-  oslo-config-generator --config-file=tools/config/networking-baremetal-config-generator.conf
+  oslo-config-generator --config-file=tools/config/networking-baremetal-ironic-neutron-agent.conf
+  oslo-config-generator --config-file=tools/config/networking-baremetal-common-device-driver-opts.conf
+  oslo-config-generator --config-file=tools/config/networking-baremetal-netconf-openconfig-driver-opts.conf
 
 [testenv:debug]
 commands = oslo_debug_helper -t networking_baremetal/tests/unit {posargs}