Enhancements to the vCenter docs

Pre-install/7000-vcenter-plan -- add link to vCenter installation docs and
summarize the requisite steps, with screen shots.

Ref-arch/logical-setup/7000-vcenter -- corrected info about vCenter driver
for OpenStack. Added reference architecture and network topology diagrams

User-guide/vcenter.rst -- Added complete descriptions with screen shots

General: left-justified all screen shots to match the rest of the guide
and to avoid a tools bug that is sometimes doing odd things with graphics
for which :align" is specified.

relnotes/050-known-issues -- added LP to vCenter HA limitation

Closes-Bug: 1325690

Change-Id: I1ff4369a8ab03ff91f3e3c9cdebfde8a60d56808
(cherry picked from commit 5744c62ca6)

contents/contents-refarch.rst

@@ -5,6 +5,7 @@
 .. include:: /pages/reference-architecture/1000-logical-setup.rst
 .. include:: /pages/reference-architecture/1100-ha-notes.rst
 .. include:: /pages/reference-architecture/1200-mysql-galera.rst
+.. include:: /pages/reference-architecture/7000-vcenter.rst
 .. include:: /pages/reference-architecture/1700-ceph.rst
 .. include:: /pages/reference-architecture/0045-storage.rst
 .. include:: /pages/reference-architecture/6000-network-architecture.rst

pages/pre-install-guide/7000-vcenter-plan.rst

@@ -1,82 +1,118 @@
 
 .. _vcenter-plan:
 
-Preparing for vCenter Integration
+Preparing for vSphere Integration
 =================================
+Fuel 5.0 and later can deploy a Mirantis OpenStack environment
+that boots and manages virtual machines in VMware vSphere.
+VMware provides a vCenter driver for OpenStack
+that enables the Nova-compute service to
+communicate with a VMware vCenter server
+that manages one or more ESX host clusters.
+The vCenter driver makes management convenient
+from both the OpenStack Dashboard (:ref:`horizon-term`)
+and from vCenter,
+where advanced vSphere features can be accessed.
 
 This section summarizes the planning you should do
 and other steps that are required
 before you attempt to deploy Mirantis OpenStack
 with vCenter intergration.
 
-Note the following requirements for your OpenStack environment:
+For more information:
 
-- The network must use the :ref:`nova-network-term` networking topology.
+- See :ref:`vcenter-arch` for information about how vCenter support
+  is implemented in Mirantis OpenStack;
 
-The following tasks are required:
+- :ref:`vcenter-deploy` gives instructions for creating and deploying
+  a Mirantis OpenStack environment that is integrated with VMware vSphere.
 
-- Deploy VMware vCenter as discussed in
-  `vSphere Installation and Setup <http://pubs.vmware.com/vsphere-50/topic/com.vmware.ICbase/PDF/vsphere-esxi-vcenter-server-50-installation-setup-guide.pdf>`_.
+- For background information about VMware vSphere support in OpenStack,
+  see the `VMware vSphere - OpenStack Manuals
+  <http://docs.openstack.org/trunk/config-reference/content/vmware.html>`_.
 
-- Configure the appropriate network devices on the Fuel Master node:
+- The official vSphere installation guide can be found here:
+  `vSphere Installation and Setup
+  <http://pubs.vmware.com/vsphere-55/index.jsp#com.vmware.vsphere.install.doc/GUID-7C9A1E23-7FCD-4295-9CB1-C932F2423C63.html>`_.
 
-  - A `vlance` (old AMD) network card is recommended;
-    these work with all versions of vCenter.
-  - An `e1000` network card works with most enterprise vCenters.
 
-  To determine which network card is configured,
-  open the .VMX file for each virtual machine and 
-  check for one of the following settings:
+vSphere Installation
+--------------------
+Before installing Fuel and using it
+to create a Mirantis OpenStack environment
+that is integrated with VMware vSphere,
+the vSphere installation must be up and running.
+Please check that you completed the following steps:
 
-::
+* Install vSphere
+* Install vCenter
+* Install ESXi
+* Configure vCenter
 
-    ethernetXXX.virtualDev=`vlance`
-    or
-    ethernetXXX.virtualDev=`e1000`
+	* Create DataCenter
+	* Create vCenter cluster
+	* Add ESXi host(s)
 
-- Allow promiscuous mode for each network card.
-  The following string should appear in the .VMX file:
+.. raw:: pdf
 
-::
+   PageBreak
 
-    ethernetXXX.noPromisc = "false"
+ESXi Host Networks Configuration
+--------------------------------
+The ESXi host(s) network must be configured appropriately
+in order to enable intergration of Mirantis OpenStack with vCenter.
+Follow the steps below:
 
-- PXE boot must not be turned off for any card that uses the vCenter driver;
-  the following string in the VMX file is correct:
+1. Open the ESXi host page,
+   select the "Manage" tab and click on "Networking".
+   vSwitch0 and all its networks are shown.
+   Click the Add Network button:
 
-::
+.. image:: /_images/esx-manage-networks.png
+  :width: 70%
 
-  vlance.noOprom = "false"
+2. In the "Add Networking" wizard, select the Virtual Machine Port group:
 
-- If you use ESXi/vSphere with vSwitch as the networking solution:
+.. image:: /_images/esx-target-device.png
+  :width: 70%
 
-  - Create a separate port group or separate vSwitch instance
-    with the port group for each virtual network.
+.. raw: pdf
 
-  - Allow promiscuous mode for each port group.
+   PageBreak
 
-  Note that some multicast/broadcast traffic
-  does not go outside the port group,
-  so always use port groups for Neutron.
+3. On the next page, select the "Virtual Machine Port Group" option
+   to ensure that the network will be created in vSwitch0:
 
-vSwitch does not support native VLAN for Trunk ports
-and removes all VLAN tags from traffic
-that goes through Access ports.
-Therefore, you cannot mix VLAN tagged and untagged traffic;
-you must create different port groups for Trunk and Access ports.
+.. image:: /_images/esx-connection-type.png
+  :width: 70%
 
-VMware vCenter can be deployed on Mirantis OpenStack
-with or without high-availability (HA) configured.
-Note, however, that the vCenter Nova plugin runs on only one 
-Controller node, even if that Controller node is replicated 
-to provide HA.
+4. Always name the network **br100**;
+   this is the only value that works with Fuel;
+   type a VLAN Tag in the VLAN ID field;
+   (the value must be equal to the VLAN Tag at *VM Fixed*
+   on Fuel’s :ref:`network-settings-vcenter-ug` tab):
+
+.. image:: /_images/esx-connection-settings.png
+  :width: 70%
+  
+Limitations
+------------------------------
+- Only :ref:`nova-network-term` with flatDHCP mode is supported
+  in the current version of the integration.
+- OpenStack Block Storage service (Cinder)
+  with VMware VMDK datastore driver is not supported;
+  you can only use Cinder with the LVM over iSCSI option
+  as the Cinder backend.
+- Each OpenStack environment can support one vCenter cluster.
+- VMware vCenter can be deployed on Mirantis OpenStack
+  with or without high-availability (HA) configured.
+  Note, however, that the vCenter Nova plugin
+  runs on only one Controller node,
+  even if that Controller node is replicated to provide HA.
+  See `LP1312653 <https://bugs.launchpad.net/fuel/+bug/1312653>`_.
 
 For background information about how vCenter support
 is integrated into Mirantis OpenStack, see :ref:`vcenter-arch`.
 
 Follow the instructions in :ref:`vcenter-deploy`
-to deploy your Mirantis OpenStack environment
-with vCenter support.
-
-The following blog post contains useful suggestions
-`Deploying OpenStack on vSphere with Fuel <http://vbyron.com/blog/deploy-openstack-on-vsphere-with-fuel/>`_.
+to deploy your Mirantis OpenStack environment with vCenter support.

pages/reference-architecture/1000-logical-setup.rst

@@ -3,4 +3,3 @@
 .. include:: /pages/reference-architecture/logical-setup/0200-controller-nodes.rst
 .. include:: /pages/reference-architecture/logical-setup/0400-storage-nodes.rst
 .. include:: /pages/reference-architecture/logical-setup/0400-storage-nodes.rst
-.. include:: /pages/reference-architecture/logical-setup/7000-vcenter.rst

pages/reference-architecture/7000-vcenter.rst

@@ -0,0 +1,108 @@
+
+.. _vcenter-arch:
+
+VMware vSphere Integration
+==========================
+
+This section provides technical details about how vCenter support
+is implemented in Mirantis OpenStack.
+
+- See :ref:`vcenter-plan` for information about planning the deployment;
+- :ref:`vcenter-deploy` gives instructions for creating and deploying
+  a Mirantis OpenStack environment that is integrated with VMware vSphere.
+
+VMware provides a vCenter driver for OpenStack.
+This driver enables the Nova-compute service
+to communicate with a VMware vCenter server
+that manages one or more ESX host clusters.
+The vCenter driver makes management convenient
+from both the OpenStack Dashboard (:ref:`horizon-term`)
+and from vCenter,
+where advanced vSphere features can be accessed.
+
+This enables Nova Compute to deploy workloads on vSphere
+and allows vSphere features such as vMotion workload migration,
+vSphere High Availability, and Dynamic Resource Scheduling (DRS).
+DRS is enabled
+by architecting the driver to aggregate ESXi hosts in each clster
+to present one large hypervisor entitiy to the Nova scheduler,
+thus enabling OpenStack to schedule to the granularity of clusters,
+then call vSphere DRS to schedule
+the individual ESXi host within the cluster.
+The vCenter driver also interacts with
+the OpenStack Image Service (Glance)
+to copy VMDK (VMware virtual machine) images
+from the back-end image store to a database cache
+from which they can be quickly retrieved after they are loaded.
+
+The vCenter driver requires the :ref:`nova-network-term` topology,
+which means that :ref:`ovs-term` does not work with vCenter.
+
+The Nova Compute service runs on a Controller node,
+not on a separate Compute node.
+This means that, in the Multi-node Deployment mode,
+a user has a single Controller node
+with both controller and compute services running.
+
+Unlike other hypervisor drivers
+that require the Nova Compute service to be running
+on the same node as the hypervisor itself,
+the vCenter driver enables the Nova Compute service
+to manage ESXi hypervisors remotely.
+This means that you do not need a dedicated Compute node
+to use the vCenter hypervisor;
+instead, Fuel puts the Nova Compute service on a Controller node.
+
+.. raw: pdf
+
+   PageBreak
+
+Multi-node HA Deployment with vSphere integration
+-------------------------------------------------
+
+.. image:: /_images/vcenter-reference-architecture.png
+   :width: 50%
+
+In the Multi-node HA Deployment mode,
+the Nova Compute and Nova Network services run on a Controller node
+that is called the "Primary Controller".
+This is the first node in the Fuel database,
+which usually makes it the top node in the "Nodes" list in the Web UI
+and the node with the lowest ID in Fuel CLI output.
+These services cannot be moved to another Controller node
+if the Primary Controller node goes offline.
+This means that,
+while all the other OpenStack services operate in HA mode,
+the Nova Compute and Nova Network services are not protected from failure.
+See `LP1312653 <https://bugs.launchpad.net/fuel/+bug/1312653>`_.
+
+.. raw: pdf
+
+   PageBreak
+
+Example of network topology
+---------------------------
+
+.. # The link to the image source:
+.. # https://drive.google.com/file/d/0BxrQaxuQOwp3dG85ZXBuN2NiZVU/edit?usp=sharing
+.. image:: /_images/vcenter-network-topology.png
+   :width: 100%
+
+This is an example of the default Fuel OpenStack network configuration
+that a user should have
+if the Slave nodes have at least two NICs
+and are connected to a Fuel Admin (PXE) network with `eth0` interfaces.
+
+The Nova-Network service must serve DHCP requests
+and NAT translations of the VMs' traffic,
+so the VMs on the ESXi nodes
+must be connected directly to the Fixed (Private) network.
+By default, this network uses VLAN 103
+for the Nova-Network Flat DHCP topology.
+So, a user can create a tagged Port Group on the ESXi servers with VLAN 103
+and connect the corresponding `vmnic` NIC to the same switch
+as the OpenStack Controller nodes.
+
+The Nova Compute service must be able to reach
+the vCenter management IP from the OpenStack Public network
+in order to connect to the vSphere API.

pages/reference-architecture/logical-setup/7000-vcenter.rst

@@ -1,25 +1,22 @@
 
 .. _vcenter-arch:
 
-VMware vCenter Integration
+VMware vSphere Integration
 --------------------------
 
 Fuel 5.0 and later can deploy a Mirantis OpenStack environment
-that can boot and manage virtual machines in VMware vCenter.
+that can boot and manage virtual machines in VMware vSphere.
 This section provides technical details about how vCenter support
 is implemented in Mirantis OpenStack.
 See :ref:`vcenter-plan` for information about planning the deployment;
 :ref:`vcenter-deploy` gives instructions for deploying
 a Mirantis OpenStack environment
-that is integrated with VMware vCenter.
+that is integrated with VMware vSphere.
 
 VMware provides a vCenter driver for OpenStack.
-This driver includes a vSphere driver for Nova Compute,
-plus vSphere datastore drivers for :ref:`cinder-term` block storage
-and Glance image storage.
-The vCenter driver enables Nova Compute
-to communicate with a vCenter server
-that manages one or more ESXi host clusters.
+This driver enables the Nova-compute service
+to communicate with a VMware vCenter server
+that manages one or more ESX host clusters.
 The vCenter driver makes management convenient
 from both the OpenStack Dashboard (:ref:`horizon-term`)
 and from vCenter,
@@ -39,16 +36,47 @@ the OpenStack Image Service (Glance)
 to copy VMDK (VMware virtual machine) images
 from the back-end image store to a database cache
 from which they can be quickly retrieved after they are loaded.
-This also enables OpenStack Cinder
-to drive the VMware vSAN filesystem
-and block storage associated with ESXi clusters.
 
 The vCenter driver requires the :ref:`nova-network-term` topology,
 which means that :ref:`ovs-term` does not work with vCenter.
-However, VMware has also created an NSX plug-in for OpenStack Neutron
-that offers best-in-class software-defined networking,
-including features such as security groups,
-that are not supported by Nova-network.
-The NSX plug-in is derived from vCloud networking and security,
-combined with the Nicira Virtualization Platform codebase.
 
+The Nova-compute service is run not on a separete Compute node but on
+a Controller node. This means in the Multi-node Deployment mode a user will
+have a single Controller node with noth controller and compute services running.
+
+Multi-node HA Deployment with vSphere integration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: /_images/vcenter-reference-architecture.png
+   :width: 50%
+
+In the Multi-node HA Deployment mode the Nova-compute and Nova-network services
+are working on one of the Controller nodes, internally called as Primary
+Controller. Usually it's a top node from the nodes list in Web UI, and it's
+a node with the lowest ID in Fuel CLI output. Due to some circumstances there is
+no way now to move these services to another Controller node if the Primary
+Controller node become offline. It means that all the other OpenStack services,
+operates in HA mode, but the Nova-compute and Nova-network services aren't
+protected from failure.
+
+Example of network topology
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. # The link to the image source:
+.. # https://drive.google.com/file/d/0BxrQaxuQOwp3dG85ZXBuN2NiZVU/edit?usp=sharing
+.. image:: /_images/vcenter-network-topology.png
+   :width: 100%
+
+This is an example of the default Fuel OpenStack network configuration which
+a user whould have if Slave nodes have at least two NICs and are connected to
+a Fuel Admin (PXE) network with `eth0` interfaces.
+
+Because the Nova-Network service must serve DHCP requests and NAT translations
+of the VMs' traffic the VMs on the ESXi nodes must be conneted directly to
+the Fixed (Private) network. By default this network uses VLAN 103 in case of
+Nova-Network Flat DHCP mode. So, a user can create a tagged Port Group on
+the ESXi servers with VLAN 103 and connect a corresponded `vmnic` NICs to the
+same switch where the OpenStack Controller nodes are connected to.
+
+The vCenter management IP must be reached from the OpenStack Public network
+by the Nova-compute service in order to connect to the vSphere API.

pages/release-notes/v5-0/050-known-issues.rst

@@ -16,6 +16,7 @@ but it has some known limitations:
   and, if the service or the controller on which the service is deployed fail,
   OpenStack is unable to access the ESXi server resources
   for scheduling the VMs.
+  See `LP1312653 <https://bugs.launchpad.net/fuel/+bug/1312653>`_.
 * When vCenter is selected as the hypervisor,
   all Ceph, Cinder, and Nova options are disabled
   in the storage settings.

pages/user-guide/2000-deploy-new-environment.rst

@@ -162,6 +162,9 @@ The Fuel UI screen appears:
 Click on the "New OpenStack environment" icon
 to launch the wizard that creates a new OpenStack environment.
 
+If you are deploying a Mirantis OpenStack environment
+that is integrated with VMware vSphere,
+follow the instructions in :ref:`vcenter-deploy`.
 
 .. _name-distro-ug:
 

pages/user-guide/vcenter.rst

@@ -4,21 +4,152 @@
 
 .. _vcenter-deploy:
 
-vCenter deployment notes
+vSphere deployment notes
 ========================
 
 .. contents :local:
 
 :ref:`vcenter-plan` discusses actions and decisions
 that should be made before attempting to deploy
-Mirantis OpenStack with vCenter integration.
+Mirantis OpenStack with vSphere integration.
 
-To deploy an OpenStack cloud that is integrated with the vCenter server:
+To deploy an OpenStack cloud that is integrated
+with the vSphere environment,
+click on the "New OpenStack environment" icon
+to launch the wizard that creates a new OpenStack environment.
 
-- Select the vCenter :ref:`hypervisor<hypervisor-ug>`
-  when you create your OpenStack Environment.
-- Specify the credentials used to access the vCenter
-  on the :ref:`vcenter-config-ug` screen.
+.. _vcenter-start-create-env-ug:
+
+Create Environment and Choose Distribution for vCenter
+------------------------------------------------------
+
+Either the CentOS or Ubuntu distro
+can be used as the host operating system on the Slave nodes
+for environments that support integration with vSphere:
+
+.. image:: /_images/user_screen_shots/vcenter-create-env.png
+   :width: 50%
+
+Choose Deployment Mode for vCenter
+----------------------------------
+
+You can deploy Mirantis OpenStack with or without :ref:`ha-term`.
+Note that the vCenter Nova plugin runs only on the primary Controller node,
+even if that Controller node is replicated to provide HA.
+
+.. image:: /_images/user_screen_shots/vcenter-deployment-mode.png
+   :width: 50%
+
+.. raw: pdf
+
+   PageBreak
+
+Select vCenter Hypervisor for vCenter
+-------------------------------------
+
+Select the vCenter :ref:`hypervisor<hypervisor-ug>`
+when you create your OpenStack Environment.
+
+.. image:: /_images/user_screen_shots/vcenter-hv.png
+   :width: 50%
+
+Select Network Service for vCenter
+----------------------------------
+
+Choose the Nova-network FlatDHCP manager on the Network settings page.
+This the only network topology you can use
+to deploy vCenter with Fuel 5.0.
+
+.. image:: /_images/user_screen_shots/vcenter-networking.png
+   :width: 50%
+
+.. raw: pdf
+
+   PageBreak
+
+Choose Backend for Cinder and Glance with vCenter
+-------------------------------------------------
+
+Ceph cannot be used as a Cinder backend;
+you should select the LVM over iSCSI option.
+
+.. image:: /_images/user_screen_shots/vcenter-cinder.png
+   :width: 50%
+
+- If you are using the Multi-node HA mode,
+  Swift is used as a backend for Cinder
+  and is automatically installed on the Controller nodes.
+- If you are using the Multi-node (no HA) mode,
+  local storage is used as the backend for Glance.
+
+Related projects for vCenter
+----------------------------
+
+Nova-network does not support Murano,
+so you cannot run Murano in the OpenStack environment
+with vSphere integration.
+
+.. image:: /_images/user_screen_shots/vcenter-additional.png
+   :width: 50%
+
+.. raw: pdf
+
+   PageBreak
+
+Complete the creation of your vCenter environment
+-------------------------------------------------
+
+
+.. image:: /_images/user_screen_shots/deploy_env.png
+   :width: 50%
+
+
+Select "Create" and click on the icon for your named environment.
+
+Configure your environment
+==========================
+
+After you exit from the "Create a New OpenStack Environment" wizard,
+Fuel displays a set of configuration tabs
+that you use to finish configuring your environment.
+
+Let's focus on the steps specific for OpenStack environments
+integrated with vSphere.
+
+
+Assign a role or roles to each node server
+------------------------------------------
+For VMware vCenter integration.
+Nova plugin runs on the Controller node.
+Compute and Controller roles are combined on one node.
+
+.. image:: /_images/user_screen_shots/vcenter-add-nodes.png
+   :width: 50%
+
+.. _network-settings-vcenter-ug:
+
+Network settings
+----------------
+
+Only the :ref:`nova-network-term` with FlatDHCP topology
+is supported in the current version of vCenter integration in Fuel.
+
+- Select the FlatDHCP manager in the Nova-network settings
+
+.. image:: /_images/user_screen_shots/vcenter-network-manager.png
+   :width: 50%
+
+- Specify the credentials used to access the vCenter installation:
+
+.. image:: /_images/user_screen_shots/settings-vcenter.png
+   :width: 50%
+
+- Enable the 'Use VLAN tagging for fixed networks' checkbox
+  and enter the VLAN tag you selected
+  for the VLAN ID in the ESXi host network configuration:
+
+.. image:: /_images/user_screen_shots/vcenter-nova-network.png
+   :width: 50%
 
 For more information about how vCenter support is implemented,
 see :ref:`vcenter-arch`.