openstack/openstack-manuals
Code Issues Proposed changes

Merge "Cloud Admin Guide: Shared File Systems updated information"

Browse Source
This commit is contained in:
Jenkins 2015-10-28 22:14:04 +00:00 committed by Gerrit Code Review
commit 41a93dfaec
17 changed files with 1267 additions and 1075 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
doc/admin-guide-cloud/source/shared_file_systems_cgroups.rst
View File

@ -4,31 +4,32 @@
Consistency groups
==================
Consistency groups enable you to create snapshots at the exact same point in
time from multiple file system shares. For example, a database might place its
Consistency groups enable you to create snapshots from multiple file system
shares at the same point in time. For example, a database might place its
tables, logs, and configuration on separate shares. To restore this database
from a previous point in time, it makes sense to restore the logs, tables, and
configuration together from the exact same point in time.
Shared File system allows you to create a snapshot of the consistency group and
restore all shares that were associated with the consistency group by creating
a consistency group from a snapshot.
The Shared File System service allows you to create a snapshot of the
consistency group and restore all shares that were associated with a
consistency group.
.. note::
The **consistency groups and snapshots** are realized as an
**experimental** Shared File Systems API. Contributors can change or remove
the experimental part of the Shared File Systems API without maintaining
backward compatibility. The experimental API has
``"X-OpenStack-Manila-API-Experimental: true"`` header in their HTTP
requests.
**experimental** Shared File Systems API in Liberty release. Contributors
can change or remove the experimental part of the Shared File Systems API
in further releases without maintaining backward compatibility. The
experimental API has ``"X-OpenStack-Manila-API-Experimental: true"`` header
in their HTTP requests.
Consistency groups
------------------
.. note::
Before using consistency groups, make sure the Shared File System driver that
you are running has consistency group support. You can check it in the manila
scheduler reports. The ``consistency_group_support`` can have such values:
Before using consistency groups, make sure the Shared File System driver
that you are running has consistency group support. You can check it in the
``manila-scheduler`` service reports. The ``consistency_group_support`` can
have such values:
* ``pool`` or ``host``. Consistency groups are supported. Specifies the
level of consistency groups support.

264
doc/admin-guide-cloud/source/shared_file_systems_crud_share.rst
View File

@ -4,39 +4,231 @@
Share basic operations
======================
Create share
------------
General concepts
----------------
General concepts **to create file share**, you need to:
As general concepts, to create a file share and access it 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
Systems protocol (``NFS``, ``CIFS``, ``GlusterFS``, or ``HDFS`` are
supported).
specify the required arguments: the size of the share and the shared file
system protocol. ``NFS``, ``CIFS``, ``GlusterFS``, or ``HDFS`` share file
system protocols are supported.
#. You can also optionally specify the share network and the share type.
#. Use the :command:`manila create` command to create a share. This command
does the following things:
#. After the share becomes available, use the :command:`manila show` command
to get the share export location.
* If there is no available share servers, the Shared File Systems service
service will launch new instance from service image, attach it to service
network and register it as a new share server.
#. After getting the share export location, you can create an
:ref:`access rule <access_to_share>` for the share, mount it and work with
files on the remote file system.
* Creates new volume of required size and attaches it to the service
instance.
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.
* The NFS service on service instance is configured to use attached volume
and expose NFS share.
Initially there are two driver modes for the back ends:
#. After share becomes available, use the :command:`manila show` command
to get the share endpoint.
* no share servers mode
* share servers mode
In the example to create a share, the default share type and the
existing already share network are used.
Each share driver supports one or two of possible back end modes that can be
configured in :file:`manila.conf` file. The configuration option
``driver_handles_share_servers`` in :file:`manila.conf` file sets the share
servers mode or no share servers mode, and defines the driver mode for share
storage life cycle 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``, or ``HDFS`` 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 shared 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 location.
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:: console
$ manila type-list
+------+--------+-----------+------------------------------------+----------------------+
| ID | Name | is_default| required_extra_specs | optional_extra_specs |
+------+--------+-----------+------------------------------------+----------------------+
| le...| my_type| - | 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:: console
$ manila create nfs 1 --name Share2 --description "My share" --share-type my_type
+-----------------------------+--------------------------------------+
| Property | Value |
+-----------------------------+--------------------------------------+
| status | None |
| share_type_name | my_type |
| description | My share |
| availability_zone | None |
| share_network_id | None |
| export_locations | [] |
| share_server_id | None |
| host | None |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | bb9f0f28-4ca7-4fcb-a37c-9e3624584bec |
| size | 1 |
| name | Share2 |
| share_type | 1eafb65f-1987-44a9-9a98-20af91c95662 |
| created_at | 2015-10-01T09:44:59.669010 |
| export_location | None |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| metadata | {} |
+-----------------------------+--------------------------------------+
New share ``Share2`` should have a status ``available``:
.. code:: 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 | 10.254.0.7:/shares/share-d1a66eed-a724-4cbb-a886-2f97926bd3b3 |
| share_server_id | None |
| host | manila@cannes#CANNES |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | bb9f0f28-4ca7-4fcb-a37c-9e3624584bec |
| size | 1 |
| name | Share2 |
| share_type | 1eafb65f-1987-44a9-9a98-20af91c95662 |
| created_at | 2015-10-01T09:44:59.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| 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``, or ``HDFS`` 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 starting manila as the
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`.
@ -312,8 +504,12 @@ You also can force-delete a share.
The shares cannot be deleted in transitional states. The transitional
states are ``creating``, ``deleting``, ``managing``, ``unmanaging``,
``extending``, and ``shrinking`` statuses for the shares. Force-deletion
deletes an object in any state. Use the :file:`/etc/manila/policy.json` file to
grant permissions for this action to other roles.
deletes an object in any state. Use the :file:`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:
@ -321,9 +517,10 @@ Use **manila delete <share_name_or_ID>** command to delete a specified share:
$ manila delete Share2
Pay attention that if you specified the consistency group while creating a
share (see :ref:`shared_file_systems_cgroups`), you
should provide the ``--consistency-group`` parameter to delete the share:
.. note::
If you specified :ref:`the consistency group <shared_file_systems_cgroups>`
while creating a share, you should provide the ``--consistency-group``
parameter to delete the share:
.. code:: console
@ -368,11 +565,13 @@ run:
| aca..| Share1| 1 | NFS | avai..| c008658...| 10.254.0.3:/shares/share-...| manila@gen..|
+------+-------+-----+------------+-------+-----------+-----------------------------+-------------+
.. _access_to_share:
Manage access to share
----------------------
The Shared File Systems Storage Service allows to grant or deny access to
a specified share, and list the permissions for a specified 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:
@ -475,12 +674,11 @@ Allow access to the share with ``user`` access type:
.. note::
Different share features are supported by different share drivers.
For the example hereinabove was used the Generic (Cinder as back-end)
driver that doesn't support ``user`` and ``cert`` authentications methods.
For details of supporting of features by different drivers, see `Manila
share features support mapping
<http://docs.openstack.org/developer/manila/devref/share_back_ends_feature
_support_mapping.html>`_.
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 <http://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:

16
doc/admin-guide-cloud/source/shared_file_systems_key_concepts.rst
View File

@ -10,8 +10,8 @@ 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 filesystem that can be accessed by
OpenStack compute instances, or clients outside of OpenStack (depending on
deployment configuration).
OpenStack compute instances, or clients outside of OpenStack, which depends on
deployment configuration.
.. note::
A ``share`` is an abstract storage object that may or may not directly
@ -51,7 +51,7 @@ Share Access Rules
``Share access rules`` define which users can access a particular ``share``.
For example, access rules can be declared for NFS shares by listing the valid
IP networks (using CIDR notation) which should have access to the ``share``.
IP networks, in CIDR notation, which should have access to the ``share``.
Security Services
~~~~~~~~~~~~~~~~~
@ -68,13 +68,19 @@ Share Networks
~~~~~~~~~~~~~~
A ``share network`` is an object that defines a relationship between a
tenant's network/subnet (as defined in an OpenStack network service (Neutron
or Nova-network)) and the ``shares`` created by the same tenant; that is, a
tenant's network and subnet, as defined in an OpenStack Networking service or
Compute service, and the ``shares`` created by the same tenant; that is, a
tenant 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`` that can be used with any
network platform and does not require some specific network services in
OpenStack like Compute or Networking service. You can set the network
parameters in its configuration file.
Share Servers
~~~~~~~~~~~~~

34
doc/admin-guide-cloud/source/shared_file_systems_manage_and_unmanage_share.rst
View File

@ -6,30 +6,27 @@ Manage and unmanage share
To ``manage`` a share means that an administrator rather than a share driver
manages the storage life cycle. This approach is appropriate when an
administrator already has the custom non-manila share with its size, Shared
File System protocol, export path and so on, and administrator wants to
register it in the Shared File System Storage service.
administrator already has the custom non-manila share with its size, shared
file system protocol, export path and so on, and 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 System Storage service. An administrator can manage the custom share back.
Since with the generic driver, shares are hosted on Compute VMs, in the
examples the compute VM is used to create a new host and to create a share
hosted on it.
File Systems service. An administrator can manage the custom share back.
.. _unmanage_share:
Unmanage share
--------------
You can ``unmanage`` share, to take manual control on share life cycle. The
``unmanage`` operation is not supported for shares that were created on top of
share servers (created with share networks), so share service should have
option ``driver_handles_share_servers = False`` in its configuration.
You can unmanage a share that has no dependent snapshots.
You can ``unmanage`` a share, to unregister it from the Shared File System
service, and take manual control on share life cycle. The ``unmanage``
operation is not supported for shares that were created on top of share servers
and created with share networks), so share service should have option
``driver_handles_share_servers = False`` in its configuration. You can unmanage
a share that has no dependent snapshots.
To unmanage managed share, run :command:`manila unmanage <share>` command.
Then try to print the information about it. The expected behaviour is that
File System Storage service won't find the share:
Shared File Systems service won't find the share:
.. code:: console
@ -41,8 +38,8 @@ File System Storage service won't find the share:
Manage share
------------
To register the non-managed share in File System Storage service you need to
run :command:`manila manage` command which has such arguments:
To register the non-managed share in File System service you need to run
:command:`manila manage` command which has such arguments:
.. code:: console
@ -67,6 +64,9 @@ The positional arguments are:
- 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
@ -106,7 +106,7 @@ To manage share, run:
| metadata | {} |
+-----------------------------+---------------------------------------------------------------+
Check that he share is available:
Check that the share is available:
.. code:: console

26
doc/admin-guide-cloud/source/shared_file_systems_multi_backend.rst
View File

@ -1,31 +1,27 @@
.. _shared_file_systems_multi_backend:
.. highlight: ini
:linenothreshold: 5
===========================
Multi-storage configuration
===========================
Shared File Systems service can provide access to multiple file storage back
ends. In general, workflow with multiple back ends look very similar to Block
Storage service one, see :ref:`Configure multiple-storage back ends in
Openstack Block Storage service <multi_backend>`.
The Shared File Systems service can provide access to multiple file storage
back ends. In general, the workflow with multiple back ends looks very similar
to the Block Storage service one, see :ref:`Configure multiple-storage back
ends in Openstack Block Storage service <multi_backend>`.
Using `manila.conf` you can spawn multiple share services. To do it, 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
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
:linenos:
[DEFAULT]
enabled_share_backends=backendEMC1,backendEMC2,backendGeneric1,backendGeneric2,backendNetApp
enabled_share_backends=backendEMC2,backendGeneric1,backendNetApp
[backendGeneric1]
share_driver=manila.share.drivers.generic.GenericShareDriver
@ -55,9 +51,9 @@ The following example runs three configured share services:
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 separate way, you should
provide a single configuration file per each back end.
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

70
doc/admin-guide-cloud/source/shared_file_systems_network_plugins.rst
View File

@ -7,73 +7,77 @@ 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 tenants’
networked storage. There are a set of network plugins that provide a variety
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.
The Shared File Systems service may need a network resource provisioning if
share service with specified driver works in mode, when share driver manage
life cycle of share servers on its own. This behavior defines by flag
share service with specified driver works in mode, when a share driver manages
life cycle 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
plugins that will handle reservation, creation and deletion of network
plug-ins that will handle reservation, creation and deletion of network
resources including IP addresses and network interfaces.
What network plugins are available?
-----------------------------------
What network plug-ins are available?
------------------------------------
There are three different network plugins and five python classes in Manila:
There are three different network plug-ins and five python classes in the
Shared File Systems service:
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.
#. 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 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.
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 tenant environment.
b) ``manila.network.neutron.neutron_network_plugin.NeutronSingleNetworkPlug
in``. 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.
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.
2. Network plugin for working with OpenStack networking from `Nova`. It
supports either flat networks or VLAN-segmented networks.
#. Network plug-in for working with OpenStack Networking from the Compute
service. It supports either flat networks or VLAN-segmented networks.
a) ``manila.network.nova_network_plugin.NovaNetworkPlugin``. This plugin
a) ``manila.network.nova_network_plugin.NovaNetworkPlugin``. This plug-in
serves the networking needs when ``Nova networking`` is configured in
the cloud instead of Neutron. It requires a single parameter,
``nova_net_id``.
b) ``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 Shared File Systems service configuration file and
creates share servers using only one network.
b) ``manila.network.nova_network_plugin.NovaSingleNetworkPlugin``. This
plug-in works the same way as
``manila.network.nova_network_plugin.NovaNetworkPlugin``, except it takes
``nova_net_id`` from the Shared File Systems service configuration
file and creates the share servers using only one network.
When only a single network is needed, the NovaSingleNetworkPlugin (2.b) is a
simple solution. Otherwise NovaNetworkPlugin (1.a) should be chosen.
simple solution. Otherwise NovaNetworkPlugin (2.a) should be chosen.
3. Network plugin for specifying networks independently from OpenStack
#. 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 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.
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.
.. note::
These network plugins were introduced in the OpenStack Kilo release. In
These network plug-ins were introduced in the OpenStack Kilo release. In
the OpenStack Juno version, only NeutronNetworkPlugin is available.
More information about network plugins can be found in `Manila developer documentation <http://docs.openstack.org/developer/manila/adminref/network_plugins.html>`_
More information about network plug-ins can be found in `Manila developer documentation <http://docs.openstack.org/developer/manila/adminref/network_plugins.html>`_

14
doc/admin-guide-cloud/source/shared_file_systems_networking.rst
View File

@ -4,13 +4,13 @@
Networking
==========
Instead of OpenStack Block Storage service, Shared File Systems service
requires interaction with Networking service. The first of all, it because
share services should have a possibility to manage share servers on its own.
Also, lots of shared file systems provides have own access control systems and
requires network connectivity with some external auth providers, like LDAP,
Kerberos, or Microsoft Active Directory. So, management share services base
on such back end needs some interacting with Networking service.
Unlike the OpenStack Block Storage service, the Shared File Systems service
requires interaction with the Networking service. First of all, it is because
the share services require the option to self-manage share servers. Also, for
authentication and authorization of the clients, the Shared File Systems
service can be optionally configured to work with different network
authentication services, like LDAP, Kerberos protocols, or Microsoft Active
Directory.
.. toctree::
shared_file_systems_share_networks.rst

64
doc/admin-guide-cloud/source/shared_file_systems_quotas.rst
View File

@ -8,23 +8,9 @@ Limits
------
Limits are the resource limitations that are allowed for each tenant (project).
An administrator can configure limits in the :file:`/etc/manila/manila.conf`
file.
An administrator can configure limits in the :file:`manila.conf` file.
Users can query their rate and absolute limits.
The absolute limits contain information about:
- Total maximum share memory, in GBs.
- Total maximum snapshot memory, in GBs.
- Number of share-networks.
- Number of share-snapshots.
- Number of shares.
- Shares and total used memory, in GBs.
To see the absolute limits, run:
@ -52,11 +38,39 @@ 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 that can be processed
during a one-minute period.
To set the API rate limits, add configuration to the
:file:`etc/manila/api-paste.ini` file that is a part of the WSGI pipeline and
defines the actual limits. You need to restart ``manila-api`` service after
you edited :file:`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 ``ratelimit`` to ``noauth``, ``keystone``, ``keystone_nolimit``
parameters in ``[composite:openstack_share_api]`` group.
.. code-block:: ini
[composite:openstack_share_api]
noauth = faultwrap ssl ratelimit sizelimit noauth api
keystone = faultwrap ssl ratelimit sizelimit authtoken keystonecontext api
keystone_nolimit = faultwrap ssl ratelimit sizelimit authtoken keystonecontext api
To see the rate limits, run:
.. code:: 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
------
@ -82,7 +96,7 @@ for the specified project.
+--------------------+-------+
There are default quotas for a project that are set from
:file:`/etc/manila/manila.conf` file. To list default quotas for a project, use
:file:`manila.conf` file. To list default quotas for a project, use
**manila quota-defaults** command:
.. code:: console
@ -120,21 +134,3 @@ To revert quotas to default for a project or for a user, delete quotas:
.. code:: console
$ manila quota-delete --tenant demo --user demo
It is possible to set quotas for a quota class and then check that the quotas
were updated:
.. code:: console
$ manila quota-class-update my_custom_class --shares 49 --snapshot_gigabytes 999
$ manila quota-class-show my_custom_class
+--------------------+-------+
| Property | Value |
+--------------------+-------+
| gigabytes | 1000 |
| snapshot_gigabytes | 999 |
| snapshots | 50 |
| shares | 49 |
| share_networks | 10 |
+--------------------+-------+

29
doc/admin-guide-cloud/source/shared_file_systems_scheduling.rst
View File

@ -4,29 +4,30 @@
Scheduling
==========
Shared File Systems service provides unified access for variety of different
types of shared file systems. To achieve this, Shared File Systems service
use scheduler. Scheduler collects information from active share services and
take decisions, what share service will be used to create new share. To manage
this process Shared File Systems service provides Share types API.
The Shared File Systems service provides unified access for variety of
different types of shared file systems. To achieve this, the Shared File
Systems service uses a scheduler. The scheduler collects information from
active share services and takes decisions, what share service will be used to
create a new share. To manage this process, the Shared File Systems service
provides Share types API.
Share type is a list from key-value pairs called extra-specs. Some of them,
A share type is a list from key-value pairs called extra-specs. Some of them,
called required and un-scoped extra-specs, scheduler uses for lookup the
share service suitable for new share with specified share type. For more
information about extra-specs and their type see `Capabilities and Extra-Specs
information about extra-specs and their type, see `Capabilities and Extra-Specs
<http://docs.openstack.org/developer/manila/devref/capabilities_and_extra_spec
s.html>`_ section in developer documentation.
In general scheduler workflow looks like:
The general scheduler workflow in described below.
1) Share services report information about number of existed pools, their
#. Share services report information about number of existing pools, their
capacities and capabilities.
2) When request on share creation comes in, scheduler picks a service and pool
#. When request on share creation comes in, scheduler picks a service and pool
that fits the need best to serve the request, using share type filters and
back end capabilities. If back end capabilities passes thought all filters
request to the selected back end where the target pool resides;
request to the selected back end where the target pool resides.
3) Share driver gets the message and lets the target pool serve the request
as scheduler instructed. Share type extra-specs (scoped and un-scoped)
are available for the driver implementation to use as-needed.
#. Share driver gets the message and lets the target pool serve the request
as scheduler instructed. The scoped and un-scoped share type extra-specs
are available for the driver implementation to use as needed.

2
doc/admin-guide-cloud/source/shared_file_systems_security_services.rst
View File

@ -168,7 +168,7 @@ and see that a security service now has empty list of share networks:
| description | None |
+----------------+--------------------------------------+
Shared File Systems Storage allows you to update a security service fields
Shared File Systems service allows you to update a security service fields
using **manila security-service-update** command with optional arguments
such as ``--dns-ip``, ``--server``, ``--domain``, ``--user``, ``--password``,
``--name``, or ``--description``.

12
doc/admin-guide-cloud/source/shared_file_systems_services_manage.rst
View File

@ -4,12 +4,12 @@
Manage shares services
======================
The Shared File Systems service provides API allows to Cloud Administrator
manage running share services (`Share services API
The Shared File Systems service provides API that allows to manage running
share services (`Share services API
<http://developer.openstack.org/api-ref-share-v2.html#share-services>`_).
It hasn't exposed in CLI client yet. Using raw API calls, it is possible
to get list of running services all kinds. To select only share services,
you can pick items only have field ``binary`` equals to ``manila-share``.
Aslo, you can enable and disable share services. Disabling means that share
Using ``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`` equals to ``manila-share``. Also, you can enable or
disable share services using raw API requests. Disabling means that share
service excludes from scheduler cycle and new shares will not be placed on
disabled back end, but shares from this service stay available.

15
doc/admin-guide-cloud/source/shared_file_systems_share_management.rst
View File

@ -4,12 +4,6 @@
Share management
================
The default configuration of the Shared File Systems service uses the OpenStack
Block Storage based back end. In that case, the Shared File Systems service
cares about everything (VMs, networking, keypairs, security groups) by itself.
It is not production solution, but can help you to understand how the Shared
File Systems service works.
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.
@ -25,12 +19,9 @@ The shares are based on of the supported Shared File Systems protocols:
* *GLUSTERFS*. Gluster file system (GlusterFS).
* *HDFS*. Hadoop Distributed File System (HDFS).
.. note::
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
service in production.
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 service in production.
.. toctree::
shared_file_systems_crud_share.rst

7
doc/admin-guide-cloud/source/shared_file_systems_share_networks.rst
View File

@ -4,9 +4,10 @@
Share networks
==============
Share network is an entity that encapsulates interaction with Networking
service. If selected driver runs in mode requiring such kind of interaction,
you need to specify share network when share creates.
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 share network.
How to create share network
~~~~~~~~~~~~~~~~~~~~~~~~~~~

5
doc/admin-guide-cloud/source/shared_file_systems_share_resize.rst
View File

@ -5,8 +5,9 @@ Resize share
============
To change file share size, use :command:`manila extend` and
:command:`manila shrink`. For most drivers it is safe operation. In case of
using generic driver it is better to create share snapshot for backup.
:command:`manila shrink`. 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 **manila extend** and
**manila shrink** commands correspondingly and specifying the share and new

14
doc/admin-guide-cloud/source/shared_file_systems_share_types.rst
View File

@ -5,12 +5,12 @@ Share types
===========
A share type enables you to filter or choose back ends before you create a
share. A share type behaves in the same way as a Block Storage volume type
behaves.
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 manila configuration file :file:`/etc/manila/manila.conf` administrator
can set the share type used by default for the share creation and then create
a default share type.
In the Shared File Systems configuration file :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 **manila type-create** command as:
@ -126,8 +126,8 @@ The public or private share type can be deleted by means of
Share type access
-----------------
You can manage the access to the private for the different projects: add
access, remove access, and get information about access for a specified
You can manage the access to the private share type for the different projects:
add access, remove access, and get information about access for a specified
private share type.
Create a private type:

6
doc/admin-guide-cloud/source/shared_file_systems_snapshots.rst
View File

@ -4,13 +4,13 @@
Share snapshots
===============
The Shared File Systems service provides mechanism of snapshots to help users
to restore theirs own data. Use :command:`manila snapshot-create` for it.
The Shared File Systems service provides a snapshot mechanism to help users
restore data by running the `manila snapshot-create` command.
To export a snapshot, you can create shares from it, then mount new share to
instance and then directly copy files from attached share into archive.
To import snapshot, create a new share with appropriate size, attach it to
To import a snapshot, create a new share with appropriate size, attach it to
instance and then copy file from archive to attached file system.
.. note::

45
doc/admin-guide-cloud/source/shared_file_systems_troubleshoot.rst
View File

@ -4,21 +4,21 @@
Troubleshoot Shared File Systems service
========================================
Failures in share service during share creation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Failures in Share File Systems service during a share creation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If new shares go into ``error`` state during creation, follow next steps:
1. Make sure, that share services are running into debug mode. If it is not
true, you will not get any tips from logs how to fix your issue.
#. 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.
2. Find what a share service holds specified share. Do to that, run command
:command:`manila show <share_id_or_name>` and find share host in the
output. Host uniquely identifies share service holds broken share.
#. Find what share service holds a specified share. Do to 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.
3. Look thought logs of this share service. Usually, it can be found at
#. 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 find origin of issues.
traceback with extra information to help you to find the origin of issues.
No valid host was found
~~~~~~~~~~~~~~~~~~~~~~~
@ -34,30 +34,27 @@ To solve this issue look carefully through list of extra specs in share type
and list of share service reported capabilities and make sure that extra specs
are pointed in the right way.
Created share is unreachable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default new share doesn't have any active access rules. So, to provide
By default, a new share does not have any active access rules. To provide
access to new created share, you need to create appropriate access rule with
right value that defines access.
Service become unavailable after upgrade
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After upgrading Shared File Systems service from version v1 to version v2.x,
please be attentive to update service endpoint in OpenStack Identity Service.
Use :command:`keystone service-list` to get service type related to Shared
File Systems service and then :command:`keystone service-list --service
<share-service-type>`. You will get endpoints expected from running
Shared File Systems service. Make sure that these endpoints are update.
If it is not true, you need delete outdated endpoints and create a new one.
Service becomes unavailable after upgrade
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After upgrading the Shared File Systems service from version v1 to version
v2.x, please be attentive to update service endpoint in OpenStack Identity
Service. Use :command:`keystone service-list` to get service type related to
Shared File Systems service and then :command:`keystone service-list --service
<share-service-type>` command. You will get endpoints expected from running
Shared File Systems service. Make sure that these endpoints are updated.
If it is not true, you need to delete outdated endpoints and create new ones.
Failures during management of internal resources
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some drivers in Shared File Systems service can create service entities, like
servers and networks. If it is necessary to reach it you can login in
tenant ``service`` and get manual control over it.
servers and networks. If it is necessary to reach it you can log in to tenant
``service`` and get manual control over it.