openstack/manila
Code Issues Proposed changes

doc migration: admin guide

Browse Source 
Migrate the shared file systems documents from the
centralized Admin Guide as outlined in the migration
spec [1].

[1] https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html

Partial-Bug: #1706181
Needed-By: Ibe3588c3f4560c037cf109058fc357234e70a846
Depends-On: Ieea33262101a1d2459492c1c8aaac5fe042279f6
Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454

Change-Id: I7924d94b82e7c8d9716bad7a219fc38c57970773
This commit is contained in:
Tom Barron 2017-08-08 05:30:33 -04:00
parent 90060722a9
commit 2be2160ddb
25 changed files with 3396 additions and 342 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
doc/source/admin/index.rst
View File

@ -1,22 +0,0 @@
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Admin Reference
---------------
.. toctree::
:maxdepth: 3
intro
multi_backends
network_plugins

25
doc/source/admin/intro.rst
View File

@ -1,25 +0,0 @@
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Introduction to Manila Shared Filesystem Management Service
===========================================================
:term:`manila` is the File Share service project for OpenStack. To administer the
OpenStack File Share service, it is helpful to understand a number of concepts
like share networks, shares, multi-tenancy and back ends that can be configured
with Manila. When configuring the File Share service, it is required to declare
at least one back end. Manila can be configured to run in a single-node
configuration or across multiple nodes. Manila can be configured to provision
shares from one or more back ends.
The OpenStack File Share service allows you to offer file-share services to
users of an OpenStack installation.

89
doc/source/admin/multi_backends.rst
View File

@ -1,89 +0,0 @@
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Configure multiple back ends
============================
An administrator can configure an instance of Manila to provision shares from
one or more back ends. Each back end leverages an instance of a vendor-specific
implementation of the Manila driver API.
The name of the back end is declared as a configuration option
share_backend_name within a particular configuration stanza that contains the
related configuration options for that back end.
Administrators can specify that a particular share type be explicitly
associated with a single back end by including the extra spec
share_backend_name with the name specified within the back end configuration
stanza. When the Manila scheduler receives a provisioning request for a share
type with this extra spec set, it will fulfill the share provisioning request
on the specified back end (assuming all other scheduling criteria including
available capacity are met).
Enable multiple back ends
=========================
To enable multiple share back ends, you must set the enabled_share_backends
flag in the manila.conf file. This flag defines the names (separated by a
comma) of the configuration stanzas for the different back ends: one name is
associated to one configuration group for a back end.
The following example shows five configured back ends::
[DEFAULT]
enabled_share_backends=backendEMC1,backendEMC2,backendGeneric1,backendGeneric2,backendNetApp
[backendEMC1]
share_driver=manila.share.drivers.dell_emc.driver.EMCShareDriver
share_backend_name=backendEMC1
emc_share_backend=vnx
emc_nas_server=1.1.1.1
emc_nas_password=password
emc_nas_login=user
emc_nas_server_container=server_2
emc_nas_pool_name="Pool 1"
[backendEMC2]
share_driver=manila.share.drivers.dell_emc.driver.EMCShareDriver
share_backend_name=backendEMC2
emc_share_backend=vnx
emc_nas_server=1.1.1.1
emc_nas_password=password
emc_nas_login=user
emc_nas_server_container=server_3
emc_nas_pool_name="Pool 2"
[backendGeneric1]
share_driver=manila.share.drivers.generic.GenericShareDriver
share_backend_name=one_name_for_two_backends
service_instance_user=ubuntu_user
service_instance_password=ubuntu_user_password
service_image_name=ubuntu_image_name
path_to_private_key=/home/foouser/.ssh/id_rsa
path_to_public_key=/home/foouser/.ssh/id_rsa.pub
[backendGeneric2]
share_driver=manila.share.drivers.generic.GenericShareDriver
share_backend_name=one_name_for_two_backends
service_instance_user=centos_user
service_instance_password=centos_user_password
service_image_name=centos_image_name
path_to_private_key=/home/baruser/.ssh/id_rsa
path_to_public_key=/home/baruser/.ssh/id_rsa.pub
[backendNetApp]
share_driver = manila.share.drivers.netapp.common.NetAppDriver
driver_handles_share_servers = True
share_backend_name=backendNetApp
netapp_login=user
netapp_password=password
netapp_server_hostname=1.1.1.1
netapp_root_volume_aggregate=aggr01

205
doc/source/admin/network_plugins.rst
View File

@ -1,205 +0,0 @@
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Manila Network Plugins
======================
The Manila architecture defines an abstraction layer for network resource
provisioning, and it provides a number of concrete `network plugins`,
allowing administrators to choose from a variety of options for how network
resources are assigned to their tenants' networked storage. This document
describes how network plugins may be configured and used in Manila.
What is a network plugin in Manila?
-----------------------------------
A network plugin is a python class that uses a specific facility (e.g.
Neutron or Nova network) to provide network resources to the
:term:`manila-share` service.
When to use a network plugin?
-----------------------------
A Manila `share driver` may be configured in one of two modes, where it is
managing the lifecycle of `share servers` on its own or where it is merely
providing storage resources on a pre-configured share server. This mode
is defined using the boolean option `driver_handles_share_servers` in the
Manila configuration file. A network plugin is only useful when a driver is
handling its own share servers.
.. note::
Not all share drivers support both modes. Each driver must report which
mode(s) it supports to the manila-share service.
When `driver_handles_share_servers` is set to `True`, a share driver will be
called to create share servers for shares using information provided within a
`share network`. This information will be provided to one of the enabled
network plugins that will handle reservation, creation and deletion of
network resources including `IP addresses` and `network interfaces`.
As an exception, any share drivers that use Nova for the creation of share
servers should use some wrapper for network plugins, because Nova handles the
creation of network resources for its VMs. In the Manila Kilo version, only
the `Generic driver` uses Nova with the help of its own `network helpers`,
which serve the same needs but are related only to this share driver.
.. _what_network_plugins_are_available:
What network plugins are available?
-----------------------------------
There are three different network plugins and five python classes in Manila:
1 Network plugin for using the `OpenStack` networking project `Neutron`.
It allows one to use any network segmentation that Neutron supports. It is
up to each share driver to support at least one network segmentation type.
1.1 `manila.network.neutron.neutron_network_plugin.NeutronNetworkPlugin`.
This is the default network plugin. It requires that `neutron_net_id` and
`neutron_subnet_id` are provided when defining the share network that
will be used for the creation of share servers. The user may define any
number of share networks corresponding to the various physical network
segments in a tenant environment.
1.2 `manila.network.neutron.neutron_network_plugin.NeutronSingleNetworkPlugin`.
This is a simplification of the previous case. It accepts values for
`neutron_net_id` and `neutron_subnet_id` from the Manila configuration
file and uses one network for all shares.
1.3 `manila.network.neutron.neutron_network_plugin.NeutronBindNetworkPlugin`.
This driver waits for active binding and fails if a Neutron port can't be
bound or an error occurs. This plugin is useful for agent based binding
(like OVS with docker driver) and fabric binding where real HW
reconfiguration is taking place. The existing
`NeutronBindSingleNetworkPlugin` is a combination of 1.2 and 1.3.
When only a single network is needed, the NeutronSingleNetworkPlugin (1.2)
is a simple solution. Otherwise NeutronNetworkPlugin (1.1) should be chosen.
2 Network plugin for working with OpenStack native networking from `Nova`.
It supports either flat networks or VLAN-segmented networks.
2.1 `manila.network.nova_network_plugin.NovaNetworkPlugin`.
This plugin serves the networking needs when `Nova networking` is
configured in the cloud instead of Neutron. It requires a single
parameter, `nova_net_id`.
2.2 `manila.network.nova_network_plugin.NovaSingleNetworkPlugin`.
This one works in the same way as the previous one with one difference.
It takes nova_net_id from the Manila configuration file and creates
share servers using only one network.
When only a single network is needed, the NovaSingleNetworkPlugin (2.2)
is a simple solution. Otherwise NovaNetworkPlugin (1.1) should be chosen.
3 Network plugin for specifying networks independently from OpenStack
networking services.
3.1 `manila.network.standalone_network_plugin.StandaloneNetworkPlugin`.
This plug-in uses a pre-existing network that is available to the
manila-share host. This network may be handled either by OpenStack or be
created independently by any other means. The plugin supports any type of
network - flat and segmented. As above, it is completely up to the driver
to support the network type for which the network plugin is configured.
.. note::
These network plugins were introduced in the OpenStack Kilo release.
In the OpenStack Juno version, only NeutronNetworkPlugin is available.
Plugins in 1.2, 2.2, and 3.1 all ignore what the user supplies in the
share_network and instead always provide IP addresses from a single
network.
Approaches for setup of network plugins
---------------------------------------
Each manila-share service may have its own network plugin or one that is
shared with other services. All configuration options for network plugins may
be set in three ways by priorities:
- Using a separate configuration group.
For this case, the config opt `network_config_group` should be defined in
the config group of the manila-share service and have the name of
the config group with the defined options for the network plugin.
First priority.
- Using config group of manila-share service. Second priority.
- Using config group `[DEFAULT]`. Lowest priority.
A specific network plugin is enabled by setting the configuration option
`network_api_class` to one of the values defined in the previous section
:ref:`what_network_plugins_are_available`. This option can be defined in any
of the approaches above along with options for the network plugin itself.
Example of network plugin configuration
---------------------------------------
Let's configure three manila-share services that use different approaches for
configuration of network plugins.
As noted in section :ref:`what_network_plugins_are_available`, in the Kilo
version of OpenStack there are 5 (five) network plugins, three of which
require configuration options - 1.2, 2.2 and 3.1.
We will use a configuration example using network plugin 1.2, the
NeutronSingleNetworkPlugin.
Here is the configuration::
[DEFAULT]
enabled_share_backends = SHARE_BACKEND_1,SHARE_BACKEND_2,SHARE_BACKEND_3
network_api_class = manila.network.neutron.neutron_network_plugin.NeutronSingleNetworkPlugin
neutron_net_id = neutron_net_id_DEFAULT
neutron_subnet_id = neutron_subnet_id_DEFAULT
[NETWORK_PLUGIN]
neutron_net_id = neutron_net_id_NETWORK_PLUGIN
neutron_subnet_id = neutron_subnet_id_NETWORK_PLUGIN
[SHARE_BACKEND_1]
# This share backend is enabled for handling of share servers using opts
# for network plugin defined in separate config group called `NETWORK_PLUGIN`.
network_config_group = NETWORK_PLUGIN
driver_handles_share_servers = True
[SHARE_BACKEND_2]
# This share backend is enabled for handling of share servers using opts
# defined in its own config group.
driver_handles_share_servers = True
neutron_net_id = neutron_net_id_SHARE_BACKEND_2
neutron_subnet_id = neutron_subnet_id_SHARE_BACKEND_2
[SHARE_BACKEND_3]
# This share backend is enabled for handling of share servers using opts
# defined in config group [DEFAULT].
driver_handles_share_servers = True
Here is a list of neutron_net_id and neutron_subnet_id values for our
manila-share services:
- [SHARE_BACKEND_1]
- neutron_net_id=neutron_net_id_NETWORK_PLUGIN
- neutron_subnet_id=neutron_subnet_id_NETWORK_PLUGIN
- [SHARE_BACKEND_2]
- neutron_net_id=neutron_net_idSHARE_BACKEND_2
- neutron_subnet_id=neutron_subnet_id_SHARE_BACKEND_2
- [SHARE_BACKEND_3]
- neutron_net_id=neutron_net_id_DEFAULT
- neutron_subnet_id=neutron_subnet_id_DEFAULT
The value for option network_api_class was taken by each manila-share service
from group [DEFAULT] because it was not redefined in other places.
.. note::
The last approach - use of [DEFAULT] group - is not preferred for setting
network plugin options and will generate warnings in your manila-share
logs. Either of the first two approaches is recommended.

771
doc/source/admin/shared-file-systems-crud-share.rst Normal file
View File

@ -0,0 +1,771 @@
.. _shared_file_systems_crud_share:
======================
Share basic operations
======================
General concepts
----------------
To create a file share, and access it, the following general concepts
are prerequisite knowledge:
#. To create a share, use :command:`manila create` command and
specify the required arguments: the size of the share and the shared file
system protocol. ``NFS``, ``CIFS``, ``GlusterFS``, ``HDFS``, or
``CephFS`` share file system protocols are supported.
#. You can also optionally specify the share network and the share type.
#. After the share becomes available, use the :command:`manila show` command
to get the share export locations.
#. After getting the share export locations, you can create an
:ref:`access rule <access_to_share>` for the share, mount it and work with
files on the remote file system.
There are big number of the share drivers created by different vendors in the
Shared File Systems service. As a Python class, each share driver can be set
for the :ref:`back end <shared_file_systems_multi_backend>` and run in the back
end to manage the share operations.
Initially there are two driver modes for the back ends:
* no share servers mode
* share servers mode
Each share driver supports one or two of possible back end modes that can be
configured in the ``manila.conf`` file. The configuration option
``driver_handles_share_servers`` in the ``manila.conf`` file sets the share
servers mode or no share servers mode, and defines the driver mode for share
storage lifecycle management:
+------------------+-------------------------------------+--------------------+
| Mode | Config option | Description |
+==================+=====================================+====================+
| no share servers | driver_handles_share_servers = False| An administrator |
| | | rather than a share|
| | | driver manages the |
| | | bare metal storage |
| | | with some net |
| | | interface instead |
| | | of the presence of |
| | | the share servers. |
+------------------+-------------------------------------+--------------------+
| share servers | driver_handles_share_servers = True | The share driver |
| | | creates the share |
| | | server and manages,|
| | | or handles, the |
| | | share server life |
| | | cycle. |
+------------------+-------------------------------------+--------------------+
It is :ref:`the share types <shared_file_systems_share_types>` which have the
extra specifications that help scheduler to filter back ends and choose the
appropriate back end for the user that requested to create a share. The
required extra boolean specification for each share type is
``driver_handles_share_servers``. As an administrator, you can create the share
types with the specifications you need. For details of managing the share types
and configuration the back ends, see :ref:`shared_file_systems_share_types` and
:ref:`shared_file_systems_multi_backend` documentation.
You can create a share in two described above modes:
* in a no share servers mode without specifying the share network and
specifying the share type with ``driver_handles_share_servers = False``
parameter. See subsection :ref:`create_share_in_no_share_server_mode`.
* in a share servers mode with specifying the share network and the share
type with ``driver_handles_share_servers = True`` parameter. See subsection
:ref:`create_share_in_share_server_mode`.
.. _create_share_in_no_share_server_mode:
Create a share in no share servers mode
---------------------------------------
To create a file share in no share servers mode, you need to:
#. To create a share, use :command:`manila create` command and
specify the required arguments: the size of the share and the shared file
system protocol. ``NFS``, ``CIFS``, ``GlusterFS``, ``HDFS``, or
``CephFS`` share file system protocols are supported.
#. You should specify the :ref:`share type <shared_file_systems_share_types>`
with ``driver_handles_share_servers = False`` extra specification.
#. You must not specify the ``share network`` because no share servers are
created. In this mode the Shared File Systems service expects that
administrator has some bare metal storage with some net interface.
#. The :command:`manila create` command creates a share. This command does the
following things:
* The :ref:`manila-scheduler <shared_file_systems_scheduling>` service will
find the back end with ``driver_handles_share_servers = False`` mode due
to filtering the extra specifications of the share type.
* The share is created using the storage that is specified in the found
back end.
#. After the share becomes available, use the :command:`manila show` command
to get the share export locations.
In the example to create a share, the created already share type named
``my_type`` with ``driver_handles_share_servers = False`` extra specification
is used.
Check share types that exist, run:
.. code-block:: console
$ manila type-list
+------+---------+------------+------------+--------------------------------------+-------------------------+
| ID | Name | visibility | is_default | required_extra_specs | optional_extra_specs |
+------+---------+------------+------------+--------------------------------------+-------------------------+
| %ID% | my_type | public | - | driver_handles_share_servers : False | snapshot_support : True |
+------+---------+------------+------------+--------------------------------------+-------------------------+
Create a private share with ``my_type`` share type, NFS shared file system
protocol, and size 1 GB:
.. code-block:: console
$ manila create nfs 1 --name Share1 --description "My share" --share-type my_type
+-----------------------------+--------------------------------------+
| Property | Value |
+-----------------------------+--------------------------------------+
| status | creating |
| share_type_name | my_type |
| description | My share |
| availability_zone | None |
| share_network_id | None |
| share_server_id | None |
| host | |
| access_rules_status | active |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | 10f5a2a1-36f5-45aa-a8e6-00e94e592e88 |
| size | 1 |
| name | Share1 |
| share_type | 14ee8575-aac2-44af-8392-d9c9d344f392 |
| has_replicas | False |
| replication_type | None |
| created_at | 2016-03-25T12:02:46.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 907004508ef4447397ce6741a8f037c1 |
| metadata | {} |
+-----------------------------+--------------------------------------+
New share ``Share2`` should have a status ``available``:
.. code-block:: console
$ manila show Share2
+-----------------------------+----------------------------------------------------------+
| Property | Value |
+-----------------------------+----------------------------------------------------------+
| status | available |
| share_type_name | my_type |
| description | My share |
| availability_zone | nova |
| share_network_id | None |
| export_locations | |
| | path = 10.0.0.4:/shares/manila_share_a5fb1ab7_... |
| | preferred = False |
| | is_admin_only = False |
| | id = 9e078eee-bcad-40b8-b4fe-1c916cf98ed1 |
| | share_instance_id = a5fb1ab7-0bbd-465b-ac14-05706294b6e9 |
| | path = 172.18.198.52:/shares/manila_share_a5fb1ab7_... |
| | preferred = False |
| | is_admin_only = True |
| | id = 44933f59-e0e3-4483-bb88-72ba7c486f41 |
| | share_instance_id = a5fb1ab7-0bbd-465b-ac14-05706294b6e9 |
| share_server_id | None |
| host | manila@paris#epsilon |
| access_rules_status | active |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | 10f5a2a1-36f5-45aa-a8e6-00e94e592e88 |
| size | 1 |
| name | Share1 |
| share_type | 14ee8575-aac2-44af-8392-d9c9d344f392 |
| has_replicas | False |
| replication_type | None |
| created_at | 2016-03-25T12:02:46.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 907004508ef4447397ce6741a8f037c1 |
| metadata | {} |
+-----------------------------+----------------------------------------------------------+
.. _create_share_in_share_server_mode:
Create a share in share servers mode
------------------------------------
To create a file share in share servers mode, you need to:
#. To create a share, use :command:`manila create` command and
specify the required arguments: the size of the share and the shared file
system protocol. ``NFS``, ``CIFS``, ``GlusterFS``, ``HDFS``, or
``CephFS`` share file system protocols are supported.
#. You should specify the :ref:`share type <shared_file_systems_share_types>`
with ``driver_handles_share_servers = True`` extra specification.
#. You should specify the
:ref:`share network <shared_file_systems_share_networks>`.
#. The :command:`manila create` command creates a share. This command does the
following things:
* The :ref:`manila-scheduler <shared_file_systems_scheduling>` service will
find the back end with ``driver_handles_share_servers = True`` mode due to
filtering the extra specifications of the share type.
* The share driver will create a share server with the share network. For
details of creating the resources, see the `documentation <http://docs.
openstack.org/developer/manila/devref/index.html#share-backends>`_ of the
specific share driver.
#. After the share becomes available, use the :command:`manila show` command
to get the share export location.
In the example to create a share, the default share type and the already
existing share network are used.
.. note::
There is no default share type just after you started manila as the
administrator. See :ref:`shared_file_systems_share_types` to
create the default share type. To create a share network, use
:ref:`shared_file_systems_share_networks`.
Check share types that exist, run:
.. code-block:: console
$ manila type-list
+------+---------+------------+------------+--------------------------------------+-------------------------+
| ID | Name | visibility | is_default | required_extra_specs | optional_extra_specs |
+------+---------+------------+------------+--------------------------------------+-------------------------+
| %id% | default | public | YES | driver_handles_share_servers : True | snapshot_support : True |
+------+---------+------------+------------+--------------------------------------+-------------------------+
Check share networks that exist, run:
.. code-block:: console
$ manila share-network-list
+--------------------------------------+--------------+
| id | name |
+--------------------------------------+--------------+
| c895fe26-92be-4152-9e6c-f2ad230efb13 | my_share_net |
+--------------------------------------+--------------+
Create a public share with ``my_share_net`` network, ``default``
share type, NFS shared file system protocol, and size 1 GB:
.. code-block:: console
$ manila create nfs 1 \
--name "Share2" \
--description "My second share" \
--share-type default \
--share-network my_share_net \
--metadata aim=testing \
--public
+-----------------------------+--------------------------------------+
| Property | Value |
+-----------------------------+--------------------------------------+
| status | creating |
| share_type_name | default |
| description | My second share |
| availability_zone | None |
| share_network_id | c895fe26-92be-4152-9e6c-f2ad230efb13 |
| share_server_id | None |
| host | |
| access_rules_status | active |
| snapshot_id | None |
| is_public | True |
| task_state | None |
| snapshot_support | True |
| id | 195e3ba2-9342-446a-bc93-a584551de0ac |
| size | 1 |
| name | Share2 |
| share_type | bf6ada49-990a-47c3-88bc-c0cb31d5c9bf |
| has_replicas | False |
| replication_type | None |
| created_at | 2016-03-25T12:13:40.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 907004508ef4447397ce6741a8f037c1 |
| metadata | {u'aim': u'testing'} |
+-----------------------------+--------------------------------------+
The share also can be created from a share snapshot. For details, see
:ref:`shared_file_systems_snapshots`.
See the share in a share list:
.. code-block:: console
$ manila list
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+
| ID | Name | Size | Share Proto | Status | Is Public | Share Type Name | Host | Availability Zone |
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+
| 10f5a2a1-36f5-45aa-a8e6-00e94e592e88 | Share1 | 1 | NFS | available | False | my_type | manila@paris#epsilon | nova |
| 195e3ba2-9342-446a-bc93-a584551de0ac | Share2 | 1 | NFS | available | True | default | manila@london#LONDON | nova |
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+
Check the share status and see the share export locations. After ``creating``
status share should have status ``available``:
.. code-block:: console
$ manila show Share2
+----------------------+----------------------------------------------------------------------+
| Property | Value |
+----------------------+----------------------------------------------------------------------+
| status | available |
| share_type_name | default |
| description | My second share |
| availability_zone | nova |
| share_network_id | c895fe26-92be-4152-9e6c-f2ad230efb13 |
| export_locations | |
| | path = 10.254.0.3:/shares/share-fe874928-39a2-441b-8d24-29e6f0fde965 |
| | preferred = False |
| | is_admin_only = False |
| | id = de6d4012-6158-46f0-8b28-4167baca51a7 |
| | share_instance_id = fe874928-39a2-441b-8d24-29e6f0fde965 |
| | path = 10.0.0.3:/shares/share-fe874928-39a2-441b-8d24-29e6f0fde965 |
| | preferred = False |
| | is_admin_only = True |
| | id = 602d0f5c-921b-4e45-bfdb-5eec8a89165a |
| | share_instance_id = fe874928-39a2-441b-8d24-29e6f0fde965 |
| share_server_id | 2e9d2d02-883f-47b5-bb98-e053b8d1e683 |
| host | manila@london#LONDON |
| access_rules_status | active |
| snapshot_id | None |
| is_public | True |
| task_state | None |
| snapshot_support | True |
| id | 195e3ba2-9342-446a-bc93-a584551de0ac |
| size | 1 |
| name | Share2 |
| share_type | bf6ada49-990a-47c3-88bc-c0cb31d5c9bf |
| has_replicas | False |
| replication_type | None |
| created_at | 2016-03-25T12:13:40.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| project_id | 907004508ef4447397ce6741a8f037c1 |
| metadata | {u'aim': u'testing'} |
+----------------------+----------------------------------------------------------------------+
``is_public`` defines the level of visibility for the share: whether other
projects can or cannot see the share. By default, the share is private.
Update share
------------
Update the name, or description, or level of visibility for all projects for
the share if you need:
.. code-block:: console
$ manila update Share2 --description "My second share. Updated" --is-public False
$ manila show Share2
+----------------------+----------------------------------------------------------------------+
| Property | Value |
+----------------------+----------------------------------------------------------------------+
| status | available |
| share_type_name | default |
| description | My second share. Updated |
| availability_zone | nova |
| share_network_id | c895fe26-92be-4152-9e6c-f2ad230efb13 |
| export_locations | |
| | path = 10.254.0.3:/shares/share-fe874928-39a2-441b-8d24-29e6f0fde965 |
| | preferred = False |
| | is_admin_only = False |
| | id = de6d4012-6158-46f0-8b28-4167baca51a7 |
| | share_instance_id = fe874928-39a2-441b-8d24-29e6f0fde965 |
| | path = 10.0.0.3:/shares/share-fe874928-39a2-441b-8d24-29e6f0fde965 |
| | preferred = False |
| | is_admin_only = True |
| | id = 602d0f5c-921b-4e45-bfdb-5eec8a89165a |
| | share_instance_id = fe874928-39a2-441b-8d24-29e6f0fde965 |
| share_server_id | 2e9d2d02-883f-47b5-bb98-e053b8d1e683 |
| host | manila@london#LONDON |
| access_rules_status | active |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | 195e3ba2-9342-446a-bc93-a584551de0ac |
| size | 1 |
| name | Share2 |
| share_type | bf6ada49-990a-47c3-88bc-c0cb31d5c9bf |
| has_replicas | False |
| replication_type | None |
| created_at | 2016-03-25T12:13:40.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| project_id | 907004508ef4447397ce6741a8f037c1 |
| metadata | {u'aim': u'testing'} |
+----------------------+----------------------------------------------------------------------+
A share can have one of these status values:
+-----------------------------------+-----------------------------------------+
| Status | Description |
+===================================+=========================================+
| creating | The share is being created. |
+-----------------------------------+-----------------------------------------+
| deleting | The share is being deleted. |
+-----------------------------------+-----------------------------------------+
| error | An error occurred during share creation.|
+-----------------------------------+-----------------------------------------+
| error_deleting | An error occurred during share deletion.|
+-----------------------------------+-----------------------------------------+
| available | The share is ready to use. |
+-----------------------------------+-----------------------------------------+
| manage_starting | Share manage started. |
+-----------------------------------+-----------------------------------------+
| manage_error | Share manage failed. |
+-----------------------------------+-----------------------------------------+
| unmanage_starting | Share unmanage started. |
+-----------------------------------+-----------------------------------------+
| unmanage_error | Share cannot be unmanaged. |
+-----------------------------------+-----------------------------------------+
| unmanaged | Share was unmanaged. |
+-----------------------------------+-----------------------------------------+
| extending | The extend, or increase, share size |
| | request was issued successfully. |
+-----------------------------------+-----------------------------------------+
| extending_error | Extend share failed. |
+-----------------------------------+-----------------------------------------+
| shrinking | Share is being shrunk. |
+-----------------------------------+-----------------------------------------+
| shrinking_error | Failed to update quota on share |
| | shrinking. |
+-----------------------------------+-----------------------------------------+
| shrinking_possible_data_loss_error| Shrink share failed due to possible data|
| | loss. |
+-----------------------------------+-----------------------------------------+
| migrating | Share migration is in progress. |
+-----------------------------------+-----------------------------------------+
.. _share_metadata:
Share metadata
--------------
If you want to set the metadata key-value pairs on the share, run:
.. code-block:: console
$ manila metadata Share2 set project=my_abc deadline=01/20/16
Get all metadata key-value pairs of the share:
.. code-block:: console
$ manila metadata-show Share2
+----------+----------+
| Property | Value |
+----------+----------+
| aim | testing |
| project | my_abc |
| deadline | 01/20/16 |
+----------+----------+
You can update the metadata:
.. code-block:: console
$ manila metadata-update-all Share2 deadline=01/30/16
+----------+----------+
| Property | Value |
+----------+----------+
| deadline | 01/30/16 |
+----------+----------+
You also can unset the metadata using
**manila metadata <share_name> unset <metadata_key(s)>**.
Reset share state
-----------------
As administrator, you can reset the state of a share.
Use **manila reset-state [--state <state>] <share>** command to reset share
state, where ``state`` indicates which state to assign the share. Options
include ``available``, ``error``, ``creating``, ``deleting``,
``error_deleting`` states.
.. code-block:: console
$ manila reset-state Share2 --state deleting
$ manila show Share2
+----------------------+----------------------------------------------------------------------+
| Property | Value |
+----------------------+----------------------------------------------------------------------+
| status | deleting |
| share_type_name | default |
| description | My second share. Updated |
| availability_zone | nova |
| share_network_id | c895fe26-92be-4152-9e6c-f2ad230efb13 |
| export_locations | |
| | path = 10.254.0.3:/shares/share-fe874928-39a2-441b-8d24-29e6f0fde965 |
| | preferred = False |
| | is_admin_only = False |
| | id = de6d4012-6158-46f0-8b28-4167baca51a7 |
| | share_instance_id = fe874928-39a2-441b-8d24-29e6f0fde965 |
| | path = 10.0.0.3:/shares/share-fe874928-39a2-441b-8d24-29e6f0fde965 |
| | preferred = False |
| | is_admin_only = True |
| | id = 602d0f5c-921b-4e45-bfdb-5eec8a89165a |
| | share_instance_id = fe874928-39a2-441b-8d24-29e6f0fde965 |
| share_server_id | 2e9d2d02-883f-47b5-bb98-e053b8d1e683 |
| host | manila@london#LONDON |
| access_rules_status | active |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | 195e3ba2-9342-446a-bc93-a584551de0ac |
| size | 1 |
| name | Share2 |
| share_type | bf6ada49-990a-47c3-88bc-c0cb31d5c9bf |
| has_replicas | False |
| replication_type | None |
| created_at | 2016-03-25T12:13:40.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| project_id | 907004508ef4447397ce6741a8f037c1 |
| metadata | {u'deadline': u'01/30/16'} |
+----------------------+----------------------------------------------------------------------+
Delete and force-delete share
-----------------------------
You also can force-delete a share.
The shares cannot be deleted in transitional states. The transitional
states are ``creating``, ``deleting``, ``managing``, ``unmanaging``,
``migrating``, ``extending``, and ``shrinking`` statuses for the shares.
Force-deletion deletes an object in any state. Use the ``policy.json`` file
to grant permissions for this action to other roles.
.. tip::
The configuration file ``policy.json`` may be used from different places.
The path ``/etc/manila/policy.json`` is one of expected paths by default.
Use **manila delete <share_name_or_ID>** command to delete a specified share:
.. code-block:: console
$ manila delete %share_name_or_id%
.. code-block:: console
$ manila delete %share_name_or_id% --consistency-group %consistency-group-id%
If you try to delete the share in one of the transitional
state using soft-deletion you'll get an error:
.. code-block:: console
$ manila delete Share2
Delete for share 195e3ba2-9342-446a-bc93-a584551de0ac failed: Invalid share: Share status must be one of ('available', 'error', 'inactive'). (HTTP 403) (Request-ID: req-9a77b9a0-17d2-4d97-8a7a-b7e23c27f1fe)
ERROR: Unable to delete any of the specified shares.
A share cannot be deleted in a transitional status, that it why an error from
``python-manilaclient`` appeared.
Print the list of all shares for all projects:
.. code-block:: console
$ manila list --all-tenants
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+
| ID | Name | Size | Share Proto | Status | Is Public | Share Type Name | Host | Availability Zone |
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+
| 10f5a2a1-36f5-45aa-a8e6-00e94e592e88 | Share1 | 1 | NFS | available | False | my_type | manila@paris#epsilon | nova |
| 195e3ba2-9342-446a-bc93-a584551de0ac | Share2 | 1 | NFS | available | False | default | manila@london#LONDON | nova |
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+
Force-delete Share2 and check that it is absent in the list of shares,
run:
.. code-block:: console
$ manila force-delete Share2
$ manila list
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+
| ID | Name | Size | Share Proto | Status | Is Public | Share Type Name | Host | Availability Zone |
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+
| 10f5a2a1-36f5-45aa-a8e6-00e94e592e88 | Share1 | 1 | NFS | available | False | my_type | manila@paris#epsilon | nova |
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+
.. _access_to_share:
Manage access to share
----------------------
The Shared File Systems service allows to grant or deny access to a specified
share, and list the permissions for a specified share.
To grant or deny access to a share, specify one of these supported share
access levels:
- **rw**. Read and write (RW) access. This is the default value.
- **ro**. Read-only (RO) access.
You must also specify one of these supported authentication methods:
- **ip**. Authenticates an instance through its IP address. A valid
format is ``XX.XX.XX.XX`` or ``XX.XX.XX.XX/XX``. For example ``0.0.0.0/0``.
- **user**. Authenticates by a specified user or group name. A valid value is
an alphanumeric string that can contain some special characters and is from
4 to 32 characters long.
- **cert**. Authenticates an instance through a TLS certificate. Specify the
TLS identity as the IDENTKEY. A valid value is any string up to 64 characters
long in the common name (CN) of the certificate. The meaning of a string
depends on its interpretation.
- **cephx**. Ceph authentication system. Specify the Ceph auth ID that needs
to be authenticated and authorized for share access by the Ceph back end. A
valid value must be non-empty, consist of ASCII printable characters, and not
contain periods.
Try to mount NFS share with export path
``10.0.0.4:/shares/manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9`` on the
node with IP address ``10.0.0.13``:
.. code-block:: console
$ sudo mount -v -t nfs 10.0.0.4:/shares/manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9 /mnt/
mount.nfs: timeout set for Tue Oct 6 10:37:23 2015
mount.nfs: trying text-based options 'vers=4,addr=10.0.0.4,clientaddr=10.0.0.13'
mount.nfs: mount(2): Permission denied
mount.nfs: access denied by server while mounting 10.0.0.4:/shares/manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9
An error message "Permission denied" appeared, so you are not allowed to mount
a share without an access rule. Allow access to the share with ``ip`` access
type and ``10.0.0.13`` IP address:
.. code-block:: console
$ manila access-allow Share1 ip 10.0.0.13 --access-level rw
+--------------+--------------------------------------+
| Property | Value |
+--------------+--------------------------------------+
| share_id | 10f5a2a1-36f5-45aa-a8e6-00e94e592e88 |
| access_type | ip |
| access_to | 10.0.0.13 |
| access_level | rw |
| state | new |
| id | de715226-da00-4cfc-b1ab-c11f3393745e |
+--------------+--------------------------------------+
Try to mount a share again. This time it is mounted successfully:
.. code-block:: console
$ sudo mount -v -t nfs 10.0.0.4:/shares/manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9 /mnt/
Since it is allowed node on 10.0.0.13 read and write access, try to create
a file on a mounted share:
.. code-block:: console
$ cd /mnt
$ ls
lost+found
$ touch my_file.txt
Connect via SSH to the ``10.0.0.4`` node and check new file `my_file.txt`
in the ``/shares/manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9`` directory:
.. code-block:: console
$ ssh 10.0.0.4
$ cd /shares
$ ls
manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9
$ cd manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9
$ ls
lost+found my_file.txt
You have successfully created a file from instance that was given access by
its IP address.
Allow access to the share with ``user`` access type:
.. code-block:: console
$ manila access-allow Share1 user demo --access-level rw
+--------------+--------------------------------------+
| Property | Value |
+--------------+--------------------------------------+
| share_id | 10f5a2a1-36f5-45aa-a8e6-00e94e592e88 |
| access_type | user |
| access_to | demo |
| access_level | rw |
| state | new |
| id | 4f391c6b-fb4f-47f5-8b4b-88c5ec9d568a |
+--------------+--------------------------------------+
.. note::
Different share features are supported by different share drivers.
For the example, the Generic driver with the Block Storage service as a
back-end doesn't support ``user`` and ``cert`` authentications methods. For
details of supporting of features by different drivers, see `Manila share
features support mapping <https://docs.openstack.org/developer/manila/devref
/share_back_ends_feature_support_mapping.html>`_.
To verify that the access rules (ACL) were configured correctly for a share,
you list permissions for a share:
.. code-block:: console
$ manila access-list Share1
+--------------------------------------+-------------+------------+--------------+--------+
| id | access type | access to | access level | state |
+--------------------------------------+-------------+------------+--------------+--------+
| 4f391c6b-fb4f-47f5-8b4b-88c5ec9d568a | user | demo | rw | error |
| de715226-da00-4cfc-b1ab-c11f3393745e | ip | 10.0.0.13 | rw | active |
+--------------------------------------+-------------+------------+--------------+--------+
Deny access to the share and check that deleted access rule is absent in the
access rule list:
.. code-block:: console
$ manila access-deny Share1 de715226-da00-4cfc-b1ab-c11f3393745e
$ manila access-list Share1
+--------------------------------------+-------------+-----------+--------------+-------+
| id | access type | access to | access level | state |
+--------------------------------------+-------------+-----------+--------------+-------+
| 4f391c6b-fb4f-47f5-8b4b-88c5ec9d568a | user | demo | rw | error |
+--------------------------------------+-------------+-----------+--------------+-------+

57
doc/source/admin/shared-file-systems-intro.rst Normal file
View File

@ -0,0 +1,57 @@
.. _shared_file_systems_intro:
===========
Admin Guide
===========
Shared File Systems service provides a set of services for management of
shared file systems in a multi-project cloud environment. The service resembles
OpenStack block-based storage management from the OpenStack Block Storage
service project. With the Shared File Systems service, you can
create a remote file system, mount the file system on your instances, and then
read and write data from your instances to and from your file system.
The Shared File Systems service serves same purpose as the Amazon Elastic File
System (EFS) does.
The Shared File Systems service can run in a single-node or multiple
node configuration. The Shared File Systems service can be configured
to provision shares from one or more back ends, so it is required to
declare at least one back end. Shared File System service contains
several configurable components.
It is important to understand these components:
* Share networks
* Shares
* Multi-tenancy
* Back ends
The Shared File Systems service consists of four types of services,
most of which are similar to those of the Block Storage service:
- ``manila-api``
- ``manila-data``
- ``manila-scheduler``
- ``manila-share``
Installation of first three - ``manila-api``, ``manila-data``, and
``manila-scheduler`` is common for almost all deployments. But configuration
of ``manila-share`` is backend-specific and can differ from deployment to
deployment.
.. toctree::
:maxdepth: 1
shared-file-systems-key-concepts.rst
shared-file-systems-share-management.rst
shared-file-systems-share-migration.rst
shared-file-systems-share-types.rst
shared-file-systems-snapshots.rst
shared-file-systems-security-services.rst
shared-file-systems-share-replication.rst
shared-file-systems-multi-backend.rst
shared-file-systems-networking.rst
shared-file-systems-troubleshoot.rst

119
doc/source/admin/shared-file-systems-key-concepts.rst Normal file
View File

@ -0,0 +1,119 @@
.. _shared_file_systems_key_concepts:
============
Key concepts
============
Share
~~~~~
In the Shared File Systems service ``share`` is the fundamental resource unit
allocated by the Shared File System service. It represents an allocation of a
persistent, readable, and writable filesystems. Compute instances access these
filesystems. Depending on the deployment configuration, clients outside of
OpenStack can also access the filesystem.
.. note::
A ``share`` is an abstract storage object that may or may not directly
map to a "share" concept from the underlying storage provider.
See the description of ``share instance`` for more details.
Share instance
~~~~~~~~~~~~~~
This concept is tied with ``share`` and represents created resource on specific
back end, when ``share`` represents abstraction between end user and
back-end storages. In common cases, it is one-to-one relation.
One single ``share`` has more than one ``share instance`` in two cases:
- When ``share migration`` is being applied
- When ``share replication`` is enabled
Therefore, each ``share instance`` stores information specific to real
allocated resource on storage. And ``share`` represents the information
that is common for ``share instances``.
A user with ``member`` role will not be able to work with it directly. Only
a user with ``admin`` role has rights to perform actions against specific
share instances.
Snapshot
~~~~~~~~
A ``snapshot`` is a point-in-time, read-only copy of a ``share``. You can
create ``Snapshots`` from an existing, operational ``share`` regardless
of whether a client has mounted the file system. A ``snapshot``
can serve as the content source for a new ``share``. Specify the
**Create from snapshot** option when creating a new ``share`` on the
dashboard.
Storage Pools
~~~~~~~~~~~~~
With the Kilo release of OpenStack, Shared File Systems can use
``storage pools``. The storage may present one or more logical storage
resource pools that the Shared File Systems service
will select as a storage location when provisioning ``shares``.
Share Type
~~~~~~~~~~
``Share type`` is an abstract collection of criteria used to characterize
``shares``. They are most commonly used to create a hierarchy of functional
capabilities. This hierarchy represents tiered storage services levels. For
example, an administrator might define a premium ``share type`` that
indicates a greater level of performance than a basic ``share type``.
Premium represents the best performance level.
Share Access Rules
~~~~~~~~~~~~~~~~~~
``Share access rules`` define which users can access a particular ``share``.
For example, administrators can declare rules for NFS shares by
listing the valid IP networks which will access the ``share``. List the
IP networks in CIDR notation.
Security Services
~~~~~~~~~~~~~~~~~
``Security services``allow granular client access rules for
administrators. They can declare rules for authentication or
authorization to access ``share`` content. External services including LDAP,
Active Directory, and Kerberos can be declared as resources. Examine and
consult these resources when making an access decision for a
particular ``share``. You can associate ``Shares`` with multiple
security services, but only one service per one type.
Share Networks
~~~~~~~~~~~~~~
A ``share network`` is an object that defines a relationship between a
project network and subnet, as defined in an OpenStack Networking service or
Compute service. The ``share network`` is also defined in ``shares``
created by the same project. A project may find it desirable to
provision ``shares`` such that only instances connected to a particular
OpenStack-defined network have access to the ``share``. Also,
``security services`` can be attached to ``share networks``,
because most of auth protocols require some interaction with network services.
The Shared File Systems service has the ability to work outside of OpenStack.
That is due to the ``StandaloneNetworkPlugin``. The plugin is compatible with
any network platform, and does not require specific network services in
OpenStack like Compute or Networking service. You can set the network
parameters in the ``manila.conf`` file.
Share Servers
~~~~~~~~~~~~~
A ``share server`` is a logical entity that hosts the shares created
on a specific ``share network``. A ``share server`` may be a
configuration object within the storage controller, or it may represent
logical resources provisioned within an OpenStack deployment used to
support the data path used to access ``shares``.
``Share servers`` interact with network services to determine the appropriate
IP addresses on which to export ``shares`` according to the related ``share
network``. The Shared File Systems service has a pluggable network model that
allows ``share servers`` to work with different implementations of
the Networking service.

162
doc/source/admin/shared-file-systems-manage-and-unmanage-share.rst Normal file
View File

@ -0,0 +1,162 @@
.. _shared_file_systems_manage_and_unmanage_share:
=========================
Manage and unmanage share
=========================
To ``manage`` a share means that an administrator, rather than a share
driver, manages the storage lifecycle. This approach is appropriate when an
administrator already has the custom non-manila share with its size, shared
file system protocol, and export path, and an administrator wants to
register it in the Shared File System service.
To ``unmanage`` a share means to unregister a specified share from the Shared
File Systems service. Administrators can revert an unmanaged share to managed
status if needed.
.. _unmanage_share:
Unmanage a share
----------------
The ``unmanage`` operation is not supported for shares that were
created on top of share servers and created with share networks.
The Share service should have the
option ``driver_handles_share_servers = False``
set in the ``manila.conf`` file. You can unmanage a share that has
no dependent snapshots.
To unmanage managed share, run the :command:`manila unmanage <share>`
command. Then try to print the information about the share. The
returned result should indicate that Shared File Systems service won't
find the share:
.. code-block:: console
$ manila unmanage share_for_docs
$ manila show share_for_docs
ERROR: No share with a name or ID of 'share_for_docs' exists.
.. _manage_share:
Manage a share
--------------
To register the non-managed share in the File System service, run the
:command:`manila manage` command:
.. code-block:: console
manila manage [--name <name>] [--description <description>]
[--share_type <share-type>]
[--driver_options [<key=value> [<key=value> ...]]]
<service_host> <protocol> <export_path>
The positional arguments are:
- service_host. The manage-share service host in
``host@backend#POOL`` format, which consists of the host name for
the back end, the name of the back end, and the pool name for the
back end.
- protocol. The Shared File Systems protocol of the share to manage. Valid
values are NFS, CIFS, GlusterFS, or HDFS.
- export_path. The share export path in the format appropriate for the
protocol:
- NFS protocol. 10.0.0.1:/foo_path.
- CIFS protocol. \\\\10.0.0.1\\foo_name_of_cifs_share.
- HDFS protocol. hdfs://10.0.0.1:foo_port/foo_share_name.
- GlusterFS. 10.0.0.1:/foo_volume.
The ``driver_options`` is an optional set of one or more key and value pairs
that describe driver options. Note that the share type must have the
``driver_handles_share_servers = False`` option. As a result, a special share
type named ``for_managing`` was used in example.
To manage share, run:
.. code-block:: console
$ manila manage \
manila@paris#shares \
nfs \
1.0.0.4:/shares/manila_share_6d2142d8_2b9b_4405_867f_8a48094c893f \
--name share_for_docs \
--description "We manage share." \
--share_type for_managing
+-----------------------------+--------------------------------------+
| Property | Value |
+-----------------------------+--------------------------------------+
| status | manage_starting |
| share_type_name | for_managing |
| description | We manage share. |
| availability_zone | None |
| share_network_id | None |
| share_server_id | None |
| host | manila@paris#shares |
| access_rules_status | active |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | ddfb1240-ed5e-4071-a031-b842035a834a |
| size | None |
| name | share_for_docs |
| share_type | 14ee8575-aac2-44af-8392-d9c9d344f392 |
| has_replicas | False |
| replication_type | None |
| created_at | 2016-03-25T15:22:43.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 907004508ef4447397ce6741a8f037c1 |
| metadata | {} |
+-----------------------------+--------------------------------------+
Check that the share is available:
.. code-block:: console
$ manila show share_for_docs
+----------------------+--------------------------------------------------------------------------+
| Property | Value |
+----------------------+--------------------------------------------------------------------------+
| status | available |
| share_type_name | for_managing |
| description | We manage share. |
| availability_zone | None |
| share_network_id | None |
| export_locations | |
| | path = 1.0.0.4:/shares/manila_share_6d2142d8_2b9b_4405_867f_8a48094c893f |
| | preferred = False |
| | is_admin_only = False |
| | id = d4d048bf-4159-4a94-8027-e567192b8d30 |
| | share_instance_id = 4c8e3887-4f9a-4775-bab4-e5840a09c34e |
| | path = 2.0.0.3:/shares/manila_share_6d2142d8_2b9b_4405_867f_8a48094c893f |
| | preferred = False |
| | is_admin_only = True |
| | id = 1dd4f0a3-778d-486a-a851-b522f6e7cf5f |
| | share_instance_id = 4c8e3887-4f9a-4775-bab4-e5840a09c34e |
| share_server_id | None |
| host | manila@paris#shares |
| access_rules_status | active |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | ddfb1240-ed5e-4071-a031-b842035a834a |
| size | 1 |
| name | share_for_docs |
| share_type | 14ee8575-aac2-44af-8392-d9c9d344f392 |
| has_replicas | False |
| replication_type | None |
| created_at | 2016-03-25T15:22:43.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| project_id | 907004508ef4447397ce6741a8f037c1 |
| metadata | {} |
+----------------------+--------------------------------------------------------------------------+

107
doc/source/admin/shared-file-systems-manage-and-unmanage-snapshot.rst Normal file
View File

@ -0,0 +1,107 @@
.. _shared_file_systems_manage_and_unmanage_snapshot:
==================================
Manage and unmanage share snapshot
==================================
To ``manage`` a share snapshot means that an administrator, rather than a
share driver, manages the storage lifecycle. This approach is appropriate
when an administrator manages share snapshots outside of the Shared File
Systems service and wants to register it with the service.
To ``unmanage`` a share snapshot means to unregister a specified share
snapshot from the Shared File Systems service. Administrators can revert an
unmanaged share snapshot to managed status if needed.
.. _unmanage_share_snapshot:
Unmanage a share snapshot
-------------------------
The ``unmanage`` operation is not supported for shares that were
created on top of share servers and created with share networks.
The Share service should have the option
``driver_handles_share_servers = False`` set in the ``manila.conf`` file.
To unmanage managed share snapshot, run the
:command:`manila snapshot-unmanage <share_snapshot>`
command. Then try to print the
information about the share snapshot. The returned result should indicate that
Shared File Systems service won't find the share snapshot:
.. code-block:: console
$ manila snapshot-unmanage my_test_share_snapshot
$ manila snapshot-show my_test_share_snapshot
ERROR: No sharesnapshot with a name or ID of 'my_test_share_snapshot'
exists.
.. _manage_share_snapshot:
Manage a share snapshot
-----------------------
To register the non-managed share snapshot in the File System service, run the
:command:`manila snapshot-manage` command:
.. code-block:: console
manila snapshot-manage [--name <name>] [--description <description>]
[--driver_options [<key=value> [<key=value> ...]]]
<share> <provider_location>
The positional arguments are:
- share. Name or ID of the share.
- provider_location. Provider location of the share snapshot on the backend.
The ``driver_options`` is an optional set of one or more key and value pairs
that describe driver options.
To manage share snapshot, run:
.. code-block:: console
$ manila snapshot-manage \
9ba52cc6-c97e-4b40-8653-4bcbaaf9628d \
4d1e2863-33dd-4243-bf39-f7354752097d \
--name my_test_share_snapshot \
--description "My test share snapshot" \
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| status | manage_starting |
| share_id | 9ba52cc6-c97e-4b40-8653-4bcbaaf9628d |
| user_id | d9f4003655c94db5b16c591920be1f91 |
| description | My test share snapshot |
| created_at | 2016-07-25T04:49:42.600980 |
| size | None |
| share_proto | NFS |
| provider_location | 4d1e2863-33dd-4243-bf39-f7354752097d |
| id | 89c663b5-026d-45c7-a43b-56ef0ba0faab |
| project_id | aaa33a0ca4324965a3e65ae47e864e94 |
| share_size | 1 |
| name | my_test_share_snapshot |
+-------------------+--------------------------------------+
Check that the share snapshot is available:
.. code-block:: console
$ manila snapshot-show my_test_share_snapshot
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| status | available |
| share_id | 9ba52cc6-c97e-4b40-8653-4bcbaaf9628d |
| user_id | d9f4003655c94db5b16c591920be1f91 |
| description | My test share snapshot |
| created_at | 2016-07-25T04:49:42.000000 |
| size | 1 |
| share_proto | NFS |
| provider_location | 4d1e2863-33dd-4243-bf39-f7354752097d |
| id | 89c663b5-026d-45c7-a43b-56ef0ba0faab |
| project_id | aaa33a0ca4324965a3e65ae47e864e94 |
| share_size | 1 |
| name | my_test_share_snapshot |
+-------------------+--------------------------------------+

59
doc/source/admin/shared-file-systems-multi-backend.rst Normal file
View File

@ -0,0 +1,59 @@
.. _shared_file_systems_multi_backend:
===========================
Multi-storage configuration
===========================
The Shared File Systems service can provide access to one or more file storage
back ends. In general, the workflow with multiple back ends looks similar
to the Block Storage service one.
Using ``manila.conf``, you can spawn multiple share services. To do it, you
should set the `enabled_share_backends` flag in the ``manila.conf`` file. This
flag defines the comma-separated names of the configuration stanzas for the
different back ends. One name is associated to one configuration group for a
back end.
The following example runs three configured share services:
.. code-block:: ini
[DEFAULT]
enabled_share_backends=backendEMC1,backendGeneric1,backendNetApp
[backendGeneric1]
share_driver=manila.share.drivers.generic.GenericShareDriver
share_backend_name=one_name_for_two_backends
service_instance_user=ubuntu_user
service_instance_password=ubuntu_user_password
service_image_name=ubuntu_image_name
path_to_private_key=/home/foouser/.ssh/id_rsa
path_to_public_key=/home/foouser/.ssh/id_rsa.pub
[backendEMC1]
share_driver=manila.share.drivers.emc.driver.EMCShareDriver
share_backend_name=backendEMC2
emc_share_backend=vnx
emc_nas_server=1.1.1.1
emc_nas_password=password
emc_nas_login=user
emc_nas_server_container=server_3
emc_nas_pool_name="Pool 2"
[backendNetApp]
share_driver = manila.share.drivers.netapp.common.NetAppDriver
driver_handles_share_servers = True
share_backend_name=backendNetApp
netapp_login=user
netapp_password=password
netapp_server_hostname=1.1.1.1
netapp_root_volume_aggregate=aggr01
To spawn separate groups of share services, you can use separate configuration
files. If it is necessary to control each back end in a separate way, you
should provide a single configuration file per each back end.
.. toctree::
shared-file-systems-scheduling.rst
shared-file-systems-services-manage.rst

88
doc/source/admin/shared-file-systems-network-plugins.rst Normal file
View File

@ -0,0 +1,88 @@
.. _shared_file_systems_network_plugins:
================
Network plug-ins
================
The Shared File Systems service architecture defines an abstraction layer for
network resource provisioning and allowing administrators to choose from a
different options for how network resources are assigned to their projects’
networked storage. There are a set of network plug-ins that provide a variety
of integration approaches with the network services that are available with
OpenStack.
What is a network plugin in Manila?
-----------------------------------
A network plugin is a python class that uses a specific facility (e.g.
Neutron network) to provide network resources to the
:term:`manila-share` service.
When to use a network plugin?
-----------------------------
A Manila `share driver` may be configured in one of two modes, where it is
managing the lifecycle of `share servers` on its own or where it is merely
providing storage resources on a pre-configured share server. This mode
is defined using the boolean option `driver_handles_share_servers` in the
Manila configuration file. A network plugin is only useful when a driver is
handling its own share servers.
.. note::
Not all share drivers support both modes. Each driver must report which
mode(s) it supports to the manila-share service.
When `driver_handles_share_servers` is set to `True`, a share driver will be
called to create share servers for shares using information provided within a
`share network`. This information will be provided to one of the enabled
network plugins that will handle reservation, creation and deletion of
network resources including `IP addresses` and `network interfaces`.
The Shared File Systems service may need a network resource provisioning if
share service with specified driver works in mode, when a share driver manages
lifecycle of share servers on its own. This behavior is defined by a flag
``driver_handles_share_servers`` in share service configuration. When
``driver_handles_share_servers`` is set to ``True``, a share driver will be
called to create share servers for shares using information provided within a
share network. This information will be provided to one of the enabled network
plug-ins that will handle reservation, creation and deletion of network
resources including IP addresses and network interfaces.
What network plug-ins are available?
------------------------------------
There are two network plug-ins and three python classes in the
Shared File Systems service:
#. Network plug-in for using the OpenStack Networking service. It allows to use
any network segmentation that the Networking service supports. It is up to
each share driver to support at least one network segmentation type.
a) ``manila.network.neutron.neutron_network_plugin.NeutronNetworkPlugin``.
This is a default network plug-in. It requires the ``neutron_net_id`` and
the ``neutron_subnet_id`` to be provided when defining the share network
that will be used for the creation of share servers. The user may define
any number of share networks corresponding to the various physical
network segments in a project environment.
b) ``manila.network.neutron.neutron_network_plugin.NeutronSingleNetworkPlugin``.
This is a simplification of the previous case. It accepts values for
``neutron_net_id`` and ``neutron_subnet_id`` from the ``manila.conf``
configuration file and uses one network for all shares.
When only a single network is needed, the NeutronSingleNetworkPlugin (1.b)
is a simple solution. Otherwise NeutronNetworkPlugin (1.a) should be chosen.
#. Network plug-in for specifying networks independently from OpenStack
networking services.
a) ``manila.network.standalone_network_plugin.StandaloneNetworkPlugin``.
This plug-in uses a pre-existing network that is available to the
manila-share host. This network may be handled either by OpenStack or be
created independently by any other means. The plug-in supports any type
of network - flat and segmented. As above, it is completely up to the
share driver to support the network type for which the network plug-in is
configured.
More information about network plug-ins can be found in `Manila developer documentation <https://docs.openstack.org/developer/manila/adminref/network_plugins.html>`_

17
doc/source/admin/shared-file-systems-networking.rst Normal file
View File

@ -0,0 +1,17 @@
.. _shared_file_systems_networking:
==========
Networking
==========
Unlike the OpenStack Block Storage service, the Shared File Systems service
must connect to the Networking service. The share service requires the
option to self-manage share servers. For client authentication and
authorization, you can configure the Shared File Systems service to
work with different network authentication services, like LDAP, Kerberos
protocols, or Microsoft Active Directory.
.. toctree::
shared-file-systems-share-networks.rst
shared-file-systems-network-plugins.rst

152
doc/source/admin/shared-file-systems-quotas.rst Normal file
View File

@ -0,0 +1,152 @@
.. _shared_file_systems_quotas:
=================
Quotas and limits
=================
Limits
~~~~~~
Limits are the resource limitations that are allowed for each project.
An administrator can configure limits in the ``manila.conf`` file.
Users can query their rate and absolute limits.
To see the absolute limits, run:
.. code-block:: console
$ manila absolute-limits
+----------------------------+-------+
| Name | Value |
+----------------------------+-------+
| maxTotalShareGigabytes | 1000 |
| maxTotalShareNetworks | 10 |
| maxTotalShareSnapshots | 50 |
| maxTotalShares | 50 |
| maxTotalSnapshotGigabytes | 1000 |
| totalShareGigabytesUsed | 1 |
| totalShareNetworksUsed | 2 |
| totalShareSnapshotsUsed | 1 |
| totalSharesUsed | 1 |
| totalSnapshotGigabytesUsed | 1 |
+----------------------------+-------+
Rate limits control the frequency at which users can issue specific API
requests. Administrators use rate limiting to configure limits on the type and
number of API calls that can be made in a specific time interval. For example,
a rate limit can control the number of ``GET`` requests processed
during a one-minute period.
To set the API rate limits, modify the
``etc/manila/api-paste.ini`` file, which is a part of the WSGI pipeline and
defines the actual limits. You need to restart ``manila-api`` service after
you edit the ``etc/manila/api-paste.ini`` file.
.. code-block:: ini
[filter:ratelimit]
paste.filter_factory = manila.api.v1.limits:RateLimitingMiddleware.factory
limits = (POST, "*/shares", ^/shares, 120, MINUTE);(PUT, "*/shares", .*, 120, MINUTE);(DELETE, "*", .*, 120, MINUTE)
Also, add the ``ratelimit`` to ``noauth``, ``keystone``, ``keystone_nolimit``
parameters in the ``[composite:openstack_share_api]`` and
``[composite:openstack_share_api_v2]`` groups.
.. code-block:: ini
[composite:openstack_share_api]
use = call:manila.api.middleware.auth:pipeline_factory
noauth = cors faultwrap ssl ratelimit sizelimit noauth api
keystone = cors faultwrap ssl ratelimit sizelimit authtoken keystonecontext api
keystone_nolimit = cors faultwrap ssl ratelimit sizelimit authtoken keystonecontext api
[composite:openstack_share_api_v2]
use = call:manila.api.middleware.auth:pipeline_factory
noauth = cors faultwrap ssl ratelimit sizelimit noauth apiv2
keystone = cors faultwrap ssl ratelimit sizelimit authtoken keystonecontext apiv2
keystone_nolimit = cors faultwrap ssl ratelimit sizelimit authtoken keystonecontext apiv2
To see the rate limits, run:
.. code-block:: console
$ manila rate-limits
+--------+------------+-------+--------+--------+----------------------+
| Verb | URI | Value | Remain | Unit | Next_Available |
+--------+------------+-------+--------+--------+----------------------+
| DELETE | "*" | 120 | 120 | MINUTE | 2015-10-20T15:17:20Z |
| POST | "*/shares" | 120 | 120 | MINUTE | 2015-10-20T15:17:20Z |
| PUT | "*/shares" | 120 | 120 | MINUTE | 2015-10-20T15:17:20Z |
+--------+------------+-------+--------+--------+----------------------+
Quotas
~~~~~~
Quota sets provide quota management support.
To list the quotas for a project or user, use the :command:`manila quota-show`
command. If you specify the optional ``--user`` parameter, you get the
quotas for this user in the specified project. If you omit this parameter,
you get the quotas for the specified project.
.. note::
The Shared File Systems service does not perform mapping of usernames and
project names to IDs. Provide only ID values to get correct setup
of quotas. Setting it by names you set quota for nonexistent project/user.
In case quota is not set explicitly by project/user ID,
The Shared File Systems service just applies default quotas.
.. code-block:: console
$ manila quota-show --tenant %project_id% --user %user_id%
+--------------------+-------+
| Property | Value |
+--------------------+-------+
| gigabytes | 1000 |
| snapshot_gigabytes | 1000 |
| snapshots | 50 |
| shares | 50 |
| share_networks | 10 |
+--------------------+-------+
There are default quotas for a project that are set from the
``manila.conf`` file. To list the default quotas for a project, use
the :command:`manila quota-defaults` command:
.. code-block:: console
$ manila quota-defaults --tenant %project_id%
+--------------------+-------+
| Property | Value |
+--------------------+-------+
| gigabytes | 1000 |
| snapshot_gigabytes | 1000 |
| snapshots | 50 |
| shares | 50 |
| share_networks | 10 |
+--------------------+-------+
The administrator can update the quotas for a specific project, or for a
specific user by providing both the ``--tenant`` and ``--user`` optional
arguments. It is possible to update the ``shares``, ``snapshots``,
``gigabytes``, ``snapshot-gigabytes``, and ``share-networks`` quotas.
.. code-block:: console
$ manila quota-update %project_id% --user %user_id% --shares 49 --snapshots 49
As administrator, you can also permit or deny the force-update of a quota that
is already used, or if the requested value exceeds the configured quota limit.
To force-update a quota, use ``force`` optional key.
.. code-block:: console
$ manila quota-update %project_id% --shares 51 --snapshots 51 --force
To revert quotas to default for a project or for a user, delete quotas:
.. code-block:: console
$ manila quota-delete --tenant %project_id% --user %user_id%

33
doc/source/admin/shared-file-systems-scheduling.rst Normal file
View File

@ -0,0 +1,33 @@
.. _shared_file_systems_scheduling:
==========
Scheduling
==========
The Shared File Systems service uses a scheduler to provide unified
access for a variety of different types of shared file systems. The
scheduler collects information from the active shared services, and
makes decisions such as what shared services will be used to create
a new share. To manage this process, the Shared File Systems service
provides Share types API.
A share type is a list from key-value pairs called extra-specs. The
scheduler uses required and un-scoped extra-specs to look up
the shared service most suitable for a new share with the specified share type.
For more information about extra-specs and their type, see `Capabilities
and Extra-Specs <https://docs.openstack.org/developer/manila/devref/capabilities_and_extra_specs.html>`_ section in developer documentation.
The general scheduler workflow:
#. Share services report information about their existing pool number, their
capacities, and their capabilities.
#. When a request on share creation arrives, the scheduler picks a service
and pool that best serves the request, using share type
filters and back end capabilities. If back end capabilities pass through,
all filters request the selected back end where the target pool resides.
#. The share driver receives a reply on the request status, and lets the
target pool serve the request as the scheduler instructs. The scoped
and un-scoped share types are available for the driver implementation
to use as needed.

186
doc/source/admin/shared-file-systems-security-services.rst Normal file
View File

@ -0,0 +1,186 @@
.. _shared_file_systems_security_services:
=================
Security services
=================
A security service stores client configuration information used for
authentication and authorization (AuthN/AuthZ). For example, a share server
will be the client for an existing service such as LDAP, Kerberos, or
Microsoft Active Directory.
You can associate a share with one to three security service types:
- ``ldap``: LDAP.
- ``kerberos``: Kerberos.
- ``active_directory``: Microsoft Active Directory.
You can configure a security service with these options:
- A DNS IP address.
- An IP address or host name.
- A domain.
- A user or group name.
- The password for the user, if you specify a user name.
You can add the security service to the
:ref:`share network <shared_file_systems_share_networks>`.
To create a security service, specify the security service type, a
description of a security service, DNS IP address used inside project's
network, security service IP address or host name, domain, security
service user or group used by project, and a password for the user. The
share name is optional.
Create a ``ldap`` security service:
.. code-block:: console
$ manila security-service-create ldap --dns-ip 8.8.8.8 --server 10.254.0.3 --name my_ldap_security_service
+-------------+--------------------------------------+
| Property | Value |
+-------------+--------------------------------------+
| status | new |
| domain | None |
| password | None |
| name | my_ldap_security_service |
| dns_ip | 8.8.8.8 |
| created_at | 2015-09-25T10:19:06.019527 |
| updated_at | None |
| server | 10.254.0.3 |
| user | None |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| type | ldap |
| id | 413479b2-0d20-4c58-a9d3-b129fa592d8e |
| description | None |
+-------------+--------------------------------------+
To create ``kerberos`` security service, run:
.. code-block:: console
$ manila security-service-create kerberos --server 10.254.0.3 --user demo --password secret --name my_kerberos_security_service --description "Kerberos security service"
+-------------+--------------------------------------+
| Property | Value |
+-------------+--------------------------------------+
| status | new |
| domain | None |
| password | secret |
| name | my_kerberos_security_service |
| dns_ip | None |
| created_at | 2015-09-25T10:26:03.211849 |
| updated_at | None |
| server | 10.254.0.3 |
| user | demo |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| type | kerberos |
| id | 7f46a447-2534-453d-924d-bd7c8e63bbec |
| description | Kerberos security service |
+-------------+--------------------------------------+
To see the list of created security service use
:command:`manila security-service-list`:
.. code-block:: console
$ manila security-service-list
+--------------------------------------+------------------------------+--------+----------+
| id | name | status | type |
+--------------------------------------+------------------------------+--------+----------+
| 413479b2-0d20-4c58-a9d3-b129fa592d8e | my_ldap_security_service | new | ldap |
| 7f46a447-2534-453d-924d-bd7c8e63bbec | my_kerberos_security_service | new | kerberos |
+--------------------------------------+------------------------------+--------+----------+
You can add a security service to the existing
:ref:`share network <shared_file_systems_share_networks>`, which is not
yet used (a ``share network`` not associated with a share).
Add a security service to the share network with
``share-network-security-service-add`` specifying share network and
security service. The command returns information about the
security service. You can see view new attributes and ``share_networks``
using the associated share network ID.
.. code-block:: console
$ manila share-network-security-service-add share_net2 my_ldap_security_service
$ manila security-service-show my_ldap_security_service
+----------------+-------------------------------------------+
| Property | Value |
+----------------+-------------------------------------------+
| status | new |
| domain | None |
| password | None |
| name | my_ldap_security_service |
| dns_ip | 8.8.8.8 |
| created_at | 2015-09-25T10:19:06.000000 |
| updated_at | None |
| server | 10.254.0.3 |
| share_networks | [u'6d36c41f-d310-4aff-a0c2-ffd870e91cab'] |
| user | None |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| type | ldap |
| id | 413479b2-0d20-4c58-a9d3-b129fa592d8e |
| description | None |
+----------------+-------------------------------------------+
It is possible to see the list of security services associated
with a given share network. List security services for ``share_net2``
share network with:
.. code-block:: console
$ manila share-network-security-service-list share_net2
+--------------------------------------+--------------------------+--------+------+
| id | name | status | type |
+--------------------------------------+--------------------------+--------+------+
| 413479b2-0d20-4c58-a9d3-b129fa592d8e | my_ldap_security_service | new | ldap |
+--------------------------------------+--------------------------+--------+------+
You also can dissociate a security service from the share network
and confirm that the security service now has an empty list of
share networks:
.. code-block:: console
$ manila share-network-security-service-remove share_net2 my_ldap_security_service
$ manila security-service-show my_ldap_security_service
+----------------+--------------------------------------+
| Property | Value |
+----------------+--------------------------------------+
| status | new |
| domain | None |
| password | None |
| name | my_ldap_security_service |
| dns_ip | 8.8.8.8 |
| created_at | 2015-09-25T10:19:06.000000 |
| updated_at | None |
| server | 10.254.0.3 |
| share_networks | [] |
| user | None |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| type | ldap |
| id | 413479b2-0d20-4c58-a9d3-b129fa592d8e |
| description | None |
+----------------+--------------------------------------+
The Shared File Systems service allows you to update a security service field
using :command:`manila security-service-update` command with optional
arguments such as ``--dns-ip``, ``--server``, ``--domain``,
``--user``, ``--password``, ``--name``, or
``--description``.
To remove a security service not associated with any share networks
run:
.. code-block:: console
$ manila security-service-delete my_ldap_security_service

16
doc/source/admin/shared-file-systems-services-manage.rst Normal file
View File

@ -0,0 +1,16 @@
.. _shared_file_systems_services_manage.rst:
======================
Manage shares services
======================
The Shared File Systems service provides API that allows to manage running
share services (`Share services API
<https://developer.openstack.org/api-ref/shared-file-systems/>`_).
Using the :command:`manila service-list` command, it is possible to get a list
of all kinds of running services. To select only share services, you can pick
items that have field ``binary`` equal to ``manila-share``. Also, you can
enable or disable share services using raw API requests. Disabling means that
share services are excluded from the scheduler cycle and new shares will not
be placed on the disabled back end. However, shares from this service stay
available.

33
doc/source/admin/shared-file-systems-share-management.rst Normal file
View File

@ -0,0 +1,33 @@
.. _shared_file_systems_share_management:
================
Share management
================
A share is a remote, mountable file system. You can mount a share to and access
a share from several hosts by several users at a time.
You can create a share and associate it with a network, list shares, and show
information for, update, and delete a specified share.
You can also create snapshots of shares. To create a snapshot, you specify the
ID of the share that you want to snapshot.
The shares are based on of the supported Shared File Systems protocols:
* *NFS*. Network File System (NFS).
* *CIFS*. Common Internet File System (CIFS).
* *GLUSTERFS*. Gluster file system (GlusterFS).
* *HDFS*. Hadoop Distributed File System (HDFS).
* *CEPHFS*. Ceph File System (CephFS).
The Shared File Systems service provides set of drivers that enable you to use
various network file storage devices, instead of the base implementation. That
is the real purpose of the Shared File Systems service in production.
.. toctree::
shared-file-systems-crud-share.rst
shared-file-systems-manage-and-unmanage-share.rst
shared-file-systems-manage-and-unmanage-snapshot.rst
shared-file-systems-share-resize.rst
shared-file-systems-quotas.rst

306
doc/source/admin/shared-file-systems-share-migration.rst Normal file
View File

@ -0,0 +1,306 @@
.. _shared_file_systems_share_migration:
===============
Share migration
===============
Share migration is the feature that migrates a share between different storage
pools.
Use cases
~~~~~~~~~
As an administrator, you may want to migrate your share from one storage pool
to another for several reasons. Examples include:
* Maintenance or evacuation
* Evacuate a back end for hardware or software upgrades
* Evacuate a back end experiencing failures
* Evacuate a back end which is tagged end-of-life
* Optimization
* Defragment back ends to empty and be taken offline to conserve power
* Rebalance back ends to maximize available performance
* Move data and compute closer together to reduce network utilization and
decrease latency or increase bandwidth
* Moving shares
* Migrate from old hardware generation to a newer generation
* Migrate from one vendor to another
Migration workflows
~~~~~~~~~~~~~~~~~~~
Moving shares across different storage pools is generally expected to be a
disruptive operation that disconnects existing clients when the source ceases
to exist. For this reason, share migration is implemented in a 2-phase approach
that allows the administrator to control the timing of the disruption. The
first phase performs data copy while users retain access to the share. When
copying is complete, the second phase may be triggered to perform a switchover
that may include a last sync and deleting the source, generally requiring users
to reconnect to continue accessing the share.
In order to migrate a share, one of two possible mechanisms may be employed,
which provide different capabilities and affect how the disruption occurs with
regards to user access during data copy phase and disconnection during
switchover phase. Those two mechanisms are:
* Driver-assisted migration: This mechanism is intended to make use of driver
optimizations to migrate shares between pools of the same storage vendor.
This mechanism allows migrating shares nondisruptively while the source
remains writable, preserving all filesystem metadata and snapshots. The
migration workload is performed in the storage back end.
* Host-assisted migration: This mechanism is intended to migrate shares in an
agnostic manner between two different pools, regardless of storage vendor.
The implementation for this mechanism does not offer the same properties
found in driver-assisted migration. In host-assisted migration, the source
remains readable, snapshots must be deleted prior to starting the migration,
filesystem metadata may be lost, and the clients will get disconnected by the
end of migration. The migration workload is performed by the Data Service,
which is a dedicated manila service for intensive data operations.
When starting a migration, driver-assisted migration is attempted first. If
the shared file system service detects it is not possible to perform the
driver-assisted migration, it proceeds to attempt host-assisted migration.
Using the migration APIs
~~~~~~~~~~~~~~~~~~~~~~~~
The commands to interact with the share migration API are:
* ``migration_start``: starts a migration while retaining access to the share.
Migration is paused and waits for ``migration_complete`` invocation when it
has copied all data and is ready to take down the source share.
.. code-block:: console
$ manila migration-start share_1 ubuntu@generic2#GENERIC2 --writable False --preserve-snapshots False --preserve-metadata False --nondisruptive False
.. note::
This command has no output.
* ``migration_complete``: completes a migration, removing the source share and
setting the destination share instance to ``available``.
.. code-block:: console
$ manila migration-complete share_1
.. note::
This command has no output.
* ``migration_get_progress``: obtains migration progress information of a
share.
.. code-block:: console
$ manila migration-get-progress share_1
+----------------+--------------------------+
| Property | Value |
+----------------+--------------------------+
| task_state | data_copying_in_progress |
| total_progress | 37 |
+----------------+--------------------------+
* ``migration_cancel``: cancels an in-progress migration of a share.
.. code-block:: console
$ manila migration-cancel share_1
.. note::
This command has no output.
The parameters
--------------
To start a migration, an administrator should specify several parameters. Among
those, two of them are key for the migration.
* ``share``: The share that will be migrated.
* ``destination_pool``: The destination pool to which the share should be
migrated to, in format host@backend#pool.
Several other parameters, referred to here as ``driver-assisted parameters``,
*must* be specified in the ``migration_start`` API. They are:
* ``preserve_metadata``: whether preservation of filesystem metadata should be
enforced for this migration.
* ``preserve_snapshots``: whether preservation of snapshots should be enforced
for this migration.
* ``writable``: whether the source share remaining writable should be enforced
for this migration.
* ``nondisruptive``: whether it should be enforced to keep clients connected
throughout the migration.
Specifying any of the boolean parameters above as ``True`` will disallow a
host-assisted migration.
In order to appropriately move a share to a different storage pool, it may be
required to change one or more share properties, such as the share type, share
network, or availability zone. To accomplish this, use the optional parameters:
* ``new_share_type_id``: Specify the ID of the share type that should be set in
the migrated share.
* ``new_share_network_id``: Specify the ID of the share network that should be
set in the migrated share.
If driver-assisted migration should not be attempted, you may provide the
optional parameter:
* ``force_host_assisted_migration``: whether driver-assisted migration attempt
should be skipped. If this option is set to ``True``, all driver-assisted
options must be set to ``False``.
Configuration
~~~~~~~~~~~~~
For share migration to work in the cloud, there are several configuration
requirements that need to be met:
For driver-assisted migration: it is necessary that the configuration of all
back end stanzas is present in the file manila.conf of all manila-share nodes.
Also, network connectivity between the nodes running manila-share service and
their respective storage back ends is required.
For host-assisted migration: it is necessary that the Data Service
(manila-data) is installed and configured in a node connected to the cloud's
administrator network. The drivers pertaining to the source back end and
destination back end involved in the migration should be able to provide shares
that can be accessed from the administrator network. This can easily be
accomplished if the driver supports ``admin_only`` export locations, else it is
up to the administrator to set up means of connectivity.
In order for the Data Service to mount the source and destination instances, it
must use manila share access APIs to grant access to mount the instances.
The access rule type varies according to the share protocol, so there are a few
config options to set the access value for each type:
* ``data_node_access_ip``: For IP-based access type, provide the value of the
IP of the Data Service node in the administrator network. For NFS shares,
drivers should always add rules with the "no_root_squash" property.
* ``data_node_access_cert``: For certificate-based access type, provide the
value of the certificate name that grants access to the Data Service.
* ``data_node_access_admin_user``: For user-based access type, provide the
value of a username that grants access and administrator privileges to the
files in the share.
* ``data_node_mount_options``: Provide the value of a mapping of protocol name
to respective mount options. The Data Service makes use of mount command
templates that by default have a dedicated field to inserting mount options
parameter. The default value for this config option already includes the
username and password parameters for CIFS shares and NFS v3 enforcing
parameter for NFS shares.
* ``mount_tmp_location``: Provide the value of a string representing the path
where the share instances used in migration should be temporarily mounted.
The default value is ``/tmp/``.
* ``check_hash``: This boolean config option value determines whether the hash
of all files copied in migration should be validated. Setting this option
increases the time it takes to migrate files, and is recommended for
ultra-dependable systems. It defaults to disabled.
The configuration options above are respective to the Data Service only and
should be defined the ``DEFAULT`` group of the ``manila.conf`` configuration
file. Also, the Data Service node must have all the protocol-related libraries
pre-installed to be able to run the mount commands for each protocol.
You may need to change some driver-specific configuration options from their
default value to work with specific drivers. If so, they must be set under the
driver configuration stanza in ``manila.conf``. See a detailed description for
each one below:
* ``migration_ignore_files``: Provide value as a list containing the names of
files or folders to be ignored during migration for a specific driver. The
default value is a list containing only ``lost+found`` folder.
* ``share_mount_template``: Provide a string that defines the template for the
mount command for a specific driver. The template should contain the
following entries to be formatted by the code:
* proto: The share protocol. Automatically formatted by the Data Service.
* options: The mount options to be formatted by the Data Service according to
the data_node_mount_options config option.
* export: The export path of the share. Automatically formatted by the Data
Service with the share's ``admin_only`` export location.
* path: The path to mount the share. Automatically formatted by the Data
Serivce according to the mount_tmp_location config option.
The default value for this config option is::
mount -vt %(proto)s %(options)s %(export)s %(path)s.
* ``share_unmount_template``: Provide the value of a string that defines the
template for the unmount command for a specific driver. The template should
contain the path of where the shares are mounted, according to the
``mount_tmp_location`` config option, to be formatted automatically by the
Data Service. The default value for this config option is::
umount -v %(path)s
* ``protocol_access_mapping``: Provide the value of a mapping of access rule
type to protocols supported. The default value specifies IP and user based
access types mapped to NFS and CIFS respectively, which are the combinations
supported by manila. If a certain driver uses a different protocol for IP or
user access types, or is not included in the default mapping, it should be
specified in this configuration option.
Other remarks
~~~~~~~~~~~~~
* There is no need to manually add any of the previously existing access rules
after a migration is complete, they will be persisted on the destination
after the migration.
* Once migration of a share has started, the user will see the status
``migrating`` and it will block other share actions, such as adding or
removing access rules, creating or deleting snapshots, resizing, among
others.
* The destination share instance export locations, although it may exist from
the beginning of a host-assisted migration, are not visible nor accessible as
access rules cannot be added.
* During a host-assisted migration, an access rule granting access to the Data
Service will be added and displayed by querying the ``access-list`` API. This
access rule should not be tampered with, it will otherwise cause migration to
fail.
* Resources allocated are cleaned up automatically when a migration fails,
except if this failure occurs during the 2nd phase of a driver-assisted
migration. Each step in migration is saved to the field ``task_state``
present in the Share model. If for any reason the state is not set to
``migration_error`` during a failure, it will need to be reset using the
``reset-task-state`` API.
* It is advised that the node running the Data Service is well secured, since
it will be mounting shares with highest privileges, temporarily exposing user
data to whoever has access to this node.
* The two mechanisms of migration are affected differently by service restarts:
* If performing a host-assisted migration, all services may be restarted
except for the manila-data service when performing the copy (the
``task_state`` field value starts with ``data_copying_``). In other steps
of the host-assisted migration, both the source and destination
manila-share services should not be restarted.
* If performing a driver-assisted migration, the migration is affected
minimally by driver restarts if the ``task_state`` is
``migration_driver_in_progress``, while the copy is being done in the
back end. Otherwise, the source and destination manila-share services
should not be restarted.

151
doc/source/admin/shared-file-systems-share-networks.rst Normal file
View File

@ -0,0 +1,151 @@
.. _shared_file_systems_share_networks:
==============
Share networks
==============
Share network is an entity that encapsulates interaction with the OpenStack
Networking service. If the share driver that you selected runs in a mode
requiring Networking service interaction, specify the share network when
creating a new share network.
How to create share network
~~~~~~~~~~~~~~~~~~~~~~~~~~~
To list networks in a project, run:
.. code-block:: console
$ openstack network list
+--------------+---------+--------------------+
| ID | Name | Subnets |
+--------------+---------+--------------------+
| bee7411d-... | public | 884a6564-0f11-... |
| | | e6da81fa-5d5f-... |
| 5ed5a854-... | private | 74dcfb5a-b4d7-... |
| | | cc297be2-5213-... |
+--------------+---------+--------------------+
A share network stores network information that share servers can use where
shares are hosted. You can associate a share with a single share network.
When you create or update a share, you can optionally specify the ID of a share
network through which instances can access the share.
When you create a share network, you can specify only one type of network:
- OpenStack Networking (neutron). Specify a network ID and subnet ID.
In this case ``manila.network.nova_network_plugin.NeutronNetworkPlugin``
will be used.
- Legacy networking (nova-network). Specify a network ID.
In this case ``manila.network.nova_network_plugin.NoveNetworkPlugin``
will be used.
For more information about supported plug-ins for share networks, see
:ref:`shared_file_systems_network_plugins`.
A share network has these attributes:
- The IP block in Classless Inter-Domain Routing (CIDR) notation from which to
allocate the network.
- The IP version of the network.
- The network type, which is `vlan`, `vxlan`, `gre`, or `flat`.
If the network uses segmentation, a segmentation identifier. For example, VLAN,
VXLAN, and GRE networks use segmentation.
To create a share network with private network and subnetwork, run:
.. code-block:: console
$ manila share-network-create --neutron-net-id 5ed5a854-21dc-4ed3-870a-117b7064eb21 \
--neutron-subnet-id 74dcfb5a-b4d7-4855-86f5-a669729428dc --name my_share_net --description "My first share network"
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| name | my_share_net |
| segmentation_id | None |
| created_at | 2015-09-24T12:06:32.602174 |
| neutron_subnet_id | 74dcfb5a-b4d7-4855-86f5-a669729428dc |
| updated_at | None |
| network_type | None |
| neutron_net_id | 5ed5a854-21dc-4ed3-870a-117b7064eb21 |
| ip_version | None |
| nova_net_id | None |
| cidr | None |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| id | 5c3cbabb-f4da-465f-bc7f-fadbe047b85a |
| description | My first share network |
+-------------------+--------------------------------------+
The ``segmentation_id``, ``cidr``, ``ip_version``, and ``network_type``
share network attributes are automatically set to the values determined by the
network provider.
To check the network list, run:
.. code-block:: console
$ manila share-network-list
+--------------------------------------+--------------+
| id | name |
+--------------------------------------+--------------+
| 5c3cbabb-f4da-465f-bc7f-fadbe047b85a | my_share_net |
+--------------------------------------+--------------+
If you configured the generic driver with ``driver_handles_share_servers =
True`` (with the share servers) and already had previous operations in the Shared
File Systems service, you can see ``manila_service_network`` in the neutron
list of networks. This network was created by the generic driver for internal
use.
.. code-block:: console
$ openstack network list
+--------------+------------------------+--------------------+
| ID | Name | Subnets |
+--------------+------------------------+--------------------+
| 3b5a629a-e...| manila_service_network | 4f366100-50... |
| bee7411d-... | public | 884a6564-0f11-... |
| | | e6da81fa-5d5f-... |
| 5ed5a854-... | private | 74dcfb5a-b4d7-... |
| | | cc297be2-5213-... |
+--------------+------------------------+--------------------+
You also can see detailed information about the share network including
``network_type``, and ``segmentation_id`` fields:
.. code-block:: console
$ openstack network show manila_service_network
+---------------------------+--------------------------------------+
| Field | Value |
+---------------------------+--------------------------------------+
| admin_state_up | UP |
| availability_zone_hints | |
| availability_zones | nova |
| created_at | 2016-12-13T09:31:30Z |
| description | |
| id | 3b5a629a-e7a1-46a3-afb2-ab666fb884bc |
| ipv4_address_scope | None |
| ipv6_address_scope | None |
| mtu | 1450 |
| name | manila_service_network |
| port_security_enabled | True |
| project_id | f6ac448a469b45e888050cf837b6e628 |
| provider:network_type | vxlan |
| provider:physical_network | None |
| provider:segmentation_id | 73 |
| revision_number | 7 |
| router:external | Internal |
| shared | False |
| status | ACTIVE |
| subnets | 682e3329-60b0-440f-8749-83ef53dd8544 |
| tags | [] |
| updated_at | 2016-12-13T09:31:36Z |
+---------------------------+--------------------------------------+
You also can add and remove the security services from the share network.
For more detail, see :ref:`shared_file_systems_security_services`.

601
doc/source/admin/shared-file-systems-share-replication.rst Normal file
View File

@ -0,0 +1,601 @@
.. _shared_file_systems_share_replication:
=================
Share replication
=================
Replication of data has a number of use cases in the cloud. One use case is
High Availability of the data in a shared file system, used for example, to
support a production database. Another use case is ensuring Data Protection;
i.e being prepared for a disaster by having a replication location that will be
ready to back up your primary data source.
The Shared File System service supports user facing APIs that allow users to
create shares that support replication, add and remove share replicas and
manage their snapshots and access rules. Three replication types are currently
supported and they vary in the semantics associated with the primary share and
the secondary copies.
.. important::
**Share replication** is an **experimental** Shared File Systems API in
the Mitaka release. Contributors can change or remove the experimental
part of the Shared File Systems API in further releases without maintaining
backward compatibility. Experimental APIs have an
``X-OpenStack-Manila-API-Experimental: true`` header in their HTTP requests.
Replication types supported
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before using share replication, make sure the Shared File System driver that
you are running supports this feature. You can check it in the
``manila-scheduler`` service reports. The ``replication_type`` capability
reported can have one of the following values:
writable
The driver supports creating ``writable`` share replicas. All share replicas
can be accorded read/write access and would be synchronously mirrored.
readable
The driver supports creating ``read-only`` share replicas. All secondary
share replicas can be accorded read access. Only the primary (or ``active``
share replica) can be written into.
dr
The driver supports creating ``dr`` (abbreviated from Disaster Recovery)
share replicas. A secondary share replica is inaccessible until after a
``promotion``.
None
The driver does not support Share Replication.
.. note::
The term ``active`` share replica refers to the ``primary`` share. In
``writable`` style of replication, all share replicas are ``active``, and
there could be no distinction of a ``primary`` share. In ``readable`` and
``dr`` styles of replication, a ``secondary`` share replica may be referred
to as ``passive``, ``non-active`` or simply, ``replica``.
Configuration
~~~~~~~~~~~~~
Two new configuration options have been introduced to support Share
Replication.
replica_state_update_interval
Specify this option in the ``DEFAULT`` section of your ``manila.conf``.
The Shared File Systems service requests periodic update of the
`replica_state` of all ``non-active`` share replicas. The update occurs with
respect to an interval corresponding to this option. If it is not specified,
it defaults to 300 seconds.
replication_domain
Specify this option in the backend stanza when using a multi-backend style
configuration. The value can be any ASCII string. Two backends that can
replicate between each other would have the same ``replication_domain``.
This comes from the premise that the Shared File Systems service expects
Share Replication to be performed between symmetric backends. This option
is *required* for using the Share Replication feature.
Health of a share replica
~~~~~~~~~~~~~~~~~~~~~~~~~
Apart from the ``status`` attribute, share replicas have the
``replica_state`` attribute to denote the state of data replication on the
storage backend. The ``primary`` share replica will have it's `replica_state`
attribute set to `active`. The ``secondary`` share replicas may have one of
the following as their ``replica_state``:
in_sync
The share replica is up to date with the ``active`` share replica (possibly
within a backend-specific ``recovery point objective``).
out_of_sync
The share replica is out of date (all new share replicas start out in
this ``replica_state``).
error
When the scheduler fails to schedule this share replica or some potentially
irrecoverable error occurred with regard to updating data for this replica.
Promotion or failover
~~~~~~~~~~~~~~~~~~~~~
For ``readable`` and ``dr`` types of replication, we refer to the task
of switching a `non-active` share replica with the ``active`` replica as
`promotion`. For the ``writable`` style of replication, promotion does
not make sense since all share replicas are ``active`` (or writable) at all
times.
The `status` attribute of the non-active replica being promoted will be
set to ``replication_change`` during its promotion. This has been classified as
a ``busy`` state and thus API interactions with the share are restricted
while one of its share replicas is in this state.
Share replication workflows
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following examples have been implemented with the ZFSonLinux driver that
is a reference implementation in the Shared File Systems service. It operates
in ``driver_handles_share_servers=False`` mode and supports the ``readable``
type of replication. In the example, we assume a configuration of two
Availability Zones (configuration option: ``storage_availability_zone``),
called `availability_zone_1` and `availability_zone_2`.
Multiple availability zones are not necessary to use the replication feature.
However, the use of an availability zone as a ``failure domain`` is encouraged.
Pay attention to the network configuration for the ZFS driver. Here, we assume
a configuration of ``zfs_service_ip`` and ``zfs_share_export_ip`` from two
separate networks. The service network is reachable from the host where the
``manila-share`` service is running. The share export IP is from a network that
allows user access.
See `Configuring the ZFSonLinux driver <https://docs.openstack.org/ocata/config-reference/shared-file-systems/drivers/zfs-on-linux-driver.html>`_
for information on how to set up the ZFSonLinux driver.
Creating a share that supports replication
------------------------------------------
Create a new share type and specify the `replication_type` as an extra-spec
within the share-type being used.
Use the :command:`manila type-create` command to create a new share type.
Specify the name and the value for the extra-spec
``driver_handles_share_servers``.
.. code-block:: console
$ manila type-create readable_type_replication False
+----------------------+--------------------------------------+
| Property | Value |
+----------------------+--------------------------------------+
| required_extra_specs | driver_handles_share_servers : False |
| Name | readable_type_replication |
| Visibility | public |
| is_default | - |
| ID | 3b3ee3f7-6e43-4aa1-859d-0b0511c43074 |
| optional_extra_specs | snapshot_support : True |
+----------------------+--------------------------------------+
Use the :command:`manila type-key` command to set an extra-spec to the
share type.
.. code-block:: console
$ manila type-key readable_type_replication set replication_type=readable
.. note::
This command has no output. To verify the extra-spec, use the
:command:`manila extra-specs-list` command and specify the share type's name
or ID as a parameter.
Create a share with the share type
Use the :command:`manila create` command to create a share. Specify the share
protocol, size and the availability zone.
.. code-block:: console
$ manila create NFS 1 --share_type readable_type_replication --name my_share --description "This share will have replicas" --az availability_zone_1
+-----------------------------+--------------------------------------+
| Property | Value |
+-----------------------------+--------------------------------------+
| status | creating |
| share_type_name | readable_type_replication |
| description | This share will have replicas |
| availability_zone | availability_zone_1 |
| share_network_id | None |
| share_server_id | None |
| host | |
| access_rules_status | active |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | e496ed61-8f2e-436b-b299-32c3e90991cc |
| size | 1 |
| name | my_share |
| share_type | 3b3ee3f7-6e43-4aa1-859d-0b0511c43074 |
| has_replicas | False |
| replication_type | readable |
| created_at | 2016-03-29T20:22:18.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 48a5ca76ac69405e99dc1c13c5195186 |
| metadata | {} |
+-----------------------------+--------------------------------------+
Use the :command:`manila show` command to retrieve details of the share.
Specify the share ID or name as a parameter.
.. code-block:: console
$ manila show my_share
+-----------------------------+--------------------------------------------------------------------+
| Property | Value |
+-----------------------------+--------------------------------------------------------------------+
| status | available |
| share_type_name | readable_type_replication |
| description | This share will have replicas |
| availability_zone | availability_zone_1 |
| share_network_id | None |
| export_locations | |
| | path = |
| |10.32.62.26:/alpha/manila_share_38efc042_50c2_4825_a6d8_cba2a8277b28|
| | preferred = False |
| | is_admin_only = False |
| | id = e1d754b5-ec06-42d2-afff-3e98c0013faf |
| | share_instance_id = 38efc042-50c2-4825-a6d8-cba2a8277b28 |
| | path = |
| |172.21.0.23:/alpha/manila_share_38efc042_50c2_4825_a6d8_cba2a8277b28|
| | preferred = False |
| | is_admin_only = True |
| | id = 6f843ecd-a7ea-4939-86de-e1e01d9e8672 |
| | share_instance_id = 38efc042-50c2-4825-a6d8-cba2a8277b28 |
| share_server_id | None |
| host | openstack4@zfsonlinux_1#alpha |
| access_rules_status | active |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | e496ed61-8f2e-436b-b299-32c3e90991cc |
| size | 1 |
| name | my_share |
| share_type | 3b3ee3f7-6e43-4aa1-859d-0b0511c43074 |
| has_replicas | False |
| replication_type | readable |
| created_at | 2016-03-29T20:22:18.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 48a5ca76ac69405e99dc1c13c5195186 |
| metadata | {} |
+-----------------------------+--------------------------------------------------------------------+
.. note::
When you create a share that supports replication, an ``active`` replica is
created for you. You can verify this with the
:command:`manila share-replica-list` command.
Creating and promoting share replicas
-------------------------------------
Create a share replica
Use the :command:`manila share-replica-create` command to create a share
replica. Specify the share ID or name as a parameter. You may
optionally provide the `availability_zone` and `share_network_id`. In the
example below, `share_network_id` is not used since the ZFSonLinux driver
does not support it.
.. code-block:: console
$ manila share-replica-create my_share --az availability_zone_2
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| status | creating |
| share_id | e496ed61-8f2e-436b-b299-32c3e90991cc |
| availability_zone | availability_zone_2 |
| created_at | 2016-03-29T20:24:53.148992 |
| updated_at | None |
| share_network_id | None |
| share_server_id | None |
| host | |
| replica_state | None |
| id | 78a5ef96-6c36-42e0-b50b-44efe7c1807e |
+-------------------+--------------------------------------+
See details of the newly created share replica
Use the :command:`manila share-replica-show` command to see details
of the newly created share replica. Specify the share replica's ID as a
parameter.
.. code-block:: console
$ manila share-replica-show 78a5ef96-6c36-42e0-b50b-44efe7c1807e
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| status | available |
| share_id | e496ed61-8f2e-436b-b299-32c3e90991cc |
| availability_zone | availability_zone_2 |
| created_at | 2016-03-29T20:24:53.000000 |
| updated_at | 2016-03-29T20:24:58.000000 |
| share_network_id | None |
| share_server_id | None |
| host | openstack4@zfsonlinux_2#beta |
| replica_state | in_sync |
| id | 78a5ef96-6c36-42e0-b50b-44efe7c1807e |
+-------------------+--------------------------------------+
See all replicas of the share
Use the :command:`manila share-replica-list` command to see all the replicas
of the share. Specify the share ID or name as an optional parameter.
.. code-block:: console
$ manila share-replica-list --share-id my_share
+--------------------------------------+-----------+---------------+--------------------------------------+-------------------------------+---------------------+----------------------------+
| ID | Status | Replica State | Share ID | Host | Availability Zone | Updated At |
+--------------------------------------+-----------+---------------+--------------------------------------+-------------------------------+---------------------+----------------------------+
| 38efc042-50c2-4825-a6d8-cba2a8277b28 | available | active | e496ed61-8f2e-436b-b299-32c3e90991cc | openstack4@zfsonlinux_1#alpha | availability_zone_1 | 2016-03-29T20:22:19.000000 |
| 78a5ef96-6c36-42e0-b50b-44efe7c1807e | available | in_sync | e496ed61-8f2e-436b-b299-32c3e90991cc | openstack4@zfsonlinux_2#beta | availability_zone_2 | 2016-03-29T20:24:58.000000 |
+--------------------------------------+-----------+---------------+--------------------------------------+-------------------------------+---------------------+----------------------------+
Promote the secondary share replica to be the new active replica
Use the :command:`manila share-replica-promote` command to promote a
non-active share replica to become the ``active`` replica. Specify the
non-active replica's ID as a parameter.
.. code-block:: console
$ manila share-replica-promote 78a5ef96-6c36-42e0-b50b-44efe7c1807e
.. note::
This command has no output.
The promotion may take time. During the promotion, the ``replica_state``
attribute of the share replica being promoted will be set to
``replication_change``.
.. code-block:: console
$ manila share-replica-list --share-id my_share
+--------------------------------------+-----------+--------------------+--------------------------------------+-------------------------------+---------------------+----------------------------+
| ID | Status | Replica State | Share ID | Host | Availability Zone | Updated At |
+--------------------------------------+-----------+--------------------+--------------------------------------+-------------------------------+---------------------+----------------------------+
| 38efc042-50c2-4825-a6d8-cba2a8277b28 | available | active | e496ed61-8f2e-436b-b299-32c3e90991cc | openstack4@zfsonlinux_1#alpha | availability_zone_1 | 2016-03-29T20:32:19.000000 |
| 78a5ef96-6c36-42e0-b50b-44efe7c1807e | available | replication_change | e496ed61-8f2e-436b-b299-32c3e90991cc | openstack4@zfsonlinux_2#beta | availability_zone_2 | 2016-03-29T20:32:19.000000 |
+--------------------------------------+-----------+--------------------+--------------------------------------+-------------------------------+---------------------+----------------------------+
Once the promotion is complete, the ``replica_state`` will be set to
``active``.
.. code-block:: console
$ manila share-replica-list --share-id my_share
+--------------------------------------+-----------+---------------+--------------------------------------+-------------------------------+---------------------+----------------------------+
| ID | Status | Replica State | Share ID | Host | Availability Zone | Updated At |
+--------------------------------------+-----------+---------------+--------------------------------------+-------------------------------+---------------------+----------------------------+
| 38efc042-50c2-4825-a6d8-cba2a8277b28 | available | in_sync | e496ed61-8f2e-436b-b299-32c3e90991cc | openstack4@zfsonlinux_1#alpha | availability_zone_1 | 2016-03-29T20:32:19.000000 |
| 78a5ef96-6c36-42e0-b50b-44efe7c1807e | available | active | e496ed61-8f2e-436b-b299-32c3e90991cc | openstack4@zfsonlinux_2#beta | availability_zone_2 | 2016-03-29T20:32:19.000000 |
+--------------------------------------+-----------+---------------+--------------------------------------+-------------------------------+---------------------+----------------------------+
Access rules
------------
Create an IP access rule for the share
Use the :command:`manila access-allow` command to add an access rule.
Specify the share ID or name, protocol and the target as parameters.
.. code-block:: console
$ manila access-allow my_share ip 0.0.0.0/0 --access-level rw
+--------------+--------------------------------------+
| Property | Value |
+--------------+--------------------------------------+
| share_id | e496ed61-8f2e-436b-b299-32c3e90991cc |
| access_type | ip |
| access_to | 0.0.0.0/0 |
| access_level | rw |
| state | new |
| id | 8b339cdc-c1e0-448f-bf6d-f068ee6e8f45 |
+--------------+--------------------------------------+
.. note::
Access rules are not meant to be different across the replicas of the share.
However, as per the type of replication, drivers may choose to modify the
access level prescribed. In the above example, even though read/write access
was requested for the share, the driver will provide read-only access to
the non-active replica to the same target, because of the semantics of
the replication type: ``readable``. However, the target will have read/write
access to the (currently) non-active replica when it is promoted to
become the ``active`` replica.
The :command:`manila access-deny` command can be used to remove a previously
applied access rule.
List the export locations of the share
Use the :command:`manila share-export-locations-list` command to list the
export locations of a share.
.. code-block:: console
$ manila share-export-location-list my_share
+--------------------------------------+---------------------------------------------------------------------------+-----------+
| ID | Path | Preferred |
+--------------------------------------+---------------------------------------------------------------------------+-----------+
| 3ed3fbf5-2fa1-4dc0-8440-a0af72398cb6 | 10.32.62.21:/beta/subdir/manila_share_78a5ef96_6c36_42e0_b50b_44efe7c1807e| False |
| 6f843ecd-a7ea-4939-86de-e1e01d9e8672 | 172.21.0.23:/alpha/manila_share_38efc042_50c2_4825_a6d8_cba2a8277b28 | False |
| e1d754b5-ec06-42d2-afff-3e98c0013faf | 10.32.62.26:/alpha/manila_share_38efc042_50c2_4825_a6d8_cba2a8277b28 | False |
| f3c5585f-c2f7-4264-91a7-a4a1e754e686 | 172.21.0.29:/beta/subdir/manila_share_78a5ef96_6c36_42e0_b50b_44efe7c1807e| False |
+--------------------------------------+---------------------------------------------------------------------------+-----------+
Identify the export location corresponding to the share replica on the user
accessible network and you may mount it on the target node.
.. note::
As an administrator, you can list the export locations for a particular
share replica by using the
:command:`manila share-instance-export-location-list` command and
specifying the share replica's ID as a parameter.
Snapshots
---------
Create a snapshot of the share
Use the :command:`manila snapshot-create` command to create a snapshot
of the share. Specify the share ID or name as a parameter.
.. code-block:: console
$ manila snapshot-create my_share --name "my_snapshot"
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| status | creating |
| share_id | e496ed61-8f2e-436b-b299-32c3e90991cc |
| description | None |
| created_at | 2016-03-29T21:14:03.000000 |
| share_proto | NFS |
| provider_location | None |
| id | 06cdccaf-93a0-4e57-9a39-79fb1929c649 |
| size | 1 |
| share_size | 1 |
| name | my_snapshot |
+-------------------+--------------------------------------+
Show the details of the snapshot
Use the :command:`manila snapshot-show` to view details of a snapshot.
Specify the snapshot ID or name as a parameter.
.. code-block:: console
$ manila snapshot-show my_snapshot
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| status | available |
| share_id | e496ed61-8f2e-436b-b299-32c3e90991cc |
| description | None |
| created_at | 2016-03-29T21:14:03.000000 |
| share_proto | NFS |
| provider_location | None |
| id | 06cdccaf-93a0-4e57-9a39-79fb1929c649 |
| size | 1 |
| share_size | 1 |
| name | my_snapshot |
+-------------------+--------------------------------------+
.. note::
The ``status`` attribute of a snapshot will transition from ``creating``
to ``available`` only when it is present on all the share replicas that have
their ``replica_state`` attribute set to ``active`` or ``in_sync``.
Likewise, the ``replica_state`` attribute of a share replica will
transition from ``out_of_sync`` to ``in_sync`` only when all ``available``
snapshots are present on it.
Planned failovers
-----------------
As an administrator, you can use the :command:`manila share-replica-resync`
command to attempt to sync data between ``active`` and ``non-active`` share
replicas of a share before promotion. This will ensure that share replicas have
the most up-to-date data and their relationships can be safely switched.
.. code-block:: console
$ manila share-replica-resync 38efc042-50c2-4825-a6d8-cba2a8277b28
.. note::
This command has no output.
Updating attributes
-------------------
If an error occurs while updating data or replication relationships (during
a ``promotion``), the Shared File Systems service may not be able to determine
the consistency or health of a share replica. It may require administrator
intervention to make any fixes on the storage backend as necessary. In such a
situation, state correction within the Shared File Systems service is possible.
As an administrator, you can:
Reset the ``status`` attribute of a share replica
Use the :command:`manila share-replica-reset-state` command to reset
the ``status`` attribute. Specify the share replica's ID as a parameter
and use the ``--state`` option to specify the state intended.
.. code-block:: console
$ manila share-replica-reset-state 38efc042-50c2-4825-a6d8-cba2a8277b28 --state=available
.. note::
This command has no output.
Reset the ``replica_state`` attribute
Use the :command:`manila share-replica-reset-replica-state` command to
reset the ``replica_state`` attribute. Specify the share replica's ID
and use the ``--state`` option to specify the state intended.
.. code-block:: console
$ manila share-replica-reset-replica-state 38efc042-50c2-4825-a6d8-cba2a8277b28 --state=out_of_sync
.. note::
This command has no output.
Force delete a specified share replica in any state
Use the :command:`manila share-replica-delete` command with the
'--force' key to remove the share replica, regardless of the state it is in.
.. code-block:: console
$ manila share-replica-show 9513de5d-0384-4528-89fb-957dd9b57680
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| status | error |
| share_id | e496ed61-8f2e-436b-b299-32c3e90991cc |
| availability_zone | availability_zone_1 |
| created_at | 2016-03-30T01:32:47.000000 |
| updated_at | 2016-03-30T01:34:25.000000 |
| share_network_id | None |
| share_server_id | None |
| host | openstack4@zfsonlinux_1#alpha |
| replica_state | out_of_sync |
| id | 38efc042-50c2-4825-a6d8-cba2a8277b28 |
+-------------------+--------------------------------------+
$ manila share-replica-delete --force 38efc042-50c2-4825-a6d8-cba2a8277b28
.. note::
This command has no output.
Use the ``policy.json`` file to grant permissions for these actions to other
roles.
Deleting share replicas
-----------------------
Use the :command:`manila share-replica-delete` command with the share
replica's ID to delete a share replica.
.. code-block:: console
$ manila share-replica-delete 38efc042-50c2-4825-a6d8-cba2a8277b28
.. note::
This command has no output.
.. note::
You cannot delete the last ``active`` replica with this command. You should
use the :command:`manila delete` command to remove the share.

111
doc/source/admin/shared-file-systems-share-resize.rst Normal file
View File

@ -0,0 +1,111 @@
.. _shared_file_systems_share_resize:
============
Resize share
============
To change file share size, use the :command:`manila extend` command and
the :command:`manila shrink` command. For most drivers it is safe
operation. If you want to be sure that your data is safe, you can make
a share back up by creating a snapshot of it.
You can extend and shrink the share with the :command:`manila extend` and
:command:`manila shrink` commands respectively, and specify the share
with the new size that does not exceed the quota. For details, see
:ref:`Quotas and Limits <shared_file_systems_quotas>`. You also cannot shrink
share size to 0 or to a greater value than the current share size.
While extending, the share has an ``extending`` status. This means that
the increase share size request was issued successfully.
To extend the share and check the result, run:
.. code-block:: console
$ manila extend docs_resize 2
$ manila show docs_resize
+----------------------+--------------------------------------------------------------------------+
| Property | Value |
+----------------------+--------------------------------------------------------------------------+
| status | available |
| share_type_name | my_type |
| description | None |
| availability_zone | nova |
| share_network_id | None |
| export_locations | |
| | path = 1.0.0.4:/shares/manila_share_b8afc508_8487_442b_b170_ea65b07074a8 |
| | preferred = False |
| | is_admin_only = False |
| | id = 3ffb76f4-92b9-4639-83fd-025bc3e302ff |
| | share_instance_id = b8afc508-8487-442b-b170-ea65b07074a8 |
| | path = 2.0.0.3:/shares/manila_share_b8afc508_8487_442b_b170_ea65b07074a8 |
| | preferred = False |
| | is_admin_only = True |
| | id = 1f0e263f-370d-47d3-95f6-1be64088b9da |
| | share_instance_id = b8afc508-8487-442b-b170-ea65b07074a8 |
| share_server_id | None |
| host | manila@paris#shares |
| access_rules_status | active |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | b07dbebe-a328-403c-b402-c8871c89e3d1 |
| size | 2 |
| name | docs_resize |
| share_type | 14ee8575-aac2-44af-8392-d9c9d344f392 |
| has_replicas | False |
| replication_type | None |
| created_at | 2016-03-25T15:33:18.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| project_id | 907004508ef4447397ce6741a8f037c1 |
| metadata | {} |
+----------------------+--------------------------------------------------------------------------+
While shrinking, the share has a ``shrinking`` status. This means that the
decrease share size request was issued successfully. To shrink the share and
check the result, run:
.. code-block:: console
$ manila shrink docs_resize 1
$ manila show docs_resize
+----------------------+--------------------------------------------------------------------------+
| Property | Value |
+----------------------+--------------------------------------------------------------------------+
| status | available |
| share_type_name | my_type |
| description | None |
| availability_zone | nova |
| share_network_id | None |
| export_locations | |
| | path = 1.0.0.4:/shares/manila_share_b8afc508_8487_442b_b170_ea65b07074a8 |
| | preferred = False |
| | is_admin_only = False |
| | id = 3ffb76f4-92b9-4639-83fd-025bc3e302ff |
| | share_instance_id = b8afc508-8487-442b-b170-ea65b07074a8 |
| | path = 2.0.0.3:/shares/manila_share_b8afc508_8487_442b_b170_ea65b07074a8 |
| | preferred = False |
| | is_admin_only = True |
| | id = 1f0e263f-370d-47d3-95f6-1be64088b9da |
| | share_instance_id = b8afc508-8487-442b-b170-ea65b07074a8 |
| share_server_id | None |
| host | manila@paris#shares |
| access_rules_status | active |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | b07dbebe-a328-403c-b402-c8871c89e3d1 |
| size | 1 |
| name | docs_resize |
| share_type | 14ee8575-aac2-44af-8392-d9c9d344f392 |
| has_replicas | False |
| replication_type | None |
| created_at | 2016-03-25T15:33:18.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| project_id | 907004508ef4447397ce6741a8f037c1 |
| metadata | {} |
+----------------------+--------------------------------------------------------------------------+

179
doc/source/admin/shared-file-systems-share-types.rst Normal file
View File

@ -0,0 +1,179 @@
.. _shared_file_systems_share_types:
===========
Share types
===========
A share type enables you to filter or choose back ends before you create a
share and to set data for the share driver. A share type behaves in the same
way as a Block Storage volume type behaves.
In the Shared File Systems configuration file ``manila.conf``, the
administrator can set the share type used by default for the share creation
and then create a default share type.
To create a share type, use :command:`manila type-create` command as:
.. code-block:: console
manila type-create [--snapshot_support <snapshot_support>]
[--is_public <is_public>]
<name> <spec_driver_handles_share_servers>
where the ``name`` is the share type name, ``--is_public`` defines the level of
the visibility for the share type, ``snapshot_support`` and
``spec_driver_handles_share_servers`` are the extra specifications used to
filter back ends. Administrators can create share types with these extra
specifications for the back ends filtering:
- ``driver_handles_share_servers``. Required. Defines the driver mode for share
server lifecycle management. Valid values are ``true``/``1`` and
``false``/``0``.
Set to True when the share driver can manage, or handle, the share server
lifecycle.
Set to False when an administrator, rather than a share driver, manages
the bare metal storage with some net interface instead of the presence
of the share servers.
- ``snapshot_support``. Filters back ends by whether they do or do not support
share snapshots. Default is ``True``.
Set to True to find back ends that support share snapshots.
Set to False to find back ends that do not support share snapshots.
.. note::
The extra specifications set in the share types are operated in the
:ref:`shared_file_systems_scheduling`.
Administrators can also set additional extra specifications for a share type
for the following purposes:
- *Filter back ends*. Unqualified extra specifications written in
this format: ``extra_spec=value``. For example, **netapp_raid_type=raid4**.
- *Set data for the driver*. Qualified extra specifications always written
with the prefix with a colon, except for the special ``capabilities``
prefix, in this format: ``vendor:extra_spec=value``. For example,
**netapp:thin_provisioned=true**.
The scheduler uses the special capabilities prefix for filtering. The scheduler
can only create a share on a back end that reports capabilities matching the
un-scoped extra-spec keys for the share type. For details, see `Capabilities
and Extra-Specs <https://docs.openstack.org/developer/manila/devref/
capabilities_and_extra_specs.html>`_.
Each driver implementation determines which extra specification keys it uses.
For details, see the documentation for the driver.
An administrator can use the ``policy.json`` file to grant permissions for
share type creation with extra specifications to other roles.
You set a share type to private or public and
:ref:`manage the access<share_type_access>` to the private share types. By
default a share type is created as publicly accessible. Set
``--is_public`` to ``False`` to make the share type private.
Share type operations
---------------------
To create a new share type you need to specify the name of the new share
type. You also require an extra spec ``driver_handles_share_servers``.
The new share type can also be public.
.. code-block:: console
$ manila type-create netapp1 False --is_public True
$ manila type-list
+-----+--------+-----------+-----------+-----------------------------------+-----------------------+
| ID | Name | Visibility| is_default| required_extra_specs | optional_extra_specs |
+-----+--------+-----------+-----------+-----------------------------------+-----------------------+
| c0..| netapp1| public | - | driver_handles_share_servers:False| snapshot_support:True |
+-----+--------+-----------+-----------+-----------------------------------+-----------------------+
You can set or unset extra specifications for a share type
using **manila type-key <share_type> set <key=value>** command. Since it is up
to each driver what extra specification keys it uses, see the documentation
for the specified driver.
.. code-block:: console
$ manila type-key netapp1 set thin_provisioned=True
It is also possible to view a list of current share types and extra
specifications:
.. code-block:: console
$ manila extra-specs-list
+-------------+---------+-------------------------------------+
| ID | Name | all_extra_specs |
+-------------+---------+-------------------------------------+
| c0086582-...| netapp1 | snapshot_support : True |
| | | thin_provisioned : True |
| | | driver_handles_share_servers : True |
+-------------+---------+-------------------------------------+
Use :command:`manila type-key <share_type> unset <key>` to unset an extra
specification.
The public or private share type can be deleted with the
:command:`manila type-delete <share_type>` command.
.. _share_type_access:
Share type access
-----------------
You can manage access to a private share type for different projects.
Administrators can provide access, remove access, and retrieve
information about access for a specified private share.
Create a private type:
.. code-block:: console
$ manila type-create my_type1 True --is_public False
+----------------------+--------------------------------------+
| Property | Value |
+----------------------+--------------------------------------+
| required_extra_specs | driver_handles_share_servers : True |
| Name | my_type1 |
| Visibility | private |
| is_default | - |
| ID | 06793be5-9a79-4516-89fe-61188cad4d6c |
| optional_extra_specs | snapshot_support : True |
+----------------------+--------------------------------------+
.. note::
If you run :command:`manila type-list` only public share types appear.
To see private share types, run :command:`manila type-list` with
``--all`` optional argument.
Grant access to created private type for a demo and alt_demo projects
by providing their IDs:
.. code-block:: console
$ manila type-access-add my_type1 d8f9af6915404114ae4f30668a4f5ba7
$ manila type-access-add my_type1 e4970f57f1824faab2701db61ee7efdf
To view information about access for a private share, type ``my_type1``:
.. code-block:: console
$ manila type-access-list my_type1
+----------------------------------+
| Project_ID |
+----------------------------------+
| d8f9af6915404114ae4f30668a4f5ba7 |
| e4970f57f1824faab2701db61ee7efdf |
+----------------------------------+
After granting access to the share, the target project
can see the share type in the list, and create private
shares.
To deny access for a specified project, use
:command:`manila type-access-remove <share_type> <project_id>` command.

140
doc/source/admin/shared-file-systems-snapshots.rst Normal file
View File

@ -0,0 +1,140 @@
.. _shared_file_systems_snapshots:
===============
Share snapshots
===============
The Shared File Systems service provides a snapshot mechanism to help users
restore data by running the :command:`manila snapshot-create` command.
To export a snapshot, create a share from it, then mount the new share
to an instance. Copy files from the attached share into the archive.
To import a snapshot, create a new share with appropriate size, attach it to
instance, and then copy a file from the archive to the attached file
system.
.. note::
You cannot delete a share while it has saved dependent snapshots.
Create a snapshot from the share:
.. code-block:: console
$ manila snapshot-create Share1 --name Snapshot1 --description "Snapshot of Share1"
+-------------+--------------------------------------+
| Property | Value |
+-------------+--------------------------------------+
| status | creating |
| share_id | aca648eb-8c03-4394-a5cc-755066b7eb66 |
| name | Snapshot1 |
| created_at | 2015-09-25T05:27:38.862040 |
| share_proto | NFS |
| id | 962e8126-35c3-47bb-8c00-f0ee37f42ddd |
| size | 1 |
| share_size | 1 |
| description | Snapshot of Share1 |
+-------------+--------------------------------------+
Update snapshot name or description if needed:
.. code-block:: console
$ manila snapshot-rename Snapshot1 Snapshot_1 --description "Snapshot of Share1. Updated."
Check that status of a snapshot is ``available``:
.. code-block:: console
$ manila snapshot-show Snapshot1
+-------------+--------------------------------------+
| Property | Value |
+-------------+--------------------------------------+
| status | available |
| share_id | aca648eb-8c03-4394-a5cc-755066b7eb66 |
| name | Snapshot1 |
| created_at | 2015-09-25T05:27:38.000000 |
| share_proto | NFS |
| id | 962e8126-35c3-47bb-8c00-f0ee37f42ddd |
| size | 1 |
| share_size | 1 |
| description | Snapshot of Share1 |
+-------------+--------------------------------------+
To restore your data from a snapshot, use :command:`manila create` with
key ``--snapshot-id``. This creates a new share from an
existing snapshot. Create a share from a snapshot and check whether
it is available:
.. code-block:: console
$ manila create nfs 1 --name Share2 --metadata source=snapshot --description "Share from a snapshot." --snapshot-id 962e8126-35c3-47bb-8c00-f0ee37f42ddd
+-----------------------------+--------------------------------------+
| Property | Value |
+-----------------------------+--------------------------------------+
| status | None |
| share_type_name | default |
| description | Share from a snapshot. |
| availability_zone | None |
| share_network_id | None |
| export_locations | [] |
| share_server_id | None |
| host | None |
| snapshot_id | 962e8126-35c3-47bb-8c00-f0ee37f42ddd |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | b6b0617c-ea51-4450-848e-e7cff69238c7 |
| size | 1 |
| name | Share2 |
| share_type | c0086582-30a6-4060-b096-a42ec9d66b86 |
| created_at | 2015-09-25T06:25:50.240417 |
| export_location | None |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| metadata | {u'source': u'snapshot'} |
+-----------------------------+--------------------------------------+
$ manila show Share2
+-----------------------------+-------------------------------------------+
| Property | Value |
+-----------------------------+-------------------------------------------+
| status | available |
| share_type_name | default |
| description | Share from a snapshot. |
| availability_zone | nova |
| share_network_id | 5c3cbabb-f4da-465f-bc7f-fadbe047b85a |
| export_locations | 10.254.0.3:/shares/share-1dc2a471-3d47-...|
| share_server_id | 41b7829d-7f6b-4c96-aea5-d106c2959961 |
| host | manila@generic1#GENERIC1 |
| snapshot_id | 962e8126-35c3-47bb-8c00-f0ee37f42ddd |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | b6b0617c-ea51-4450-848e-e7cff69238c7 |
| size | 1 |
| name | Share2 |
| share_type | c0086582-30a6-4060-b096-a42ec9d66b86 |
| created_at | 2015-09-25T06:25:50.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| metadata | {u'source': u'snapshot'} |
+-----------------------------+-------------------------------------------+
You can soft-delete a snapshot using :command:`manila snapshot-delete
<snapshot_name_or_ID>`. If a snapshot is in busy state, and during
the delete an ``error_deleting`` status appeared, administrator can
force-delete it or explicitly reset the state.
Use :command:`snapshot-reset-state [--state <state>] <snapshot>` to update
the state of a snapshot explicitly. A valid value of a status are
``available``, ``error``, ``creating``, ``deleting``, ``error_deleting``.
If no state is provided, the ``available`` state will be used.
Use :command:`manila snapshot-force-delete <snapshot>` to force-delete
a specified share snapshot in any state.

107
doc/source/admin/shared-file-systems-troubleshoot.rst Normal file
View File

@ -0,0 +1,107 @@
.. _shared_file_systems_troubleshoot:
========================================
Troubleshoot Shared File Systems service
========================================
Failures in Share File Systems service during a share creation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Problem
-------
New shares can enter ``error`` state during the creation process.
Solution
--------
#. Make sure, that share services are running in debug mode. If the debug mode
is not set, you will not get any tips from logs how to fix your issue.
#. Find what share service holds a specified share. To do that, run command
:command:`manila show <share_id_or_name>` and find a share host in the
output. Host uniquely identifies what share service holds the broken share.
#. Look thought logs of this share service. Usually, it can be found at
``/etc/var/log/manila-share.log``. This log should contain kind of
traceback with extra information to help you to find the origin of issues.
No valid host was found
~~~~~~~~~~~~~~~~~~~~~~~
Problem
-------
If a share type contains invalid extra specs, the scheduler will not be
able to locate a valid host for the shares.
Solution
--------
To diagnose this issue, make sure that scheduler service is running in
debug mode. Try to create a new share and look for message ``Failed to
schedule create_share: No valid host was found.`` in
``/etc/var/log/manila-scheduler.log``.
To solve this issue look carefully through the list of extra specs in
the share type, and the list of share services reported capabilities.
Make sure that extra specs are pointed in the right way.
Created share is unreachable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Problem
-------
By default, a new share does not have any active access rules.
Solution
--------
To provide access to new share, you need to create
appropriate access rule with the right value.
The value must defines access.
Service becomes unavailable after upgrade
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Problem
-------
After upgrading the Shared File Systems service from version v1 to version
v2.x, you must update the service endpoint in the OpenStack Identity service.
Otherwise, the service may become unavailable.
Solution
--------
#. To get the service type related to the Shared File Systems service, run:
.. code-block:: console
# openstack endpoint list
# openstack endpoint show <share-service-type>
You will get the endpoints expected from running the Shared File Systems
service.
#. Make sure that these endpoints are updated. Otherwise, delete the outdated
endpoints and create new ones.
Failures during management of internal resources
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Problem
-------
The Shared File System service manages internal resources effectively.
Administrators may need to manually adjust internal resources to
handle failures.
Solution
--------
Some drivers in the Shared File Systems service can create service entities,
like servers and networks. If it is necessary, you can log in to
project ``service`` and take manual control over it.

2
doc/source/index.rst
View File

@ -49,7 +49,7 @@ Admin Docs
.. toctree::
:maxdepth: 1
admin/index
admin/shared-file-systems-intro.rst
Contributor/Developer Docs
==========================