openstack/openstack-manuals
Code Issues Proposed changes

Merge "Add 'Shared File Systems' to Cloud Admin Guide"

Browse Source
This commit is contained in:
Jenkins 2015-10-13 00:44:03 +00:00 committed by Gerrit Code Review
commit 496ea31e9a
20 changed files with 2272 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/admin-guide-cloud/source/index.rst
View File

@ -24,6 +24,7 @@ Contents
compute.rst
objectstorage.rst
blockstorage.rst
shared_file_systems.rst
networking.rst
telemetry.rst
database.rst

29
doc/admin-guide-cloud/source/shared_file_systems.rst Normal file
View File

@ -0,0 +1,29 @@
.. _shared_file_systems:
===================
Shared File Systems
===================
Shared File Systems service provides a set of services for management of
shared file systems in a multi-tenant cloud environment, similar to how
OpenStack provides for block-based storage management through 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.
.. toctree::
:maxdepth: 1
shared_file_systems_intro.rst
shared_file_systems_key_concepts.rst
shared_file_systems_share_management.rst
shared_file_systems_share_types.rst
shared_file_systems_snapshots.rst
shared_file_systems_security_services.rst
shared_file_systems_cgroups.rst
shared_file_systems_multi_backend.rst
shared_file_systems_networking.rst
shared_file_systems_troubleshoot.rst

313
doc/admin-guide-cloud/source/shared_file_systems_cgroups.rst Normal file
View File

@ -0,0 +1,313 @@
.. _shared_file_systems_cgroups:
==================
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
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.
.. 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.
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:
* ``pool`` or ``host``. Consistency groups are supported. Specifies the
level of consistency groups support.
* ``false``. Consistency groups are not supported.
Create a new consistency group, specify a share network and one or more share
types. In the example a consistency group ``cgroup1`` was created with
specifying two comma-separated share types:
.. code:: console
$ manila cg-create --name cgroup1 --description "My first CG." --share-types my_type1,default --share-network my_share_net
+----------------------+--------------------------------------+
| Property | Value |
+----------------------+--------------------------------------+
| status | creating |
| description | My first CG. |
| source_cgsnapshot_id | None |
| created_at | 2015-09-29T15:01:12.102472 |
| share_network_id | 5c3cbabb-f4da-465f-bc7f-fadbe047b85a |
| share_server_id | None |
| host | None |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| share_types | a4218aa5-f16a-42b3-945d-113496d40558 |
| | c0086582-30a6-4060-b096-a42ec9d66b86 |
| id | 6fdd91bc-7a48-48b4-8e40-0f4f98d0ecd6 |
| name | cgroup1 |
+----------------------+--------------------------------------+
Check that consistency group is in available status:
.. code:: console
$ manila cg-show cgroup1
+----------------------+--------------------------------------+
| Property | Value |
+----------------------+--------------------------------------+
| status | available |
| description | My first CG. |
| source_cgsnapshot_id | None |
| created_at | 2015-09-29T15:05:40.000000 |
| share_network_id | 5c3cbabb-f4da-465f-bc7f-fadbe047b85a |
| share_server_id | None |
| host | manila@generic1#GENERIC1 |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| share_types | c0086582-30a6-4060-b096-a42ec9d66b86 |
| | a4218aa5-f16a-42b3-945d-113496d40558 |
| id | 6fdd91bc-7a48-48b4-8e40-0f4f98d0ecd6 |
| name | cgroup1 |
+----------------------+--------------------------------------+
To add a share to the consistency group you need to create a share with a
``--consistency-group`` option where you specify the ID of the consistency
group in ``available`` status:
.. code:: console
$ manila create nfs 1 --name "Share2" --description "My second share" --share-type default --share-network my_share_net --consistency-group cgroup1
+-----------------------------+--------------------------------------+
| Property | Value |
+-----------------------------+--------------------------------------+
| status | None |
| share_type_name | default |
| description | My second 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 | 7bcd888b-681b-4836-ac9c-c3add4e62537 |
| size | 1 |
| name | Share2 |
| share_type | c0086582-30a6-4060-b096-a42ec9d66b86 |
| created_at | 2015-09-29T15:09:24.156387 |
| export_location | None |
| share_proto | NFS |
| consistency_group_id | 6fdd91bc-7a48-48b4-8e40-0f4f98d0ecd6 |
| source_cgsnapshot_member_id | None |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| metadata | {} |
+-----------------------------+--------------------------------------+
Admin can rename the consistency group or change its description using
**manila cg-update** command, or delete it by **manila cg-delete**.
As an administrator, you can also reset the state of a consistency group and
force-delete a specified consistency group in any state. Use the
:file:`policy.json` file to grant permissions for these actions to other roles.
Use **manila cg-reset-state [--state <state>] <consistency_group>** to update
the state of a consistency group explicitly. A valid value of a status are
``available``, ``error``, ``creating``, ``deleting``, ``error_deleting``.
If no state is provided, available will be used.
.. code:: console
$ manila cg-reset-state cgroup1 --state error
Use **manila cg-delete <consistency_group> [<consistency_group> ...]** to
soft-delete one or more consistency group.
.. note::
The consistency group can be deleted only if it has no dependent
:ref:`shared_file_systems_cgsnapshots`.
.. code:: console
$ manila cg-delete cgroup1
Use **manila cg-delete --force <consistency_group> [<consistency_group> ...]**
to force-delete a specified consistency group in any state.
.. code:: console
$ manila cg-delete --force cgroup1
.. _shared_file_systems_cgsnapshots:
Consistency group snapshots
---------------------------
You can create snapshots of consistency groups. To create a snapshot, you
specify the ID or name of the consistency group that you want to snapshot.
After you create a consistency group snapshot, you can create a consistency
group from it.
Create a snapshot of consistency group ``cgroup1``:
.. code:: console
$ manila cg-snapshot-create cgroup1 --name CG_snapshot1 --description "A snapshot of the first CG."
+----------------------+--------------------------------------+
| Property | Value |
+----------------------+--------------------------------------+
| status | creating |
| name | CG_snapshot1 |
| created_at | 2015-09-29T15:26:16.839704 |
| consistency_group_id | 6fdd91bc-7a48-48b4-8e40-0f4f98d0ecd6 |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| id | 876ad24c-1efd-4607-a2b1-6a2c90034fa5 |
| description | A snapshot of the first CG. |
+----------------------+--------------------------------------+
Check the status of created consistency group snapshot:
.. code:: console
$ manila cg-snapshot-show CG_snapshot1
+----------------------+--------------------------------------+
| Property | Value |
+----------------------+--------------------------------------+
| status | available |
| name | CG_snapshot1 |
| created_at | 2015-09-29T15:26:22.000000 |
| consistency_group_id | 6fdd91bc-7a48-48b4-8e40-0f4f98d0ecd6 |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| id | 876ad24c-1efd-4607-a2b1-6a2c90034fa5 |
| description | A snapshot of the first CG. |
+----------------------+--------------------------------------+
Admin can rename the consistency group snapshot or change its description using
**cg-snapshot-update** command, or delete it by **cg-snapshot-delete**.
A consistency group snapshot can have **members**. The consistency group
snapshot members are the shares that belong to some consistency group. To add a
member, include the ``--consistency-group`` optional parameter in the create
share command. This ID must match the ID of the consistency group from which
the consistency group snapshot was created. Then, while restoring data,
for example, and operating with consistency group snapshots you can quickly
find which shares belong to a specified consistency group.
You created the share ``Share2`` in ``cgroup1`` consistency group. Since
you made a snapshot of it, you can see that the only member of the consistency
group snapshot is ``Share2`` share:
.. code:: console
$ manila cg-snapshot-members CG_snapshot1
+--------------+------+----------------------------+----------------+--------------+--------------+
| Id | Size | Created_at | Share_protocol | Share_id | Share_type_id|
+--------------+------+----------------------------+----------------+--------------+--------------+
| 5c62af2b-... | 1 | 2015-09-29T15:26:22.000000 | NFS | 7bcd888b-... | c0086582-... |
+--------------+------+----------------------------+----------------+--------------+--------------+
After you create a consistency group snapshot, you can create a consistency
group from it:
.. code:: console
$ manila cg-create --source-cgsnapshot-id 876ad24c-1efd-4607-a2b1-6a2c90034fa5 --name cgroup2 --description "A consistency group from a CG snapshot."
+----------------------+-----------------------------------------+
| Property | Value |
+----------------------+-----------------------------------------+
| status | creating |
| description | A consistency group from a CG snapshot. |
| source_cgsnapshot_id | 876ad24c-1efd-4607-a2b1-6a2c90034fa5 |
| created_at | 2015-09-29T15:47:47.937991 |
| share_network_id | None |
| share_server_id | None |
| host | manila@generic1#GENERIC1 |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| share_types | c0086582-30a6-4060-b096-a42ec9d66b86 |
| | a4218aa5-f16a-42b3-945d-113496d40558 |
| id | ffee08d9-c86c-45e5-861e-175c731daca2 |
| name | cgroup2 |
+----------------------+-----------------------------------------+
Check the list of consistency group. There are two groups now:
.. code:: console
$ manila cg-list
+-------------------+---------+-----------------------------------------+-----------+
| id | name | description | status |
+-------------------+---------+-----------------------------------------+-----------+
| 6fdd91bc-7a48-... | cgroup1 | My first CG. | available |
| ffee08d9-c86c-... | cgroup2 | A consistency group from a CG snapshot. | available |
+-------------------+---------+-----------------------------------------+-----------+
Check a list of the shares. New share with
``ba52454e-2ea3-47fa-a683-3176a01295e6`` ID was created when you created a
consistency group ``cgroup2`` from a snapshot with a member.
.. code:: console
$ manila list
+------+-------+-----+------------+----------+----------+-----------+--------------------------+
| ID | Name | Size| Share Proto| Status | Is Public| Share Type| Host |
+------+-------+-----+------------+----------+----------+-----------+--------------------------+
| 7bc..| Share2| 1 | NFS | available| False | c008658...| manila@generic1#GENERIC1 |
| ba5..| None | 1 | NFS | available| False | c008658...| manila@generic1#GENERIC1 |
+------+-------+-----+------------+----------+----------+-----------+--------------------------+
Print detailed information about new share:
.. note::
Pay attention on the ``source_cgsnapshot_member_id`` and
``consistency_group_id`` fields in a new share. It has
``source_cgsnapshot_member_id`` that is equal to the ID of the consistency
group snapshot and ``consistency_group_id`` that is equal to the ID of
``cgroup2`` that was created from a snapshot.
.. code:: console
$ manila show ba52454e-2ea3-47fa-a683-3176a01295e6
+-----------------------------+---------------------------------------------------------------+
| Property | Value |
+-----------------------------+---------------------------------------------------------------+
| status | available |
| share_type_name | default |
| description | None |
| availability_zone | None |
| share_network_id | None |
| export_locations | 10.254.0.5:/shares/share-5acadf4d-f81a-4515-b5ce-3ab641ab4d1e |
| share_server_id | None |
| host | manila@generic1#GENERIC1 |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | ba52454e-2ea3-47fa-a683-3176a01295e6 |
| size | 1 |
| name | None |
| share_type | c0086582-30a6-4060-b096-a42ec9d66b86 |
| created_at | 2015-09-29T15:47:48.000000 |
| share_proto | NFS |
| consistency_group_id | ffee08d9-c86c-45e5-861e-175c731daca2 |
| source_cgsnapshot_member_id | 5c62af2b-0870-4d00-b3fa-174831eb15ca |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| metadata | {} |
+-----------------------------+---------------------------------------------------------------+
As an administrator, you can also reset the state of a consistency group
snapshot with **cg-snapshot-reset-state** and force-delete a specified
consistency group snapshot in any state using **cg-snapshot-delete** with
``--force`` key. Use the :file:`policy.json` file to grant permissions for
these actions to other roles.

510
doc/admin-guide-cloud/source/shared_file_systems_crud_share.rst Normal file
View File

@ -0,0 +1,510 @@
.. _shared_file_systems_crud_share:
======================
Share basic operations
======================
Create share
------------
General concepts **to create file share**, 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).
#. 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:
* 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.
* Creates new volume of required size and attaches it to the service
instance.
* The NFS service on service instance is configured to use attached volume
and expose NFS share.
#. After share becomes available, use the :command:`manila show` command
to get the share endpoint.
In the example to create a share, the default share type and the
existing already share network are used.
.. note::
There is no default share type just after you starting 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:: console
$ manila type-list
+------+--------+-----------+-----------+----------------------------------+----------------------+
| ID | Name | Visibility| is_default| required_extra_specs | optional_extra_specs |
+------+--------+-----------+-----------+----------------------------------+----------------------+
| c0...| default| public | YES | driver_handles_share_servers:True| snapshot_support:True|
+------+--------+-----------+-----------+----------------------------------+----------------------+
Check share networks that exist, run:
.. code:: console
$ manila share-network-list
+--------------------------------------+--------------+
| id | name |
+--------------------------------------+--------------+
| 5c3cbabb-f4da-465f-bc7f-fadbe047b85a | 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:: console
$ manila create nfs 1 --name "Share1" --description "My first share" --share-type default --share-network my_share_net --metadata aim=testing --public
+-----------------------------+--------------------------------------+
| Property | Value |
+-----------------------------+--------------------------------------+
| status | None |
| share_type_name | default |
| description | My first share |
| availability_zone | None |
| share_network_id | None |
| export_locations | [] |
| share_server_id | None |
| host | None |
| snapshot_id | None |
| is_public | True |
| task_state | None |
| snapshot_support | True |
| id | aca648eb-8c03-4394-a5cc-755066b7eb66 |
| size | 1 |
| name | Share1 |
| share_type | c0086582-30a6-4060-b096-a42ec9d66b86 |
| created_at | 2015-09-24T12:19:06.925951 |
| export_location | None |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| 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:: console
$ manila list
+----+-------+-----+------------+-----------+-------------------------------+----------------------+
| ID | Name | Size| Share Proto| Share Type| Export location | Host |
+----+-------+-----+------------+-----------+-------------------------------+----------------------+
| a..| Share1| 1 | NFS | c0086... | 10.254.0.3:/shares/share-2d5..| manila@generic1#GEN..|
+----+-------+-----+------------+-----------+-------------------------------+----------------------+
Check the share status and see the share export location. After ``creating``
status share should have status ``available``:
.. code:: console
$ manila show Share1
+-----------------------------+-------------------------------------------+
| Property | Value |
+-----------------------------+-------------------------------------------+
| status | available |
| share_type_name | default |
| description | My first share |
| availability_zone | nova |
| share_network_id | 5c3cbabb-f4da-465f-bc7f-fadbe047b85a |
| export_locations | 10.254.0.3:/shares/share-2d5e2c0a-1f84... |
| share_server_id | 41b7829d-7f6b-4c96-aea5-d106c2959961 |
| host | manila@generic1#GENERIC1 |
| snapshot_id | None |
| is_public | True |
| task_state | None |
| snapshot_support | True |
| id | aca648eb-8c03-4394-a5cc-755066b7eb66 |
| size | 1 |
| name | Share1 |
| share_type | c0086582-30a6-4060-b096-a42ec9d66b86 |
| created_at | 2015-09-24T12:19:06.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| metadata | {u'aim': u'testing'} |
+-----------------------------+-------------------------------------------+
``is_public`` defines the level of visibility for the share: whether other
tenants 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 tenants for
the share if you need:
.. code:: console
$ manila update Share1 --description "My first share. Updated" --is-public False
$ manila show Share1
+-----------------------------+--------------------------------------------+
| Property | Value |
+-----------------------------+--------------------------------------------+
| status | available |
| share_type_name | default |
| description | My first share. Updated |
| availability_zone | nova |
| share_network_id | 5c3cbabb-f4da-465f-bc7f-fadbe047b85a |
| export_locations | 10.254.0.3:/shares/share-2d5e2c0a-1f84-... |
| share_server_id | 41b7829d-7f6b-4c96-aea5-d106c2959961 |
| host | manila@generic1#GENERIC1 |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | aca648eb-8c03-4394-a5cc-755066b7eb66 |
| size | 1 |
| name | Share1 |
| share_type | c0086582-30a6-4060-b096-a42ec9d66b86 |
| created_at | 2015-09-24T12:19:06.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| 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. |
+-----------------------------------+-----------------------------------------+
.. _share_metadata:
Share metadata
--------------
If you want to set the metadata key-value pairs on the share, run:
.. code:: console
$ manila metadata Share1 set project=my_abc deadline=01/20/16
Get all metadata key-value pairs of the share:
.. code:: console
$ manila metadata-show Share1
+----------+----------+
| Property | Value |
+----------+----------+
| aim | testing |
| project | my_abc |
| deadline | 01/20/16 |
+----------+----------+
You can update the metadata:
.. code:: console
$ manila metadata-update-all Share1 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:: console
$ manila reset-state Share2 --state deleting
$ manila show Share2
+-----------------------------+-------------------------------------------+
| Property | Value |
+-----------------------------+-------------------------------------------+
| status | deleting |
| share_type_name | default |
| description | Share from a snapshot. |
| availability_zone | nova |
| share_network_id | 5c3cbabb-f4da-465f-bc7f-fadbe047b85a |
| export_locations | [] |
| 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 |
| export_location | 10.254.0.3:/shares/share-1dc2a471-3d47-...|
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| metadata | {u'source': u'snapshot'} |
+-----------------------------+-------------------------------------------+
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``,
``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.
Use **manila delete <share_name_or_ID>** command to delete a specified share:
.. code:: console
$ 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:
.. code:: console
$ manila delete ba52454e-2ea3-47fa-a683-3176a01295e6 --consistency-group ffee08d9-c86c-45e5-861e-175c731daca2
If you try to delete the share in one of the transitional
state using soft-deletion you'll get an error:
.. code:: console
$ manila delete b6b0617c-ea51-4450-848e-e7cff69238c7
Delete for share b6b0617c-ea51-4450-848e-e7cff69238c7 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 tenants:
.. code:: console
$ manila list --all-tenants
+------+-------+-----+------------+-------+-----------+-----------------------------+-------------+
| ID | Name | Size| Share Proto| Status| Share Type| Export location | Host |
+------+-------+-----+------------+-------+-----------+-----------------------------+-------------+
| aca..| Share1| 1 | NFS | avai..| c008658...| 10.254.0.3:/shares/share-...| manila@gen..|
| b6b..| Share2| 1 | NFS | dele..| c008658...| 10.254.0.3:/shares/share-...| manila@gen..|
+------+-------+-----+------------+-------+-----------+-----------------------------+-------------+
Force-delete Share2 and check that it is absent in the list of shares,
run:
.. code:: console
$ manila force-delete b6b0617c-ea51-4450-848e-e7cff69238c7
$ manila list
+------+-------+-----+------------+-------+-----------+-----------------------------+-------------+
| ID | Name | Size| Share Proto| Status| Share Type| Export location | Host |
+------+-------+-----+------------+-------+-----------+-----------------------------+-------------+
| aca..| Share1| 1 | NFS | avai..| c008658...| 10.254.0.3:/shares/share-...| manila@gen..|
+------+-------+-----+------------+-------+-----------+-----------------------------+-------------+
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.
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``.
- **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.
- **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.
Try to mount NFS share with export path
``10.254.0.5:/shares/share-5789ddcf-35c9-4b64-a28a-7f6a4a574b6a`` on the
node with IP address ``10.254.0.4``:
.. code:: console
$ sudo mount -v -t nfs 10.254.0.5:/shares/share-5789ddcf-35c9-4b64-a28a-7f6a4a574b6a /mnt/
mount.nfs: timeout set for Tue Oct 6 10:37:23 2015
mount.nfs: trying text-based options 'vers=4,addr=10.254.0.5,clientaddr=10.254.0.4'
mount.nfs: mount(2): Permission denied
mount.nfs: access denied by server while mounting 10.254.0.5:/shares/share-5789ddcf-35c9-4b64-a28a-7f6a4a574b6a
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.254.0.4`` IP address:
.. code:: console
$ manila access-allow Share2 ip 10.254.0.4 --access-level rw
+--------------+--------------------------------------+
| Property | Value |
+--------------+--------------------------------------+
| share_id | 7bcd888b-681b-4836-ac9c-c3add4e62537 |
| access_type | ip |
| access_to | 10.254.0.4 |
| access_level | rw |
| state | new |
| id | de715226-da00-4cfc-b1ab-c11f3393745e |
+--------------+--------------------------------------+
Try to mount a share again. This time it is mounted successfully:
.. code:: console
$ sudo mount -v -t nfs 10.254.0.5:/shares/share-5789ddcf-35c9-4b64-a28a-7f6a4a574b6a /mnt/
Since it is allowed node on 10.254.0.4 read and write access, try to create
a file on a mounted share:
.. code:: console
$ cd /mnt
$ ls
lost+found
$ touch my_file.txt
Connect via SSH to the 10.254.0.5 node and check new file `my_file.txt`
in the ``/shares/share-5789ddcf-35c9-4b64-a28a-7f6a4a574b6a`` directory:
.. code:: console
$ ssh manila@10.254.0.5
$ cd /shares
$ ls
share-5789ddcf-35c9-4b64-a28a-7f6a4a574b6a
$ cd share-5789ddcf-35c9-4b64-a28a-7f6a4a574b6a
$ 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:: console
$ manila access-allow Share2 user demo --access-level rw
+--------------+--------------------------------------+
| Property | Value |
+--------------+--------------------------------------+
| share_id | 7bcd888b-681b-4836-ac9c-c3add4e62537 |
| 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 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>`_.
To verify that the access rules (ACL) were configured correctly for a share,
you list permissions for a share:
.. code:: console
$ manila access-list Share2
+--------------------------------------+-------------+------------+--------------+--------+
| id | access type | access to | access level | state |
+--------------------------------------+-------------+------------+--------------+--------+
| 4f391c6b-fb4f-47f5-8b4b-88c5ec9d568a | user | demo | rw | error |
| de715226-da00-4cfc-b1ab-c11f3393745e | ip | 10.254.0.4 | rw | active |
+--------------------------------------+-------------+------------+--------------+--------+
Deny access to the share and check that deleted access rule is absent in the
access rule list:
.. code:: console
$ manila access-deny Share2 de715226-da00-4cfc-b1ab-c11f3393745e
$ manila access-list Share2
+--------------------------------------+-------------+-----------+--------------+-------+
| id | access type | access to | access level | state |
+--------------------------------------+-------------+-----------+--------------+-------+
| 4f391c6b-fb4f-47f5-8b4b-88c5ec9d568a | user | demo | rw | error |
+--------------------------------------+-------------+-----------+--------------+-------+

24
doc/admin-guide-cloud/source/shared_file_systems_intro.rst Normal file
View File

@ -0,0 +1,24 @@
.. _shared_file_systems_intro:
============
Introduction
============
The OpenStack File Share service allows you to offer file-share services to
users of an OpenStack installation. The Shared File Systems service can be
configured to run in a single-node configuration or across multiple nodes. 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. To
administer the Shared File Systems service, it is helpful to understand a
number of concepts like share networks, shares, multi-tenancy and back ends
that can be configured with the Shared File Systems service. The Shared File
Systems service consists of three types of services, which are similar to
those of the Block Storage service:
- ``manila-api``
- ``manila-scheduler``
- ``manila-share``
Installation of first two - ``manila-api`` and ``manila-scheduler`` is common
for almost all deployments. But configuration of ``manila-share`` is
backend-specific and can differ from deployment to deployment.

91
doc/admin-guide-cloud/source/shared_file_systems_key_concepts.rst Normal file
View File

@ -0,0 +1,91 @@
.. _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 filesystem that can be accessed by
OpenStack compute instances, or clients outside of OpenStack (depending on
deployment configuration).
.. note::
A ``share`` is an abstract storage object that may or may not directly
map to a "share" concept from the underlying storage provider.
Snapshot
~~~~~~~~
A ``snapshot`` is a point-in-time, read-only copy of a ``share``.
``Snapshots`` can be created from an existing ``share`` that is operational
regardless of whether a client has mounted the file system. A ``snapshot``
can serve as the content source for a new ``share`` when the ``share``
is created with the create from snapshot option specified.
Storage Pools
~~~~~~~~~~~~~
With the Kilo release of OpenStack, the Shared File Systems service has
introduced the concept of ``storage pools``. The storage may present one or
more logical storage resource pools from which 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 that represent a tiered level of storage services; for example, a
cloud administrator might define a premium ``share type`` that indicates a
greater level of performance than a basic ``share type``, which would
represent a best-effort level of performance.
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``.
Security Services
~~~~~~~~~~~~~~~~~
``Security services`` are the concept in the Shared File Systems service that
allow Finer-grained client access rules to be declared for authentication or
authorization to access ``share`` content. External services including LDAP,
Active Directory, Kerberos can be declared as resources that should be
consulted when making an access decision to a particular ``share``. ``Shares``
can be associated to multiple security services but only one service per one
type.
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 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.
Share Servers
~~~~~~~~~~~~~
A ``share server`` is a logical entity that hosts the shares that are
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 that are 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 Network
service.

139
doc/admin-guide-cloud/source/shared_file_systems_manage_and_unmanage_share.rst Normal file
View File

@ -0,0 +1,139 @@
.. _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 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.
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.
.. _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.
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:
.. code:: console
$ manila unmanage Share3
$ manila show Share3
ERROR: No share with a name or ID of 'Share3' exists.
.. _manage_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:
.. code:: 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 this format:
``host@backend#POOL`` 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. A valid
value is 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.
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
``driver_handles_share_servers = False`` option, so special share type named
``for_managing`` was used in example.
To manage share, run:
.. code:: console
$ manila manage manila@cannes#CANNES nfs 10.254.0.7:/shares/share-d1a66eed-a724-4cbb-a886-2f97926bd3b3 --name Share --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 |
| export_locations | [] |
| share_server_id | None |
| host | manila@cannes#CANNES |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | 5c1f644a-6521-4699-b480-b03d17e2d21d |
| size | None |
| name | Share3 |
| share_type | 1eafb65f-1987-44a9-9a98-20af91c95662 |
| created_at | 2015-10-01T10:35:52.000000 |
| export_location | 10.254.0.7:/shares/share-d1a66eed-a724-4cbb-a886-2f97926bd3b3 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| metadata | {} |
+-----------------------------+---------------------------------------------------------------+
Check that he share is available:
.. code:: console
$ manila show Share
+-----------------------------+---------------------------------------------------------------+
| Property | Value |
+-----------------------------+---------------------------------------------------------------+
| status | available |
| share_type_name | for_managing |
| description | We manage 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 | 5c1f644a-6521-4699-b480-b03d17e2d21d |
| size | 1 |
| name | Share3 |
| share_type | 1eafb65f-1987-44a9-9a98-20af91c95662 |
| created_at | 2015-10-01T10:35:52.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| metadata | {} |
+-----------------------------+---------------------------------------------------------------+

64
doc/admin-guide-cloud/source/shared_file_systems_multi_backend.rst Normal file
View File

@ -0,0 +1,64 @@
.. _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>`.
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
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
[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
[backendEMC2]
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 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

79
doc/admin-guide-cloud/source/shared_file_systems_network_plugins.rst Normal file
View File

@ -0,0 +1,79 @@
.. _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 tenants’
networked storage. There are a set of network plugins 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
``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
resources including IP addresses and network interfaces.
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.
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.
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.
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.
a) ``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``.
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.
When only a single network is needed, the NovaSingleNetworkPlugin (2.b) is a
simple solution. Otherwise NovaNetworkPlugin (1.a) should be chosen.
3. Network plugin 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.
.. note::
These network plugins 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>`_

17
doc/admin-guide-cloud/source/shared_file_systems_networking.rst Normal file
View File

@ -0,0 +1,17 @@
.. _shared_file_systems_networking:
==========
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.
.. toctree::
shared_file_systems_share_networks.rst
shared_file_systems_network_plugins.rst

140
doc/admin-guide-cloud/source/shared_file_systems_quotas.rst Normal file
View File

@ -0,0 +1,140 @@
.. _shared_file_systems_quotas:
=================
Quotas and limits
=================
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.
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:
.. code:: 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 that can be processed
during a one-minute period.
To see the rate limits, run:
.. code:: console
$ manila rate-limits
Quotas
------
Quota sets provide quotas management support.
To list the quotas for a tenant or user, use **manila quota-show** command.
If you specify the optional ``--user`` parameter, you get the quotas for this
user in the specified tenant. If you omit this parameter, you get the quotas
for the specified project.
.. code:: console
$ manila quota-show --tenant demo --user demo
+--------------------+-------+
| 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
:file:`/etc/manila/manila.conf` file. To list default quotas for a project, use
**manila quota-defaults** command:
.. code:: console
$ manila quota-defaults --tenant demo
+--------------------+-------+
| Property | Value |
+--------------------+-------+
| gigabytes | 1000 |
| snapshot_gigabytes | 1000 |
| snapshots | 50 |
| shares | 50 |
| share_networks | 10 |
+--------------------+-------+
Administrator can update the quotas for a specified tenant or for a specified
user by providing both ``--tenant`` and ``--user`` optional arguments.
It is possible to update ``snapshots``, ``gigabytes``, ``snapshot-gigabytes``,
and ``share-networks`` quotas.
.. code:: console
$ manila quota-update demo --user demo --shares 49 --snapshots 49
As administrator, you can also permit or deny the force-update of a quota that
is already used and the requested value exceeds the configured quota. To
force-update a quota, use ``force`` optional key.
.. code:: console
$ manila quota-update demo --shares 51 --snapshots 51 --force
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 |
+--------------------+-------+

32
doc/admin-guide-cloud/source/shared_file_systems_scheduling.rst Normal file
View File

@ -0,0 +1,32 @@
.. _shared_file_systems_scheduling:
==========
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.
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
<http://docs.openstack.org/developer/manila/devref/capabilities_and_extra_spec
s.html>`_ section in developer documentation.
In general scheduler workflow looks like:
1) Share services report information about number of existed pools, their
capacities and capabilities.
2) 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;
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.

181
doc/admin-guide-cloud/source/shared_file_systems_security_services.rst Normal file
View File

@ -0,0 +1,181 @@
.. _shared_file_systems_security_services:
=================
Security services
=================
A security service stores configuration information for clients 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 from 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.
The security service can be added to the
:ref:`share network <shared_file_systems_share_networks>`.
To create a security service, specify the security service type and optionally
name, description of a security service, DNS IP address used inside tenant's
network, security service IP address or hostname, domain, security service user
or group used by tenant, a password of user.
Create a ``ldap`` security service:
.. code:: 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:: 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
**manila security-service-list**:
.. code:: 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>` that is not used yet
(is not associated with a share).
Add a security service to the share network with
**share-network-security-service-add** specifying share network, security
service and print the information about the security service. You can see
new attribute ``share_networks`` with associated share network ID.
.. code:: 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
given share network. List security services for ``share_net2`` share network:
.. code:: 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 see that a security service now has empty list of share networks:
.. code:: 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 |
+----------------+--------------------------------------+
Shared File Systems Storage 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``.
To remove a security service, that is not assosiated with any share networks,
run:
.. code:: console
$ manila security-service-delete my_ldap_security_service

15
doc/admin-guide-cloud/source/shared_file_systems_services_manage.rst Normal file
View File

@ -0,0 +1,15 @@
.. _shared_file_systems_services_manage.rst:
======================
Manage shares services
======================
The Shared File Systems service provides API allows to Cloud Administrator
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
service excludes from scheduler cycle and new shares will not be placed on
disabled back end, but shares from this service stay available.

39
doc/admin-guide-cloud/source/shared_file_systems_share_management.rst Normal file
View File

@ -0,0 +1,39 @@
.. _shared_file_systems_share_management:
================
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.
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).
.. 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.
.. toctree::
shared_file_systems_crud_share.rst
shared_file_systems_manage_and_unmanage_share.rst
shared_file_systems_share_resize.rst
shared_file_systems_quotas.rst

139
doc/admin-guide-cloud/source/shared_file_systems_share_networks.rst Normal file
View File

@ -0,0 +1,139 @@
.. _shared_file_systems_share_networks:
==============
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.
How to create share network
~~~~~~~~~~~~~~~~~~~~~~~~~~~
List networks in a tenant, run:
.. code:: console
$ neutron net-list
+--------------+---------+---------------------------------------+
| id | name | subnets |
+--------------+---------+---------------------------------------+
| bee7411d-... | public | 884a6564-0f11-... 2001:db8::/64 |
| | | e6da81fa-5d5f-... 172.24.4.0/24 |
| 5ed5a854-... | private | 74dcfb5a-b4d7-... 10.0.0.0/24 |
| | | cc297be2-5213-... fd7d:177d:a48b::/64 |
+--------------+---------+---------------------------------------+
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`, `flat`, or `local`.
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:: 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.
Check network list, run:
.. code:: 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 had already some operations in the Shared
File Systems service, you can see ``manila_service_network`` in the neutron
list of networks. This network was created by Generic driver for inner usage.
.. code:: console
$ neutron net-list
+--------------+------------------------+------------------------------------+
| id | name | subnets |
+--------------+------------------------+------------------------------------+
| 3b5a629a-e...| manila_service_network | 4f366100-50... 10.254.0.0/28 |
| bee7411d-d...| public | 884a6564-01... 2001:db8::/64 |
| | | e6da81fa-55... 172.24.4.0/24 |
| 5ed5a854-2...| private | 74dcfb5a-bd... 10.0.0.0/24 |
| | | cc297be2-51... fd7d:177d:a48b::/64 |
+--------------+------------------------+------------------------------------+
You also can see detailed information about the share network including
``network_type``, ``segmentation_id`` fields:
.. code:: console
$ neutron net-show manila_service_network
+---------------------------+--------------------------------------+
| Field | Value |
+---------------------------+--------------------------------------+
| admin_state_up | True |
| id | 3b5a629a-e7a1-46a3-afb2-ab666fb884bc |
| mtu | 0 |
| name | manila_service_network |
| port_security_enabled | True |
| provider:network_type | vxlan |
| provider:physical_network | |
| provider:segmentation_id | 1068 |
| router:external | False |
| shared | False |
| status | ACTIVE |
| subnets | 4f366100-5108-4fa2-b5b1-989a121c1403 |
| tenant_id | 24c6491074e942309a908c674606f598 |
+---------------------------+--------------------------------------+
You also can add and remove the security services to the share network. For
details, see :ref:`shared_file_systems_security_services`.

86
doc/admin-guide-cloud/source/shared_file_systems_share_resize.rst Normal file
View File

@ -0,0 +1,86 @@
.. _shared_file_systems_share_resize:
============
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.
You can extend and shrink the share with **manila extend** and
**manila shrink** commands correspondingly and specifying the share and new
size that doesn't exceed the quota. For details, see
:ref:`Quotas and Limits <shared_file_systems_quotas>`. You also cannot shrink
size to 0 or to a greater value than the current share size.
While extending the share gets ``extending`` status that means that the
increase share size request was issued successfully.
To extend the share and check the result, run:
.. code:: console
$ manila extend Share1 2
$ manila show Share1
+-----------------------------+-------------------------------------------+
| Property | Value |
+-----------------------------+-------------------------------------------+
| status | available |
| share_type_name | default |
| description | My first share. Updated |
| availability_zone | nova |
| share_network_id | 5c3cbabb-f4da-465f-bc7f-fadbe047b85a |
| export_locations | 10.254.0.3:/shares/share-2d5e2c0a-1f84-...|
| share_server_id | 41b7829d-7f6b-4c96-aea5-d106c2959961 |
| host | manila@generic1#GENERIC1 |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | aca648eb-8c03-4394-a5cc-755066b7eb66 |
| size | 2 |
| name | Share1 |
| share_type | c0086582-30a6-4060-b096-a42ec9d66b86 |
| created_at | 2015-09-24T12:19:06.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| metadata | {u'deadline': u'01/30/16'} |
+-----------------------------+-------------------------------------------+
While shrinking the share gets ``shrinking`` status that means that the
decrease share size request was issued successfully. To shrink the share and
check the result, run:
.. code:: console
$ manila shrink Share1 1
$ manila show Share1
+-----------------------------+-------------------------------------------+
| Property | Value |
+-----------------------------+-------------------------------------------+
| status | available |
| share_type_name | default |
| description | My first share. Updated |
| availability_zone | nova |
| share_network_id | 5c3cbabb-f4da-465f-bc7f-fadbe047b85a |
| export_locations | 10.254.0.3:/shares/share-2d5e2c0a-1f84-...|
| share_server_id | 41b7829d-7f6b-4c96-aea5-d106c2959961 |
| host | manila@generic1#GENERIC1 |
| snapshot_id | None |
| is_public | False |
| task_state | None |
| snapshot_support | True |
| id | aca648eb-8c03-4394-a5cc-755066b7eb66 |
| size | 1 |
| name | Share1 |
| share_type | c0086582-30a6-4060-b096-a42ec9d66b86 |
| created_at | 2015-09-24T12:19:06.000000 |
| share_proto | NFS |
| consistency_group_id | None |
| source_cgsnapshot_member_id | None |
| project_id | 20787a7ba11946adad976463b57d8a2f |
| metadata | {u'deadline': u'01/30/16'} |
+-----------------------------+-------------------------------------------+

174
doc/admin-guide-cloud/source/shared_file_systems_share_types.rst Normal file
View File

@ -0,0 +1,174 @@
.. _shared_file_systems_share_types:
===========
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.
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.
To create a share type, use **manila type-create** command as:
.. code:: 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 that are
used for the back ends filtering:
- ``driver_handles_share_servers``. Required. Defines the driver mode for share
server life cycle management. Valid values are ``true``/``1`` and
``false``/``0``.
Set to True when the share driver can manage, or handle, the share server
life cycle.
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 that are written in
this format: ``extra_spec=value``. For example, **netapp_raid_type=raid4**.
- *Set data for the driver*. Qualified extra specifications that are written
always 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 that match the
un-scoped extra-spec keys for the share type. For details, see `Capabilities
and Extra-Specs <http://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 :file:`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 name of new share type and
required extra spec ``driver_handles_share_servers``. Also, the new share type
can be public.
.. code:: 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 | No | 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 a specified driver.
.. code:: console
$ manila type-key netapp1 set thin_provisioned=True
It is also possible for administrator to see a list of current share types and
extra specifications:
.. code:: console
$ manila extra-specs-list
+-------------+---------+-------------------------------------+
| ID | Name | all_extra_specs |
+-------------+---------+-------------------------------------+
| c0086582-...| netapp1 | snapshot_support : True |
| | | thin_provisioned : True |
| | | driver_handles_share_servers : True |
+-------------+---------+-------------------------------------+
Use **manila type-key <share_type> unset <key>** to unset an extra
specification.
The public or private share type can be deleted by means of
**manila type-delete <share_type>** command.
.. _share_type_access:
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
private share type.
Create a private type:
.. code:: console
$ manila type-create my_type1 True --is_public False
+-----+---------+-----------+-----------+----------------------------------+----------------------+
| ID | Name | Visibility| is_default| required_extra_specs | optional_extra_specs |
+-----+---------+-----------+-----------+----------------------------------+----------------------+
| a4..| my_type1| private | - | driver_handles_share_servers:True| snapshot_support:True|
+-----+---------+-----------+-----------+----------------------------------+----------------------+
.. note::
If you run **manila type-list** you see only public types. To see the
private types also, run **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:: console
$ manila type-access-add my_type1 d8f9af6915404114ae4f30668a4f5ba7
$ manila type-access-add my_type1 e4970f57f1824faab2701db61ee7efdf
Get information about access for a private share type ``my_type1``:
.. code:: console
$ manila type-access-list my_type1
+----------------------------------+
| Project_ID |
+----------------------------------+
| d8f9af6915404114ae4f30668a4f5ba7 |
| e4970f57f1824faab2701db61ee7efdf |
+----------------------------------+
After you granted the access to the share type users that belong to project
with granted access can see the type in the list and create shares with
allowed private share type.
To deny access for a specified project, use
**manila type-access-remove <share_type> <project_id>** command.

136
doc/admin-guide-cloud/source/shared_file_systems_snapshots.rst Normal file
View File

@ -0,0 +1,136 @@
.. _shared_file_systems_snapshots:
===============
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.
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
instance and then copy file from archive to attached file system.
.. note::
You cannot delete share cannot while it has saved dependent snapshots.
Create a snapshot from the share:
.. code:: 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 name or description of a snapshot if it is needed:
.. code:: console
$ manila snapshot-rename Snapshot1 Snapshot_1 --description "Snapshot of Share1. Updated."
Check that status of a snapshot is ``available``:
.. code:: 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 snapshot, use :command:`manila create` with key
``--snapshot-id``. This creates a new share from exiting snapshot.
Create a share from a snapshot and check whether it is available:
.. code:: 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 **manila snapshot-delete
<snapshot_name_or_ID>**. If a snapshot is in busy state and during deleting
got the ``error_deleting`` status, administrator can force-delete it or
explicitly reset the state.
Use **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, available will be used.
Use **manila snapshot-force-delete <snapshot>** to force-delete a specified
share snapshot in any state.

63
doc/admin-guide-cloud/source/shared_file_systems_troubleshoot.rst Normal file
View File

@ -0,0 +1,63 @@
.. _shared_file_systems_troubleshoot:
========================================
Troubleshoot Shared File Systems service
========================================
Failures in share service during 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.
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.
3. 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.
No valid host was found
~~~~~~~~~~~~~~~~~~~~~~~
You should manage share types very carefully. If share type contains invalid
extra spec scheduler will never find valid host for share of this type.
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 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
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.
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.