Folder rename, file rename, flattening of directories

Current folder name	New folder name	        Book title
----------------------------------------------------------
basic-install 	        DELETE
cli-guide	        DELETE
common	                common
NEW	                admin-guide-cloud	Cloud Administrators Guide
docbkx-example	        DELETE
openstack-block-storage-admin 	DELETE
openstack-compute-admin 	DELETE
openstack-config 	config-reference	OpenStack Configuration Reference
openstack-ha 	        high-availability-guide	OpenStack High Availabilty Guide
openstack-image	        image-guide	OpenStack Virtual Machine Image Guide
openstack-install 	install-guide	OpenStack Installation Guide
openstack-network-connectivity-admin 	admin-guide-network 	OpenStack Networking Administration Guide
openstack-object-storage-admin 	DELETE
openstack-security 	security-guide	OpenStack Security Guide
openstack-training 	training-guide	OpenStack Training Guide
openstack-user 	        user-guide	OpenStack End User Guide
openstack-user-admin 	user-guide-admin	OpenStack Admin User Guide
glossary	        NEW        	OpenStack Glossary

bug: #1220407

Change-Id: Id5ffc774b966ba7b9a591743a877aa10ab3094c7
author: diane fleming
This commit is contained in:
Diane Fleming
2013-09-06 23:40:23 -05:00
committed by annegentle
parent f4bb021c6a
commit 64b6c9261e
1009 changed files with 1427 additions and 93084 deletions

View File

@@ -0,0 +1,599 @@
<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>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>
<programlisting>
ssh-keygen -t rsa
</programlisting>
<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="35%"/>
<col width="15%"/>
<col width="15%"/>
<col width="35%"/>
<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_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>
</tbody>
</table>
</simplesect>
<simplesect>
<title>Working with multiple back-ends</title>
<para>Cinder has support for multiple back-ends. This
can be accomplished by running multiple instances of
<systemitem class="service">cinder-volume</systemitem>, each with its own configuration file,
or by including multiple sections in one configuration
file. For example:
<programlisting>
[DEFAULT]
...
enabled_backends = v7k1,v7k2
[v7k1]
...
[v7k2]
...
</programlisting>Here,
common options are placed under
<literal>[DEFAULT]</literal>, while options
specific to a back-end are placed in the appropriate
section.</para>
<para>By default, volumes are allocated between back-ends
to balance allocated space.
However, <literal>volume types</literal> can be used to have
finer-grained control over where volumes are allocated.
Each volume type contains a set of key-value pairs called
<literal>extra specs</literal>.
Volume types are typically set a priori by an administrator,
and can be managed using the cinder client, using the
<literal>type-create</literal>, <literal>type-delete</literal>,
<literal>type-key</literal>, and <literal>type-list</literal>
arguments.</para>
<para>The <literal>extra specs</literal> keys which have the
"capabilities" prefix (called "scope") are interpreted by the
Cinder scheduler and used to make placement decisions according
to the capabilities of the available back-ends.</para>
<para>The following are examples of supported key-values:
</para>
<para>In the following example, the volume is placed on a
controller named <literal>myv7000</literal>, in a pool named
<literal>openstack</literal>:
<programlisting>
capabilities:volume_backend_name=my7000_openstack
</programlisting></para>
<para>In the next example, the volume is placed
on a controller that supports compression. Specifying
False requires that the volume is placed on a
back-end that does not support compression (if no
constraints on compression support are required, do
not set this key):</para>
<programlisting>
capabilities:compression_support='&lt;is&gt; True'
</programlisting>
<para>The next example shows how Easy Tier support can be with
set with the same semantics as
<literal>compression_support</literal>:</para>
<programlisting>
capabilities:easytier_support='&lt;is&gt; True'
</programlisting>
<para>The connection protocol used to attach volumes to
instances can also be specified using volume types.
In this example, the volume is placed on a controller
that supports Fibre Channel, and Fibre Channel is used
when attaching that volume.
FC can also be replaced with iSCSI.</para>
<programlisting>
capabilities:storage_protocol='&lt;in&gt; FC'
</programlisting>
</simplesect>
<simplesect>
<title>Configuring per-volume creation options</title>
<para>The volume types previously described 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, or by omitting the 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>
</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>Complete volume type examples</title>
<para>In the following example, the volume is placed on
a controller named that supports Fibre Channel and
compression, FC is used when attaching the volume,
and compression is enabled:</para>
<programlisting>
cinder type-create compressed
cinder type-key compressed set capabilities:storage_protocol=''&lt;in&gt; FC' capabilities:compression_support='&lt;is&gt; True' drivers:compression=True
</programlisting>
<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>