Update documentation for Windows iSCSI cinder-volume driver

Includes a guide for setting up Cinder Volume on Windows using the
Windows iSCSI volume driver.

Note that the Nova Compute Hyper-V driver documentation is to be
updated as well, and as some sections are common (NTP
configuration and requirements), those specific sections have
been updated and linked in the Cinder Volume documentation.

Change-Id: Ieb54ea6d67963f9ce2dd8f5be8e18ba96b0b4474
This commit is contained in:
Lucian Petrut 2014-10-01 12:12:06 +03:00
parent b8987a2ea0
commit 881e1a55c7
4 changed files with 253 additions and 141 deletions

View File

@ -0,0 +1,136 @@
<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xml:id="windows-iscsi-volume-driver"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude">
<?dbhtml stop-chunking?>
<title>Windows iSCSI volume driver</title>
<para>Windows Server 2012 and Windows Storage Server 2012 offer an
integrated iSCSI Target service that can be used with OpenStack Block Storage
in your stack. Being entirely a software solution, consider it in particular
for mid-sized networks where the costs of a SAN might be excessive.</para>
<para>The Windows <systemitem class="service">cinder-volume</systemitem>
driver works with OpenStack Compute on any hypervisor. It includes snapshotting
support and the “boot from volume” feature.</para>
<para>This driver creates volumes backed by fixed-type VHD images on Windows
Server 2012 and dynamic-type VHDX on Windows Server 2012 R2, stored locally
on a user-specified path. The system uses those images as iSCSI disks and
exports them through iSCSI targets. Each volume has its own iSCSI target.</para>
<para>This driver has been tested with Windows Server 2012 and Windows Server
R2 using the Server and Storage Server distributions.</para>
<para>Install the <systemitem class="service">cinder-volume</systemitem>
service as well as the required Python components directly onto the Windows
node.</para>
<para>You may install and configure <systemitem class="service">cinder-volume
</systemitem> and its dependencies manually using the following guide or you
may use the <literal>Cinder Volume Installer</literal>, presented below.</para>
<section xml:id="installing-cinder-volume-using-msi">
<title>Installing using the OpenStack cinder volume installer</title>
<para>In case you want to avoid all the manual setup, you can use
Cloudbase Solutions installer. You can find it at <link
xlink:href="https://www.cloudbase.it/downloads/CinderVolumeSetup_Beta.msi">
https://www.cloudbase.it/downloads/CinderVolumeSetup_Beta.msi</link>. It
installs an independent Python environment, in order to avoid conflicts
with existing applications, dynamically generates a <filename>cinder.conf
</filename> file based on the parameters provided by you.</para>
<para><systemitem class="service">cinder-volume</systemitem> will be
configured to run as a Windows Service, which can be restarted
using:</para>
<screen><prompt>PS C:\&gt;</prompt> <userinput>net stop cinder-volume ; net start cinder-volume</userinput></screen>
<para>The installer can also be used in unattended mode. More details
about how to use the installer and its features can be found at <link
xlink:href="https://www.cloudbase.it">https://www.cloudbase.it</link></para>
</section>
<section xml:id="windows-server-configuration">
<title>Windows Server configuration</title>
<para>The required service in order to run <systemitem class="service">
cinder-volume</systemitem> on Windows is <literal>wintarget</literal>.
This will require the iSCSI Target Server Windows feature to be installed.
You can install it by running the following command:</para>
<screen><prompt>PS C:\&gt;</prompt> <userinput>Add-WindowsFeature
FS-iSCSITarget-ServerAdd-WindowsFeatureFS-iSCSITarget-Server</userinput></screen>
<note>
<para>The Windows Server installation requires at least 16 GB of disk space.
The volumes hosted by this node need the extra space.</para>
</note>
<para>For <systemitem class="service">cinder-volume</systemitem> to work
properly, you must configure NTP as explained in
<xref linkend="configure-ntp-windows"/>.</para>
<para>Next, install the requirements as described in <xref
linkend="windows-requirements"/>.</para>
</section>
<section xml:id="getting-the-code">
<title>Getting the code</title>
<para>Git can be used to download the necessary source code. The installer
to run Git on Windows can be downloaded here:</para>
<para><link
xlink:href="https://github.com/msysgit/msysgit/releases/download/Git-1.9.2-preview20140411/Git-1.9.2-preview20140411.exe">
https://github.com/msysgit/msysgit/releases/download/Git-1.9.2-preview20140411/Git-1.9.2-preview20140411.exe</link></para>
<para>Once installed, run the following to clone the OpenStack
Block Storage code.</para>
<screen><prompt>PS C:\&gt;</prompt> <userinput>git.exe clone https://github.com/openstack/cinder.git</userinput></screen>
</section>
<section xml:id="configure-cinder-volume">
<title>Configure cinder-volume</title>
<para>The <filename>cinder.conf</filename> file may be placed in
<filename>C:\etc\cinder</filename>. Below is a config sample for using
the Windows iSCSI Driver:</para>
<programlisting language="ini">[DEFAULT]
auth_strategy = keystone
volume_name_template = volume-%s
volume_driver = cinder.volume.drivers.windows.WindowsDriver
glance_api_servers = <replaceable>IP_ADDRESS</replaceable>:9292
rabbit_host = <replaceable>IP_ADDRESS</replaceable>
rabbit_port = 5672
sql_connection = mysql://root:Passw0rd@<replaceable>IP_ADDRESS</replaceable>/cinder
windows_iscsi_lun_path = C:\iSCSIVirtualDisks
verbose = True
rabbit_password = Passw0rd
logdir = C:\OpenStack\Log\
image_conversion_dir = C:\ImageConversionDir
debug = True</programlisting>
<para>The following table contains a reference to the only driver specific
option that will be used by the Block Storage Windows driver:</para>
<xi:include href="../../../common/tables/cinder-windows.xml"/>
</section>
<section xml:id="running-cinder-volume">
<title>Running cinder-volume</title>
<para>After configuring <systemitem class="service">cinder-volume</systemitem>
using the <filename>cinder.conf</filename> file, you may use the following
commands to install and run the service (note that you must replace the
variables with the proper paths):</para>
<screen><prompt>PS C:\&gt;</prompt> <userinput>python $CinderClonePath\setup.py install</userinput>
<prompt>PS C:\&gt;</prompt> <userinput>cmd /c C:\python27\python.exe c:\python27\Scripts\cinder-volume" -config-file $CinderConfPath</userinput></screen>
</section>
</section>

View File

@ -1,11 +0,0 @@
<section xml:id="windows-volume-driver"
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">
<title>Windows</title>
<para>There is a volume back-end for Windows. Set the following in your
<filename>cinder.conf</filename>, and use the options below to configure it.</para>
<programlisting language="ini">volume_driver=cinder.volume.drivers.windows.WindowsDriver</programlisting>
<xi:include href="../../../common/tables/cinder-windows.xml"/>
</section>

View File

@ -38,7 +38,7 @@
<xi:include href="drivers/sheepdog-driver.xml"/> <xi:include href="drivers/sheepdog-driver.xml"/>
<xi:include href="drivers/solidfire-volume-driver.xml"/> <xi:include href="drivers/solidfire-volume-driver.xml"/>
<xi:include href="drivers/vmware-vmdk-driver.xml"/> <xi:include href="drivers/vmware-vmdk-driver.xml"/>
<xi:include href="drivers/windows-volume-driver.xml"/> <xi:include href="drivers/windows-iscsi-volume-driver.xml"/>
<xi:include href="drivers/xen-sm-driver.xml"/> <xi:include href="drivers/xen-sm-driver.xml"/>
<xi:include href="drivers/xenapi-nfs.xml"/> <xi:include href="drivers/xenapi-nfs.xml"/>
<xi:include href="drivers/zadara-volume-driver.xml"/> <xi:include href="drivers/zadara-volume-driver.xml"/>

View File

@ -23,7 +23,7 @@
<para>Server and Core (with the Hyper-V role enabled), and Hyper-V Server</para> <para>Server and Core (with the Hyper-V role enabled), and Hyper-V Server</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> </para>
<section xml:id="installation-architecture-hyper-v"> <section xml:id="installation-architecture-hyper-v">
<title>Hyper-V configuration</title> <title>Hyper-V configuration</title>
<para>The following sections discuss how to prepare the Windows Hyper-V node for operation <para>The following sections discuss how to prepare the Windows Hyper-V node for operation
@ -35,14 +35,16 @@
it into an OS volume and VM volume. It is up to the individual deploying to it into an OS volume and VM volume. It is up to the individual deploying to
decide.</para> decide.</para>
</section> </section>
<section xml:id="configure-ntp-hyper-v"> <section xml:id="configure-ntp-windows">
<title>Configure NTP</title> <title>Configure NTP</title>
<para>Network time services must be configured to ensure proper operation of the Hyper-V <para>Network time services must be configured to ensure proper operation of the OpenStack nodes. To set network time on your Windows host you must run the following commands:</para>
compute node. To set network time on your Hyper-V host you must run the
following commands:</para>
<screen><prompt>C:\></prompt><userinput>net stop w32time</userinput> <screen><prompt>C:\></prompt><userinput>net stop w32time</userinput>
<prompt>C:\></prompt><userinput>w32tm /config /manualpeerlist:pool.ntp.org,0x8 /syncfromflags:MANUAL</userinput> <prompt>C:\></prompt><userinput>w32tm /config /manualpeerlist:pool.ntp.org,0x8 /syncfromflags:MANUAL</userinput>
<prompt>C:\></prompt><userinput>net start w32time</userinput></screen> <prompt>C:\></prompt><userinput>net start w32time</userinput></screen>
<para>Keep in mind that the node will have to be time synchronized with
the other nodes of your OpenStack environment, so it is important to use
the same NTP server. Note that in case of an Active Directory environment,
you may do this only for the AD Domain Controller.</para>
</section> </section>
<section xml:id="hyper-v-virtual-switch"> <section xml:id="hyper-v-virtual-switch">
<title>Configure Hyper-V virtual switching</title> <title>Configure Hyper-V virtual switching</title>
@ -152,136 +154,121 @@
>http://ariessysadmin.blogspot.ro/2012/04/hyper-v-live-migration-of-windows.html</link> >http://ariessysadmin.blogspot.ro/2012/04/hyper-v-live-migration-of-windows.html</link>
</para> </para>
</section> </section>
<section xml:id="python-requirements-hyper-v"> <section xml:id="windows-requirements">
<title>Python Requirements</title> <title>Requirements</title>
<para><emphasis role="bold">Python</emphasis></para> <section xml:id="windows-python-requirements">
<para>Python 2.7.3 must be installed prior to installing the OpenStack Compute Driver on the <title>Python</title>
Hyper-V server. Download and then install the MSI for windows here:<itemizedlist> <para>Python 2.7 32bit must be installed as most of the libraries are not
working properly on the 64bit version.</para>
<procedure>
<title>Setting up Python prerequisites</title>
<step>
<para>Download and then install it using the MSI installer from
here:</para>
<para><link
xlink:href="http://www.python.org/ftp/python/2.7.3/python-2.7.3.msi">
http://www.python.org/ftp/python/2.7.3/python-2.7.3.msi</link></para>
<screen><prompt>PS C:\&gt;</prompt> <userinput>$src = “http://www.python.org/ftp/python/2.7.3/python-2.7.3.msi”</userinput>
<prompt>PS C:\&gt;</prompt> <userinput>$dest = “$env:temp\python-2.7.3.msi”</userinput>
<prompt>PS C:\&gt;</prompt> <userinput>Invoke-WebRequest Uri $src OutFile $dest</userinput>
<prompt>PS C:\&gt;</prompt> <userinput>Unblock-File $dest</userinput>
<prompt>PS C:\&gt;</prompt> <userinput>Start-Process $dest</userinput></screen>
</step>
<step>
<para>Make sure that the <filename>Python</filename> and
<filename>Python\Scripts</filename> paths are set up in the
<envar>PATH</envar> environment variable.</para>
</step>
</procedure>
</section>
<section xml:id="windows-python-dependencies">
<title>Python dependencies</title>
<para>The following packages need to be downloaded and manually
installed:</para>
<variablelist>
<varlistentry>
<term><package>setuptools</package></term>
<listitem>
<para><link
xlink:href="http://pypi.python.org/packages/2.7/s/setuptools/setuptools-0.6c11.win32-py2.7.exe">
http://pypi.python.org/packages/2.7/s/setuptools/setuptools-0.6c11.win32-py2.7.exel</link></para>
</listitem>
</varlistentry>
<varlistentry>
<term><package>pip</package></term>
<listitem>
<para><link
xlink:href="http://pip.readthedocs.org/en/latest/installing.html">
http://pip.readthedocs.org/en/latest/installing.html</link></para>
</listitem>
</varlistentry>
<varlistentry>
<term><package>MySQL-python</package></term>
<listitem>
<para><link xlink:href="http://codegood.com/download/10/">
http://codegood.com/download/10/</link></para>
</listitem>
</varlistentry>
<varlistentry>
<term><package>PyWin32</package></term>
<listitem>
<para><link
xlink:href="http://sourceforge.net/projects/pywin32/files/pywin32/Build%20217/pywin32-217.win32-py2.7.exe">
http://sourceforge.net/projects/pywin32/files/pywin32/Build%20217/pywin32-217.win32-py2.7.exe</link></para>
</listitem>
</varlistentry>
<varlistentry>
<term><package>Greenlet</package></term>
<listitem>
<para><link
xlink:href="http://www.lfd.uci.edu/~gohlke/pythonlibs/#greenlet">
http://www.lfd.uci.edu/~gohlke/pythonlibs/#greenlet</link></para>
</listitem>
</varlistentry>
<varlistentry>
<term><package>PyCryto</package></term>
<listitem>
<para><link
xlink:href="http://www.voidspace.org.uk/downloads/pycrypto26/pycrypto-2.6.win32-py2.7.exe">
http://www.voidspace.org.uk/downloads/pycrypto26/pycrypto-2.6.win32-py2.7.exe</link></para>
</listitem>
</varlistentry>
</variablelist>
<para>The following packages must be installed with pip:</para>
<itemizedlist>
<listitem> <listitem>
<para> <para><package>ecdsa</package></para>
<link xlink:href="http://www.python.org/ftp/python/2.7.3/python-2.7.3.msi"
>http://www.python.org/ftp/python/2.7.3/python-2.7.3.msi</link>
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Install the MSI accepting the default options.</para> <para><package>amqp</package></para>
</listitem> </listitem>
<listitem> <listitem>
<para>The installation will put python in C:/python27.</para> <para><package>wmi</package></para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> <screen><prompt>PS C:\&gt;</prompt> <userinput>pip install ecdsa</userinput>
<para><emphasis role="bold">Setuptools</emphasis></para> <prompt>PS C:\&gt;</prompt> <userinput>pip install amqp</userinput>
<para>You will require pip to install the necessary python module dependencies. The <prompt>PS C:\&gt;</prompt> <userinput>pip install wmi</userinput></screen>
installer will install under the C:\python27 directory structure. Setuptools for Python </section>
2.7 for Windows can be download from here:</para> <section xml:id="windows-other-dependencies">
<para><link <title>Other dependencies</title>
xlink:href="http://pypi.python.org/packages/2.7/s/setuptools/setuptools-0.6c11.win32-py2.7.exe#md5=57e1e64f6b7c7f1d2eddfc9746bbaf20" <para><literal>qemu-img</literal> is required for some of the image
> http://pypi.python.org/packages/2.7/s/setuptools/setuptools-0.6c11.win32-py2.7.exe related operations. You can get it from here: <link
</link> xlink:href="http://qemu.weilnetz.de/">http://qemu.weilnetz.de/</link>. You
</para> must make sure that the <literal>qemu-img</literal> path is set in the
<para><emphasis role="bold">Python Dependencies</emphasis></para> PATH environment variable.</para>
<para>You must download and manually install the following packages on the Compute <para>Some Python packages need to be compiled, so you may use MinGW or
node:</para> Visual Studio. You can get MinGW from here: <link
<itemizedlist> xlink:href="http://sourceforge.net/projects/mingw/">
<listitem> http://sourceforge.net/projects/mingw/</link>. You must configure which
<para><emphasis role="bold">MySQL-python</emphasis></para> compiler to be used for this purpose by using the
<para> <filename>distutils.cfg</filename> file in
<link xlink:href="http://codegood.com/download/10/" <filename>$Python27\Lib\distutils</filename>, which can contain:</para>
>http://codegood.com/download/10/</link> <programlisting language="ini">[build]
</para> compiler = mingw32</programlisting>
</listitem> <para>As a last step for setting up MinGW, make sure that the MinGW
<listitem> binaries' directories are set up in PATH.</para>
<para><emphasis role="bold">pywin32</emphasis></para> </section>
<para>Download and run the installer from the following location</para>
<para>
<link
xlink:href="http://sourceforge.net/projects/pywin32/files/pywin32/Build%20217/pywin32-217.win32-py2.7.exe"
>http://sourceforge.net/projects/pywin32/files/pywin32/Build%20217/pywin32-217.win32-py2.7.exe</link>
</para>
</listitem>
<listitem>
<para><emphasis role="bold">greenlet</emphasis></para>
<para>Select the link below:</para>
<para><link xlink:href="http://www.lfd.uci.edu/~gohlke/pythonlibs/"
>http://www.lfd.uci.edu/~gohlke/pythonlibs/</link></para>
<para>You must scroll to the greenlet section for the following file:
greenlet-0.4.0.win32-py2.7.exe</para>
<para>Click on the file, to initiate the download. Once the download is complete,
run the installer.</para>
</listitem>
</itemizedlist>
<para>You must install the following Python packages through <command>easy_install</command> or <command>pip</command>. Run the
following replacing PACKAGENAME with the following packages:</para>
<screen><prompt>C:\></prompt><userinput>c:\Python27\Scripts\pip.exe install <replaceable>PACKAGE_NAME</replaceable></userinput></screen>
<itemizedlist>
<listitem>
<para>amqplib</para>
</listitem>
<listitem>
<para>anyjson</para>
</listitem>
<listitem>
<para>distribute</para>
</listitem>
<listitem>
<para>eventlet</para>
</listitem>
<listitem>
<para>httplib2</para>
</listitem>
<listitem>
<para>iso8601</para>
</listitem>
<listitem>
<para>jsonschema</para>
</listitem>
<listitem>
<para>kombu</para>
</listitem>
<listitem>
<para>netaddr</para>
</listitem>
<listitem>
<para>paste</para>
</listitem>
<listitem>
<para>paste-deploy</para>
</listitem>
<listitem>
<para>prettytable</para>
</listitem>
<listitem>
<para>python-cinderclient</para>
</listitem>
<listitem>
<para>python-glanceclient</para>
</listitem>
<listitem>
<para>python-keystoneclient</para>
</listitem>
<listitem>
<para>repoze.lru</para>
</listitem>
<listitem>
<para>routes</para>
</listitem>
<listitem>
<para>sqlalchemy</para>
</listitem>
<listitem>
<para>simplejson</para>
</listitem>
<listitem>
<para>warlock</para>
</listitem>
<listitem>
<para>webob</para>
</listitem>
<listitem>
<para>wmi</para>
</listitem>
</itemizedlist>
</section> </section>
<section xml:id="install-nova-windows-hyper-v"> <section xml:id="install-nova-windows-hyper-v">
<title>Install Nova-compute</title> <title>Install Nova-compute</title>
@ -354,7 +341,7 @@ connection=mysql://nova:passwd@<replaceable>IP_ADDRESS</replaceable>/nova</progr
controller; however, I'm not seeing smiley faces for Hyper-V compute nodes, what controller; however, I'm not seeing smiley faces for Hyper-V compute nodes, what
do I do?</para> do I do?</para>
<para><emphasis role="italic">Verify that you are synchronized with a network time <para><emphasis role="italic">Verify that you are synchronized with a network time
source. For instructions about how to configure NTP on your Hyper-V compute node, see <xref linkend="configure-ntp-hyper-v"/>.</emphasis></para> source. For instructions about how to configure NTP on your Hyper-V compute node, see <xref linkend="configure-ntp-windows"/>.</emphasis></para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</section> </section>