Files
openstack-manuals/doc/config-reference/block-storage/drivers/hds-hnas-driver.xml
Adriano Rosso 00942d9bed Updates HNAS driver documentation for Kilo
Inserts information for the configuration of the new features,
updates the documentation format and changes some descriptions
of HNAS driver for Kilo version.

Change-Id: I3afe4ade5030c8771e5f5749b9d50f7d5af7f39f
2015-04-15 14:19:49 -03:00

620 lines
27 KiB
XML

<!DOCTYPE section [
<!ENTITY % openstack SYSTEM "../../../common/entities/openstack.ent">
%openstack;
]>
<section xml:id="hds-hnas-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>HDS HNAS iSCSI and NFS driver</title>
<?dbhtml stop-chunking?>
<para>This Block Storage volume driver provides iSCSI and NFS support for
<link xlink:href="http://www.hds.com/products/file-and-content/network-attached-storage/"
>HNAS (Hitachi Network-attached Storage)</link>
arrays such as, HNAS 3000 and 4000 family.</para>
<section xml:id="hds-hnas-supported-operations">
<title>Supported operations</title>
<para>The NFS and iSCSI drivers support these operations:</para>
<itemizedlist>
<listitem>
<para>Create, delete, attach, and detach volumes.</para>
</listitem>
<listitem>
<para>Create, list, and delete volume snapshots.</para>
</listitem>
<listitem>
<para>Create a volume from a snapshot.</para>
</listitem>
<listitem>
<para>Copy an image to a volume.</para>
</listitem>
<listitem>
<para>Copy a volume to an image.</para>
</listitem>
<listitem>
<para>Clone a volume.</para>
</listitem>
<listitem>
<para>Extend a volume.</para>
</listitem>
<listitem>
<para>Get volume statistics.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="hds-hnas-storage-reqs">
<title>HNAS storage requirements</title>
<para>
Before using iSCSI and NFS services, use the HNAS Web
Interface to create storage pool(s), file system(s), and assign
an EVS. Make sure that the file system used is not created as
<literal>replication targets</literal>. Additionally:
</para>
<variablelist>
<varlistentry><term><emphasis>For NFS:</emphasis></term>
<listitem>
<para>
Create NFS exports, choose a path for them (it must
be different from "/") and set the <guilabel>Show
snapshots</guilabel> option to <literal>hide and disable
access</literal>.
</para>
<para>
Also, configure the option <literal>norootsquash
</literal> as <option>"* (rw, norootsquash)",</option> so
cinder services can change the permissions of its volumes.
</para>
<para>
In order to use the hardware accelerated features of
NFS HNAS, we recommend setting <literal>max-nfs-version
</literal> to 3.
Refer to HNAS command line reference to see how to
configure this option.
</para>
</listitem>
</varlistentry>
<varlistentry><term><emphasis>For iSCSI:</emphasis></term>
<listitem>
<para>You need to set an iSCSI domain.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="hds-hnas-cinder-reqs">
<title>Block storage host requirements</title>
<variablelist>
<varlistentry><term><emphasis>All versions:</emphasis></term>
<listitem>
<orderedlist>
<listitem>
<para><package>nfs-utils</package> for RPM packages</para>
</listitem>
<listitem>
<para>
<package>nfs-common</package>, <package>libc6-i386</package>
for DEB packages (<package>libc6-i386</package> only required on
Ubuntu 12.04)
</para>
</listitem>
<listitem>
<para>
HDS SSC package (<package>hds-ssc-v1.0-1</package>) to
communicate with an HNAS array using the <command>SSC
</command> command. This utility package is available
in the RPM package distributed with the hardware
through physical media or it can be manually
copied from the SMU to the Block Storage host.
</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
<varlistentry><term><emphasis>Version: 2.2-1:</emphasis></term>
<listitem>
<orderedlist>
<listitem>
<para>
Icehouse OpenStack deployment for RHOSP 5
(RH 7.0), SUSE Cloud 4, and Mirantis Fuel (Ubuntu or
CentOS hosts)
</para>
</listitem>
<listitem>
<para><package>hds-ssc-v1.0-1</package> package if not using SSH auth
</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="hds-hnas-pkg-install">
<title>Package installation</title>
<procedure>
<para>If you are installing the driver from an RPM or DEB package,
follow the steps bellow:</para>
<step><para>Install SSC:</para>
<screen><prompt>$</prompt> <userinput>rpm -i hds-ssc-v1.0-1.rpm</userinput></screen>
<para>Or in Ubuntu:</para>
<screen><prompt>$</prompt> <userinput>dpkg -i hds-ssc_1.0-1_all.deb</userinput></screen>
</step>
<step><para>Install the dependencies:</para>
<screen><prompt>#</prompt> <userinput>yum install nfs-utils nfs-utils-lib</userinput></screen>
<para>Or in Ubuntu:</para>
<screen><prompt>#</prompt> <userinput>apt-get install nfs-common</userinput></screen>
<para>Or in openSUSE and SUSE Linux Enterprise Server:</para>
<screen><prompt>#</prompt> <userinput>zypper install nfs-client</userinput></screen>
<para>If you are using Ubuntu 12.04, you also need to install
<package>libc6-i386</package></para>
</step>
<step><para>Configure the driver as described in the "Driver
Configuration" section.</para></step>
<step><para>Restart all cinder services (volume, scheduler and
backup).</para></step>
</procedure>
</section>
<section xml:id="hds-hnas-drive-config">
<title>Driver configuration</title>
<para>The HDS driver supports the concept of differentiated
services (also referred to as quality of service) by mapping
volume types to services provided through HNAS.</para>
<para>HNAS supports a variety of storage options and file
system capabilities, which are selected through the definition
of volume types and the use of multiple back ends. The driver
maps up to four volume types into separated exports or file
systems, and can support any number if using multiple back
ends.</para>
<para>The configuration for the driver is read from an
XML-formatted file (one per back end), which you need to create
and set its path in the <filename>cinder.conf</filename> configuration
file. Below are the configuration needed in
the <filename>cinder.conf</filename> configuration file
<footnote xml:id="hds-hnas-no-fixed-location-1">
<para>The configuration file location may differ.</para>
</footnote>:
</para>
<programlisting language="ini">[DEFAULT]
enabled_backends = hnas_iscsi1, hnas_nfs1</programlisting>
<para>For HNAS iSCSI driver create this section:</para>
<programlisting language="ini">[hnas_iscsi1]
volume_driver = cinder.volume.drivers.hds.iscsi.HDSISCSIDriver
hds_hnas_iscsi_config_file = <replaceable>/path/to/config/hnas_config_file.xml</replaceable>
volume_backend_name = <replaceable>HNAS-ISCSI</replaceable></programlisting>
<para>For HNAS NFS driver create this section:</para>
<programlisting language="ini">[hnas_nfs1]
volume_driver = cinder.volume.drivers.hds.nfs.HDSNFSDriver
hds_hnas_nfs_config_file = <replaceable>/path/to/config/hnas_config_file.xml</replaceable>
volume_backend_name = <replaceable>HNAS-NFS</replaceable></programlisting>
<para>The XML file has the following format:
</para>
<programlisting language="xml">&lt;?xml version = "1.0" encoding = "UTF-8" ?&gt;
&lt;config&gt;
&lt;mgmt_ip0&gt;172.24.44.15&lt;/mgmt_ip0&gt;
&lt;hnas_cmd&gt;ssc&lt;/hnas_cmd&gt;
&lt;chap_enabled&gt;False&lt;/chap_enabled&gt;
&lt;ssh_enabled&gt;False&lt;/ssh_enabled&gt;
&lt;cluster_admin_ip0&gt;10.1.1.1&lt;/cluster_admin_ip0&gt;
&lt;username&gt;supervisor&lt;/username&gt;
&lt;password&gt;supervisor&lt;/password&gt;
&lt;svc_0&gt;
&lt;volume_type&gt;default&lt;/volume_type&gt;
&lt;iscsi_ip&gt;172.24.44.20&lt;/iscsi_ip&gt;
&lt;hdp&gt;fs01-husvm&lt;/hdp&gt;
&lt;/svc_0&gt;
&lt;svc_1&gt;
&lt;volume_type&gt;platinun&lt;/volume_type&gt;
&lt;iscsi_ip&gt;172.24.44.20&lt;/iscsi_ip&gt;
&lt;hdp&gt;fs01-platinun&lt;/hdp&gt;
&lt;/svc_1&gt;
&lt;/config&gt;</programlisting>
</section>
<section xml:id="hds-hnas-xml-config-options">
<title>HNAS volume driver XML configuration options</title>
<para>An OpenStack Block Storage node using HNAS drivers can have up to
four services. Each service is defined by a <literal>svc_n
</literal> tag (<literal>svc_0</literal>, <literal>svc_1</literal>,
<literal>svc_2</literal>, or <literal>svc_3</literal>
<footnote xml:id="hds-hnas-stats-all-hdp">
<para>There is no relative precedence or weight among these
four labels.</para>
</footnote>, for example). These are the configuration options
avaliable for each service label:
</para>
<table rules="all">
<caption>Configuration options for service labels</caption>
<col width="25%"/>
<col width="10%"/>
<col width="15%"/>
<col width="50%"/>
<thead>
<tr>
<td>Option</td>
<td>Type</td>
<td>Default</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>
<para><option>volume_type</option></para>
</td>
<td><para>Required</para></td>
<td><para><literal>default</literal></para></td>
<td>
<para>
When a <literal>create_volume</literal> call with
a certain volume type happens, the volume type will
try to be matched up with this tag. In each
configuration file you must define the <literal>
default</literal> volume type in the service
labels and, if no volume type is specified, the
<literal>default</literal> is used. Other labels
are case sensitive and should match exactly. If no
configured volume types match the incoming
requested type, an error occurs in the volume
creation.
</para>
</td>
</tr>
<tr>
<td>
<para><option>iscsi_ip</option></para>
</td>
<td><para>Required only for iSCSI</para></td>
<td><para/></td>
<td>
<para>
An iSCSI IP address dedicated to the service.
</para>
</td>
</tr>
<tr>
<td>
<para><option>hdp</option></para>
</td>
<td><para>Required</para></td>
<td><para/></td>
<td>
<para>
For iSCSI driver: virtual file system label
associated with the service.
</para>
<para>
For NFS driver: path to the volume
(&lt;ip_address&gt;:/&lt;path&gt;) associated with
the service.
</para>
<para>
Additionally, this entry must be added in the file
used to list available NFS shares. This file is
located, by default, in
<filename>/etc/cinder/nfs_shares</filename> or you
can specify the location in the
<literal>nfs_shares_config</literal> option in the
<filename>cinder.conf</filename> configuration file.
</para>
</td>
</tr>
</tbody>
</table>
<para>
These are the configuration options available to the
<literal>config</literal> section of the XML config file:
</para>
<table rules="all">
<caption>Configuration options</caption>
<col width="25%"/>
<col width="10%"/>
<col width="15%"/>
<col width="50%"/>
<thead>
<tr>
<td>Option</td>
<td>Type</td>
<td>Default</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td><para><option>mgmt_ip0</option></para>
</td>
<td><para>Required</para></td>
<td><para/></td>
<td>
<para>
Management Port 0 IP address. Should be the IP
address of the "Admin" EVS.
</para>
</td>
</tr>
<tr>
<td><para><option>hnas_cmd</option></para>
</td>
<td><para>Optional</para></td>
<td><para>ssc</para></td>
<td>
<para>
Command to communicate to HNAS array.
</para>
</td>
</tr>
<tr>
<td><para><option>chap_enabled</option></para>
</td>
<td><para>Optional (iSCSI only)</para></td>
<td><para><literal>True</literal></para></td>
<td>
<para>
Boolean tag used to enable CHAP authentication
protocol.
</para>
</td>
</tr>
<tr>
<td><para><option>username</option></para>
</td>
<td><para>Required</para></td>
<td><para>supervisor</para></td>
<td>
<para>It's always required on HNAS.</para>
</td>
</tr>
<tr>
<td><para><option>password</option></para>
</td>
<td><para>Required</para></td>
<td><para>supervisor</para></td>
<td>
<para>Password is always required on HNAS.</para>
</td>
</tr>
<tr>
<td>
<para>
<option>svc_0, svc_1, svc_2, svc_3</option>
</para>
</td>
<td>
<para>Optional</para>
</td>
<td>
<para>
(at least one label has to be defined)
</para>
</td>
<td>
<para>
Service labels: these four predefined
names help four different sets of
configuration options. Each can specify
HDP and a unique volume type.
</para>
</td>
</tr>
<tr>
<td>
<para>
<option>cluster_admin_ip0</option>
</para>
</td>
<td>
<para>Optional if <option>ssh_enabled</option>
is <literal>True</literal></para>
</td>
<td>
</td>
<td>
<para>
The address of HNAS cluster admin.
</para>
</td>
</tr>
<tr>
<td>
<para>
<option>ssh_enabled</option>
</para>
</td>
<td>
<para>Optional</para>
</td>
<td>
<para><literal>False</literal></para>
</td>
<td>
<para>
Enables SSH authentication between Block Storage
host and the SMU.
</para>
</td>
</tr>
<tr>
<td>
<para>
<option>ssh_private_key</option>
</para>
</td>
<td>
<para>Required if <literal>ssh_enabled</literal> is
<literal>True</literal></para>
</td>
<td>
<para><literal>False</literal></para>
</td>
<td>
<para>
Path to the SSH private key used to authenticate
in HNAS SMU. The public key must be uploaded to
HNAS SMU using <literal>ssh-register-public-key
</literal> (this is an SSH subcommand). Note that
copying the public key HNAS using
<literal>ssh-copy-id</literal> doesn't work
properly as the SMU periodically wipe out those
keys.
</para>
</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="hds-hnas-service-labels">
<title>Service labels</title>
<para>
HNAS driver supports differentiated types of service using the service
labels. It is possible to create up to four types of them, as gold,
platinun, silver and ssd, for example.
</para>
<para>
Each service is treated by OpenStack Block Storage as a unit of
scheduling (pool). After creating the services in the XML
configuration file, you must configure one
<literal>volume_type</literal> per service. Each <literal>
volume_type</literal> must have the metadata <literal>
service_label</literal> with the same name configured in the
<literal>&lt;volume_type&gt; </literal> section of that
service. If this is not set, OpenStack Block Storage will
schedule the volume creation to the pool with largest avaliable
free space or other criteria configured in volume filters.
</para>
<screen><prompt>$</prompt> <userinput>cinder type-create 'default'</userinput>
<prompt>$</prompt> <userinput>cinder type-key 'default' set service_label = 'default'</userinput>
<prompt>$</prompt> <userinput>cinder type-create 'platinun-tier'</userinput>
<prompt>$</prompt> <userinput>cinder type-key 'platinun' set service_label = 'platinun'</userinput></screen>
</section>
<section xml:id="hds-hnas-multibend-config">
<title>Multi-back-end configuration</title>
<para>
If you use multiple back ends and intend to enable the creation of
a volume in a specific back end, you must configure volume types to
set the <literal>volume_backend_name</literal> option to the
appropriate back end. Then, create <literal>volume_type</literal>
configurations with the same <literal>volume_backend_name
</literal>.
</para>
<screen><prompt>$</prompt> <userinput>cinder type-create 'iscsi'</userinput>
<prompt>$</prompt> <userinput>cinder type-key 'iscsi' set volume_backend_name = 'HNAS-ISCSI'</userinput>
<prompt>$</prompt> <userinput>cinder type-create 'nfs'</userinput>
<prompt>$</prompt> <userinput>cinder type-key 'nfs' set volume_backend_name = 'HNAS-NFS'</userinput></screen>
<para>
You can deploy multiple OpenStack HNAS drivers instances that each
control a separate HNAS array. Each service (<literal>svc_0, svc_1,
svc_2, svc_3</literal>) on the instances need to have a volume_type
and service_label metadata associated with it. If no metadata is
associated with a pool, OpenStack Block Storage filtering algorithm
selects the pool with the largest available free space.
</para>
</section>
<section xml:id="hds-hnas-ssh-config">
<title>SSH configuration</title>
<para>
Instead of using <command>SSC</command> on the Block Storage host
and store its credential on the XML configuration file, HNAS driver
supports <command>SSH</command> authentication. To configure that:
</para>
<procedure>
<step>
<para>
Create a pair of public keys in the Block Storage host
(leave the pass-phrase empty):
</para>
<screen><prompt>$</prompt> <userinput>mkdir -p <replaceable>/opt/hds/ssh</replaceable></userinput></screen>
</step>
<step>
<para>
Change the owner of the key to <literal>cinder</literal>
(or the user the volume service will be run):
</para>
<screen><prompt>#</prompt> <userinput>chown -R cinder.cinder <replaceable>/opt/hds/ssh</replaceable></userinput></screen>
</step>
<step>
<para>
Export your pubkey to SMU (HNAS):
</para>
<screen><prompt>$</prompt> <userinput>ssh-copy-id -i <replaceable>/opt/hds/ssh/hnaskey.pub</replaceable> [manager|supervisor]@&lt;smu-ip&gt;</userinput></screen>
</step>
<step>
<para>
Check the communication with HNAS:
</para>
<screen><prompt>$</prompt> <userinput>ssh [manager|supervisor]@&lt;smu-ip&gt; 'ssc &lt;cluster_admin_ip0&gt; df -a'</userinput></screen>
</step>
</procedure>
<para>
<literal>&lt;cluster_admin_ip0&gt;</literal> is "localhost" for
single node deployments. This should return a list of avaliable
file systems on HNAS.
</para>
</section>
<section xml:id="hds-hnas-xml-config">
<title>Editing the XML config file:</title>
<orderedlist>
<listitem>
<para>
Set the "username".
</para>
</listitem>
<listitem>
<para>
Enable SSH adding the line <literal>"&lt;ssh_enabled&gt;
True&lt;/ssh_enabled&gt;"</literal> under <literal>
"&lt;config&gt;"</literal> session.
</para>
</listitem>
<listitem>
<para>
Set the private key path: <literal>"&lt;ssh_private_key&gt;
/opt/hds/ssh/hnaskey&lt;/ssh_private_key&gt;" </literal>under
<literal>"&lt;config&gt;"</literal> session.
</para>
</listitem>
<listitem>
<para>
If the HNAS is in a multi-cluster configuration set <literal>
"&lt;cluster_admin_ip0&gt;"</literal> to the cluster
node admin IP. In a single node HNAS, leave it empty.
</para>
</listitem>
<listitem>
<para>
Restart the cinder service.
</para>
</listitem>
</orderedlist>
</section>
<section xml:id="hds-hnas-additional-notes">
<title>Additional notes</title>
<itemizedlist>
<listitem>
<para>
The <literal>get_volume_stats()</literal> function always
provides the available capacity based on the
combined sum of all the HDPs that are used in these
services labels.
</para>
</listitem>
<listitem>
<para>
After changing the configuration on the storage,
the OpenStack Block Storage driver must be
restarted.
</para>
</listitem>
<listitem>
<para>
HNAS iSCSI driver, due to an HNAS limitation,
allows only 32 volumes per target.
</para>
</listitem>
<listitem>
<para>
On RedHat, if the system is configured to use SELinux, you
need to set <option>"virt_use_nfs = on"</option> for NFS
driver work properly.
</para>
</listitem>
</itemizedlist>
</section>
</section>