diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 8c448d3dad..df9f5bfe1a 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -48,6 +48,8 @@ deployment. shared-file-systems-share-server-management.rst shared-file-systems-share-migration.rst shared-file-systems-share-types.rst + shared-file-systems-share-group-types.rst + shared-file-systems-share-groups.rst shared-file-systems-snapshots.rst shared-file-systems-security-services.rst shared-file-systems-share-replication.rst diff --git a/doc/source/admin/shared-file-systems-share-group-types.rst b/doc/source/admin/shared-file-systems-share-group-types.rst new file mode 100644 index 0000000000..39581a7aab --- /dev/null +++ b/doc/source/admin/shared-file-systems-share-group-types.rst @@ -0,0 +1,181 @@ +.. _shared_file_systems_share_group_types: + +================= +Share group types +================= + +Share group types are types for share groups just like :ref:`share types for +shares`. +A group type is associated with group specs similar to the way extra specs are +associated with a share type. + +A share group type aids the scheduler to filter or choose back ends when you +create a share group and to set any backend specific parameters on the share +group. Any driver that can perform a group operation in an advantaged way may +report that as a group capability, such as: + +* Ordered writes +* Consistent snapshots +* Group replication +* Group backup + +Share group types may contain group specs corresponding to the group +capabilities reported by the backends. A group capability applies across all +the shares inside the share group, for example, a backend may support +`consistent_snapshot_support`, and using this group type extra spec in the +group type will allow scheduling share groups onto that backend. Any time a +snapshot of the group is initiated, a crash consistent simultaneous snapshot +of all the constituent shares is taken. +Shares in a share group may each have different share types because they can +each be on separate pools, have different capabilities and perhaps end users +can even be billed differently for using each of them. To allow for this +possibility, one or more share types can be associated with a group type. The +admin also specifies which share type(s) a given group type may contain. +At least one share type must be provided to create a share group type. +When an user creates a share group, the scheduler creates the group on one of +the backends that match the specified share type(s) and share group type. + +In the Shared File Systems configuration file ``manila.conf``, the +administrator can set the share group type used by default for the share group +creation. + +To create a share group type, use :command:`manila share-group-type-create` command as: + +.. code-block:: console + + manila share-group-type-create [--is_public ] + [--group-specs [ [ ...]]] + + + +Where the ``name`` is the share group type name and ``--is_public`` defines +the level of the visibility for the share group type. One share group can +include multiple ``share_types``. ``--group-specs`` are the extra +specifications used to filter back ends. + +.. note:: + + The extra specifications set in the share group types are explained further + in :ref:`shared_file_systems_scheduling`. + +Administrators can create share group types with these extra specifications for +the back ends filtering. +An administrator can use the ``policy.json`` file to grant permissions for +share group type creation with extra specifications to other roles. + +You set a share group type to private or public and +:ref:`manage the access` to the private share group types. By +default a share group type is created as publicly accessible. Set +``--is_public`` to ``False`` to make the share group type private. + +Share group type operations +--------------------------- + +To create a new share group type you need to specify the name of the new share +group type and existing share types. The new share group type can also be public. +One share group can include multiple share types. + +.. code-block:: console + + $ manila share-group-type-create group_type_for_cg default_share_type --is_public True + +------------+--------------------------------------+ + | Property | Value | + +------------+--------------------------------------+ + | is_default | - | + | ID | cfe42f20-d13e-4348-9370-f0763e426db3 | + | Visibility | public | + | Name | group_type_for_cg | + +------------+--------------------------------------+ + + $ manila share-group-type-list + +--------------------------------------+-------------------+------------+------------+ + | ID | Name | visibility | is_default | + +--------------------------------------+-------------------+------------+------------+ + | cfe42f20-d13e-4348-9370-f0763e426db3 | group_type_for_cg | public | - | + +--------------------------------------+-------------------+------------+------------+ + +You can set or unset extra specifications for a share group type +using **manila share-group-type-key set ** command. + +.. code-block:: console + + $ manila share-group-type-key group_type_for_cg set consistent_snapshot_support=host + +It is also possible to view a list of current share group types and extra +specifications: + +.. code-block:: console + + $ manila share-group-type-specs-list + +--------------------------------------+-------------------+------------------------------------+ + | ID | Name | all_extra_specs | + +--------------------------------------+-------------------+------------------------------------+ + | cfe42f20-d13e-4348-9370-f0763e426db3 | group_type_for_cg | consistent_snapshot_support : host | + +--------------------------------------+-------------------+------------------------------------+ + + +Use :command:`manila share-group-type-key unset ` to +unset an extra specification. + +A public or private share group type can be deleted with the +:command:`manila share-group-type-delete ` command. + +.. _share_group_type_access: + +Share group type access +----------------------- + +You can manage access to a private share group type for different projects. +Administrators can provide access, revoke access, and retrieve +information about access for a specified private share group. + +Create a private group type: + +.. code-block:: console + + $ manila share-group-type-create my_type1 default_share_type --is_public False + +------------+--------------------------------------+ + | Property | Value | + +------------+--------------------------------------+ + | is_default | - | + | ID | f57cf3db-2503-4c0f-915c-4f1335d95465 | + | Visibility | private | + | Name | my_type1 | + +------------+--------------------------------------+ + +.. note:: + + If you run :command:`manila share-group-type-list` only public share group + types appear. To see private share group types, run :command:`manila + share-group-type-list` with ``--all`` optional argument. + +Grant access to created private type for a demo and alt_demo projects +by providing their IDs: + +.. code-block:: console + + $ manila share-group-type-access-add my_type1 d8f9af6915404114ae4f30668a4f5ba7 + $ manila share-group-type-access-add my_type1 e4970f57f1824faab2701db61ee7efdf + +To view information about access for a private share, :command:`manila type-access-list my_type1`: + +.. code-block:: console + + $ manila type-access-list my_type1 + +----------------------------------+ + | Project_ID | + +----------------------------------+ + | d8f9af6915404114ae4f30668a4f5ba7 | + | e4970f57f1824faab2701db61ee7efdf | + +----------------------------------+ + +After granting access to the share group type, the target project +can see the share group type in the list, and create private +share groups. + +To deny access for a specified project, use +:command:`manila share-group-type-access-remove ` command. + +.. code-block:: console + + $ manila share-group-type-access-remove my_type1 e4970f57f1824faab2701db61ee7efdf diff --git a/doc/source/admin/shared-file-systems-share-groups.rst b/doc/source/admin/shared-file-systems-share-groups.rst new file mode 100644 index 0000000000..376103522b --- /dev/null +++ b/doc/source/admin/shared-file-systems-share-groups.rst @@ -0,0 +1,325 @@ +.. + Copyright (c) 2017 Jun Zhong + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + +============ +Share groups +============ + +Share group support is available in Manila since the Ocata release. A share +group is a group of shares upon which users can perform group based operations, +such as taking a snapshot together. This framework is meant to allow migrating +or replicating a group of shares in unison in future releases of manila. +Support currently exists for creating group types and group specs, creating +groups of shares, and creating snapshots of groups. These group operations can +be performed using the command line client. + +To create a share group, and access it, the following general concepts +are prerequisite knowledge: + +#. To create a share group, use :command:`manila share-group-create` command. + +#. You can specify the ``share-network``, :ref:`share group type `, + ``source-share-group-snapshot``, ``availability-zone``, + :ref:`share type `. + +#. After the share group becomes available, use the :command:`manila create` + command to create a share within the share group. + +.. note:: + A share group is limited to a single backend, i.e. all shares created within + a particular share group end up on the same backend. If the backend supports + pools, the shares may be created within separate pools. So this feature is + apt for those that would like co-locality of different shares. + +Actions on a share group +~~~~~~~~~~~~~~~~~~~~~~~~ + +A few actions, such as extend & shrink, are inherently applicable only to +individual shares. One could theoretically apply extend to a group, increasing +the size of each member, but this would not be a use-case covered initially. +Any actions in this category must remain available to group members, and +other actions such as taking snapshots of group members can be allowed, but +actions such as migration or replication would be available only at the group +level and not on its members. + +====================== ======================================================== +Share Action Share Group Action +====================== ======================================================== +Create (share type) Create (share types, group type) +Delete Delete (group) +Snapshot Snapshot (may or may not be a consistent group snapshot) +Create from snapshot Create from group snapshot +Clone Clone group (and all members) (planned) +Replicate Replicate (planned) +Migrate Migrate (planned) +Extend/shrink N/A +====================== ======================================================== + +Creating a share with share group +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Creating a share group type +--------------------------- + +In this example, we will create a new share group type and specify the +`consistent_snapshot_support` as an group-spec within the +share-group-type-create being used. + +Use the :command:`manila type-list` command to get a share type. +Then use the share type to create a share group type. + +.. code-block:: console + + $ manila type-list + +--------------------------------------+---------------------+------------+------------+--------------------------------------+-----------------------------+ + | ID | Name | visibility | is_default | required_extra_specs | optional_extra_specs | + +--------------------------------------+---------------------+------------+------------+--------------------------------------+-----------------------------+ + | ee6287aa-448b-432b-a928-41ce9d8e149f | default_share_type | public | - | driver_handles_share_servers : False | | + +--------------------------------------+---------------------+------------+------------+--------------------------------------+-----------------------------+ + +Use the :command:`manila share-group-type-create` command to create a new +share group type. Specify the name and share types. + +.. code-block:: console + + $ manila share-group-type-create group_type_for_cg default_share_type + +------------+--------------------------------------+ + | Property | Value | + +------------+--------------------------------------+ + | is_default | - | + | ID | cfe42f20-d13e-4348-9370-f0763e426db3 | + | Visibility | public | + | Name | group_type_for_cg | + +------------+--------------------------------------+ + +Use the :command:`manila share-group-type-key` command to set a group-spec to the +share group type. + +.. code-block:: console + + $ manila share-group-type-key group_type_for_cg set consistent_snapshot_support=host + +.. note:: + This command has no output. To verify the group-spec, use the + :command:`manila share-group-type-specs-list` command and specify + the share group type's name or ID as a parameter. + +Creating a share group +---------------------- + +Use the :command:`manila share-group-create` command to create a share group. +Specify the share group type that we created. + +.. code-block:: console + + $ manila share-group-create --share-group-type group_type_for_cg + +--------------------------------+--------------------------------------+ + | Property | Value | + +--------------------------------+--------------------------------------+ + | status | creating | + | description | None | + | created_at | 2017-09-11T02:08:52.319921 | + | source_share_group_snapshot_id | None | + | share_network_id | None | + | share_server_id | None | + | host | None | + | share_group_type_id | cfe42f20-d13e-4348-9370-f0763e426db3 | + | project_id | 87ba30b5315c40ec8ec5e3346112eae4 | + | share_types | ee6287aa-448b-432b-a928-41ce9d8e149f | + | id | ecf78d45-546a-48df-a969-c153e68f0376 | + | name | None | + +--------------------------------+--------------------------------------+ + +.. note:: + One share group can include multiple share types. The share types are going + to be inherited directly from the share group type. + +Use the :command:`manila share-group-show` command to retrieve details of the share. +Specify the share ID or name as a parameter. + +.. code-block:: console + + $ manila share-group-show ecf78d45-546a-48df-a969-c153e68f0376 + +--------------------------------+-------------------------------------------+ + | Property | Value | + +--------------------------------+-------------------------------------------+ + | status | available | + | description | None | + | created_at | 2017-09-11T02:08:53.000000 | + | source_share_group_snapshot_id | None | + | share_network_id | None | + | share_server_id | None | + | host | ubuntu@generic2#test_pool | + | share_group_type_id | cfe42f20-d13e-4348-9370-f0763e426db3 | + | project_id | 87ba30b5315c40ec8ec5e3346112eae4 | + | share_types | ee6287aa-448b-432b-a928-41ce9d8e149f | + | id | ecf78d45-546a-48df-a969-c153e68f0376 | + | name | None | + +--------------------------------+-------------------------------------------+ + +Create a share with the share group +----------------------------------- + +Use the :command:`manila create` command to create a share. Specify the share +protocol, size, share group type and the share name. + +.. code-block:: console + + $ manila create NFS 1 --share-group ecf78d45-546a-48df-a969-c153e68f0376 --name test_group_share_1 + +---------------------------------------+-------------------------------------------+ + | Property | Value | + +---------------------------------------+-------------------------------------------+ + | status | creating | + | share_type_name | default_share_type | + | description | None | + | availability_zone | None | + | share_network_id | None | + | share_server_id | None | + | share_group_id | ecf78d45-546a-48df-a969-c153e68f0376 | + | host | ubuntu@generic2#test_pool | + | revert_to_snapshot_support | False | + | access_rules_status | active | + | snapshot_id | None | + | create_share_from_snapshot_support | False | + | is_public | False | + | task_state | None | + | snapshot_support | False | + | id | 21997eaf-712e-433e-8872-4ff085683657 | + | size | 1 | + | source_share_group_snapshot_member_id | None | + | user_id | b7f2c522a5644a83b78b3f61f50c6d71 | + | name | test_group_share_1 | + | share_type | ee6287aa-448b-432b-a928-41ce9d8e149f | + | has_replicas | False | + | replication_type | None | + | created_at | 2017-09-11T02:28:16.000000 | + | share_proto | NFS | + | mount_snapshot_support | False | + | project_id | 87ba30b5315c40ec8ec5e3346112eae4 | + | metadata | {} | + +---------------------------------------+-------------------------------------------+ + +Create another share with a same share group, and named 'test_group_share_2'. + +.. code-block:: console + + $ manila create NFS 1 --share-group ecf78d45-546a-48df-a969-c153e68f0376 --name test_group_share_2 + +---------------------------------------+-------------------------------------------+ + | Property | Value | + +---------------------------------------+-------------------------------------------+ + | status | creating | + | share_type_name | default_share_type | + | description | None | + | availability_zone | None | + | share_network_id | None | + | share_server_id | None | + | share_group_id | ecf78d45-546a-48df-a969-c153e68f0376 | + | host | ubuntu@generic2#test_pool | + | revert_to_snapshot_support | False | + | access_rules_status | active | + | snapshot_id | None | + | create_share_from_snapshot_support | False | + | is_public | False | + | task_state | None | + | snapshot_support | False | + | id | 8d34a9a3-3b8c-4771-af2c-66c78fe1e0b1 | + | size | 1 | + | source_share_group_snapshot_member_id | None | + | user_id | b7f2c522a5644a83b78b3f61f50c6d71 | + | name | test_group_share_2 | + | share_type | ee6287aa-448b-432b-a928-41ce9d8e149f | + | has_replicas | False | + | replication_type | None | + | created_at | 2017-09-11T21:01:36.000000 | + | share_proto | NFS | + | mount_snapshot_support | False | + | project_id | 87ba30b5315c40ec8ec5e3346112eae4 | + | metadata | {} | + +---------------------------------------+-------------------------------------------+ + + +Creating a share group snapshot +------------------------------- + +Create a share group sanpshot of the share group + +Use the :command:`manila share-group-snapshot-create` command to create a +share group snapshot. Specify the share group ID or name. + +.. code-block:: console + + $ manila share-group-snapshot-create ecf78d45-546a-48df-a969-c153e68f0376 + +----------------+--------------------------------------+ + | Property | Value | + +----------------+--------------------------------------+ + | status | creating | + | name | None | + | created_at | 2017-09-11T21:04:54.612737 | + | share_group_id | ecf78d45-546a-48df-a969-c153e68f0376 | + | project_id | 87ba30b5315c40ec8ec5e3346112eae4 | + | id | ac387240-08dc-4b23-80f6-ffc481e6c87a | + | description | None | + +----------------+--------------------------------------+ + +Show the members of the share group snapshot + +Use the :command:`manila share-group-snapshot-create` command to see all +share members of share group snapshot. Specify the share group snapshot +ID or name. + +.. code-block:: console + + $ manila share-group-snapshot-list-members ac387240-08dc-4b23-80f6-ffc481e6c87a + +--------------------------------------+------+ + | Share ID | Size | + +--------------------------------------+------+ + | 21997eaf-712e-433e-8872-4ff085683657 | 1 | + | 8d34a9a3-3b8c-4771-af2c-66c78fe1e0b1 | 1 | + +--------------------------------------+------+ + +Show the details of the share group snapshot + +.. code-block:: console + + $ manila share-group-snapshot-show ac387240-08dc-4b23-80f6-ffc481e6c87a + +----------------+--------------------------------------+ + | Property | Value | + +----------------+--------------------------------------+ + | status | available | + | name | None | + | created_at | 2017-09-11T21:04:55.000000 | + | share_group_id | ecf78d45-546a-48df-a969-c153e68f0376 | + | project_id | 87ba30b5315c40ec8ec5e3346112eae4 | + | id | ac387240-08dc-4b23-80f6-ffc481e6c87a | + | description | None | + +----------------+--------------------------------------+ + +Deleting share groups +--------------------- + +Use the :command:`manila share-group-delete ` +to delete share groups. + +Deleting share group snapshots +------------------------------ +Use the :command:`manila share-group-snapshot-delete ` +to delete share a share group snapshot. + +.. important:: + Before attempting to delete a share group or a share group snapshot, make + sure that all its constituent shares and snapshots were deleted. + Users will need to delete share group snapshots before attempting to delete + shares within ashare group or the group itself.