From 609f271e0fb6f54d920e86a2e8b4ff6f91488bcf Mon Sep 17 00:00:00 2001
From: Vasyl Saienko <vsaienko@mirantis.com>
Date: Wed, 25 May 2016 17:29:26 +0300
Subject: [PATCH] Add baremetal-multitenancy guide

The guide describes how Ironic Neutron integration works.
It contains howto:
 * enable ML2 plugin in Neutron
 * configure Ironic to support multitenancy

Implements: blueprint ironic-ml2-integration

Change-Id: I4fe5dc57dbd8e022fd8597eca7c072850004cc76
---
 .../source/baremetal-multitenancy.rst         | 93 +++++++++++++++++++
 doc/admin-guide/source/baremetal.rst          |  9 ++
 2 files changed, 102 insertions(+)
 create mode 100644 doc/admin-guide/source/baremetal-multitenancy.rst

diff --git a/doc/admin-guide/source/baremetal-multitenancy.rst b/doc/admin-guide/source/baremetal-multitenancy.rst
new file mode 100644
index 0000000000..ab8d75f995
--- /dev/null
+++ b/doc/admin-guide/source/baremetal-multitenancy.rst
@@ -0,0 +1,93 @@
+.. _baremetal_multitenancy:
+
+========================================
+Use multitenancy with Bare Metal service
+========================================
+
+Multitenancy allows creating a dedicated tenant network that extends the
+current Bare Metal (ironic) service capabilities of providing ``flat``
+networks. Multitenancy works in conjunction with Networking (neutron)
+service to allow provisioning of a bare metal server onto the tenant network.
+Therefore, multiple tenants can get isolated instances after deployment.
+
+Bare Metal service provides the ``local_link_connection`` information to the
+Networking service ML2 driver. The ML2 driver uses that information to plug the
+specified port to the tenant network.
+
+.. list-table:: ``local_link_connection`` fields
+   :header-rows: 1
+
+   * - Field
+     - Description
+   * - ``switch_id``
+     - Required. Identifies a switch and can be an LLDP-based MAC address or
+       an OpenFlow-based ``datapath_id``.
+   * - ``port_id``
+     - Required. Port ID on the switch, for example, Gig0/1.
+   * - ``switch_info``
+     - Optional. Used to distinguish different switch models or other
+       vendor specific-identifier.
+
+Configure Networking service ML2 driver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To enable the Networking service ML2 driver, edit the
+``/etc/neutron/plugins/ml2/ml2_conf.ini`` file:
+
+#. Add the name of your ML2 driver.
+#. Add the vendor ML2 plugin configuration options.
+
+.. code-block:: ini
+
+   [ml2]
+   ...
+   mechanism_drivers = my_mechanism_driver
+
+   [my_vendor]
+   param_1 = ...
+   param_2 = ...
+   param_3 = ...
+
+For more details, see
+`Networking service mechanism drivers <http://docs.openstack.org/mitaka/networking-guide/config-ml2-plug-in.html#mechanism-drivers>`__.
+
+Configure Bare Metal service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After you configure the Networking service ML2 driver, configure Bare Metal
+service:
+
+#. Edit the ``/etc/ironic/ironic.conf`` for the ``ironic-conductor`` service.
+   Set the ``network_interface`` node field to a valid network driver that is
+   used to switch, clean, and provision networks.
+
+   .. code-block:: ini
+
+      [DEFAULT]
+      ...
+      enabled_network_interfaces=flat,neutron
+
+      [neutron]
+      ...
+      cleaning_network_uuid=$UUID
+      provisioning_network_uuid=$UUID
+
+   .. warning:: The ``cleaning_network_uuid`` and ``privisioning_network_uuid``
+    parameters are required for the ``neutron`` network interface. If they are
+    not set, ``ironic-conductor`` fails to start.
+
+#. Set ``neutron`` to use Networking service ML2 driver:
+
+   .. code-block:: console
+
+      $ ironic node-create -n $NAME --network-interface neutron --driver agent_ipmitool
+
+#. Create a port with appropriate ``local_link_connection`` information. Set
+   the ``pxe_enabled`` port attribute to ``True`` to create network ports for
+   for the ``pxe_enabled`` ports only:
+
+   .. code-block:: console
+
+      $ ironic --ironic-api-version latest port-create -a $HW_MAC_ADDRESS \
+        -n $NODE_UUID -l switch_id=$SWITCH_MAC_ADDRESS \
+        -l switch_info=$SWITCH_HOSTNAME -l port_id=$SWITCH_PORT --pxe-enabled true
diff --git a/doc/admin-guide/source/baremetal.rst b/doc/admin-guide/source/baremetal.rst
index c9c2e4f7e9..c7b4c910e5 100644
--- a/doc/admin-guide/source/baremetal.rst
+++ b/doc/admin-guide/source/baremetal.rst
@@ -84,6 +84,15 @@ Use Bare Metal
 
 .. TODO Add the detail command line later on.
 
+Use multitenancy with Bare Metal service
+----------------------------------------
+
+.. toctree::
+
+    baremetal-multitenancy.rst
+
+.. TODO Add guides for other features.
+
 Troubleshooting
 ~~~~~~~~~~~~~~~