openstack-manuals/doc/common/section_vmware.xml

<?xml version="1.0" encoding="utf-8"?>
<section xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="vmware">
  <title>VMware vSphere</title>
  <?dbhtml stop-chunking?>
  <section xml:id="vmware-intro">
    <title>Introduction</title>
    <para>OpenStack Compute supports the VMware vSphere product family. This section describes the
      additional configuration required to launch VMWare-based virtual machine images. vSphere
      versions 4.1 and greater are supported.</para>
    <para>There are two OpenStack Compute drivers that can be used with vSphere:</para>
    <itemizedlist>
      <listitem>
        <para>vmwareapi.VMwareVCDriver: a driver that lets <systemitem class="service"
            >nova-compute</systemitem> communicate with a VMware vCenter server managing a cluster
          of ESX hosts. With this driver and access to shared storage, advanced vSphere features
          like vMotion, High Availability, and Dynamic Resource Scheduling (DRS) are available. With
          this driver, one <systemitem class="service">nova-compute</systemitem> service is run per
          vCenter cluster.</para>
      </listitem>
      <listitem>
        <para>vmwareapi.VMwareESXDriver: a driver that lets <systemitem class="service"
            >nova-compute</systemitem> communicate directly to an ESX host, but does not support
          advanced VMware features. With this driver, one <systemitem class="service"
            >nova-compute</systemitem> service is run per ESX host.</para>
      </listitem>
    </itemizedlist>
  </section>
  <section xml:id="vmware-prereqs">
    <title>Prerequisites</title>
    <para>You will need to install the following software installed on each <systemitem
        class="service">nova-compute</systemitem> node:</para>
    <itemizedlist>
      <listitem>
        <para>python-suds: This software is needed by the <systemitem class="service"
            >nova-compute</systemitem> service to communicate with vSphere APIs. If not installed,
          the <systemitem class="service">nova-compute</systemitem> service shuts down with the
          message: "Unable to import suds".</para>
      </listitem>
    </itemizedlist>
    <para>On Ubuntu, this package can be installed by running:</para>
    <screen><prompt>$</prompt> <userinput>sudo apt-get install python-suds</userinput></screen>
  </section>
  <section xml:id="VMWareVCDriver_details">
    <title>Using the VMwareVCDriver</title>
    <para>This section covers details of using the VMwareVCDriver.</para>
    <section xml:id="VMWareVCDriver_configuration_options">
      <title>VMWareVCDriver configuration options</title>
      <para>When using the VMwareVCDriver (i.e., vCenter) with OpenStack Compute, <filename>nova.conf</filename> must
        include the following VMWare-specific config options:</para>

      <programlisting language="ini">[DEFAULT]
compute_driver=vmwareapi.VMwareVCDriver

[vmware]
host_ip=&lt;vCenter host IP&gt;
host_username=&lt;vCenter username&gt;
host_password=&lt;vCenter password&gt;
cluster_name=&lt;vCenter cluster name&gt;
wsdl_location=http://127.0.0.1:8080/vmware/SDK/wsdl/vim25/vimService.wsdl</programlisting>
      <para>Remember that you will have only one <systemitem class="service"
          >nova-compute</systemitem> service per cluster. It is recommended that this host run as a
        VM with high-availability enabled as part of that same cluster.</para>
      <para>Also note that many of the <filename>nova.conf</filename>
         options mentioned elsewhere in this document that are relevant
         to libvirt do not apply to using this driver.</para>
    </section>
    <section xml:id="vmware-wsdl-workaround">
      <title>vSphere 5.0 (and below) additional setup</title>
      <para>Users of vSphere 5.0 or earlier will need to locally host their WSDL files.
        These steps are applicable for vCenter 5.0 or ESXi 5.0 and you may
        accomplish this by either mirroring the WSDL from the vCenter or ESXi
        server you intend on using, or you may download the SDK directly from VMware.
        These are both workaround steps used to fix a <link
         xlink:href="http://kb.vmware.com/selfservice/microsites/search.do?cmd=displayKC&amp;externalId=2010507"
         >known issue</link> with the WSDL that was resolved in later versions.
      </para>
      <procedure>
        <title>Mirror WSDL from vCenter (or ESXi)</title>
        <step>
          <para>You'll need the IP address for your vCenter or
          ESXi host that you'll be mirroring the files from. Set the
          shell variable <code>VMWAREAPI_IP</code> to the IP address
          to allow you to cut and paste commands from these instructions:
          <screen><prompt>$</prompt> <userinput>export VMWAREAPI_IP=&lt;your_vsphere_host_ip&gt;</userinput></screen>
          </para>
        </step>
        <step>
          <para>
            Create a local file system directory to hold the WSDL files in.
        <screen><prompt>$</prompt> <userinput>mkdir -p /opt/stack/vmware/wsdl/5.0</userinput></screen>
          </para>
        </step>
        <step>
          <para>Change into the new directory.
        <screen><prompt>$</prompt> <userinput>cd /opt/stack/vmware/wsdl/5.0</userinput></screen>
          </para>
        </step>
        <step>
          <para>Install a command line tool that can download the the files like
          <command>wget</command>. Install it with your OS specific tools.
          </para>
        </step>
        <step>
          <para>
            Download the files to the local file cache.
        <programlisting language="bash">wget  --no-check-certificate https://$VMWAREAPI_IP/sdk/vimService.wsdl
wget  --no-check-certificate https://$VMWAREAPI_IP/sdk/vim.wsdl
wget  --no-check-certificate https://$VMWAREAPI_IP/sdk/core-types.xsd
wget  --no-check-certificate https://$VMWAREAPI_IP/sdk/query-messagetypes.xsd
wget  --no-check-certificate https://$VMWAREAPI_IP/sdk/query-types.xsd
wget  --no-check-certificate https://$VMWAREAPI_IP/sdk/vim-messagetypes.xsd
wget  --no-check-certificate https://$VMWAREAPI_IP/sdk/reflect-messagetypes.xsd
wget  --no-check-certificate https://$VMWAREAPI_IP/sdk/reflect-types.xsd</programlisting>
        There will be two files that did not fetch properly
        <filename>reflect-types.xsd</filename> and
        <filename>reflect-messagetypes.xsd</filename>. These two files
        will need to be stubbed out. The following XML listing can be
        used to replace the missing file content. The XML parser
        underneath Python can be very particular and if you put a
        space in the wrong place it can break the parser. Copy the
        contents below carefully and watch the formatting carefully.
        <programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
  &lt;schema
     targetNamespace="urn:reflect"
     xmlns="http://www.w3.org/2001/XMLSchema"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
     elementFormDefault="qualified"&gt;
  &lt;/schema&gt;
        </programlisting>
          </para>
        </step>
        <step>
          <para>
            Now that the files are locally present, tell
            the driver to look for the SOAP service WSDLs in the local
            file system and not on the remote vSphere server. The
            following setting should be added to the
            <filename>nova.conf</filename> for your nova-compute node:
        <programlisting language="ini">[vmware]
wsdl_location=file:///opt/stack/vmware/wsdl/5.0/vimService.wsdl</programlisting>
          </para>
        </step>
      </procedure>
      <para>Alternatively, download the version appropriate SDK from
      <link
      xlink:href="http://www.vmware.com/support/developer/vc-sdk/"
      >http://www.vmware.com/support/developer/vc-sdk/</link> and copy
      it into <filename>/opt/stack/vmware</filename>. You should
      ensure that the WSDL is available, in for example
      <filename>/opt/stack/vmware/SDK/wsdl/vim25/vimService.wsdl</filename>.
      Below we will point <filename>nova.conf</filename> to fetch this
      WSDL file from the local file system using a URL.</para>
        <para>When using the VMwareVCDriver (i.e vCenter) with OpenStack Compute with vSphere
        version 5.0 or below, <filename>nova.conf</filename> must include the following extra config option:</para>
      <programlisting language="ini">[vmware]
wsdl_location=file:///opt/stack/vmware/SDK/wsdl/vim25/vimService.wsdl</programlisting>
    </section>
    <section xml:id="VMwareVCDriver_limitations">
      <title>Requirements and limitations</title>
      <para>The VMwareVCDriver is new in Grizzly, and as a result there are some important
        deployment requirements and limitations to be aware of. In many cases, these items will be
        addressed in future releases.</para>
      <itemizedlist>
        <listitem>
          <para>Each cluster can only be configured with a single Datastore. If multiple Datastores
            are configured, the first one returned via the vSphere API will be used.</para>
        </listitem>
        <listitem>
          <para>Because a single <systemitem
          class="service">nova-compute</systemitem> is used per
          cluster, the <systemitem
          class="service">nova-scheduler</systemitem> views this as a
          single host with resources amounting to the aggregate
          resources of all ESX hosts managed by the cluster. This may
          result in unexpected behavior depending on your choice of
          scheduler.</para>
        </listitem>
        <listitem>
          <para>Security Groups are not supported if <systemitem
          class="service">nova-network</systemitem> is used. Security
          Groups are only supported if the VMware driver is used in
          conjunction with the OpenStack Networking Service running
          the Nicira NVP plugin.</para>
        </listitem>
      </itemizedlist>
    </section>
  </section>

  <section xml:id="VMWareESXDriver_details">
    <title>Using the VMwareESXDriver</title>
    <para>This section covers details of using the VMwareESXDriver.</para>
    <section xml:id="VMWareESXDriver_configuration_options">
      <title>VMWareESXDriver configuration options</title>
      <para>When using the VMwareESXDriver (i.e., no vCenter) with OpenStack Compute, configure
        <filename>nova.conf</filename> with the following VMWare-specific config options:</para>

      <programlisting language="ini">[DEFAULT]
compute_driver=vmwareapi.VMwareESXDriver

[vmware]
host_ip=&lt;ESXi host IP&gt;
host_username=&lt;ESXi host username&gt;
host_password=&lt;ESXi host password&gt;
wsdl_location=http://127.0.0.1:8080/vmware/SDK/wsdl/vim25/vimService.wsdl</programlisting>
      <para>Remember that you will have one <systemitem class="service">nova-compute</systemitem>
        service per ESXi host. It is recommended that this host run as a VM on the same ESXi host it
        is managing.</para>
      <para>Also note that many of the <filename>nova.conf</filename> options mentioned elsewhere in this document that
        are relevant to libvirt do not apply to using this driver.</para>
    </section>
    <section xml:id="VMwareESXDriver_limitations">
      <title>Requirements and limitations</title>
      <para>The ESXDriver is unable to take advantage of many of the advanced capabilities
        associated with the vSphere platform, namely vMotion, High Availability, and Dynamic
        Resource Scheduler (DRS).</para>
    </section>
  </section>

  <section xml:id="VMWare_images">
    <title>Images with VMware vSphere</title>
    <para>When using either VMware driver, images should be uploaded to the OpenStack Image Service
      in the VMDK format. Both thick and thin images are currently supported and all images must be
      flat (i.e. contained within 1 file). For example:</para>
    <para>To load a thick image with a SCSI adaptor:</para>
    <screen><prompt>$</prompt> <userinput>glance image-create name="ubuntu-thick-scsi" disk_format=vmdk container_format=bare \
is_public=true --property vmware_adaptertype="lsiLogic" \
--property vmware_disktype="preallocated" \
--property vmware_ostype="ubuntu64Guest" &lt; ubuntuLTS-flat.vmdk</userinput></screen>
    <para>To load a thin image with an IDE adaptor:</para>
    <screen><prompt>$</prompt> <userinput>glance image-create name="unbuntu-thin-ide" disk_format=vmdk container_format=bare \
is_public=true --property vmware_adaptertype="ide" \
--property vmware_disktype="thin" \
--property vmware_ostype="ubuntu64Guest" &lt; unbuntuLTS-thin-flat.vmdk</userinput></screen>
    <para>The complete list of supported vmware disk properties is documented in the Image
      Management section. It's critical that the adaptertype is correct; In fact, the image will not
      boot with the incorrect adaptertype. If you have the meta-data VMDK file, the
      ddb.adapterType property specifies the adaptertype. The default adaptertype is "lsilogic"
      which is SCSI.</para>
  </section>

  <section xml:id="VMWare_networking">
    <title>Networking with VMware vSphere</title>
    <para>The VMware driver support networking with both Nova-Network and the OpenStack Networking
      Service.</para>
    <itemizedlist>
      <listitem>
        <para>If using nova-network with the FlatManager or FlatDHCPManager, before provisioning
          VMs, create a port group with the same name as the <literal>flat_network_bridge</literal> value in
          <filename>nova.conf</filename> (default is <literal>br100</literal>).
          All VM NICs will be attached to this port group.</para>
      </listitem>
      <listitem>
        <para>If using nova-network with the VlanManager, before provisioning VMs, make sure the
          <literal>vlan_interface</literal> configuration option is set to match the ESX host interface
          that will handle VLAN-tagged VM traffic. OpenStack Compute will automatically create the
          corresponding port groups.</para>
      </listitem>
      <listitem>
        <para>If using the OpenStack Networking Service, before provisioning VMs, create a port group
          with the same name as the
          <literal>vmware.integration_bridge</literal> value in
          <filename>nova.conf</filename> (default is
          <literal>br-int</literal>). All VM NICs will be attached to
          this port group for management by the OpenStack Networking
          Plugin.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section xml:id="VMWare_volumes">
    <title>Volumes with VMware vSphere</title>
    <para>The VMware driver supports attaching volumes from the OpenStack Block
    Storage service. 'iscsi' volume driver provides limited support and can be
    used only for attachments. VMware VMDK driver of OpenStack Block Storage
    can be used for managing volumes based out of vSphere datastores.</para>
  </section>
  <section xml:id="VMWare_config">
    <title>Configuration Reference</title>
    <xi:include href="tables/nova-vmware.xml"/>
  </section>
</section>