259 lines
16 KiB
XML
259 lines
16 KiB
XML
<section xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xml:id="zfssa-nfs-driver" version="5.0">
|
|
<title>Oracle ZFS Storage Appliance NFS driver</title>
|
|
<para>The Oracle ZFS Storage Appliance (ZFSSA) NFS driver enables the
|
|
ZFSSA to be used seamlessly as a block storage resource. The driver enables you to
|
|
to create volumes on a ZFS share that is NFS mounted.
|
|
</para>
|
|
<simplesect>
|
|
<title>Requirements</title>
|
|
<para>Oracle ZFS Storage Appliance Software version <literal>2013.1.2.0</literal> or later</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Supported operations</title>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Create, extend, delete volumes</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Attach and detach volumes</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Create, delete 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>Volume migration</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Local cache of a bootable volume</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Appliance configuration</title>
|
|
<para>Appliance configuration using the command line interface (CLI) is described
|
|
below. To access the CLI, ensure SSH remote access is enabled, which is the default. You
|
|
can also perform configuration using the browser user interface (BUI) or the RESTful
|
|
API. Please refer to the <link
|
|
xlink:href="http://www.oracle.com/technetwork/documentation/oracle-unified-ss-193371.html">
|
|
Oracle ZFS Storage Appliance documentation</link>
|
|
for details on how to configure the Oracle ZFS Storage Appliance using the BUI, CLI and RESTful API.
|
|
</para>
|
|
<procedure>
|
|
<step>
|
|
<para>Log in to the Oracle ZFS Storage Appliance CLI and enable the REST
|
|
service. REST service needs to stay online for this driver to function.</para>
|
|
<screen><prompt>zfssa:></prompt><userinput>configuration services rest enable</userinput></screen>
|
|
</step>
|
|
<step>
|
|
<para>Create a new storage pool on the appliance if you do not want to use an
|
|
existing one. This storage pool is named <literal>'mypool'</literal> for the sake of this documentation.</para>
|
|
</step>
|
|
<step>
|
|
<para>Create a new project and share in the storage pool (<literal>mypool</literal>) if you do not want to use
|
|
existing ones. This driver will create a project and share by the names specified in <filename>cinder.conf</filename>, if the
|
|
a project or share by that name does not already exist in the storage pool (<literal>mypool</literal>).
|
|
The project and share are named '<literal>NFSProject</literal>' and '<literal>nfs_share</literal>' in the sample <filename>cinder.conf</filename> entries below.</para>
|
|
</step>
|
|
<step>
|
|
<para>To perform driver operations, create a role with the following
|
|
authorizations:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><code>scope=svc - allow_administer=true, allow_restart=true, allow_configure=true</code></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><code>scope=nas - pool=pool_name, project=project_name, share=share_name, allow_clone=true, allow_createProject=true, allow_createShare=true, allow_changeSpaceProps=true, allow_changeGeneralProps=true, allow_destroy=true, allow_rollback=true, allow_takeSnap=true</code></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>The following examples show how to create a role with authorizations.</para>
|
|
<screen><prompt>zfssa:></prompt> <userinput>configuration roles</userinput>
|
|
<prompt>zfssa:configuration roles></prompt> <userinput>role OpenStackRole</userinput>
|
|
<prompt>zfssa:configuration roles OpenStackRole (uncommitted)></prompt> <userinput>set description="OpenStack NFS Cinder Driver"</userinput>
|
|
<prompt>zfssa:configuration roles OpenStackRole (uncommitted)></prompt> <userinput>commit</userinput>
|
|
<prompt>zfssa:configuration roles></prompt> <userinput>select OpenStackRole</userinput>
|
|
<prompt>zfssa:configuration roles OpenStackRole></prompt> <userinput>authorizations create</userinput>
|
|
<prompt>zfssa:configuration roles OpenStackRole auth (uncommitted)></prompt> <userinput>set scope=svc</userinput>
|
|
<prompt>zfssa:configuration roles OpenStackRole auth (uncommitted)></prompt> <userinput>set allow_administer=true</userinput>
|
|
<prompt>zfssa:configuration roles OpenStackRole auth (uncommitted)></prompt> <userinput>set allow_restart=true</userinput>
|
|
<prompt>zfssa:configuration roles OpenStackRole auth (uncommitted)></prompt> <userinput>set allow_configure=true</userinput>
|
|
<prompt>zfssa:configuration roles OpenStackRole auth (uncommitted)></prompt> <userinput>commit</userinput></screen>
|
|
<screen><prompt>zfssa:></prompt> <userinput>configuration roles OpenStackRole authorizations> set scope=nas</userinput></screen>
|
|
<para>The following properties need to be set when the scope of this role needs to be limited to a pool (<literal>mypool</literal>), a project (<literal>NFSProject</literal>) and a
|
|
share (<literal>nfs_share</literal>) created in the steps above. This will prevent the user assigned to this role from being used to modify other pools, projects and shares.</para>
|
|
<screen><prompt>zfssa:configuration roles OpenStackRole auth (uncommitted)></prompt> <userinput>set pool=mypool</userinput>
|
|
<prompt>zfssa:configuration roles OpenStackRole auth (uncommitted)></prompt> <userinput>set project=NFSProject</userinput>
|
|
<prompt>zfssa:configuration roles OpenStackRole auth (uncommitted)></prompt> <userinput>set share=nfs_share</userinput></screen>
|
|
|
|
<para>The following properties only need to be set when a share or a project has not been created following the steps above and wish to allow
|
|
the driver to create them for you.</para>
|
|
<screen><prompt>zfssa:configuration roles OpenStackRole auth (uncommitted)></prompt> <userinput>set allow_createProject=true</userinput>
|
|
<prompt>zfssa:configuration roles OpenStackRole auth (uncommitted)></prompt> <userinput>set allow_createShare=true</userinput></screen>
|
|
<screen><prompt>zfssa:configuration roles OpenStackRole auth (uncommitted)></prompt> <userinput>set allow_clone=true</userinput>
|
|
<prompt>zfssa:configuration roles OpenStackRole auth (uncommitted)></prompt> <userinput>set allow_changeSpaceProps=true</userinput>
|
|
<prompt>zfssa:configuration roles OpenStackRole auth (uncommitted)></prompt> <userinput>set allow_destroy=true</userinput>
|
|
<prompt>zfssa:configuration roles OpenStackRole auth (uncommitted)></prompt> <userinput>set allow_rollback=true</userinput>
|
|
<prompt>zfssa:configuration roles OpenStackRole auth (uncommitted)></prompt> <userinput>set allow_takeSnap=true</userinput>
|
|
<prompt>zfssa:configuration roles OpenStackRole auth (uncommitted)></prompt> <userinput>commit</userinput></screen>
|
|
</step>
|
|
<step>
|
|
<para>Create a new user or modify an existing one and assign the new role to the
|
|
user.</para>
|
|
<para>The following example shows how to create a new user and assign the new role
|
|
to the user.</para>
|
|
<screen><prompt>zfssa:></prompt> <userinput>configuration users</userinput>
|
|
<prompt>zfssa:configuration users></prompt> <userinput>user cinder</userinput>
|
|
<prompt>zfssa:configuration users cinder (uncommitted)></prompt> <userinput>set fullname="OpenStack Cinder Driver"</userinput>
|
|
<prompt>zfssa:configuration users cinder (uncommitted)></prompt> <userinput>set initial_password=12345</userinput>
|
|
<prompt>zfssa:configuration users cinder (uncommitted)></prompt> <userinput>commit</userinput>
|
|
<prompt>zfssa:configuration users></prompt> <userinput>select cinder set roles=OpenStackRole</userinput></screen>
|
|
</step>
|
|
<step>
|
|
<para>Ensure that NFS and HTTP services on the appliance are online. Note the HTTPS
|
|
port number for later entry in the cinder service configuration file (<filename>cinder.conf</filename>). This driver uses WebDAV
|
|
over HTTPS to create snapshots and clones of volumes, and therefore needs to have the HTTP service online.</para>
|
|
<para>The following example illustrates enabling the services and showing
|
|
their properties.</para>
|
|
<screen><prompt>zfssa:></prompt> <userinput>configuration services nfs</userinput>
|
|
<prompt>zfssa:configuration services nfs></prompt> <userinput>enable</userinput>
|
|
<prompt>zfssa:configuration services nfs></prompt> <userinput>show</userinput>
|
|
<computeroutput>Properties:
|
|
<status>= online
|
|
...</computeroutput></screen>
|
|
<screen><prompt>zfssa:configuration services http></prompt> <userinput>enable</userinput>
|
|
<prompt>zfssa:configuration services http></prompt> <userinput>show</userinput>
|
|
<computeroutput>Properties:
|
|
<status>= online
|
|
require_login = true
|
|
protocols = http/https
|
|
listen_port = 80
|
|
https_port = 443</computeroutput></screen>
|
|
</step>
|
|
<step>
|
|
<para>Create a network interface to be used exclusively for data. An existing network interface may also be used. The following example
|
|
illustrates how to make a network interface for data traffic flow only.</para>
|
|
<note>
|
|
<para>For better performance and reliability, it is recommended to configure a separate subnet exclusively for data traffic in your cloud environment.</para>
|
|
</note>
|
|
<screen><prompt>zfssa:></prompt> <userinput>configuration net interfaces</userinput>
|
|
<prompt>zfssa:configuration net interfaces></prompt> <userinput>select igbx</userinput>
|
|
<prompt>zfssa:configuration net interfaces igbx></prompt> <userinput>set admin=false</userinput>
|
|
<prompt>zfssa:configuration net interfaces igbx></prompt> <userinput>commit</userinput></screen>
|
|
</step>
|
|
<step>
|
|
<para>For clustered controller systems, the following verification is required in addition to the above steps.
|
|
Skip this step if a standalone system is used.</para>
|
|
<screen>zfssa:> <userinput>configuration cluster resources list</userinput></screen>
|
|
<para>Verify that both the newly created pool and the network interface are of type "<literal>singleton</literal>" and
|
|
are not locked to the current controller. This approach ensures that the pool and the interface used
|
|
for data always belong to the active controller, regardless of the current state of the cluster.
|
|
|
|
Verify that both the network interface used for management and data, and the storage pool belong to the same head.</para>
|
|
<note>
|
|
<para>There will be a short service interruption during failback/takeover, but once the process is complete,
|
|
the driver should be able to access the ZFSSA for data as well as for management.</para>
|
|
</note>
|
|
</step>
|
|
</procedure>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Cinder service configuration</title>
|
|
<procedure>
|
|
<step>
|
|
<para>Define the following required properties in the
|
|
<filename>cinder.conf</filename> configuration file:</para>
|
|
<programlisting language="ini">volume_driver = cinder.volume.drivers.zfssa.zfssanfs.ZFSSANFSDriver
|
|
san_ip = <replaceable>myhost</replaceable>
|
|
san_login = <replaceable>username</replaceable>
|
|
san_password = <replaceable>password</replaceable>
|
|
zfssa_data_ip = <replaceable>mydata</replaceable>
|
|
zfssa_nfs_pool = <replaceable>mypool</replaceable></programlisting>
|
|
<note>
|
|
<para>Management interface <literal>san_ip</literal> can be used instead of
|
|
<literal>zfssa_data_ip</literal>, but it is not recommended.
|
|
</para>
|
|
</note>
|
|
</step>
|
|
<step>
|
|
<para>You can also define the following additional properties in the
|
|
<filename>cinder.conf</filename> configuration file:</para>
|
|
<programlisting language="ini">zfssa_nfs_project = <replaceable>NFSProject</replaceable>
|
|
zfssa_nfs_share = <replaceable>nfs_share</replaceable>
|
|
zfssa_nfs_mount_options = <replaceable></replaceable>
|
|
zfssa_nfs_share_compression = <replaceable>off</replaceable>
|
|
zfssa_nfs_share_logbias = <replaceable>latency</replaceable>
|
|
zfssa_https_port = <replaceable>443</replaceable></programlisting>
|
|
</step>
|
|
</procedure>
|
|
<note>
|
|
<para>The driver does not use the file specified in the <literal>nfs_shares_config</literal>
|
|
option.</para>
|
|
</note>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Driver options</title>
|
|
<para>The Oracle ZFS Storage Appliance NFS driver supports these options:</para>
|
|
<xi:include href="../../../common/tables/cinder-zfssa-nfs.xml"/>
|
|
<para>This driver shares additional NFS configuration options with the generic NFS driver.
|
|
For a description of these, see <xref linkend="config_table_cinder_storage_nfs"/>.
|
|
</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>ZFSSA local cache</title>
|
|
<para>The local cache feature enables ZFSSA drivers to serve the usage of bootable volumes significantly better. With the feature,
|
|
the first bootable volume created from an image is cached, so that subsequent volumes can be created directly from the cache,
|
|
instead of having image data transferred over the network multiple times.
|
|
</para>
|
|
<para>The following conditions must be met in order to use ZFSSA local cache feature:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>A storage pool needs to be configured.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>REST and NFS services need to be turned on.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>On an OpenStack controller, <filename>cinder.conf</filename> needs to contain necessary properties used to configure and
|
|
set up the ZFSSA NFS driver, including the following new properties:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><literal>zfssa_enable_local_cache</literal>: (True/False) To enable/disable the feature.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><literal>zfssa_cache_directory</literal>: The directory name inside zfssa_nfs_share where cache volumes are stored.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Every cache volume has two additional properties stored as WebDAV properties. It is important that they are not altered outside of
|
|
Block Storage when the driver is in use:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><literal>image_id</literal>: stores the image id as in Image service.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><literal>updated_at</literal>: stores the most current timestamp when the image is updated in Image service.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
</section>
|