openstack/openstack-manuals
Code Issues Proposed changes
66692c71a5
openstack-manuals/doc/admin-guide-cloud/source/shared_file_systems_cgroups.rst
Jane Zadorozhna 61c744c2c5 Cloud Admin Guide: Shared File Systems updated information 
After the technical review the Shared File Systems service
documentation in the Cloud Admin Guide needs to be updated.

Read and fixed some typos and incorrect English constructions in
the sentences of all sections. Fixed indentations in code, tip
and note directives. Also updated the following info:
* Removed references to the Generic driver, because it is default
  only on Devstack. And even for Devstack the default driver is going
  to be changed.
* Divided 'Create share' subsection on 3 subsections: added general
  concepts and info of creating a share in 2 back end modes.
* Added info that with StandaloneNetworkPlugin the Shared File Systems
  service can be configured without Networking and Compute services.
* Added export paths for GlusterFS and HDFS.
* Added notes what driver in what mode you use in examples and a noted
  what modes exist and can be configured.
* Added a console sample for "manila rate-limits" command and described
  how to add API rate limits.
* Removed information and samples about a quota classes because they are
  not used in the Shared File Systems service and are not working
  properly for the current moment (in Liberty release).
* Added second purpose of the share types.
* Removed '/etc/manila/' in manila.conf file, because its path can be
  customly changed.
* Said that consistency groups is the experimental part of API starting
  with Liberty release.
* Updated a sample in shared_file_systems_multi_backend.html file.
* Removed 'Storage' from the Shared File Systems service official name
  according to [1] document.

[1] http://git.openstack.org/cgit/openstack/governance/tree/reference/projects.yaml

Change-Id: I0530ea3c6bf74311e271cdabca26cd10afcddc92
Closes-Bug: #1508457
2015-10-27 09:43:46 +00:00

315 lines
17 KiB
ReStructuredText
Raw Blame History

.. _shared_file_systems_cgroups:
==================
Consistency groups
==================
Consistency groups enable you to create snapshots from multiple file system
shares at the same point in time. For example, a database might place its
tables, logs, and configuration on separate shares. To restore this database
from a previous point in time, it makes sense to restore the logs, tables, and
configuration together from the exact same point in time.
The Shared File System service allows you to create a snapshot of the
consistency group and restore all shares that were associated with a
consistency group.
.. note::
The **consistency groups and snapshots** are realized as an
**experimental** Shared File Systems API in Liberty release. Contributors
can change or remove the experimental part of the Shared File Systems API
in further releases without maintaining backward compatibility. The
experimental API has ``"X-OpenStack-Manila-API-Experimental: true"`` header
in their HTTP requests.
Consistency groups
------------------
.. note::
Before using consistency groups, make sure the Shared File System driver
that you are running has consistency group support. You can check it in the
``manila-scheduler`` service 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.
View Git Blame Copy Permalink