Update multi-tenancy documentation

This updates the multi-tenancy documentation. The changes include:
- use the service name (e.g. the Bare Metal service) instead of the
  project name (e.g. ironic)
- fix some grammatical issues
- refer to the ironic conductor as 'ironic-conductor' instead of 'conductor'
- remove note about setting enabled_network_interfaces config option in
  ironic-api's config file; that is no longer needed since the checks
  have been moved to the conductor side (when node creation was moved).

Change-Id: Ic4b1512672c16c1bff5b43595abd90190e23b0fe

doc/source/deploy/multitenancy.rst

@@ -1,8 +1,8 @@
 .. _multitenancy:
 
-==================================
+=======================================
-Multitenancy in Bare Metal service
+Multi-tenancy in the Bare Metal service
-==================================
+=======================================
 
 Overview
 ========
@@ -14,8 +14,8 @@ nodes in a separate provisioning network. The result of this is that multiple
 tenants can use nodes in an isolated fashion. However, this configuration does
 not support trunk ports belonging to multiple networks.
 
-Network interface is one of the driver interfaces, that manages network
+Network interface is one of the driver interfaces that manages network
-switching for nodes. Currently there are 3 network interfaces available in
+switching for nodes. There are 3 network interfaces available in
 the Bare Metal service:
 
 - ``noop`` interface is used for standalone deployments, and does not perform
@@ -25,58 +25,55 @@ the Bare Metal service:
   a single layer 2 network, separated from the cleaning network;
 
 - ``neutron`` interface provides tenant-defined networking by integrating with
-  neutron, while also separating tenant networks from the provisioning and
+  the Networking service, while also separating tenant networks from the
-  cleaning provider networks.
+  provisioning and cleaning provider networks.
 
-Configuring Ironic
+Configuring the Bare Metal service
-==================
+==================================
 
-Below is an example flow of how to setup ironic so that node provisioning will
+Below is an example flow of how to set up the Bare Metal service so that node
-happen in a multitenant environment (which means using ``neutron`` network
+provisioning will happen in a multi-tenant environment (which means using
-interface as stated above):
+``neutron`` network interface as stated above):
 
-#. Network interfaces can be enabled on ironic-conductor by adding them to
+#. Network interfaces can be enabled on ironic-conductor by adding them to the
-   ``enabled_network_interfaces`` configuration option under the default
+   ``enabled_network_interfaces`` configuration option under the ``default``
-   section::
+   section of the configuration file::
 
     [DEFAULT]
     ...
     enabled_network_interfaces=noop,flat,neutron
 
-   Please note that ``enabled_network_interfaces`` has to be set in the
+   Keep in mind that, ideally, all ironic-conductors should have the same list
-   ironic-api configuration file too, as its value is used on the API side to
+   of enabled network interfaces, but it may not be the case during
-   check if the requested network interface is available.
+   ironic-conductor upgrades. This may cause problems if one of the
+   ironic-conductors dies and some node that is taken over is mapped to an
+   ironic-conductor that does not support the node's network interface.
+   Any actions that involve calling the node's driver will fail until that
+   network interface is installed and enabled on that ironic-conductor.
 
-   Keep in mind that, ideally, all conductors should have the same list of
+#. It is recommended to set the default network interface via the
-   enabled network interfaces, but it may not be the case during conductor
+   ``default_network_interface`` configuration option under the ``default``
-   upgrades. This may cause problems if one of the conductors dies and some
+   section of the configuration file::
-   node that is taken over is mapped to a conductor that does not support the
-   node's network interface. Any actions that involve calling the node's driver
-   will fail until that network interface is installed and enabled on that
-   conductor.
-
-#. It is recommended to set the default network interface via
-   ``default_network_interface`` configuration option under the default
-   section::
 
     [DEFAULT]
     ...
     default_network_interface=neutron
 
-   It will be used for all nodes that will be created without explicitly
+   This default value will be used for all nodes that don't have a network
-   specifying the network interface.
+   interface explicitly specified in the creation request.
 
-   If it is not set, the default network interface is determined by looking at
+   If this configuration option is not set, the default network interface is
-   the ``[dhcp]dhcp_provider`` configuration option value. If it is
+   determined by looking at the ``[dhcp]dhcp_provider`` configuration option
-   ``neutron`` - ``flat`` network interface becomes the default, otherwise
+   value. If it is ``neutron``, then ``flat`` network interface becomes the
-   ``noop`` is the default.
+   default, otherwise ``noop`` is the default.
 
-#. Define a provider network in neutron, which we shall refer to as the
+#. Define a provider network in the Networking service, which we shall refer to
-   "provisioning" network, and add it in under the neutron section in
+   as the "provisioning" network, and add it in the ``neutron`` section of
-   ironic-conductor configuration file. Using ``neutron`` network interface
+   the ironic-conductor configuration file. Using ``neutron`` network interface
    requires that ``provisioning_network`` and ``cleaning_network``
-   configuration options are set to a valid neutron network UUIDs or names,
+   configuration options are set to valid Networking service's network
-   otherwise cleaning or provisioning will fail to start::
+   identifiers (UUID or name); otherwise cleaning or provisioning will fail to
+   start::
 
     [neutron]
     ...
@@ -87,53 +84,54 @@ interface as stated above):
    information about cleaning.
 
    .. warning::
-      Please make sure ironic is exclusive to the provisioning and cleaning
+      Please make sure that the Bare Metal service has exclusive access to the
-      network. Spawning instances by non-admin users in these networks and
+      provisioning and cleaning networks. Spawning instances by non-admin users
-      getting access to ironic control plane is a security risk. For this
+      in these networks and getting access to the Bare Metal service's control
-      reason, the provisioning and cleaning network should be configured as
+      plane is a security risk. For this reason, the provisioning and cleaning
-      non-shared network in the admin tenant.
+      networks should be configured as non-shared networks in the ``admin``
+      tenant.
 
    .. note::
       Spawning a bare metal instance onto the provisioning network is
       impossible, the deployment will fail. The node should be deployed onto a
       different network than the provisioning network. When you boot a bare
-      metal instance from nova, you should choose a different network in
+      metal instance from the Compute service, you should choose a different
-      neutron for your instance.
+      network in the Networking service for your instance.
 
    .. note::
-      The "provisioning" and "cleaning" networks may be the same neutron
+      The "provisioning" and "cleaning" networks may be the same network or
-      provider network, or may be distinct networks. To ensure communication
+      distinct networks. To ensure that communication between the Bare Metal
-      between ironic and the deploy ramdisk works, it's important to ensure
+      service and the deploy ramdisk works, it is important to ensure that
-      that security groups are disabled for these networks, *or* the default
+      security groups are disabled for these networks, *or* that the default
       security groups allow:
 
       * DHCP
       * TFTP
-      * egress port used for ironic (6385 by default)
+      * egress port used for the Bare Metal service (6385 by default)
       * ingress port used for ironic-python-agent (9999 by default)
       * if using the iSCSI deploy method (``pxe_*`` and ``iscsi_*`` drivers),
         the ingress port used for iSCSI (3260 by default)
       * if using the direct deploy method (``agent_*`` drivers), the egress
-        port used for swift (typically 80 or 443)
+        port used for the Object Storage service (typically 80 or 443)
       * if using iPXE, the egress port used for the HTTP server running
-        on the ironic conductor nodes (typically 80).
+        on the ironic-conductor nodes (typically 80).
 
 
 #. This step is optional and applicable only if you want to use security
    groups during provisioning and/or cleaning of the nodes. If not specified,
    default security groups are used.
 
-   First define security groups in neutron to be used for provisioning
+   First define security groups in the Networking service, to be used for
-   and/or cleaning networks. Then add the list of these security group
+   provisioning and/or cleaning networks. Then add the list of these security
-   UUIDs under the neutron section in ironic-conductor configuration file
+   group UUIDs under the ``neutron`` section of ironic-conductor's
-   as shown below::
+   configuration file as shown below::
 
     [neutron]
     ...
     cleaning_network=$CLEAN_UUID_OR_NAME
-    cleaning_network_security_groups=[$LIST_OF_CLEAN_SEC_GROUPS]
+    cleaning_network_security_groups=[$LIST_OF_CLEAN_SECURITY_GROUPS]
     provisioning_network=$PROVISION_UUID_OR_NAME
-    provisioning_network_security_groups=[$LIST_OF_PROVISION_SEC_GROUPS]
+    provisioning_network_security_groups=[$LIST_OF_PROVISION_SECURITY_GROUPS]
 
    Multiple security groups may be applied to a given network, hence,
    they are specified as a list.
@@ -143,10 +141,10 @@ interface as stated above):
    .. warning::
        If security groups are configured as described above, do not
        set the "port_security_enabled" flag to False for the corresponding
-       neutron network or port. This will cause the deploy to fail.
+       Networking service's network or port. This will cause the deploy to fail.
 
-       For example: if provisioning_network_security_groups configuration
+       For example: if ``provisioning_network_security_groups`` configuration
-       option is used, ensure that "port_security_enabled" flag for
+       option is used, ensure that "port_security_enabled" flag for the
        provisioning network is set to True. This flag is set to True by
        default; make sure not to override it by manually setting it to False.
 
@@ -155,7 +153,8 @@ interface as stated above):
    <http://docs.openstack.org/networking-guide/config-ml2.html>`_
    for details.
 
-#. Restart the ironic conductor and API services after the modifications:
+#. Restart the ironic-conductor and ironic-api services after the
+   modifications:
 
    - Fedora/RHEL7/CentOS7::
 
@@ -167,8 +166,8 @@ interface as stated above):
       sudo service ironic-api restart
       sudo service ironic-conductor restart
 
-#. Make sure that the conductor is reachable over the provisioning network
+#. Make sure that the ironic-conductor is reachable over the provisioning
-   by trying to download a file from a TFTP server on it, from some
+   network by trying to download a file from a TFTP server on it, from some
    non-control-plane server in that network::
 
     tftp $TFTP_IP -c get $FILENAME
@@ -178,7 +177,7 @@ interface as stated above):
 Configuring nodes
 =================
 
-#. Multitenancy support was added in the 1.20 API version. The following
+#. Multi-tenancy support was added in the 1.20 API version. The following
    examples assume you are using python-ironicclient version 1.5.0 or higher.
    They show the usage of both ``ironic`` and ``openstack baremetal`` commands.
 
@@ -192,10 +191,11 @@ Configuring nodes
 
     export OS_BAREMETAL_API_VERSION=1.20
 
-#. Node's ``network_interface`` field should be set to valid network interface
+#. The node's ``network_interface`` field should be set to a valid network
-   that is listed in the ``[DEFAULT]/enabled_network_interfaces`` configuration
+   interface. Valid interfaces are listed in the
-   option in the ironic-api config. Set it to ``neutron`` to use neutron ML2
+   ``[DEFAULT]/enabled_network_interfaces`` configuration option in the
-   driver:
+   ironic-conductor's configuration file. Set it to ``neutron`` to use the
+   Networking service's ML2 driver:
 
    - ``ironic`` command::
 
@@ -208,11 +208,12 @@ Configuring nodes
       --driver agent-ipmitool
 
    .. note::
-      If the ``[DEFAULT]/default_network_interface`` configuration option was
+      If the ``[DEFAULT]/default_network_interface`` configuration option is
       set, the ``--network-interface`` option does not need to be specified
-      when defining the node.
+      when creating the node.
 
-#. To update existing node's network interface, use the following commands:
+#. To update an existing node's network interface to ``neutron``, use the
+   following commands:
 
    - ``ironic`` command::
 
@@ -224,7 +225,7 @@ Configuring nodes
       --network-interface neutron
 
 #. The Bare Metal service provides the ``local_link_connection`` information to
-   the Networking service ML2 driver. The ML2 driver uses that information to
+   the Networking service's ML2 driver. The ML2 driver uses that information to
    plug the specified port to the tenant network.
 
    .. list-table:: ``local_link_connection`` fields
@@ -239,7 +240,7 @@ Configuring nodes
         - Required. Port ID on the switch, for example, Gig0/1.
       * - ``switch_info``
         - Optional. Used to distinguish different switch models or other
-          vendor specific-identifier. Some ML2 plugins may require this
+          vendor-specific identifier. Some ML2 plugins may require this
           field.
 
    Create a port as follows: