openstack-manuals/doc/config-reference/block-storage/drivers/ibm-storwize-svc-driver.xml

698 lines
35 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>Configure 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; you do not 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; you do not
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 and the
<literal>storwize_svc_iscsi_chap_enabled</literal>
is set to <literal>True</literal>, the driver will
associate randomly-generated CHAP secrets with all
hosts on the Storwize family system. OpenStack compute
nodes use these secrets when creating iSCSI
connections. <note>
<para>CHAP secrets are added to existing hosts as
well as newly-created ones. If the CHAP option
is enabled, hosts will not be able to access
the storage without the generated
secrets.</para>
</note>
<note>
<para>Not all OpenStack Compute drivers support
CHAP authentication. Please check
compatibility before using.</para>
</note>
<note>
<para>CHAP secrets are passed from OpenStack Block
Storage to Compute in clear text. This
communication should be secured to ensure that
CHAP secrets are not discovered.</para>
</note></para>
</simplesect>
<simplesect>
<title>Configure 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>Configure 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 <systemitem
class="service">cinder-volume</systemitem>
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>Create a SSH key pair with 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>Configure the Storwize family and SVC driver</title>
<simplesect>
<title>Enable 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.ibm.storwize_svc.StorwizeSVCDriver</programlisting>
</simplesect>
<simplesect>
<title>Storwize family and SVC driver options 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>
<th>Flag name</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><para><literal>san_ip</literal></para>
</td>
<td><para>Required</para></td>
<td><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/></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/></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/></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/></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_iscsi_chap_enabled
</literal></para>
</td>
<td><para>Optional</para></td>
<td><para>True</para></td>
<td><para>Configure CHAP authentication for
iSCSI connections</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>
<xi:include
href="../../../common/tables/cinder-storwize.xml"/>
</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_back-end_name - Specify
a specific back-end where the volume should be
created. The back-end 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_back-end_name=myV7000_openstackpool</programlisting></para>
</listitem>
<listitem>
<para>capabilities:compression_support - Specify a
back-end according to compression support. A
value of <literal>True</literal> should be
used to request a back-end that supports
compression, and a value of
<literal>False</literal> will request a
back-end 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 back-end 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>Configure 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:</para>
<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>
<para>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: 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</para>
<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>
</simplesect>
</section>
<section xml:id="ibm-storwize-svc-driver3">
<title>Operational notes for the Storwize family and SVC
driver</title>
<simplesect>
<title>Migrate volumes</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>Extend 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>
<simplesect>
<title>Volume retype</title>
<para>The IBM Storwize/SVC driver enables you to modify
volume types. When you modify volume types, you can
also change these extra specs properties:</para>
<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>iogrp</para>
</listitem>
</itemizedlist>
<note>
<para>When you change the <literal>rsize</literal>,
<literal>grainsize</literal> or
<literal>compression</literal> properties,
volume copies are asynchronously synchronized on
the array.</para>
</note>
<note>
<para>To change the <literal>iogrp</literal> property,
IBM Storwize/SVC firmware version 6.4.0 or later
is required.</para>
</note>
</simplesect>
</section>
</section>