[docs] Further edits in DVS User Guide 3.0.0

This patch:

- addresses comments from https://review.openstack.org/333346
- improves the wording in the existing guide.

Link for PDF build:
https://drive.google.com/a/mirantis.com/file/d/0B2pEhXPCoNIIV29oZXN6Ql9KU28/view
Change-Id: I2a92cf199cb05477b587d3a8623f210186845830

docs/user_guide/appendix.rst

@@ -1,7 +1,7 @@
 .. _links:
 
 Useful links
-============
+------------
 
 For more information about Fuel VMware DVS plugin described in this document,
 see:

docs/user_guide/config.rst

@@ -1,14 +1,14 @@
 .. _configure_env:
 
 Configure an environment with VMware DVS plugin
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------------
 
 Configuring and deploying an environment with VMware DVS plugin involves
 creating an environment in Fuel and modifying the environment settings.
 
 **To configure an OpenStack environment with VMware DVS plugin:**
 
-#. Using Fuel Web UI, follow steps 1-5 of the `Create a new OpenStack
+#. Using the Fuel web UI, follow steps 1 to 5 of the `Create a new OpenStack
    environment <http://docs.openstack.org/developer/fuel-docs/userdocs/fuel-user-guide/create-environment/start-create-env.html>`_
    instruction.
 
@@ -31,14 +31,14 @@ creating an environment in Fuel and modifying the environment settings.
    environment <http://docs.openstack.org/developer/fuel-docs/userdocs/fuel-user-guide/create-environment/start-create-env.html>`_
    instruction.
 
-#. In the :guilabel:`Nodes` tab of the Fuel Web UI, `add
+#. In the :guilabel:`Nodes` tab of the Fuel web UI, `add
    <http://docs.openstack.org/developer/fuel-docs/userdocs/fuel-user-guide/configure-environment/add-nodes.html>`_
-   at least 1 :guilabel:`Controller` node to the environment:
+   at least one :guilabel:`Controller` node to the environment:
 
    .. figure:: _static/nodes-controller.png
       :width: 90%
 
-   (Optional) You can also add 1 dedicated :guilabel:`Compute VMware` node:
+   (Optional) You can also add one dedicated :guilabel:`Compute VMware` node:
 
    .. figure:: _static/nodes-vmware.png
       :width: 90%
@@ -55,12 +55,12 @@ creating an environment in Fuel and modifying the environment settings.
       :guilabel:`Use the VMware DVS firewall driver`.
 
    .. figure:: _static/settings.png
-      :width: 100%
+      :width: 90%
 
    .. caution::
-      VMware DVS ML2 plugin does not support the Distributed Virtual Routers
+      The VMware DVS ML2 plugin does not support the Distributed Virtual
-      (DVR) feature. Therefore, do not select :guilabel:`Neutron DVR` in
+      Routers (DVR) feature. Therefore, do not select :guilabel:`Neutron DVR`
-      :menuselection:`Neutron L3 Configuration -> Neutron Advanced Configuration`.
+      in :menuselection:`Neutron L3 Configuration -> Neutron Advanced Configuration`.
 
 .. raw:: latex
 
@@ -71,9 +71,7 @@ creating an environment in Fuel and modifying the environment settings.
    .. figure:: _static/vmware.png
       :width: 90%
 
-#. Make additional configuration adjustments as described in the
+#. Make additional `configuration adjustments <http://docs.openstack.org/developer/fuel-docs/userdocs/fuel-user-guide/configure-environment.html>`_.
-   `Configure your environment <http://docs.openstack.org/developer/fuel-docs/userdocs/fuel-user-guide/configure-environment.html>`_
-   section of Fuel User Guide.
 
 #. Proceed to the `environment deployment <http://docs.openstack.org/developer/fuel-docs/userdocs/fuel-user-guide/deploy-environment.html>`_.
 

docs/user_guide/definitions.rst

@@ -1,7 +1,7 @@
 .. _definitions:
 
 Key terms
-~~~~~~~~~
+---------
 
 The table below lists the key terms, acronyms, and abbreviations that are used
 in this document.

docs/user_guide/install.rst

@@ -1,5 +1,5 @@
 Install VMware DVS plugin
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
 
 Before you proceed with the VMware DVS plugin installation, verify that:
 
@@ -8,7 +8,7 @@ Before you proceed with the VMware DVS plugin installation, verify that:
 #. All the nodes of your future environment are :guilabel:`DISCOVERED` on the
    Fuel Master node.
 
-#. You have a connectivity to correctly configured vCenter with VDSes and
+#. You have connectivity to correctly configured vCenter with VDSes and
    clusters created.
 
 **To install the VMware DVS plugin:**
@@ -22,7 +22,7 @@ Before you proceed with the VMware DVS plugin installation, verify that:
 
      $ scp fuel-plugin-vmware-dvs-3.0-3.0.0-1.noarch.rpm <Fuel Master node ip>:/tmp
 
-#. Log into the Fuel Master node CLI as root.
+#. Log in to the Fuel Master node CLI as root.
 
 #. Install the plugin:
 

docs/user_guide/intro.rst

@@ -1,5 +1,5 @@
 Introduction
-~~~~~~~~~~~~
+------------
 
 The purpose of this document is to describe how to install, configure,
 and use the VMware DVS plugin 3.0.0 for Fuel 9.0.
@@ -10,12 +10,12 @@ Neutron ML2 plugin allows using Neutron for networking in such environments.
 Therefore, you get the following advanced network features for your
 environment:
 
-- Create multi-tier networks (for example: web tier, database tier,
+- Create multi-tier networks (for example, web tier, database tier,
   application tier)
 
-- Control over IP addressing and security groups' rules.
+- Control over IP addressing and security groups' rules
 
-- Add and configure custom services (for example: firewall,
+- Add and configure custom services (for example, firewall,
   intrusion-prevention system)
 
-- VPN/Bridge to a remote physical hosting or customer premises.
+- Use VPN/bridge to a remote physical hosting or customer premises

docs/user_guide/license.rst

@@ -1,5 +1,5 @@
 Licenses
-~~~~~~~~
+--------
 
 ================= ============
 **Component**     **License**

docs/user_guide/limitations.rst

@@ -1,15 +1,12 @@
 Limitations
-~~~~~~~~~~~
+-----------
 
 The VMware DVS plugin 3.0.0 for Fuel has the following limitations:
 
-* The plugin is enabled only in environments with Neutron as the
+* The plugin is enabled only on environments with Neutron as the
   networking option.
 * Only VLANs are supported for the tenant network separation.
 * Only vSphere versions 5.5 and 6.0 are supported.
-* There is no IPv6 support.
+* IPv6 is not supported.
-* Each vSphere Cluster shoud be connected with individual (one and only one) VDS.
+* Neutron Distributed Virtual Routers (DVR) feature is not supported.
-
+* Each vSphere cluster should be connected to one (and only one) VDS.
-.. raw:: latex
-
-   \pagebreak

docs/user_guide/prerequisites.rst

@@ -1,16 +1,16 @@
 .. _prereqs:
 
 Prerequisites
-~~~~~~~~~~~~~
+-------------
 
-Before you install and start using VMware DVS plugin on Fuel, complete the
+Before you install and start using the VMware DVS plugin on Fuel, complete the
 following steps:
 
 #. Install and set up
    `Fuel 9.0 <http://docs.openstack.org/developer/fuel-docs/userdocs/fuel-install-guide.html>`__.
 
-#. Read the *Plan the vSphere integration* section in
+#. Plan the vSphere integration. For details, see
-   `Mirantis OpenStack Planning Guide <https://docs.mirantis.com/openstack/fuel/fuel-8.0/mos-planning-guide.html#plan-the-vsphere-integration>`_.
+   `Mirantis OpenStack Planning Guide <https://docs.mirantis.com/openstack/fuel/fuel-9.0/mos-planning-guide.html#plan-the-vsphere-integration>`_.
 
    .. seealso::
     * `VMware vSphere 5.5 official documentation <http://pubs.vmware.com/vsphere-55/index.jsp>`_
@@ -34,15 +34,16 @@ following steps:
           * dvPort group.Modify
           * dvPort group.Policy operation
 
-   It allows the VMware DVS plugin to use manipulation resources of VMware
+   This allows the VMware DVS plugin to use manipulation resources of VMware
    vSphere Distributed Switch (VDS).
 
-#. Create and properly configure VDSes on vCenter that will be used in
+#. Create and properly configure VDSes on vCenter that will be used for
    your environment. For details, see the VDS videos in the
    :menuselection:`Technical Details -> Resources` section on the
-   `VMware Distributed Switch page <https://www.vmware.com/products/vsphere/features/distributed-switch>`__.
+   `VMware Distributed Switch <https://www.vmware.com/products/vsphere/features/distributed-switch>`__
+   page.
 
-#. Connect the VMware DVS plugin to the precreated and configured VDSes.
+#. Connect the VMware DVS plugin to the pre-created and configured VDSes.
 
    .. note::
     The VMware DVS plugin does not create new VDSes but uses the existing ones.

docs/user_guide/release_notes.rst

@@ -1,7 +1,7 @@
 Release notes
-~~~~~~~~~~~~~
+-------------
 
-VMware DVS plugin 3.0.0 contains the following updates:
+The VMware DVS plugin 3.0.0 contains the following updates:
 
 * Added a new consistent engine for remote security groups.
 
@@ -11,7 +11,3 @@ VMware DVS plugin 3.0.0 contains the following updates:
 * Improved the VMware DVS plugin overall performance.
 
 * Improved the VMware DVS plugin documentation.
-
-.. raw:: latex
-
-   \pagebreak

docs/user_guide/requirements.rst

@@ -1,11 +1,7 @@
 Requirements
-~~~~~~~~~~~~
+------------
 
 The VMware DVS plugin 3.0.0 for Fuel has the following requirements:
 
 * Fuel 9.0 on Mitaka
 * vCenter 5.5/6.0
-
-.. raw:: latex
-
-   \pagebreak

docs/user_guide/troubleshooting.rst

@@ -1,13 +1,20 @@
 Troubleshooting
-~~~~~~~~~~~~~~~
+---------------
 
-VMware DVS driver consists of two parts: the mechanism driver of Neutron and
+This section contains a guidance on how to ensure that the VMware DVS plugin
-the VMware DVS agent. Therefore, two main sources of information for
+is up and running on your deployed environment.
-troubleshooting are ``/var/log/neutron/server.log`` and
+
-``/var/log/neutron/vmware-dvs-agent-....log``.
+**To find logs**
+
+The VMware DVS driver consists of two parts: the mechanism driver of Neutron
+and the VMware DVS agent. Therefore, two main sources of information for
+troubleshooting are:
+
+* ``/var/log/neutron/server.log``
+* ``/var/log/neutron/vmware-dvs-agent-....log``
+
+**To verify Neutron configuration files**
 
-**To verify Neutron configuration files:**
- 
 To deliver a stable performance of the VMware DVS plugin, verify that the
 Neutron configuration files contain the following values:
 
@@ -45,11 +52,15 @@ Neutron configuration files contain the following values:
    vsphere_hostname=<vsphere_ip>
    vsphere_password=<vsphere_password>
 
-Verify that all neutron-dvs-agent services are launched on corresponding nodes:
+**To verify neutron-dvs-agent services**
 
-* On controllers: under corosync
+All neutron-dvs-agent services should run on the corresponding nodes:
-* On compute-vmware: using the init script
 
-Verify the connectivity between controller nodes and vCenter:
+* On controllers: ``p_neutron_plugin_vmware_dvs_agent_${host}`` in Corosync
+* On compute-vmware: ``neutron-plugin-vmware-dvs-agent-${host}`` in the init
+  script
 
-.. TODO: add CLI command
+**To verify connectivity**
+
+Check the connectivity between controller nodes and vCenter using the
+:command:`ping` command.

docs/user_guide/using_neutron.rst

@@ -2,9 +2,9 @@ Using advanced Neutron possibilities with VMware DVS plugin
 -----------------------------------------------------------
 
 Once you deploy an OpenStack environment with VMware DVS plugin, you can
-start using Neutron for networking. When neutron creates a new network it
+start using Neutron for networking. When Neutron creates a new network, it
-doesn't affect any VDS until a port in that network would attached to VM, that
+does not affect any VDS until a port in that network is attached to a VM
-launched on a corresponding Cluster.
+launched on a corresponding environment.
 
 **DVS security groups**
 
@@ -44,12 +44,13 @@ Example of a common egress TCP rule:
 
 * TCP egress to any ports 0.0.0.0/0 CIDR
 
-It works in the following way:
+It works as follows:
 
 * TCP egress from any IP ports 32768-65535 to any IP any port
 * TCP ingress from any IP any port to any IP ports 32768-65535
 
-Once applied, the private ports of your VM like HTTP or SSH will be closed.
+Once applied, the private ports of your VM, such as HTTP or SSH, will be
+closed.
 
 The VMWare DVS plugin supports only symmetric ICMP interaction. If your host
 can ping a destination host, it means that the destination host can ping your
@@ -58,3 +59,4 @@ host by reverse rules.
 .. raw:: latex
 
    \pagebreak
+

docs/user_guide/verification.rst

@@ -1,5 +1,22 @@
-Verification
+Verify a deployed environment with VMware DVS plugin
-++++++++++++
+----------------------------------------------------
 
-After deployment of an environment with VMware DVS plugin all corresponding
+After you deploy an environment with VMware DVS plugin, complete the
-OSTF tests should pass.
+following verification steps:
+
+#. Log in to a controller node.
+#. Verify whether the DVS agent is available in the list of Neutron agents:
+
+   .. code-block:: console
+
+    $ neutron agent-list
+    +----+-----------+-----------+-----------------+------+---------------+-----------------+
+    |id  |agent_type |host       |availability_zone|alive |admin_state_up |binary           |
+    +----+-----------+-----------+-----------------+----------------------+-----------------+
+    |... |DVS agent  |vcenter-sn2|                 |:-)   |True           |neutron-dvs-agent|
+    +----+-----------+-----------+-----------------+------+---------------+-----------------+
+
+#. Log in to the Fuel web UI.
+#. Click the :guilabel:`Health Check` tab.
+#. Run necessary health tests. For details, see:
+   `Verify your OpenStack environment <http://docs.openstack.org/developer/fuel-docs/userdocs/fuel-user-guide/verify-environment.html>`_.