openstack-manuals/doc/config-reference/block-storage/drivers/ibm-storwize-svc-driver.xml
Diane Fleming a6fa07c617 Spellchecked book
bug: #1220266

Change-Id: I5e05fc56ce7c8aa602221a20fb73eecaf1a9f5dc
author: diane fleming
2013-09-23 12:53:26 -05:00

649 lines
32 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<section xml:id="ibm-storwize-svc-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>IBM Storwize Family and SVC Volume Driver</title>
<para>The volume management driver for Storwize family and
SAN Volume Controller (SVC) provides OpenStack Compute
instances with access to IBM Storwize family or SVC
storage systems.</para>
<section xml:id="ibm-storwize-svc-driver1">
<title>Configuring the Storwize Family and SVC System</title>
<simplesect>
<title>Network Configuration</title>
<para>The Storwize family or SVC system must be
configured for iSCSI, Fibre Channel, or both.</para>
<para>If using iSCSI, each Storwize family or SVC node should
have at least one iSCSI IP address.
The IBM Storwize/SVC driver uses an iSCSI IP address associated
with the volume's preferred
node (if available) to attach the volume to the
instance, otherwise it uses the first available
iSCSI IP address of the system.
The driver obtains the iSCSI IP address
directly from the storage system;
there is no need to provide these
iSCSI IP addresses directly to the driver.</para>
<note>
<para>If using iSCSI, ensure that the compute nodes
have iSCSI network access to the Storwize family
or SVC system.</para>
</note>
<note>
<para>OpenStack Nova's Grizzly version supports iSCSI
multipath.
Once this is configured on the Nova host (outside the
scope of this documentation), multipath is enabled.
</para>
</note>
<para>If using Fibre Channel (FC), each Storwize family or SVC
node should have at least one WWPN port configured.
If the <literal>storwize_svc_multipath_enabled</literal> flag
is set to True in the Cinder configuration file, the driver
uses all available WWPNs to attach the volume to the
instance (details about the configuration flags appear in the
<link linkend="ibm-storwize-svc-driver2"> next section</link>).
If the flag is not set, the driver uses the WWPN
associated with the volume's preferred node (if available),
otherwise it uses the first available WWPN of the system.
The driver obtains the WWPNs directly from the storage system;
there is no need to provide these WWPNs directly to the driver.
</para>
<note>
<para>If using FC, ensure that the compute nodes
have FC connectivity to the Storwize family
or SVC system.</para>
</note>
</simplesect>
<simplesect>
<title>iSCSI CHAP Authentication</title>
<para>If using iSCSI for data access, all new hosts created by
the driver on the Storwize family or SVC system has a
randomly-generated CHAP secret associated with them.
OpenStack compute nodes use these secrets when creating
iSCSI connections.
<note>
<para>CHAP secrets are not added to existing
hosts.</para>
</note>
<note>
<para>CHAP secrets are passed from Cinder to Nova
in clear text. This communication should be
secured to ensure that CHAP secrets are not
discovered.</para>
</note>
</para>
</simplesect>
<simplesect>
<title>Configuring storage pools</title>
<para>Each instance of the IBM Storwize/SVC driver allocates
all volumes in a single pool.
The pool should be created in advance and be
provided to the driver using the
<literal>storwize_svc_volpool_name</literal>
configuration flag.
Details about the configuration flags and how
to provide the flags to the driver appear in the
<link linkend="ibm-storwize-svc-driver2">
next section</link>.</para>
</simplesect>
<simplesect>
<title>Configuring user authentication for the driver
</title>
<para>The driver requires access to the Storwize
family or SVC system management interface.
The driver communicates with
the management using SSH.
The driver should be provided with the Storwize
family or SVC management IP using the
<literal>san_ip</literal>
flag, and the management port should be
provided by the
<literal>san_ssh_port</literal> flag.
By default, the port value is configured to
be port 22 (SSH).</para>
<note>
<para>Make sure the compute node running
the nova-volume management driver has SSH
network access to
the storage system.</para>
</note>
<para>To allow the driver to communicate with the
Storwize family or SVC system,
you must provide the driver with
a user on the storage system. The driver has two
authentication methods: password-based
authentication and SSH key pair authentication.
The user should have an Administrator role.
It is suggested to create a new
user for the management driver.
Please consult with your
storage and security administrator regarding
the preferred authentication method and how
passwords or SSH keys should be stored in a
secure manner.</para>
<note>
<para>When creating a new user on the Storwize or
SVC system, make sure the user belongs to
the Administrator group or to another group
that has an Administrator role.</para>
</note>
<para>If using password authentication, assign a
password to the user on the Storwize or SVC
system.
The driver configuration flags for the user and
password are <literal>san_login</literal> and
<literal>san_password</literal>, respectively.
</para>
<para>If you are using the SSH key pair
authentication, create SSH
private and public keys using the instructions
below or by any other method.
Associate the public key with the
user by uploading the public key: select the
"choose file" option in the Storwize family or
SVC management GUI under "SSH public key".
Alternatively, you may associate the SSH public
key using the command line interface;
details can be found in the
Storwize and SVC documentation.
The private key should
be provided to the driver using the
<literal>san_private_key</literal>
configuration flag.</para>
</simplesect>
<simplesect>
<title>Creating a SSH key pair using OpenSSH</title>
<para>You can create an SSH key pair using OpenSSH,
by running:
</para>
<screen><prompt>$</prompt> <userinput>ssh-keygen -t rsa</userinput></screen>
<para>The command prompts for a file to save the key
pair.
For example, if you select 'key' as the
filename, two files are created:
<literal>key</literal> and
<literal>key.pub</literal>.
The <literal>key</literal>
file holds the private SSH key and
<literal>key.pub</literal> holds the public
SSH key.
</para>
<para>The command also prompts for a pass phrase,
which should be empty.</para>
<para>The private key file should be provided to the
driver using the
<literal>san_private_key</literal>
configuration flag. The public key should be
uploaded to the Storwize family or SVC system
using the storage management GUI or command
line interface.</para>
<note>
<para>Ensure that Cinder has read permissions on
the private key file.</para>
</note>
</simplesect>
</section>
<section xml:id="ibm-storwize-svc-driver2">
<title>Configuring the Storwize Family and SVC Driver</title>
<simplesect>
<title>Enabling the Storwize family and SVC driver
</title>
<para>Set the volume driver to the Storwize family and
SVC driver by setting the
<literal>volume_driver</literal> option in
<filename>cinder.conf</filename> as follows:</para>
<programlisting>volume_driver = cinder.volume.drivers.storwize_svc.StorwizeSVCDriver</programlisting>
</simplesect>
<simplesect>
<title>Configuring options for the Storwize family and
SVC driver in cinder.conf</title>
<para>The following options specify default values for all
volumes.
Some can be over-ridden using volume types, which
are described below.</para>
<table rules="all">
<caption>List of configuration flags for Storwize
storage and SVC driver</caption>
<col width="40%"/>
<col width="10%"/>
<col width="12%"/>
<col width="38%"/>
<thead>
<tr>
<td>Flag name</td>
<td>Type</td>
<td>Default</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td><para><literal>san_ip</literal></para>
</td>
<td><para>Required</para></td>
<td><para></para></td>
<td><para>Management IP or host name</para>
</td>
</tr>
<tr>
<td><para><literal>san_ssh_port</literal>
</para>
</td>
<td><para>Optional</para></td>
<td><para>22</para></td>
<td><para>Management port</para></td>
</tr>
<tr>
<td><para><literal>san_login</literal></para>
</td>
<td><para>Required</para></td>
<td><para></para></td>
<td><para>Management login username</para>
</td>
</tr>
<tr>
<td><para><literal>san_password</literal>
</para>
</td>
<td><para>Required
<footnote xml:id='storwize-svc-fn1'>
<para>The authentication requires either a
password
(<literal>san_password</literal>) or
SSH private key
(<literal>san_private_key</literal>).
One must be specified. If both are
specified, the driver uses only the
SSH private key.
</para></footnote>
</para></td>
<td><para></para></td>
<td><para>Management login password</para>
</td>
</tr>
<tr>
<td><para><literal>san_private_key</literal>
</para>
</td>
<td><para>Required
<footnoteref linkend='storwize-svc-fn1'/>
</para></td>
<td><para></para></td>
<td><para>Management login SSH private key
</para>
</td>
</tr>
<tr>
<td><para>
<literal>storwize_svc_volpool_name</literal>
</para>
</td>
<td><para>Required</para></td>
<td><para></para></td>
<td><para>Default pool name for volumes</para></td>
</tr>
<tr>
<td><para>
<literal>storwize_svc_vol_rsize</literal>
</para>
</td>
<td><para>Optional</para></td>
<td><para>2</para></td>
<td><para>Initial physical allocation (percentage)
<footnote xml:id='storwize-svc-fn3'>
<para>
The driver creates thin-provisioned
volumes by default. The
<literal>storwize_svc_vol_rsize</literal>
flag defines the initial physical
allocation percentage for thin-provisioned
volumes, or if set to
<literal>-1</literal>,
the driver creates full allocated
volumes. More details
about the available options are available
in the Storwize family and SVC
documentation.
</para></footnote>
</para></td>
</tr>
<tr>
<td><para>
<literal>storwize_svc_vol_warning</literal>
</para>
</td>
<td><para>Optional</para></td>
<td><para>0 (disabled)</para></td>
<td><para>Space allocation warning threshold
(percentage)
<footnoteref linkend='storwize-svc-fn3'/>
</para></td>
</tr>
<tr>
<td><para>
<literal>storwize_svc_vol_autoexpand</literal>
</para>
</td>
<td><para>Optional</para></td>
<td><para>True</para></td>
<td><para>Enable or disable volume auto expand
<footnote xml:id='storwize-svc-fn4'>
<para>
Defines whether thin-provisioned volumes
can be auto expanded by the storage
system, a value of <literal>True</literal>
means that auto expansion is
enabled, a value of
<literal>False</literal>
disables auto expansion.
Details about this option can be
found in the
<literal>autoexpand</literal>
flag of the Storwize
family and SVC command line interface
<literal>mkvdisk</literal> command.
</para></footnote>
</para></td>
</tr>
<tr>
<td><para>
<literal>storwize_svc_vol_grainsize</literal>
</para>
</td>
<td><para>Optional</para></td>
<td><para>256</para></td>
<td><para>Volume grain size
<footnoteref linkend='storwize-svc-fn3'/>
in KB</para></td>
</tr>
<tr>
<td><para>
<literal>storwize_svc_vol_compression
</literal>
</para>
</td>
<td><para>Optional</para></td>
<td><para>False</para></td>
<td><para>
Enable or disable Real-time Compression
<footnote xml:id='storwize-svc-fn5'>
<para>Defines whether Real-time Compression
is used for the volumes created with
OpenStack. Details on Real-time
Compression can be found in the
Storwize family and SVC documentation.
The Storwize or SVC system must have
compression enabled for this feature
to work.
</para>
</footnote>
</para>
</td>
</tr>
<tr>
<td><para>
<literal>storwize_svc_vol_easytier</literal>
</para>
</td>
<td><para>Optional</para></td>
<td><para>True</para></td>
<td><para>Enable or disable Easy Tier
<footnote xml:id='storwize-svc-fn6'>
<para>Defines whether Easy Tier is used
for the volumes created with OpenStack.
Details on EasyTier can be found in the
Storwize family and SVC documentation.
The Storwize or SVC system must have
Easy Tier enabled for this feature to
work.
</para></footnote>
</para></td>
</tr>
<tr>
<td><para>
<literal>storwize_svc_vol_iogrp</literal>
</para>
</td>
<td><para>Optional</para></td>
<td><para>0</para></td>
<td><para>The I/O group in which to allocate vdisks
</para></td>
</tr>
<tr>
<td><para>
<literal>storwize_svc_flashcopy_timeout
</literal>
</para>
</td>
<td><para>Optional</para></td>
<td><para>120</para></td>
<td><para>FlashCopy timeout threshold
<footnote xml:id='storwize-svc-fn7'>
<para>The driver wait timeout threshold
when creating an OpenStack
snapshot. This is actually the
maximum amount of time that the driver
waits for the Storwize family
or SVC system to prepare a new
FlashCopy mapping. The driver
accepts a maximum wait time of 600
seconds (10 minutes).</para></footnote>
(seconds)</para></td>
</tr>
<tr>
<td><para>
<literal>storwize_svc_connection_protocol
</literal>
</para>
</td>
<td><para>Optional</para></td>
<td><para>iSCSI</para></td>
<td><para>Connection protocol to use (currently
supports 'iSCSI' or 'FC')
</para></td>
</tr>
<tr>
<td><para>
<literal>storwize_svc_multipath_enabled
</literal>
</para>
</td>
<td><para>Optional</para></td>
<td><para>False</para></td>
<td><para>Enable multipath for FC connections
<footnote xml:id='storwize-svc-fn8'>
<para>Multipath for iSCSI connections requires no
storage-side configuration and is enabled
if the compute host has multipath configured.
</para></footnote>
</para></td>
</tr>
<tr>
<td><para>
<literal>storwize_svc_multihost_enabled
</literal>
</para>
</td>
<td><para>Optional</para></td>
<td><para>True</para></td>
<td><para>Enable mapping vdisks to multiple hosts
<footnote xml:id='storwize-svc-fn9'>
<para>This option allows the driver to map a vdisk
to more than one host at a time. This scenario
occurs during migration of a virtual machine
with an attached volume; the volume is
simultaneously mapped to both the source and
destination compute hosts. If your deployment
does not require attaching vdisks to multiple
hosts, setting this flag to False will provide
added safety.
</para></footnote>
</para></td>
</tr>
</tbody>
</table>
</simplesect>
<simplesect>
<title>Placement with volume types</title>
<para>The IBM Storwize/SVC driver exposes capabilities
that can be added to the <literal>extra specs</literal>
of volume types, and used by the filter scheduler to
determine placement of new volumes. Make sure to prefix
these keys with <literal>capabilities:</literal> to
indicate that the scheduler should use them. The following
<literal>extra specs</literal> are supported:</para>
<itemizedlist>
<listitem><para>capabilities:volume_backend_name - Specify
a specific backend where the volume should be created. The
backend name is a concatenation of the name of the
IBM Storwize/SVC storage system as shown in
<literal>lssystem</literal>, an underscore,
and the name of the pool (mdisk group). For example:
<programlisting>capabilities:volume_backend_name=myV7000_openstackpool</programlisting>
</para></listitem>
<listitem><para>capabilities:compression_support - Specify
a backend according to compression support. A value of
<literal>True</literal> should be used to request a backend
that supports compression, and a value of
<literal>False</literal> will request a backend that does
not support compression. If you do not have constraints on
compression support, do not set this key. Note that
specifying <literal>True</literal> does not enable
compression; it only requests that the volume be placed on
a backend that supports compression. Example syntax:
<programlisting>capabilities:compression_support='&lt;is&gt; True'</programlisting>
</para></listitem>
<listitem><para>capabilities:easytier_support - Similar
semantics as the <literal>compression_support</literal> key,
but for specifying according to support of the Easy Tier
feature. Example syntax:
<programlisting>capabilities:easytier_support='&lt;is&gt; True'</programlisting>
</para></listitem>
<listitem><para>capabilities:storage_protocol - Specifies
the connection protocol used to attach volumes of this type
to instances. Legal values are <literal>iSCSI</literal> and
<literal>FC</literal>. This <literal>extra specs</literal>
value is used for both placement and setting the protocol
used for this volume. In the example syntax, note &lt;in&gt;
is used as opposed to &lt;is&gt; used in the previous
examples.
<programlisting>capabilities:storage_protocol='&lt;in&gt; FC'</programlisting>
</para></listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Configuring per-volume creation options</title>
<para>Volume types can also
be used to pass options to the IBM Storwize/SVC
driver, which over-ride the default values set in the
configuration file. Contrary to the previous examples
where the "capabilities" scope was used to pass
parameters to the Cinder scheduler, options can be
passed to the IBM Storwize/SVC driver with the
"drivers" scope.</para>
<para>The following <literal>extra specs</literal> keys are
supported by the IBM Storwize/SVC driver:
<itemizedlist>
<listitem><para>rsize</para></listitem>
<listitem><para>warning</para></listitem>
<listitem><para>autoexpand</para></listitem>
<listitem><para>grainsize</para></listitem>
<listitem><para>compression</para></listitem>
<listitem><para>easytier</para></listitem>
<listitem><para>multipath</para></listitem>
<listitem><para>iogrp</para></listitem>
</itemizedlist>
These keys have the same semantics as their counterparts in the
configuration file. They are set similarly; for example,
<literal>rsize=2</literal> or
<literal>compression=False</literal>.
</para>
</simplesect>
<simplesect>
<title>Example using volume types</title>
<para>In the following example, we create a volume type to specify
a controller that supports iSCSI and
compression, to use iSCSI when attaching the volume,
and to enable compression:</para>
<screen><prompt>$</prompt> <userinput>cinder type-create compressed</userinput>
<prompt>$</prompt> <userinput>cinder type-key compressed set capabilities:storage_protocol='&lt;in&gt; iSCSI' capabilities:compression_support='&lt;is&gt; True' drivers:compression=True</userinput></screen>
<para>We can then create a 50GB volume using this type:</para>
<screen><prompt>$</prompt> <userinput>cinder create --display-name "compressed volume" --volume-type compressed 50</userinput></screen>
<para>Volume types can be used, for example, to provide users
with different
<itemizedlist>
<listitem><para>
performance levels (such as, allocating entirely on an HDD
tier, using Easy Tier for an HDD-SDD mix, or allocating
entirely on an SSD tier)
</para></listitem>
<listitem><para>
resiliency levels (such as, allocating volumes in
pools with different RAID levels)
</para></listitem>
<listitem><para>
features (such as, enabling/disabling Real-time
Compression)
</para></listitem>
</itemizedlist>
</para>
</simplesect>
</section>
<section xml:id="ibm-storwize-svc-driver3">
<title>Operational Notes for the Storwize Family and SVC Driver</title>
<simplesect>
<title>Volume Migration</title>
<para>In the context of OpenStack Block Storage's volume
migration feature, the IBM Storwize/SVC driver enables the
storage's virtualization technology. When migrating a
volume from one pool to another, the volume will appear
in the destination pool almost immediately, while the
storage moves the data in the background.</para>
<note>
<para>To enable this feature, both pools involved in
a given volume migration must have the same values
for <literal>extent_size</literal>. If the pools
have different values for
<literal>extent_size</literal>, the data will still
be moved directly between the pools (not host-side
copy), but the operation will be synchronous.</para>
</note>
</simplesect>
<simplesect>
<title>Extending Volumes</title>
<para>The IBM Storwize/SVC driver allows for extending a
volume's size, but only for volumes without snapshots.</para>
</simplesect>
<simplesect>
<title>Snapshots and Clones</title>
<para>Snapshots are implemented using FlashCopy with no
background copy (space-efficient). Volume clones
(volumes created from existing volumes) are implemented
with FlashCopy, but with background copy enabled. This
means that volume clones are independent, full copies.
While this background copy is taking place, attempting
to delete or extend the source volume will result in
that operation waiting for the copy to complete.</para>
</simplesect>
</section>
</section>