From 2be2160ddb7c2f237a021f88cf953691b806fce4 Mon Sep 17 00:00:00 2001 From: Tom Barron Date: Tue, 8 Aug 2017 05:30:33 -0400 Subject: [PATCH] doc migration: admin guide Migrate the shared file systems documents from the centralized Admin Guide as outlined in the migration spec [1]. [1] https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html Partial-Bug: #1706181 Needed-By: Ibe3588c3f4560c037cf109058fc357234e70a846 Depends-On: Ieea33262101a1d2459492c1c8aaac5fe042279f6 Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454 Change-Id: I7924d94b82e7c8d9716bad7a219fc38c57970773 --- doc/source/admin/index.rst | 22 - doc/source/admin/intro.rst | 25 - doc/source/admin/multi_backends.rst | 89 -- doc/source/admin/network_plugins.rst | 205 ----- .../admin/shared-file-systems-crud-share.rst | 771 ++++++++++++++++++ .../admin/shared-file-systems-intro.rst | 57 ++ .../shared-file-systems-key-concepts.rst | 119 +++ ...file-systems-manage-and-unmanage-share.rst | 162 ++++ ...e-systems-manage-and-unmanage-snapshot.rst | 107 +++ .../shared-file-systems-multi-backend.rst | 59 ++ .../shared-file-systems-network-plugins.rst | 88 ++ .../admin/shared-file-systems-networking.rst | 17 + .../admin/shared-file-systems-quotas.rst | 152 ++++ .../admin/shared-file-systems-scheduling.rst | 33 + .../shared-file-systems-security-services.rst | 186 +++++ .../shared-file-systems-services-manage.rst | 16 + .../shared-file-systems-share-management.rst | 33 + .../shared-file-systems-share-migration.rst | 306 +++++++ .../shared-file-systems-share-networks.rst | 151 ++++ .../shared-file-systems-share-replication.rst | 601 ++++++++++++++ .../shared-file-systems-share-resize.rst | 111 +++ .../admin/shared-file-systems-share-types.rst | 179 ++++ .../admin/shared-file-systems-snapshots.rst | 140 ++++ .../shared-file-systems-troubleshoot.rst | 107 +++ doc/source/index.rst | 2 +- 25 files changed, 3396 insertions(+), 342 deletions(-) delete mode 100644 doc/source/admin/index.rst delete mode 100644 doc/source/admin/intro.rst delete mode 100644 doc/source/admin/multi_backends.rst delete mode 100644 doc/source/admin/network_plugins.rst create mode 100644 doc/source/admin/shared-file-systems-crud-share.rst create mode 100644 doc/source/admin/shared-file-systems-intro.rst create mode 100644 doc/source/admin/shared-file-systems-key-concepts.rst create mode 100644 doc/source/admin/shared-file-systems-manage-and-unmanage-share.rst create mode 100644 doc/source/admin/shared-file-systems-manage-and-unmanage-snapshot.rst create mode 100644 doc/source/admin/shared-file-systems-multi-backend.rst create mode 100644 doc/source/admin/shared-file-systems-network-plugins.rst create mode 100644 doc/source/admin/shared-file-systems-networking.rst create mode 100644 doc/source/admin/shared-file-systems-quotas.rst create mode 100644 doc/source/admin/shared-file-systems-scheduling.rst create mode 100644 doc/source/admin/shared-file-systems-security-services.rst create mode 100644 doc/source/admin/shared-file-systems-services-manage.rst create mode 100644 doc/source/admin/shared-file-systems-share-management.rst create mode 100644 doc/source/admin/shared-file-systems-share-migration.rst create mode 100644 doc/source/admin/shared-file-systems-share-networks.rst create mode 100644 doc/source/admin/shared-file-systems-share-replication.rst create mode 100644 doc/source/admin/shared-file-systems-share-resize.rst create mode 100644 doc/source/admin/shared-file-systems-share-types.rst create mode 100644 doc/source/admin/shared-file-systems-snapshots.rst create mode 100644 doc/source/admin/shared-file-systems-troubleshoot.rst diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst deleted file mode 100644 index 9a348f3eec..0000000000 --- a/doc/source/admin/index.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - - -Admin Reference ---------------- -.. toctree:: - :maxdepth: 3 - - intro - multi_backends - network_plugins diff --git a/doc/source/admin/intro.rst b/doc/source/admin/intro.rst deleted file mode 100644 index 9bec39bb22..0000000000 --- a/doc/source/admin/intro.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -Introduction to Manila Shared Filesystem Management Service -=========================================================== - -:term:`manila` is the File Share service project for OpenStack. To administer the -OpenStack File Share service, it is helpful to understand a number of concepts -like share networks, shares, multi-tenancy and back ends that can be configured -with Manila. When configuring the File Share service, it is required to declare -at least one back end. Manila can be configured to run in a single-node -configuration or across multiple nodes. Manila can be configured to provision -shares from one or more back ends. -The OpenStack File Share service allows you to offer file-share services to -users of an OpenStack installation. diff --git a/doc/source/admin/multi_backends.rst b/doc/source/admin/multi_backends.rst deleted file mode 100644 index 4affb45480..0000000000 --- a/doc/source/admin/multi_backends.rst +++ /dev/null @@ -1,89 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -Configure multiple back ends -============================ -An administrator can configure an instance of Manila to provision shares from -one or more back ends. Each back end leverages an instance of a vendor-specific -implementation of the Manila driver API. - -The name of the back end is declared as a configuration option -share_backend_name within a particular configuration stanza that contains the -related configuration options for that back end. - -Administrators can specify that a particular share type be explicitly -associated with a single back end by including the extra spec -share_backend_name with the name specified within the back end configuration -stanza. When the Manila scheduler receives a provisioning request for a share -type with this extra spec set, it will fulfill the share provisioning request -on the specified back end (assuming all other scheduling criteria including -available capacity are met). - -Enable multiple back ends -========================= -To enable multiple share back ends, you must set the enabled_share_backends -flag in the manila.conf file. This flag defines the names (separated by a -comma) of the configuration stanzas for the different back ends: one name is -associated to one configuration group for a back end. - -The following example shows five configured back ends:: - - [DEFAULT] - enabled_share_backends=backendEMC1,backendEMC2,backendGeneric1,backendGeneric2,backendNetApp - - [backendEMC1] - share_driver=manila.share.drivers.dell_emc.driver.EMCShareDriver - share_backend_name=backendEMC1 - emc_share_backend=vnx - emc_nas_server=1.1.1.1 - emc_nas_password=password - emc_nas_login=user - emc_nas_server_container=server_2 - emc_nas_pool_name="Pool 1" - - [backendEMC2] - share_driver=manila.share.drivers.dell_emc.driver.EMCShareDriver - share_backend_name=backendEMC2 - emc_share_backend=vnx - emc_nas_server=1.1.1.1 - emc_nas_password=password - emc_nas_login=user - emc_nas_server_container=server_3 - emc_nas_pool_name="Pool 2" - - [backendGeneric1] - share_driver=manila.share.drivers.generic.GenericShareDriver - share_backend_name=one_name_for_two_backends - service_instance_user=ubuntu_user - service_instance_password=ubuntu_user_password - service_image_name=ubuntu_image_name - path_to_private_key=/home/foouser/.ssh/id_rsa - path_to_public_key=/home/foouser/.ssh/id_rsa.pub - - [backendGeneric2] - share_driver=manila.share.drivers.generic.GenericShareDriver - share_backend_name=one_name_for_two_backends - service_instance_user=centos_user - service_instance_password=centos_user_password - service_image_name=centos_image_name - path_to_private_key=/home/baruser/.ssh/id_rsa - path_to_public_key=/home/baruser/.ssh/id_rsa.pub - - [backendNetApp] - share_driver = manila.share.drivers.netapp.common.NetAppDriver - driver_handles_share_servers = True - share_backend_name=backendNetApp - netapp_login=user - netapp_password=password - netapp_server_hostname=1.1.1.1 - netapp_root_volume_aggregate=aggr01 diff --git a/doc/source/admin/network_plugins.rst b/doc/source/admin/network_plugins.rst deleted file mode 100644 index 1898706c2d..0000000000 --- a/doc/source/admin/network_plugins.rst +++ /dev/null @@ -1,205 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -Manila Network Plugins -====================== - -The Manila architecture defines an abstraction layer for network resource -provisioning, and it provides a number of concrete `network plugins`, -allowing administrators to choose from a variety of options for how network -resources are assigned to their tenants' networked storage. This document -describes how network plugins may be configured and used in Manila. - -What is a network plugin in Manila? ------------------------------------ - -A network plugin is a python class that uses a specific facility (e.g. -Neutron or Nova network) to provide network resources to the -:term:`manila-share` service. - -When to use a network plugin? ------------------------------ - -A Manila `share driver` may be configured in one of two modes, where it is -managing the lifecycle of `share servers` on its own or where it is merely -providing storage resources on a pre-configured share server. This mode -is defined using the boolean option `driver_handles_share_servers` in the -Manila configuration file. A network plugin is only useful when a driver is -handling its own share servers. - -.. note:: - - Not all share drivers support both modes. Each driver must report which - mode(s) it supports to the manila-share service. - -When `driver_handles_share_servers` is set to `True`, a share driver will be -called to create share servers for shares using information provided within a -`share network`. This information will be provided to one of the enabled -network plugins that will handle reservation, creation and deletion of -network resources including `IP addresses` and `network interfaces`. - -As an exception, any share drivers that use Nova for the creation of share -servers should use some wrapper for network plugins, because Nova handles the -creation of network resources for its VMs. In the Manila Kilo version, only -the `Generic driver` uses Nova with the help of its own `network helpers`, -which serve the same needs but are related only to this share driver. - -.. _what_network_plugins_are_available: - -What network plugins are available? ------------------------------------ - -There are three different network plugins and five python classes in Manila: - -1 Network plugin for using the `OpenStack` networking project `Neutron`. - It allows one to use any network segmentation that Neutron supports. It is - up to each share driver to support at least one network segmentation type. - - 1.1 `manila.network.neutron.neutron_network_plugin.NeutronNetworkPlugin`. - This is the default network plugin. It requires that `neutron_net_id` and - `neutron_subnet_id` are provided when defining the share network that - will be used for the creation of share servers. The user may define any - number of share networks corresponding to the various physical network - segments in a tenant environment. - - 1.2 `manila.network.neutron.neutron_network_plugin.NeutronSingleNetworkPlugin`. - This is a simplification of the previous case. It accepts values for - `neutron_net_id` and `neutron_subnet_id` from the Manila configuration - file and uses one network for all shares. - - 1.3 `manila.network.neutron.neutron_network_plugin.NeutronBindNetworkPlugin`. - This driver waits for active binding and fails if a Neutron port can't be - bound or an error occurs. This plugin is useful for agent based binding - (like OVS with docker driver) and fabric binding where real HW - reconfiguration is taking place. The existing - `NeutronBindSingleNetworkPlugin` is a combination of 1.2 and 1.3. - - When only a single network is needed, the NeutronSingleNetworkPlugin (1.2) - is a simple solution. Otherwise NeutronNetworkPlugin (1.1) should be chosen. - -2 Network plugin for working with OpenStack native networking from `Nova`. - It supports either flat networks or VLAN-segmented networks. - - 2.1 `manila.network.nova_network_plugin.NovaNetworkPlugin`. - This plugin serves the networking needs when `Nova networking` is - configured in the cloud instead of Neutron. It requires a single - parameter, `nova_net_id`. - - 2.2 `manila.network.nova_network_plugin.NovaSingleNetworkPlugin`. - This one works in the same way as the previous one with one difference. - It takes nova_net_id from the Manila configuration file and creates - share servers using only one network. - - When only a single network is needed, the NovaSingleNetworkPlugin (2.2) - is a simple solution. Otherwise NovaNetworkPlugin (1.1) should be chosen. - -3 Network plugin for specifying networks independently from OpenStack - networking services. - - 3.1 `manila.network.standalone_network_plugin.StandaloneNetworkPlugin`. - This plug-in uses a pre-existing network that is available to the - manila-share host. This network may be handled either by OpenStack or be - created independently by any other means. The plugin supports any type of - network - flat and segmented. As above, it is completely up to the driver - to support the network type for which the network plugin is configured. - -.. note:: - - These network plugins were introduced in the OpenStack Kilo release. - In the OpenStack Juno version, only NeutronNetworkPlugin is available. - Plugins in 1.2, 2.2, and 3.1 all ignore what the user supplies in the - share_network and instead always provide IP addresses from a single - network. - -Approaches for setup of network plugins ---------------------------------------- - -Each manila-share service may have its own network plugin or one that is -shared with other services. All configuration options for network plugins may -be set in three ways by priorities: - -- Using a separate configuration group. - For this case, the config opt `network_config_group` should be defined in - the config group of the manila-share service and have the name of - the config group with the defined options for the network plugin. - First priority. -- Using config group of manila-share service. Second priority. -- Using config group `[DEFAULT]`. Lowest priority. - -A specific network plugin is enabled by setting the configuration option -`network_api_class` to one of the values defined in the previous section -:ref:`what_network_plugins_are_available`. This option can be defined in any -of the approaches above along with options for the network plugin itself. - -Example of network plugin configuration ---------------------------------------- - -Let's configure three manila-share services that use different approaches for -configuration of network plugins. -As noted in section :ref:`what_network_plugins_are_available`, in the Kilo -version of OpenStack there are 5 (five) network plugins, three of which -require configuration options - 1.2, 2.2 and 3.1. -We will use a configuration example using network plugin 1.2, the -NeutronSingleNetworkPlugin. - -Here is the configuration:: - - [DEFAULT] - enabled_share_backends = SHARE_BACKEND_1,SHARE_BACKEND_2,SHARE_BACKEND_3 - network_api_class = manila.network.neutron.neutron_network_plugin.NeutronSingleNetworkPlugin - neutron_net_id = neutron_net_id_DEFAULT - neutron_subnet_id = neutron_subnet_id_DEFAULT - - [NETWORK_PLUGIN] - neutron_net_id = neutron_net_id_NETWORK_PLUGIN - neutron_subnet_id = neutron_subnet_id_NETWORK_PLUGIN - - [SHARE_BACKEND_1] - # This share backend is enabled for handling of share servers using opts - # for network plugin defined in separate config group called `NETWORK_PLUGIN`. - network_config_group = NETWORK_PLUGIN - driver_handles_share_servers = True - - [SHARE_BACKEND_2] - # This share backend is enabled for handling of share servers using opts - # defined in its own config group. - driver_handles_share_servers = True - neutron_net_id = neutron_net_id_SHARE_BACKEND_2 - neutron_subnet_id = neutron_subnet_id_SHARE_BACKEND_2 - - [SHARE_BACKEND_3] - # This share backend is enabled for handling of share servers using opts - # defined in config group [DEFAULT]. - driver_handles_share_servers = True - -Here is a list of neutron_net_id and neutron_subnet_id values for our -manila-share services: - -- [SHARE_BACKEND_1] - - neutron_net_id=neutron_net_id_NETWORK_PLUGIN - - neutron_subnet_id=neutron_subnet_id_NETWORK_PLUGIN -- [SHARE_BACKEND_2] - - neutron_net_id=neutron_net_idSHARE_BACKEND_2 - - neutron_subnet_id=neutron_subnet_id_SHARE_BACKEND_2 -- [SHARE_BACKEND_3] - - neutron_net_id=neutron_net_id_DEFAULT - - neutron_subnet_id=neutron_subnet_id_DEFAULT - -The value for option network_api_class was taken by each manila-share service -from group [DEFAULT] because it was not redefined in other places. - -.. note:: - - The last approach - use of [DEFAULT] group - is not preferred for setting - network plugin options and will generate warnings in your manila-share - logs. Either of the first two approaches is recommended. diff --git a/doc/source/admin/shared-file-systems-crud-share.rst b/doc/source/admin/shared-file-systems-crud-share.rst new file mode 100644 index 0000000000..1483cbcc2c --- /dev/null +++ b/doc/source/admin/shared-file-systems-crud-share.rst @@ -0,0 +1,771 @@ +.. _shared_file_systems_crud_share: + +====================== +Share basic operations +====================== + +General concepts +---------------- + +To create a file share, and access it, the following general concepts +are prerequisite knowledge: + +#. To create a share, use :command:`manila create` command and + specify the required arguments: the size of the share and the shared file + system protocol. ``NFS``, ``CIFS``, ``GlusterFS``, ``HDFS``, or + ``CephFS`` share file system protocols are supported. + +#. You can also optionally specify the share network and the share type. + +#. After the share becomes available, use the :command:`manila show` command + to get the share export locations. + +#. After getting the share export locations, you can create an + :ref:`access rule ` for the share, mount it and work with + files on the remote file system. + +There are big number of the share drivers created by different vendors in the +Shared File Systems service. As a Python class, each share driver can be set +for the :ref:`back end ` and run in the back +end to manage the share operations. + +Initially there are two driver modes for the back ends: + +* no share servers mode +* share servers mode + +Each share driver supports one or two of possible back end modes that can be +configured in the ``manila.conf`` file. The configuration option +``driver_handles_share_servers`` in the ``manila.conf`` file sets the share +servers mode or no share servers mode, and defines the driver mode for share +storage lifecycle management: + ++------------------+-------------------------------------+--------------------+ +| Mode | Config option | Description | ++==================+=====================================+====================+ +| no share servers | driver_handles_share_servers = False| An administrator | +| | | rather than a share| +| | | driver manages the | +| | | bare metal storage | +| | | with some net | +| | | interface instead | +| | | of the presence of | +| | | the share servers. | ++------------------+-------------------------------------+--------------------+ +| share servers | driver_handles_share_servers = True | The share driver | +| | | creates the share | +| | | server and manages,| +| | | or handles, the | +| | | share server life | +| | | cycle. | ++------------------+-------------------------------------+--------------------+ + +It is :ref:`the share types ` which have the +extra specifications that help scheduler to filter back ends and choose the +appropriate back end for the user that requested to create a share. The +required extra boolean specification for each share type is +``driver_handles_share_servers``. As an administrator, you can create the share +types with the specifications you need. For details of managing the share types +and configuration the back ends, see :ref:`shared_file_systems_share_types` and +:ref:`shared_file_systems_multi_backend` documentation. + +You can create a share in two described above modes: + +* in a no share servers mode without specifying the share network and + specifying the share type with ``driver_handles_share_servers = False`` + parameter. See subsection :ref:`create_share_in_no_share_server_mode`. + +* in a share servers mode with specifying the share network and the share + type with ``driver_handles_share_servers = True`` parameter. See subsection + :ref:`create_share_in_share_server_mode`. + +.. _create_share_in_no_share_server_mode: + +Create a share in no share servers mode +--------------------------------------- + +To create a file share in no share servers mode, you need to: + +#. To create a share, use :command:`manila create` command and + specify the required arguments: the size of the share and the shared file + system protocol. ``NFS``, ``CIFS``, ``GlusterFS``, ``HDFS``, or + ``CephFS`` share file system protocols are supported. + +#. You should specify the :ref:`share type ` + with ``driver_handles_share_servers = False`` extra specification. + +#. You must not specify the ``share network`` because no share servers are + created. In this mode the Shared File Systems service expects that + administrator has some bare metal storage with some net interface. + +#. The :command:`manila create` command creates a share. This command does the + following things: + + * The :ref:`manila-scheduler ` service will + find the back end with ``driver_handles_share_servers = False`` mode due + to filtering the extra specifications of the share type. + + * The share is created using the storage that is specified in the found + back end. + +#. After the share becomes available, use the :command:`manila show` command + to get the share export locations. + +In the example to create a share, the created already share type named +``my_type`` with ``driver_handles_share_servers = False`` extra specification +is used. + +Check share types that exist, run: + +.. code-block:: console + + $ manila type-list + +------+---------+------------+------------+--------------------------------------+-------------------------+ + | ID | Name | visibility | is_default | required_extra_specs | optional_extra_specs | + +------+---------+------------+------------+--------------------------------------+-------------------------+ + | %ID% | my_type | public | - | driver_handles_share_servers : False | snapshot_support : True | + +------+---------+------------+------------+--------------------------------------+-------------------------+ + +Create a private share with ``my_type`` share type, NFS shared file system +protocol, and size 1 GB: + +.. code-block:: console + + $ manila create nfs 1 --name Share1 --description "My share" --share-type my_type + +-----------------------------+--------------------------------------+ + | Property | Value | + +-----------------------------+--------------------------------------+ + | status | creating | + | share_type_name | my_type | + | description | My share | + | availability_zone | None | + | share_network_id | None | + | share_server_id | None | + | host | | + | access_rules_status | active | + | snapshot_id | None | + | is_public | False | + | task_state | None | + | snapshot_support | True | + | id | 10f5a2a1-36f5-45aa-a8e6-00e94e592e88 | + | size | 1 | + | name | Share1 | + | share_type | 14ee8575-aac2-44af-8392-d9c9d344f392 | + | has_replicas | False | + | replication_type | None | + | created_at | 2016-03-25T12:02:46.000000 | + | share_proto | NFS | + | consistency_group_id | None | + | source_cgsnapshot_member_id | None | + | project_id | 907004508ef4447397ce6741a8f037c1 | + | metadata | {} | + +-----------------------------+--------------------------------------+ + +New share ``Share2`` should have a status ``available``: + +.. code-block:: console + + $ manila show Share2 + +-----------------------------+----------------------------------------------------------+ + | Property | Value | + +-----------------------------+----------------------------------------------------------+ + | status | available | + | share_type_name | my_type | + | description | My share | + | availability_zone | nova | + | share_network_id | None | + | export_locations | | + | | path = 10.0.0.4:/shares/manila_share_a5fb1ab7_... | + | | preferred = False | + | | is_admin_only = False | + | | id = 9e078eee-bcad-40b8-b4fe-1c916cf98ed1 | + | | share_instance_id = a5fb1ab7-0bbd-465b-ac14-05706294b6e9 | + | | path = 172.18.198.52:/shares/manila_share_a5fb1ab7_... | + | | preferred = False | + | | is_admin_only = True | + | | id = 44933f59-e0e3-4483-bb88-72ba7c486f41 | + | | share_instance_id = a5fb1ab7-0bbd-465b-ac14-05706294b6e9 | + | share_server_id | None | + | host | manila@paris#epsilon | + | access_rules_status | active | + | snapshot_id | None | + | is_public | False | + | task_state | None | + | snapshot_support | True | + | id | 10f5a2a1-36f5-45aa-a8e6-00e94e592e88 | + | size | 1 | + | name | Share1 | + | share_type | 14ee8575-aac2-44af-8392-d9c9d344f392 | + | has_replicas | False | + | replication_type | None | + | created_at | 2016-03-25T12:02:46.000000 | + | share_proto | NFS | + | consistency_group_id | None | + | source_cgsnapshot_member_id | None | + | project_id | 907004508ef4447397ce6741a8f037c1 | + | metadata | {} | + +-----------------------------+----------------------------------------------------------+ + +.. _create_share_in_share_server_mode: + +Create a share in share servers mode +------------------------------------ + +To create a file share in share servers mode, you need to: + +#. To create a share, use :command:`manila create` command and + specify the required arguments: the size of the share and the shared file + system protocol. ``NFS``, ``CIFS``, ``GlusterFS``, ``HDFS``, or + ``CephFS`` share file system protocols are supported. + +#. You should specify the :ref:`share type ` + with ``driver_handles_share_servers = True`` extra specification. + +#. You should specify the + :ref:`share network `. + +#. The :command:`manila create` command creates a share. This command does the + following things: + + * The :ref:`manila-scheduler ` service will + find the back end with ``driver_handles_share_servers = True`` mode due to + filtering the extra specifications of the share type. + + * The share driver will create a share server with the share network. For + details of creating the resources, see the `documentation `_ of the + specific share driver. + +#. After the share becomes available, use the :command:`manila show` command + to get the share export location. + +In the example to create a share, the default share type and the already +existing share network are used. + +.. note:: + + There is no default share type just after you started manila as the + administrator. See :ref:`shared_file_systems_share_types` to + create the default share type. To create a share network, use + :ref:`shared_file_systems_share_networks`. + +Check share types that exist, run: + +.. code-block:: console + + $ manila type-list + +------+---------+------------+------------+--------------------------------------+-------------------------+ + | ID | Name | visibility | is_default | required_extra_specs | optional_extra_specs | + +------+---------+------------+------------+--------------------------------------+-------------------------+ + | %id% | default | public | YES | driver_handles_share_servers : True | snapshot_support : True | + +------+---------+------------+------------+--------------------------------------+-------------------------+ + +Check share networks that exist, run: + +.. code-block:: console + + $ manila share-network-list + +--------------------------------------+--------------+ + | id | name | + +--------------------------------------+--------------+ + | c895fe26-92be-4152-9e6c-f2ad230efb13 | my_share_net | + +--------------------------------------+--------------+ + +Create a public share with ``my_share_net`` network, ``default`` +share type, NFS shared file system protocol, and size 1 GB: + +.. code-block:: console + + $ manila create nfs 1 \ + --name "Share2" \ + --description "My second share" \ + --share-type default \ + --share-network my_share_net \ + --metadata aim=testing \ + --public + +-----------------------------+--------------------------------------+ + | Property | Value | + +-----------------------------+--------------------------------------+ + | status | creating | + | share_type_name | default | + | description | My second share | + | availability_zone | None | + | share_network_id | c895fe26-92be-4152-9e6c-f2ad230efb13 | + | share_server_id | None | + | host | | + | access_rules_status | active | + | snapshot_id | None | + | is_public | True | + | task_state | None | + | snapshot_support | True | + | id | 195e3ba2-9342-446a-bc93-a584551de0ac | + | size | 1 | + | name | Share2 | + | share_type | bf6ada49-990a-47c3-88bc-c0cb31d5c9bf | + | has_replicas | False | + | replication_type | None | + | created_at | 2016-03-25T12:13:40.000000 | + | share_proto | NFS | + | consistency_group_id | None | + | source_cgsnapshot_member_id | None | + | project_id | 907004508ef4447397ce6741a8f037c1 | + | metadata | {u'aim': u'testing'} | + +-----------------------------+--------------------------------------+ + +The share also can be created from a share snapshot. For details, see +:ref:`shared_file_systems_snapshots`. + +See the share in a share list: + +.. code-block:: console + + $ manila list + +--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+ + | ID | Name | Size | Share Proto | Status | Is Public | Share Type Name | Host | Availability Zone | + +--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+ + | 10f5a2a1-36f5-45aa-a8e6-00e94e592e88 | Share1 | 1 | NFS | available | False | my_type | manila@paris#epsilon | nova | + | 195e3ba2-9342-446a-bc93-a584551de0ac | Share2 | 1 | NFS | available | True | default | manila@london#LONDON | nova | + +--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+ + +Check the share status and see the share export locations. After ``creating`` +status share should have status ``available``: + +.. code-block:: console + + $ manila show Share2 + +----------------------+----------------------------------------------------------------------+ + | Property | Value | + +----------------------+----------------------------------------------------------------------+ + | status | available | + | share_type_name | default | + | description | My second share | + | availability_zone | nova | + | share_network_id | c895fe26-92be-4152-9e6c-f2ad230efb13 | + | export_locations | | + | | path = 10.254.0.3:/shares/share-fe874928-39a2-441b-8d24-29e6f0fde965 | + | | preferred = False | + | | is_admin_only = False | + | | id = de6d4012-6158-46f0-8b28-4167baca51a7 | + | | share_instance_id = fe874928-39a2-441b-8d24-29e6f0fde965 | + | | path = 10.0.0.3:/shares/share-fe874928-39a2-441b-8d24-29e6f0fde965 | + | | preferred = False | + | | is_admin_only = True | + | | id = 602d0f5c-921b-4e45-bfdb-5eec8a89165a | + | | share_instance_id = fe874928-39a2-441b-8d24-29e6f0fde965 | + | share_server_id | 2e9d2d02-883f-47b5-bb98-e053b8d1e683 | + | host | manila@london#LONDON | + | access_rules_status | active | + | snapshot_id | None | + | is_public | True | + | task_state | None | + | snapshot_support | True | + | id | 195e3ba2-9342-446a-bc93-a584551de0ac | + | size | 1 | + | name | Share2 | + | share_type | bf6ada49-990a-47c3-88bc-c0cb31d5c9bf | + | has_replicas | False | + | replication_type | None | + | created_at | 2016-03-25T12:13:40.000000 | + | share_proto | NFS | + | consistency_group_id | None | + | project_id | 907004508ef4447397ce6741a8f037c1 | + | metadata | {u'aim': u'testing'} | + +----------------------+----------------------------------------------------------------------+ + +``is_public`` defines the level of visibility for the share: whether other +projects can or cannot see the share. By default, the share is private. + +Update share +------------ + +Update the name, or description, or level of visibility for all projects for +the share if you need: + +.. code-block:: console + + $ manila update Share2 --description "My second share. Updated" --is-public False + + $ manila show Share2 + +----------------------+----------------------------------------------------------------------+ + | Property | Value | + +----------------------+----------------------------------------------------------------------+ + | status | available | + | share_type_name | default | + | description | My second share. Updated | + | availability_zone | nova | + | share_network_id | c895fe26-92be-4152-9e6c-f2ad230efb13 | + | export_locations | | + | | path = 10.254.0.3:/shares/share-fe874928-39a2-441b-8d24-29e6f0fde965 | + | | preferred = False | + | | is_admin_only = False | + | | id = de6d4012-6158-46f0-8b28-4167baca51a7 | + | | share_instance_id = fe874928-39a2-441b-8d24-29e6f0fde965 | + | | path = 10.0.0.3:/shares/share-fe874928-39a2-441b-8d24-29e6f0fde965 | + | | preferred = False | + | | is_admin_only = True | + | | id = 602d0f5c-921b-4e45-bfdb-5eec8a89165a | + | | share_instance_id = fe874928-39a2-441b-8d24-29e6f0fde965 | + | share_server_id | 2e9d2d02-883f-47b5-bb98-e053b8d1e683 | + | host | manila@london#LONDON | + | access_rules_status | active | + | snapshot_id | None | + | is_public | False | + | task_state | None | + | snapshot_support | True | + | id | 195e3ba2-9342-446a-bc93-a584551de0ac | + | size | 1 | + | name | Share2 | + | share_type | bf6ada49-990a-47c3-88bc-c0cb31d5c9bf | + | has_replicas | False | + | replication_type | None | + | created_at | 2016-03-25T12:13:40.000000 | + | share_proto | NFS | + | consistency_group_id | None | + | project_id | 907004508ef4447397ce6741a8f037c1 | + | metadata | {u'aim': u'testing'} | + +----------------------+----------------------------------------------------------------------+ + +A share can have one of these status values: + ++-----------------------------------+-----------------------------------------+ +| Status | Description | ++===================================+=========================================+ +| creating | The share is being created. | ++-----------------------------------+-----------------------------------------+ +| deleting | The share is being deleted. | ++-----------------------------------+-----------------------------------------+ +| error | An error occurred during share creation.| ++-----------------------------------+-----------------------------------------+ +| error_deleting | An error occurred during share deletion.| ++-----------------------------------+-----------------------------------------+ +| available | The share is ready to use. | ++-----------------------------------+-----------------------------------------+ +| manage_starting | Share manage started. | ++-----------------------------------+-----------------------------------------+ +| manage_error | Share manage failed. | ++-----------------------------------+-----------------------------------------+ +| unmanage_starting | Share unmanage started. | ++-----------------------------------+-----------------------------------------+ +| unmanage_error | Share cannot be unmanaged. | ++-----------------------------------+-----------------------------------------+ +| unmanaged | Share was unmanaged. | ++-----------------------------------+-----------------------------------------+ +| extending | The extend, or increase, share size | +| | request was issued successfully. | ++-----------------------------------+-----------------------------------------+ +| extending_error | Extend share failed. | ++-----------------------------------+-----------------------------------------+ +| shrinking | Share is being shrunk. | ++-----------------------------------+-----------------------------------------+ +| shrinking_error | Failed to update quota on share | +| | shrinking. | ++-----------------------------------+-----------------------------------------+ +| shrinking_possible_data_loss_error| Shrink share failed due to possible data| +| | loss. | ++-----------------------------------+-----------------------------------------+ +| migrating | Share migration is in progress. | ++-----------------------------------+-----------------------------------------+ + +.. _share_metadata: + +Share metadata +-------------- + +If you want to set the metadata key-value pairs on the share, run: + +.. code-block:: console + + $ manila metadata Share2 set project=my_abc deadline=01/20/16 + +Get all metadata key-value pairs of the share: + +.. code-block:: console + + $ manila metadata-show Share2 + +----------+----------+ + | Property | Value | + +----------+----------+ + | aim | testing | + | project | my_abc | + | deadline | 01/20/16 | + +----------+----------+ + +You can update the metadata: + +.. code-block:: console + + $ manila metadata-update-all Share2 deadline=01/30/16 + +----------+----------+ + | Property | Value | + +----------+----------+ + | deadline | 01/30/16 | + +----------+----------+ + +You also can unset the metadata using +**manila metadata unset **. + +Reset share state +----------------- + +As administrator, you can reset the state of a share. + +Use **manila reset-state [--state ] ** command to reset share +state, where ``state`` indicates which state to assign the share. Options +include ``available``, ``error``, ``creating``, ``deleting``, +``error_deleting`` states. + +.. code-block:: console + + $ manila reset-state Share2 --state deleting + + $ manila show Share2 + +----------------------+----------------------------------------------------------------------+ + | Property | Value | + +----------------------+----------------------------------------------------------------------+ + | status | deleting | + | share_type_name | default | + | description | My second share. Updated | + | availability_zone | nova | + | share_network_id | c895fe26-92be-4152-9e6c-f2ad230efb13 | + | export_locations | | + | | path = 10.254.0.3:/shares/share-fe874928-39a2-441b-8d24-29e6f0fde965 | + | | preferred = False | + | | is_admin_only = False | + | | id = de6d4012-6158-46f0-8b28-4167baca51a7 | + | | share_instance_id = fe874928-39a2-441b-8d24-29e6f0fde965 | + | | path = 10.0.0.3:/shares/share-fe874928-39a2-441b-8d24-29e6f0fde965 | + | | preferred = False | + | | is_admin_only = True | + | | id = 602d0f5c-921b-4e45-bfdb-5eec8a89165a | + | | share_instance_id = fe874928-39a2-441b-8d24-29e6f0fde965 | + | share_server_id | 2e9d2d02-883f-47b5-bb98-e053b8d1e683 | + | host | manila@london#LONDON | + | access_rules_status | active | + | snapshot_id | None | + | is_public | False | + | task_state | None | + | snapshot_support | True | + | id | 195e3ba2-9342-446a-bc93-a584551de0ac | + | size | 1 | + | name | Share2 | + | share_type | bf6ada49-990a-47c3-88bc-c0cb31d5c9bf | + | has_replicas | False | + | replication_type | None | + | created_at | 2016-03-25T12:13:40.000000 | + | share_proto | NFS | + | consistency_group_id | None | + | project_id | 907004508ef4447397ce6741a8f037c1 | + | metadata | {u'deadline': u'01/30/16'} | + +----------------------+----------------------------------------------------------------------+ + +Delete and force-delete share +----------------------------- + +You also can force-delete a share. +The shares cannot be deleted in transitional states. The transitional +states are ``creating``, ``deleting``, ``managing``, ``unmanaging``, +``migrating``, ``extending``, and ``shrinking`` statuses for the shares. +Force-deletion deletes an object in any state. Use the ``policy.json`` file +to grant permissions for this action to other roles. + +.. tip:: + + The configuration file ``policy.json`` may be used from different places. + The path ``/etc/manila/policy.json`` is one of expected paths by default. + +Use **manila delete ** command to delete a specified share: + +.. code-block:: console + + $ manila delete %share_name_or_id% + +.. code-block:: console + + $ manila delete %share_name_or_id% --consistency-group %consistency-group-id% + + +If you try to delete the share in one of the transitional +state using soft-deletion you'll get an error: + +.. code-block:: console + + $ manila delete Share2 + Delete for share 195e3ba2-9342-446a-bc93-a584551de0ac failed: Invalid share: Share status must be one of ('available', 'error', 'inactive'). (HTTP 403) (Request-ID: req-9a77b9a0-17d2-4d97-8a7a-b7e23c27f1fe) + ERROR: Unable to delete any of the specified shares. + +A share cannot be deleted in a transitional status, that it why an error from +``python-manilaclient`` appeared. + +Print the list of all shares for all projects: + +.. code-block:: console + + $ manila list --all-tenants + +--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+ + | ID | Name | Size | Share Proto | Status | Is Public | Share Type Name | Host | Availability Zone | + +--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+ + | 10f5a2a1-36f5-45aa-a8e6-00e94e592e88 | Share1 | 1 | NFS | available | False | my_type | manila@paris#epsilon | nova | + | 195e3ba2-9342-446a-bc93-a584551de0ac | Share2 | 1 | NFS | available | False | default | manila@london#LONDON | nova | + +--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+ + +Force-delete Share2 and check that it is absent in the list of shares, +run: + +.. code-block:: console + + $ manila force-delete Share2 + + $ manila list + +--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+ + | ID | Name | Size | Share Proto | Status | Is Public | Share Type Name | Host | Availability Zone | + +--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+ + | 10f5a2a1-36f5-45aa-a8e6-00e94e592e88 | Share1 | 1 | NFS | available | False | my_type | manila@paris#epsilon | nova | + +--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+ + +.. _access_to_share: + +Manage access to share +---------------------- + +The Shared File Systems service allows to grant or deny access to a specified +share, and list the permissions for a specified share. + +To grant or deny access to a share, specify one of these supported share +access levels: + +- **rw**. Read and write (RW) access. This is the default value. + +- **ro**. Read-only (RO) access. + +You must also specify one of these supported authentication methods: + +- **ip**. Authenticates an instance through its IP address. A valid + format is ``XX.XX.XX.XX`` or ``XX.XX.XX.XX/XX``. For example ``0.0.0.0/0``. + +- **user**. Authenticates by a specified user or group name. A valid value is + an alphanumeric string that can contain some special characters and is from + 4 to 32 characters long. + +- **cert**. Authenticates an instance through a TLS certificate. Specify the + TLS identity as the IDENTKEY. A valid value is any string up to 64 characters + long in the common name (CN) of the certificate. The meaning of a string + depends on its interpretation. + +- **cephx**. Ceph authentication system. Specify the Ceph auth ID that needs + to be authenticated and authorized for share access by the Ceph back end. A + valid value must be non-empty, consist of ASCII printable characters, and not + contain periods. + +Try to mount NFS share with export path +``10.0.0.4:/shares/manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9`` on the +node with IP address ``10.0.0.13``: + +.. code-block:: console + + $ sudo mount -v -t nfs 10.0.0.4:/shares/manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9 /mnt/ + mount.nfs: timeout set for Tue Oct 6 10:37:23 2015 + mount.nfs: trying text-based options 'vers=4,addr=10.0.0.4,clientaddr=10.0.0.13' + mount.nfs: mount(2): Permission denied + mount.nfs: access denied by server while mounting 10.0.0.4:/shares/manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9 + +An error message "Permission denied" appeared, so you are not allowed to mount +a share without an access rule. Allow access to the share with ``ip`` access +type and ``10.0.0.13`` IP address: + +.. code-block:: console + + $ manila access-allow Share1 ip 10.0.0.13 --access-level rw + +--------------+--------------------------------------+ + | Property | Value | + +--------------+--------------------------------------+ + | share_id | 10f5a2a1-36f5-45aa-a8e6-00e94e592e88 | + | access_type | ip | + | access_to | 10.0.0.13 | + | access_level | rw | + | state | new | + | id | de715226-da00-4cfc-b1ab-c11f3393745e | + +--------------+--------------------------------------+ + +Try to mount a share again. This time it is mounted successfully: + +.. code-block:: console + + $ sudo mount -v -t nfs 10.0.0.4:/shares/manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9 /mnt/ + +Since it is allowed node on 10.0.0.13 read and write access, try to create +a file on a mounted share: + +.. code-block:: console + + $ cd /mnt + $ ls + lost+found + $ touch my_file.txt + +Connect via SSH to the ``10.0.0.4`` node and check new file `my_file.txt` +in the ``/shares/manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9`` directory: + +.. code-block:: console + + $ ssh 10.0.0.4 + $ cd /shares + $ ls + manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9 + $ cd manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9 + $ ls + lost+found my_file.txt + +You have successfully created a file from instance that was given access by +its IP address. + +Allow access to the share with ``user`` access type: + +.. code-block:: console + + $ manila access-allow Share1 user demo --access-level rw + +--------------+--------------------------------------+ + | Property | Value | + +--------------+--------------------------------------+ + | share_id | 10f5a2a1-36f5-45aa-a8e6-00e94e592e88 | + | access_type | user | + | access_to | demo | + | access_level | rw | + | state | new | + | id | 4f391c6b-fb4f-47f5-8b4b-88c5ec9d568a | + +--------------+--------------------------------------+ + +.. note:: + + Different share features are supported by different share drivers. + For the example, the Generic driver with the Block Storage service as a + back-end doesn't support ``user`` and ``cert`` authentications methods. For + details of supporting of features by different drivers, see `Manila share + features support mapping `_. + +To verify that the access rules (ACL) were configured correctly for a share, +you list permissions for a share: + +.. code-block:: console + + $ manila access-list Share1 + +--------------------------------------+-------------+------------+--------------+--------+ + | id | access type | access to | access level | state | + +--------------------------------------+-------------+------------+--------------+--------+ + | 4f391c6b-fb4f-47f5-8b4b-88c5ec9d568a | user | demo | rw | error | + | de715226-da00-4cfc-b1ab-c11f3393745e | ip | 10.0.0.13 | rw | active | + +--------------------------------------+-------------+------------+--------------+--------+ + +Deny access to the share and check that deleted access rule is absent in the +access rule list: + +.. code-block:: console + + $ manila access-deny Share1 de715226-da00-4cfc-b1ab-c11f3393745e + + $ manila access-list Share1 + +--------------------------------------+-------------+-----------+--------------+-------+ + | id | access type | access to | access level | state | + +--------------------------------------+-------------+-----------+--------------+-------+ + | 4f391c6b-fb4f-47f5-8b4b-88c5ec9d568a | user | demo | rw | error | + +--------------------------------------+-------------+-----------+--------------+-------+ diff --git a/doc/source/admin/shared-file-systems-intro.rst b/doc/source/admin/shared-file-systems-intro.rst new file mode 100644 index 0000000000..814a3dfd43 --- /dev/null +++ b/doc/source/admin/shared-file-systems-intro.rst @@ -0,0 +1,57 @@ +.. _shared_file_systems_intro: + +=========== +Admin Guide +=========== + +Shared File Systems service provides a set of services for management of +shared file systems in a multi-project cloud environment. The service resembles +OpenStack block-based storage management from the OpenStack Block Storage +service project. With the Shared File Systems service, you can +create a remote file system, mount the file system on your instances, and then +read and write data from your instances to and from your file system. + +The Shared File Systems service serves same purpose as the Amazon Elastic File +System (EFS) does. + +The Shared File Systems service can run in a single-node or multiple +node configuration. The Shared File Systems service can be configured +to provision shares from one or more back ends, so it is required to +declare at least one back end. Shared File System service contains +several configurable components. + +It is important to understand these components: + +* Share networks +* Shares +* Multi-tenancy +* Back ends + +The Shared File Systems service consists of four types of services, +most of which are similar to those of the Block Storage service: + +- ``manila-api`` +- ``manila-data`` +- ``manila-scheduler`` +- ``manila-share`` + +Installation of first three - ``manila-api``, ``manila-data``, and +``manila-scheduler`` is common for almost all deployments. But configuration +of ``manila-share`` is backend-specific and can differ from deployment to +deployment. + +.. toctree:: + :maxdepth: 1 + + shared-file-systems-key-concepts.rst + shared-file-systems-share-management.rst + shared-file-systems-share-migration.rst + shared-file-systems-share-types.rst + shared-file-systems-snapshots.rst + shared-file-systems-security-services.rst + shared-file-systems-share-replication.rst + shared-file-systems-multi-backend.rst + shared-file-systems-networking.rst + shared-file-systems-troubleshoot.rst + + diff --git a/doc/source/admin/shared-file-systems-key-concepts.rst b/doc/source/admin/shared-file-systems-key-concepts.rst new file mode 100644 index 0000000000..9c58f7dea2 --- /dev/null +++ b/doc/source/admin/shared-file-systems-key-concepts.rst @@ -0,0 +1,119 @@ +.. _shared_file_systems_key_concepts: + +============ +Key concepts +============ + +Share +~~~~~ + +In the Shared File Systems service ``share`` is the fundamental resource unit +allocated by the Shared File System service. It represents an allocation of a +persistent, readable, and writable filesystems. Compute instances access these +filesystems. Depending on the deployment configuration, clients outside of +OpenStack can also access the filesystem. + +.. note:: + + A ``share`` is an abstract storage object that may or may not directly + map to a "share" concept from the underlying storage provider. + See the description of ``share instance`` for more details. + +Share instance +~~~~~~~~~~~~~~ +This concept is tied with ``share`` and represents created resource on specific +back end, when ``share`` represents abstraction between end user and +back-end storages. In common cases, it is one-to-one relation. +One single ``share`` has more than one ``share instance`` in two cases: + +- When ``share migration`` is being applied + +- When ``share replication`` is enabled + +Therefore, each ``share instance`` stores information specific to real +allocated resource on storage. And ``share`` represents the information +that is common for ``share instances``. +A user with ``member`` role will not be able to work with it directly. Only +a user with ``admin`` role has rights to perform actions against specific +share instances. + +Snapshot +~~~~~~~~ + +A ``snapshot`` is a point-in-time, read-only copy of a ``share``. You can +create ``Snapshots`` from an existing, operational ``share`` regardless +of whether a client has mounted the file system. A ``snapshot`` +can serve as the content source for a new ``share``. Specify the +**Create from snapshot** option when creating a new ``share`` on the +dashboard. + +Storage Pools +~~~~~~~~~~~~~ + +With the Kilo release of OpenStack, Shared File Systems can use +``storage pools``. The storage may present one or more logical storage +resource pools that the Shared File Systems service +will select as a storage location when provisioning ``shares``. + +Share Type +~~~~~~~~~~ + +``Share type`` is an abstract collection of criteria used to characterize +``shares``. They are most commonly used to create a hierarchy of functional +capabilities. This hierarchy represents tiered storage services levels. For +example, an administrator might define a premium ``share type`` that +indicates a greater level of performance than a basic ``share type``. +Premium represents the best performance level. + + +Share Access Rules +~~~~~~~~~~~~~~~~~~ + +``Share access rules`` define which users can access a particular ``share``. +For example, administrators can declare rules for NFS shares by +listing the valid IP networks which will access the ``share``. List the +IP networks in CIDR notation. + +Security Services +~~~~~~~~~~~~~~~~~ + +``Security services``allow granular client access rules for +administrators. They can declare rules for authentication or +authorization to access ``share`` content. External services including LDAP, +Active Directory, and Kerberos can be declared as resources. Examine and +consult these resources when making an access decision for a +particular ``share``. You can associate ``Shares`` with multiple +security services, but only one service per one type. + +Share Networks +~~~~~~~~~~~~~~ + +A ``share network`` is an object that defines a relationship between a +project network and subnet, as defined in an OpenStack Networking service or +Compute service. The ``share network`` is also defined in ``shares`` +created by the same project. A project may find it desirable to +provision ``shares`` such that only instances connected to a particular +OpenStack-defined network have access to the ``share``. Also, +``security services`` can be attached to ``share networks``, +because most of auth protocols require some interaction with network services. + +The Shared File Systems service has the ability to work outside of OpenStack. +That is due to the ``StandaloneNetworkPlugin``. The plugin is compatible with +any network platform, and does not require specific network services in +OpenStack like Compute or Networking service. You can set the network +parameters in the ``manila.conf`` file. + +Share Servers +~~~~~~~~~~~~~ + +A ``share server`` is a logical entity that hosts the shares created +on a specific ``share network``. A ``share server`` may be a +configuration object within the storage controller, or it may represent +logical resources provisioned within an OpenStack deployment used to +support the data path used to access ``shares``. + +``Share servers`` interact with network services to determine the appropriate +IP addresses on which to export ``shares`` according to the related ``share +network``. The Shared File Systems service has a pluggable network model that +allows ``share servers`` to work with different implementations of +the Networking service. diff --git a/doc/source/admin/shared-file-systems-manage-and-unmanage-share.rst b/doc/source/admin/shared-file-systems-manage-and-unmanage-share.rst new file mode 100644 index 0000000000..a278573d2d --- /dev/null +++ b/doc/source/admin/shared-file-systems-manage-and-unmanage-share.rst @@ -0,0 +1,162 @@ +.. _shared_file_systems_manage_and_unmanage_share: + +========================= +Manage and unmanage share +========================= + +To ``manage`` a share means that an administrator, rather than a share +driver, manages the storage lifecycle. This approach is appropriate when an +administrator already has the custom non-manila share with its size, shared +file system protocol, and export path, and an administrator wants to +register it in the Shared File System service. + +To ``unmanage`` a share means to unregister a specified share from the Shared +File Systems service. Administrators can revert an unmanaged share to managed +status if needed. + +.. _unmanage_share: + +Unmanage a share +---------------- + +The ``unmanage`` operation is not supported for shares that were +created on top of share servers and created with share networks. +The Share service should have the +option ``driver_handles_share_servers = False`` +set in the ``manila.conf`` file. You can unmanage a share that has +no dependent snapshots. + +To unmanage managed share, run the :command:`manila unmanage ` +command. Then try to print the information about the share. The +returned result should indicate that Shared File Systems service won't +find the share: + +.. code-block:: console + + $ manila unmanage share_for_docs + $ manila show share_for_docs + ERROR: No share with a name or ID of 'share_for_docs' exists. + +.. _manage_share: + +Manage a share +-------------- +To register the non-managed share in the File System service, run the +:command:`manila manage` command: + +.. code-block:: console + + manila manage [--name ] [--description ] + [--share_type ] + [--driver_options [ [ ...]]] + + +The positional arguments are: + +- service_host. The manage-share service host in + ``host@backend#POOL`` format, which consists of the host name for + the back end, the name of the back end, and the pool name for the + back end. + +- protocol. The Shared File Systems protocol of the share to manage. Valid + values are NFS, CIFS, GlusterFS, or HDFS. + +- export_path. The share export path in the format appropriate for the + protocol: + + - NFS protocol. 10.0.0.1:/foo_path. + + - CIFS protocol. \\\\10.0.0.1\\foo_name_of_cifs_share. + + - HDFS protocol. hdfs://10.0.0.1:foo_port/foo_share_name. + + - GlusterFS. 10.0.0.1:/foo_volume. + +The ``driver_options`` is an optional set of one or more key and value pairs +that describe driver options. Note that the share type must have the +``driver_handles_share_servers = False`` option. As a result, a special share +type named ``for_managing`` was used in example. + +To manage share, run: + +.. code-block:: console + + $ manila manage \ + manila@paris#shares \ + nfs \ + 1.0.0.4:/shares/manila_share_6d2142d8_2b9b_4405_867f_8a48094c893f \ + --name share_for_docs \ + --description "We manage share." \ + --share_type for_managing + +-----------------------------+--------------------------------------+ + | Property | Value | + +-----------------------------+--------------------------------------+ + | status | manage_starting | + | share_type_name | for_managing | + | description | We manage share. | + | availability_zone | None | + | share_network_id | None | + | share_server_id | None | + | host | manila@paris#shares | + | access_rules_status | active | + | snapshot_id | None | + | is_public | False | + | task_state | None | + | snapshot_support | True | + | id | ddfb1240-ed5e-4071-a031-b842035a834a | + | size | None | + | name | share_for_docs | + | share_type | 14ee8575-aac2-44af-8392-d9c9d344f392 | + | has_replicas | False | + | replication_type | None | + | created_at | 2016-03-25T15:22:43.000000 | + | share_proto | NFS | + | consistency_group_id | None | + | source_cgsnapshot_member_id | None | + | project_id | 907004508ef4447397ce6741a8f037c1 | + | metadata | {} | + +-----------------------------+--------------------------------------+ + +Check that the share is available: + +.. code-block:: console + + $ manila show share_for_docs + +----------------------+--------------------------------------------------------------------------+ + | Property | Value | + +----------------------+--------------------------------------------------------------------------+ + | status | available | + | share_type_name | for_managing | + | description | We manage share. | + | availability_zone | None | + | share_network_id | None | + | export_locations | | + | | path = 1.0.0.4:/shares/manila_share_6d2142d8_2b9b_4405_867f_8a48094c893f | + | | preferred = False | + | | is_admin_only = False | + | | id = d4d048bf-4159-4a94-8027-e567192b8d30 | + | | share_instance_id = 4c8e3887-4f9a-4775-bab4-e5840a09c34e | + | | path = 2.0.0.3:/shares/manila_share_6d2142d8_2b9b_4405_867f_8a48094c893f | + | | preferred = False | + | | is_admin_only = True | + | | id = 1dd4f0a3-778d-486a-a851-b522f6e7cf5f | + | | share_instance_id = 4c8e3887-4f9a-4775-bab4-e5840a09c34e | + | share_server_id | None | + | host | manila@paris#shares | + | access_rules_status | active | + | snapshot_id | None | + | is_public | False | + | task_state | None | + | snapshot_support | True | + | id | ddfb1240-ed5e-4071-a031-b842035a834a | + | size | 1 | + | name | share_for_docs | + | share_type | 14ee8575-aac2-44af-8392-d9c9d344f392 | + | has_replicas | False | + | replication_type | None | + | created_at | 2016-03-25T15:22:43.000000 | + | share_proto | NFS | + | consistency_group_id | None | + | project_id | 907004508ef4447397ce6741a8f037c1 | + | metadata | {} | + +----------------------+--------------------------------------------------------------------------+ diff --git a/doc/source/admin/shared-file-systems-manage-and-unmanage-snapshot.rst b/doc/source/admin/shared-file-systems-manage-and-unmanage-snapshot.rst new file mode 100644 index 0000000000..1ac7e693a4 --- /dev/null +++ b/doc/source/admin/shared-file-systems-manage-and-unmanage-snapshot.rst @@ -0,0 +1,107 @@ +.. _shared_file_systems_manage_and_unmanage_snapshot: + +================================== +Manage and unmanage share snapshot +================================== + +To ``manage`` a share snapshot means that an administrator, rather than a +share driver, manages the storage lifecycle. This approach is appropriate +when an administrator manages share snapshots outside of the Shared File +Systems service and wants to register it with the service. + +To ``unmanage`` a share snapshot means to unregister a specified share +snapshot from the Shared File Systems service. Administrators can revert an +unmanaged share snapshot to managed status if needed. + +.. _unmanage_share_snapshot: + +Unmanage a share snapshot +------------------------- + +The ``unmanage`` operation is not supported for shares that were +created on top of share servers and created with share networks. +The Share service should have the option +``driver_handles_share_servers = False`` set in the ``manila.conf`` file. + +To unmanage managed share snapshot, run the +:command:`manila snapshot-unmanage ` +command. Then try to print the +information about the share snapshot. The returned result should indicate that +Shared File Systems service won't find the share snapshot: + +.. code-block:: console + + $ manila snapshot-unmanage my_test_share_snapshot + $ manila snapshot-show my_test_share_snapshot + ERROR: No sharesnapshot with a name or ID of 'my_test_share_snapshot' + exists. + +.. _manage_share_snapshot: + +Manage a share snapshot +----------------------- +To register the non-managed share snapshot in the File System service, run the +:command:`manila snapshot-manage` command: + +.. code-block:: console + + manila snapshot-manage [--name ] [--description ] + [--driver_options [ [ ...]]] + + +The positional arguments are: + +- share. Name or ID of the share. + +- provider_location. Provider location of the share snapshot on the backend. + +The ``driver_options`` is an optional set of one or more key and value pairs +that describe driver options. + +To manage share snapshot, run: + +.. code-block:: console + + $ manila snapshot-manage \ + 9ba52cc6-c97e-4b40-8653-4bcbaaf9628d \ + 4d1e2863-33dd-4243-bf39-f7354752097d \ + --name my_test_share_snapshot \ + --description "My test share snapshot" \ + +-------------------+--------------------------------------+ + | Property | Value | + +-------------------+--------------------------------------+ + | status | manage_starting | + | share_id | 9ba52cc6-c97e-4b40-8653-4bcbaaf9628d | + | user_id | d9f4003655c94db5b16c591920be1f91 | + | description | My test share snapshot | + | created_at | 2016-07-25T04:49:42.600980 | + | size | None | + | share_proto | NFS | + | provider_location | 4d1e2863-33dd-4243-bf39-f7354752097d | + | id | 89c663b5-026d-45c7-a43b-56ef0ba0faab | + | project_id | aaa33a0ca4324965a3e65ae47e864e94 | + | share_size | 1 | + | name | my_test_share_snapshot | + +-------------------+--------------------------------------+ + +Check that the share snapshot is available: + +.. code-block:: console + + $ manila snapshot-show my_test_share_snapshot + +-------------------+--------------------------------------+ + | Property | Value | + +-------------------+--------------------------------------+ + | status | available | + | share_id | 9ba52cc6-c97e-4b40-8653-4bcbaaf9628d | + | user_id | d9f4003655c94db5b16c591920be1f91 | + | description | My test share snapshot | + | created_at | 2016-07-25T04:49:42.000000 | + | size | 1 | + | share_proto | NFS | + | provider_location | 4d1e2863-33dd-4243-bf39-f7354752097d | + | id | 89c663b5-026d-45c7-a43b-56ef0ba0faab | + | project_id | aaa33a0ca4324965a3e65ae47e864e94 | + | share_size | 1 | + | name | my_test_share_snapshot | + +-------------------+--------------------------------------+ diff --git a/doc/source/admin/shared-file-systems-multi-backend.rst b/doc/source/admin/shared-file-systems-multi-backend.rst new file mode 100644 index 0000000000..a3988ffec9 --- /dev/null +++ b/doc/source/admin/shared-file-systems-multi-backend.rst @@ -0,0 +1,59 @@ +.. _shared_file_systems_multi_backend: + +=========================== +Multi-storage configuration +=========================== + +The Shared File Systems service can provide access to one or more file storage +back ends. In general, the workflow with multiple back ends looks similar +to the Block Storage service one. + +Using ``manila.conf``, you can spawn multiple share services. To do it, you +should set the `enabled_share_backends` flag in the ``manila.conf`` file. This +flag defines the comma-separated names of the configuration stanzas for the +different back ends. One name is associated to one configuration group for a +back end. + +The following example runs three configured share services: + +.. code-block:: ini + + [DEFAULT] + enabled_share_backends=backendEMC1,backendGeneric1,backendNetApp + + [backendGeneric1] + share_driver=manila.share.drivers.generic.GenericShareDriver + share_backend_name=one_name_for_two_backends + service_instance_user=ubuntu_user + service_instance_password=ubuntu_user_password + service_image_name=ubuntu_image_name + path_to_private_key=/home/foouser/.ssh/id_rsa + path_to_public_key=/home/foouser/.ssh/id_rsa.pub + + [backendEMC1] + share_driver=manila.share.drivers.emc.driver.EMCShareDriver + share_backend_name=backendEMC2 + emc_share_backend=vnx + emc_nas_server=1.1.1.1 + emc_nas_password=password + emc_nas_login=user + emc_nas_server_container=server_3 + emc_nas_pool_name="Pool 2" + + [backendNetApp] + share_driver = manila.share.drivers.netapp.common.NetAppDriver + driver_handles_share_servers = True + share_backend_name=backendNetApp + netapp_login=user + netapp_password=password + netapp_server_hostname=1.1.1.1 + netapp_root_volume_aggregate=aggr01 + +To spawn separate groups of share services, you can use separate configuration +files. If it is necessary to control each back end in a separate way, you +should provide a single configuration file per each back end. + +.. toctree:: + + shared-file-systems-scheduling.rst + shared-file-systems-services-manage.rst diff --git a/doc/source/admin/shared-file-systems-network-plugins.rst b/doc/source/admin/shared-file-systems-network-plugins.rst new file mode 100644 index 0000000000..fa644be7e5 --- /dev/null +++ b/doc/source/admin/shared-file-systems-network-plugins.rst @@ -0,0 +1,88 @@ +.. _shared_file_systems_network_plugins: + +================ +Network plug-ins +================ + +The Shared File Systems service architecture defines an abstraction layer for +network resource provisioning and allowing administrators to choose from a +different options for how network resources are assigned to their projects’ +networked storage. There are a set of network plug-ins that provide a variety +of integration approaches with the network services that are available with +OpenStack. + +What is a network plugin in Manila? +----------------------------------- + +A network plugin is a python class that uses a specific facility (e.g. +Neutron network) to provide network resources to the +:term:`manila-share` service. + +When to use a network plugin? +----------------------------- + +A Manila `share driver` may be configured in one of two modes, where it is +managing the lifecycle of `share servers` on its own or where it is merely +providing storage resources on a pre-configured share server. This mode +is defined using the boolean option `driver_handles_share_servers` in the +Manila configuration file. A network plugin is only useful when a driver is +handling its own share servers. + +.. note:: + + Not all share drivers support both modes. Each driver must report which + mode(s) it supports to the manila-share service. + +When `driver_handles_share_servers` is set to `True`, a share driver will be +called to create share servers for shares using information provided within a +`share network`. This information will be provided to one of the enabled +network plugins that will handle reservation, creation and deletion of +network resources including `IP addresses` and `network interfaces`. + +The Shared File Systems service may need a network resource provisioning if +share service with specified driver works in mode, when a share driver manages +lifecycle of share servers on its own. This behavior is defined by a flag +``driver_handles_share_servers`` in share service configuration. When +``driver_handles_share_servers`` is set to ``True``, a share driver will be +called to create share servers for shares using information provided within a +share network. This information will be provided to one of the enabled network +plug-ins that will handle reservation, creation and deletion of network +resources including IP addresses and network interfaces. + +What network plug-ins are available? +------------------------------------ + +There are two network plug-ins and three python classes in the +Shared File Systems service: + +#. Network plug-in for using the OpenStack Networking service. It allows to use + any network segmentation that the Networking service supports. It is up to + each share driver to support at least one network segmentation type. + + a) ``manila.network.neutron.neutron_network_plugin.NeutronNetworkPlugin``. + This is a default network plug-in. It requires the ``neutron_net_id`` and + the ``neutron_subnet_id`` to be provided when defining the share network + that will be used for the creation of share servers. The user may define + any number of share networks corresponding to the various physical + network segments in a project environment. + + b) ``manila.network.neutron.neutron_network_plugin.NeutronSingleNetworkPlugin``. + This is a simplification of the previous case. It accepts values for + ``neutron_net_id`` and ``neutron_subnet_id`` from the ``manila.conf`` + configuration file and uses one network for all shares. + + When only a single network is needed, the NeutronSingleNetworkPlugin (1.b) + is a simple solution. Otherwise NeutronNetworkPlugin (1.a) should be chosen. + +#. Network plug-in for specifying networks independently from OpenStack + networking services. + + a) ``manila.network.standalone_network_plugin.StandaloneNetworkPlugin``. + This plug-in uses a pre-existing network that is available to the + manila-share host. This network may be handled either by OpenStack or be + created independently by any other means. The plug-in supports any type + of network - flat and segmented. As above, it is completely up to the + share driver to support the network type for which the network plug-in is + configured. + +More information about network plug-ins can be found in `Manila developer documentation `_ diff --git a/doc/source/admin/shared-file-systems-networking.rst b/doc/source/admin/shared-file-systems-networking.rst new file mode 100644 index 0000000000..93309be038 --- /dev/null +++ b/doc/source/admin/shared-file-systems-networking.rst @@ -0,0 +1,17 @@ +.. _shared_file_systems_networking: + +========== +Networking +========== + +Unlike the OpenStack Block Storage service, the Shared File Systems service +must connect to the Networking service. The share service requires the +option to self-manage share servers. For client authentication and +authorization, you can configure the Shared File Systems service to +work with different network authentication services, like LDAP, Kerberos +protocols, or Microsoft Active Directory. + +.. toctree:: + + shared-file-systems-share-networks.rst + shared-file-systems-network-plugins.rst diff --git a/doc/source/admin/shared-file-systems-quotas.rst b/doc/source/admin/shared-file-systems-quotas.rst new file mode 100644 index 0000000000..53403059ab --- /dev/null +++ b/doc/source/admin/shared-file-systems-quotas.rst @@ -0,0 +1,152 @@ +.. _shared_file_systems_quotas: + +================= +Quotas and limits +================= + +Limits +~~~~~~ + +Limits are the resource limitations that are allowed for each project. +An administrator can configure limits in the ``manila.conf`` file. + +Users can query their rate and absolute limits. + +To see the absolute limits, run: + +.. code-block:: console + + $ manila absolute-limits + +----------------------------+-------+ + | Name | Value | + +----------------------------+-------+ + | maxTotalShareGigabytes | 1000 | + | maxTotalShareNetworks | 10 | + | maxTotalShareSnapshots | 50 | + | maxTotalShares | 50 | + | maxTotalSnapshotGigabytes | 1000 | + | totalShareGigabytesUsed | 1 | + | totalShareNetworksUsed | 2 | + | totalShareSnapshotsUsed | 1 | + | totalSharesUsed | 1 | + | totalSnapshotGigabytesUsed | 1 | + +----------------------------+-------+ + +Rate limits control the frequency at which users can issue specific API +requests. Administrators use rate limiting to configure limits on the type and +number of API calls that can be made in a specific time interval. For example, +a rate limit can control the number of ``GET`` requests processed +during a one-minute period. + +To set the API rate limits, modify the +``etc/manila/api-paste.ini`` file, which is a part of the WSGI pipeline and +defines the actual limits. You need to restart ``manila-api`` service after +you edit the ``etc/manila/api-paste.ini`` file. + +.. code-block:: ini + + [filter:ratelimit] + paste.filter_factory = manila.api.v1.limits:RateLimitingMiddleware.factory + limits = (POST, "*/shares", ^/shares, 120, MINUTE);(PUT, "*/shares", .*, 120, MINUTE);(DELETE, "*", .*, 120, MINUTE) + +Also, add the ``ratelimit`` to ``noauth``, ``keystone``, ``keystone_nolimit`` +parameters in the ``[composite:openstack_share_api]`` and +``[composite:openstack_share_api_v2]`` groups. + +.. code-block:: ini + + [composite:openstack_share_api] + use = call:manila.api.middleware.auth:pipeline_factory + noauth = cors faultwrap ssl ratelimit sizelimit noauth api + keystone = cors faultwrap ssl ratelimit sizelimit authtoken keystonecontext api + keystone_nolimit = cors faultwrap ssl ratelimit sizelimit authtoken keystonecontext api + + [composite:openstack_share_api_v2] + use = call:manila.api.middleware.auth:pipeline_factory + noauth = cors faultwrap ssl ratelimit sizelimit noauth apiv2 + keystone = cors faultwrap ssl ratelimit sizelimit authtoken keystonecontext apiv2 + keystone_nolimit = cors faultwrap ssl ratelimit sizelimit authtoken keystonecontext apiv2 + +To see the rate limits, run: + +.. code-block:: console + + $ manila rate-limits + +--------+------------+-------+--------+--------+----------------------+ + | Verb | URI | Value | Remain | Unit | Next_Available | + +--------+------------+-------+--------+--------+----------------------+ + | DELETE | "*" | 120 | 120 | MINUTE | 2015-10-20T15:17:20Z | + | POST | "*/shares" | 120 | 120 | MINUTE | 2015-10-20T15:17:20Z | + | PUT | "*/shares" | 120 | 120 | MINUTE | 2015-10-20T15:17:20Z | + +--------+------------+-------+--------+--------+----------------------+ + +Quotas +~~~~~~ + +Quota sets provide quota management support. + +To list the quotas for a project or user, use the :command:`manila quota-show` +command. If you specify the optional ``--user`` parameter, you get the +quotas for this user in the specified project. If you omit this parameter, +you get the quotas for the specified project. + +.. note:: + + The Shared File Systems service does not perform mapping of usernames and + project names to IDs. Provide only ID values to get correct setup + of quotas. Setting it by names you set quota for nonexistent project/user. + In case quota is not set explicitly by project/user ID, + The Shared File Systems service just applies default quotas. + +.. code-block:: console + + $ manila quota-show --tenant %project_id% --user %user_id% + +--------------------+-------+ + | Property | Value | + +--------------------+-------+ + | gigabytes | 1000 | + | snapshot_gigabytes | 1000 | + | snapshots | 50 | + | shares | 50 | + | share_networks | 10 | + +--------------------+-------+ + +There are default quotas for a project that are set from the +``manila.conf`` file. To list the default quotas for a project, use +the :command:`manila quota-defaults` command: + +.. code-block:: console + + $ manila quota-defaults --tenant %project_id% + +--------------------+-------+ + | Property | Value | + +--------------------+-------+ + | gigabytes | 1000 | + | snapshot_gigabytes | 1000 | + | snapshots | 50 | + | shares | 50 | + | share_networks | 10 | + +--------------------+-------+ + +The administrator can update the quotas for a specific project, or for a +specific user by providing both the ``--tenant`` and ``--user`` optional +arguments. It is possible to update the ``shares``, ``snapshots``, +``gigabytes``, ``snapshot-gigabytes``, and ``share-networks`` quotas. + +.. code-block:: console + + $ manila quota-update %project_id% --user %user_id% --shares 49 --snapshots 49 + +As administrator, you can also permit or deny the force-update of a quota that +is already used, or if the requested value exceeds the configured quota limit. +To force-update a quota, use ``force`` optional key. + +.. code-block:: console + + $ manila quota-update %project_id% --shares 51 --snapshots 51 --force + +To revert quotas to default for a project or for a user, delete quotas: + +.. code-block:: console + + $ manila quota-delete --tenant %project_id% --user %user_id% diff --git a/doc/source/admin/shared-file-systems-scheduling.rst b/doc/source/admin/shared-file-systems-scheduling.rst new file mode 100644 index 0000000000..a970733893 --- /dev/null +++ b/doc/source/admin/shared-file-systems-scheduling.rst @@ -0,0 +1,33 @@ +.. _shared_file_systems_scheduling: + +========== +Scheduling +========== + +The Shared File Systems service uses a scheduler to provide unified +access for a variety of different types of shared file systems. The +scheduler collects information from the active shared services, and +makes decisions such as what shared services will be used to create +a new share. To manage this process, the Shared File Systems service +provides Share types API. + +A share type is a list from key-value pairs called extra-specs. The +scheduler uses required and un-scoped extra-specs to look up +the shared service most suitable for a new share with the specified share type. +For more information about extra-specs and their type, see `Capabilities +and Extra-Specs `_ section in developer documentation. + +The general scheduler workflow: + +#. Share services report information about their existing pool number, their + capacities, and their capabilities. + +#. When a request on share creation arrives, the scheduler picks a service + and pool that best serves the request, using share type + filters and back end capabilities. If back end capabilities pass through, + all filters request the selected back end where the target pool resides. + +#. The share driver receives a reply on the request status, and lets the + target pool serve the request as the scheduler instructs. The scoped + and un-scoped share types are available for the driver implementation + to use as needed. diff --git a/doc/source/admin/shared-file-systems-security-services.rst b/doc/source/admin/shared-file-systems-security-services.rst new file mode 100644 index 0000000000..ce136c512d --- /dev/null +++ b/doc/source/admin/shared-file-systems-security-services.rst @@ -0,0 +1,186 @@ +.. _shared_file_systems_security_services: + +================= +Security services +================= + +A security service stores client configuration information used for +authentication and authorization (AuthN/AuthZ). For example, a share server +will be the client for an existing service such as LDAP, Kerberos, or +Microsoft Active Directory. + +You can associate a share with one to three security service types: + +- ``ldap``: LDAP. + +- ``kerberos``: Kerberos. + +- ``active_directory``: Microsoft Active Directory. + +You can configure a security service with these options: + +- A DNS IP address. + +- An IP address or host name. + +- A domain. + +- A user or group name. + +- The password for the user, if you specify a user name. + +You can add the security service to the +:ref:`share network `. + +To create a security service, specify the security service type, a +description of a security service, DNS IP address used inside project's +network, security service IP address or host name, domain, security +service user or group used by project, and a password for the user. The +share name is optional. + +Create a ``ldap`` security service: + +.. code-block:: console + + $ manila security-service-create ldap --dns-ip 8.8.8.8 --server 10.254.0.3 --name my_ldap_security_service + +-------------+--------------------------------------+ + | Property | Value | + +-------------+--------------------------------------+ + | status | new | + | domain | None | + | password | None | + | name | my_ldap_security_service | + | dns_ip | 8.8.8.8 | + | created_at | 2015-09-25T10:19:06.019527 | + | updated_at | None | + | server | 10.254.0.3 | + | user | None | + | project_id | 20787a7ba11946adad976463b57d8a2f | + | type | ldap | + | id | 413479b2-0d20-4c58-a9d3-b129fa592d8e | + | description | None | + +-------------+--------------------------------------+ + +To create ``kerberos`` security service, run: + +.. code-block:: console + + $ manila security-service-create kerberos --server 10.254.0.3 --user demo --password secret --name my_kerberos_security_service --description "Kerberos security service" + +-------------+--------------------------------------+ + | Property | Value | + +-------------+--------------------------------------+ + | status | new | + | domain | None | + | password | secret | + | name | my_kerberos_security_service | + | dns_ip | None | + | created_at | 2015-09-25T10:26:03.211849 | + | updated_at | None | + | server | 10.254.0.3 | + | user | demo | + | project_id | 20787a7ba11946adad976463b57d8a2f | + | type | kerberos | + | id | 7f46a447-2534-453d-924d-bd7c8e63bbec | + | description | Kerberos security service | + +-------------+--------------------------------------+ + +To see the list of created security service use +:command:`manila security-service-list`: + +.. code-block:: console + + $ manila security-service-list + +--------------------------------------+------------------------------+--------+----------+ + | id | name | status | type | + +--------------------------------------+------------------------------+--------+----------+ + | 413479b2-0d20-4c58-a9d3-b129fa592d8e | my_ldap_security_service | new | ldap | + | 7f46a447-2534-453d-924d-bd7c8e63bbec | my_kerberos_security_service | new | kerberos | + +--------------------------------------+------------------------------+--------+----------+ + +You can add a security service to the existing +:ref:`share network `, which is not +yet used (a ``share network`` not associated with a share). + +Add a security service to the share network with +``share-network-security-service-add`` specifying share network and +security service. The command returns information about the +security service. You can see view new attributes and ``share_networks`` +using the associated share network ID. + +.. code-block:: console + + $ manila share-network-security-service-add share_net2 my_ldap_security_service + + $ manila security-service-show my_ldap_security_service + +----------------+-------------------------------------------+ + | Property | Value | + +----------------+-------------------------------------------+ + | status | new | + | domain | None | + | password | None | + | name | my_ldap_security_service | + | dns_ip | 8.8.8.8 | + | created_at | 2015-09-25T10:19:06.000000 | + | updated_at | None | + | server | 10.254.0.3 | + | share_networks | [u'6d36c41f-d310-4aff-a0c2-ffd870e91cab'] | + | user | None | + | project_id | 20787a7ba11946adad976463b57d8a2f | + | type | ldap | + | id | 413479b2-0d20-4c58-a9d3-b129fa592d8e | + | description | None | + +----------------+-------------------------------------------+ + +It is possible to see the list of security services associated +with a given share network. List security services for ``share_net2`` +share network with: + +.. code-block:: console + + $ manila share-network-security-service-list share_net2 + +--------------------------------------+--------------------------+--------+------+ + | id | name | status | type | + +--------------------------------------+--------------------------+--------+------+ + | 413479b2-0d20-4c58-a9d3-b129fa592d8e | my_ldap_security_service | new | ldap | + +--------------------------------------+--------------------------+--------+------+ + +You also can dissociate a security service from the share network +and confirm that the security service now has an empty list of +share networks: + +.. code-block:: console + + $ manila share-network-security-service-remove share_net2 my_ldap_security_service + + $ manila security-service-show my_ldap_security_service + +----------------+--------------------------------------+ + | Property | Value | + +----------------+--------------------------------------+ + | status | new | + | domain | None | + | password | None | + | name | my_ldap_security_service | + | dns_ip | 8.8.8.8 | + | created_at | 2015-09-25T10:19:06.000000 | + | updated_at | None | + | server | 10.254.0.3 | + | share_networks | [] | + | user | None | + | project_id | 20787a7ba11946adad976463b57d8a2f | + | type | ldap | + | id | 413479b2-0d20-4c58-a9d3-b129fa592d8e | + | description | None | + +----------------+--------------------------------------+ + +The Shared File Systems service allows you to update a security service field +using :command:`manila security-service-update` command with optional +arguments such as ``--dns-ip``, ``--server``, ``--domain``, +``--user``, ``--password``, ``--name``, or +``--description``. + +To remove a security service not associated with any share networks +run: + +.. code-block:: console + + $ manila security-service-delete my_ldap_security_service diff --git a/doc/source/admin/shared-file-systems-services-manage.rst b/doc/source/admin/shared-file-systems-services-manage.rst new file mode 100644 index 0000000000..351082bc0a --- /dev/null +++ b/doc/source/admin/shared-file-systems-services-manage.rst @@ -0,0 +1,16 @@ +.. _shared_file_systems_services_manage.rst: + +====================== +Manage shares services +====================== + +The Shared File Systems service provides API that allows to manage running +share services (`Share services API +`_). +Using the :command:`manila service-list` command, it is possible to get a list +of all kinds of running services. To select only share services, you can pick +items that have field ``binary`` equal to ``manila-share``. Also, you can +enable or disable share services using raw API requests. Disabling means that +share services are excluded from the scheduler cycle and new shares will not +be placed on the disabled back end. However, shares from this service stay +available. diff --git a/doc/source/admin/shared-file-systems-share-management.rst b/doc/source/admin/shared-file-systems-share-management.rst new file mode 100644 index 0000000000..9f4be28c93 --- /dev/null +++ b/doc/source/admin/shared-file-systems-share-management.rst @@ -0,0 +1,33 @@ +.. _shared_file_systems_share_management: + +================ +Share management +================ + +A share is a remote, mountable file system. You can mount a share to and access +a share from several hosts by several users at a time. + +You can create a share and associate it with a network, list shares, and show +information for, update, and delete a specified share. +You can also create snapshots of shares. To create a snapshot, you specify the +ID of the share that you want to snapshot. + +The shares are based on of the supported Shared File Systems protocols: + +* *NFS*. Network File System (NFS). +* *CIFS*. Common Internet File System (CIFS). +* *GLUSTERFS*. Gluster file system (GlusterFS). +* *HDFS*. Hadoop Distributed File System (HDFS). +* *CEPHFS*. Ceph File System (CephFS). + +The Shared File Systems service provides set of drivers that enable you to use +various network file storage devices, instead of the base implementation. That +is the real purpose of the Shared File Systems service in production. + +.. toctree:: + + shared-file-systems-crud-share.rst + shared-file-systems-manage-and-unmanage-share.rst + shared-file-systems-manage-and-unmanage-snapshot.rst + shared-file-systems-share-resize.rst + shared-file-systems-quotas.rst diff --git a/doc/source/admin/shared-file-systems-share-migration.rst b/doc/source/admin/shared-file-systems-share-migration.rst new file mode 100644 index 0000000000..b6055571eb --- /dev/null +++ b/doc/source/admin/shared-file-systems-share-migration.rst @@ -0,0 +1,306 @@ +.. _shared_file_systems_share_migration: + +=============== +Share migration +=============== + +Share migration is the feature that migrates a share between different storage +pools. + +Use cases +~~~~~~~~~ + +As an administrator, you may want to migrate your share from one storage pool +to another for several reasons. Examples include: + +* Maintenance or evacuation + + * Evacuate a back end for hardware or software upgrades + * Evacuate a back end experiencing failures + * Evacuate a back end which is tagged end-of-life + +* Optimization + + * Defragment back ends to empty and be taken offline to conserve power + * Rebalance back ends to maximize available performance + * Move data and compute closer together to reduce network utilization and + decrease latency or increase bandwidth + +* Moving shares + + * Migrate from old hardware generation to a newer generation + * Migrate from one vendor to another + +Migration workflows +~~~~~~~~~~~~~~~~~~~ + +Moving shares across different storage pools is generally expected to be a +disruptive operation that disconnects existing clients when the source ceases +to exist. For this reason, share migration is implemented in a 2-phase approach +that allows the administrator to control the timing of the disruption. The +first phase performs data copy while users retain access to the share. When +copying is complete, the second phase may be triggered to perform a switchover +that may include a last sync and deleting the source, generally requiring users +to reconnect to continue accessing the share. + +In order to migrate a share, one of two possible mechanisms may be employed, +which provide different capabilities and affect how the disruption occurs with +regards to user access during data copy phase and disconnection during +switchover phase. Those two mechanisms are: + +* Driver-assisted migration: This mechanism is intended to make use of driver + optimizations to migrate shares between pools of the same storage vendor. + This mechanism allows migrating shares nondisruptively while the source + remains writable, preserving all filesystem metadata and snapshots. The + migration workload is performed in the storage back end. + +* Host-assisted migration: This mechanism is intended to migrate shares in an + agnostic manner between two different pools, regardless of storage vendor. + The implementation for this mechanism does not offer the same properties + found in driver-assisted migration. In host-assisted migration, the source + remains readable, snapshots must be deleted prior to starting the migration, + filesystem metadata may be lost, and the clients will get disconnected by the + end of migration. The migration workload is performed by the Data Service, + which is a dedicated manila service for intensive data operations. + +When starting a migration, driver-assisted migration is attempted first. If +the shared file system service detects it is not possible to perform the +driver-assisted migration, it proceeds to attempt host-assisted migration. + +Using the migration APIs +~~~~~~~~~~~~~~~~~~~~~~~~ + +The commands to interact with the share migration API are: + +* ``migration_start``: starts a migration while retaining access to the share. + Migration is paused and waits for ``migration_complete`` invocation when it + has copied all data and is ready to take down the source share. + + .. code-block:: console + + $ manila migration-start share_1 ubuntu@generic2#GENERIC2 --writable False --preserve-snapshots False --preserve-metadata False --nondisruptive False + + .. note:: + This command has no output. + +* ``migration_complete``: completes a migration, removing the source share and + setting the destination share instance to ``available``. + + .. code-block:: console + + $ manila migration-complete share_1 + + .. note:: + This command has no output. + +* ``migration_get_progress``: obtains migration progress information of a + share. + + .. code-block:: console + + $ manila migration-get-progress share_1 + + +----------------+--------------------------+ + | Property | Value | + +----------------+--------------------------+ + | task_state | data_copying_in_progress | + | total_progress | 37 | + +----------------+--------------------------+ + +* ``migration_cancel``: cancels an in-progress migration of a share. + + .. code-block:: console + + $ manila migration-cancel share_1 + + .. note:: + This command has no output. + +The parameters +-------------- + +To start a migration, an administrator should specify several parameters. Among +those, two of them are key for the migration. + +* ``share``: The share that will be migrated. + +* ``destination_pool``: The destination pool to which the share should be + migrated to, in format host@backend#pool. + +Several other parameters, referred to here as ``driver-assisted parameters``, +*must* be specified in the ``migration_start`` API. They are: + +* ``preserve_metadata``: whether preservation of filesystem metadata should be + enforced for this migration. + +* ``preserve_snapshots``: whether preservation of snapshots should be enforced + for this migration. + +* ``writable``: whether the source share remaining writable should be enforced + for this migration. + +* ``nondisruptive``: whether it should be enforced to keep clients connected + throughout the migration. + +Specifying any of the boolean parameters above as ``True`` will disallow a +host-assisted migration. + +In order to appropriately move a share to a different storage pool, it may be +required to change one or more share properties, such as the share type, share +network, or availability zone. To accomplish this, use the optional parameters: + +* ``new_share_type_id``: Specify the ID of the share type that should be set in + the migrated share. + +* ``new_share_network_id``: Specify the ID of the share network that should be + set in the migrated share. + +If driver-assisted migration should not be attempted, you may provide the +optional parameter: + +* ``force_host_assisted_migration``: whether driver-assisted migration attempt + should be skipped. If this option is set to ``True``, all driver-assisted + options must be set to ``False``. + +Configuration +~~~~~~~~~~~~~ + +For share migration to work in the cloud, there are several configuration +requirements that need to be met: + +For driver-assisted migration: it is necessary that the configuration of all +back end stanzas is present in the file manila.conf of all manila-share nodes. +Also, network connectivity between the nodes running manila-share service and +their respective storage back ends is required. + +For host-assisted migration: it is necessary that the Data Service +(manila-data) is installed and configured in a node connected to the cloud's +administrator network. The drivers pertaining to the source back end and +destination back end involved in the migration should be able to provide shares +that can be accessed from the administrator network. This can easily be +accomplished if the driver supports ``admin_only`` export locations, else it is +up to the administrator to set up means of connectivity. + +In order for the Data Service to mount the source and destination instances, it +must use manila share access APIs to grant access to mount the instances. +The access rule type varies according to the share protocol, so there are a few +config options to set the access value for each type: + +* ``data_node_access_ip``: For IP-based access type, provide the value of the + IP of the Data Service node in the administrator network. For NFS shares, + drivers should always add rules with the "no_root_squash" property. + +* ``data_node_access_cert``: For certificate-based access type, provide the + value of the certificate name that grants access to the Data Service. + +* ``data_node_access_admin_user``: For user-based access type, provide the + value of a username that grants access and administrator privileges to the + files in the share. + +* ``data_node_mount_options``: Provide the value of a mapping of protocol name + to respective mount options. The Data Service makes use of mount command + templates that by default have a dedicated field to inserting mount options + parameter. The default value for this config option already includes the + username and password parameters for CIFS shares and NFS v3 enforcing + parameter for NFS shares. + +* ``mount_tmp_location``: Provide the value of a string representing the path + where the share instances used in migration should be temporarily mounted. + The default value is ``/tmp/``. + +* ``check_hash``: This boolean config option value determines whether the hash + of all files copied in migration should be validated. Setting this option + increases the time it takes to migrate files, and is recommended for + ultra-dependable systems. It defaults to disabled. + +The configuration options above are respective to the Data Service only and +should be defined the ``DEFAULT`` group of the ``manila.conf`` configuration +file. Also, the Data Service node must have all the protocol-related libraries +pre-installed to be able to run the mount commands for each protocol. + +You may need to change some driver-specific configuration options from their +default value to work with specific drivers. If so, they must be set under the +driver configuration stanza in ``manila.conf``. See a detailed description for +each one below: + +* ``migration_ignore_files``: Provide value as a list containing the names of + files or folders to be ignored during migration for a specific driver. The + default value is a list containing only ``lost+found`` folder. + +* ``share_mount_template``: Provide a string that defines the template for the + mount command for a specific driver. The template should contain the + following entries to be formatted by the code: + + * proto: The share protocol. Automatically formatted by the Data Service. + * options: The mount options to be formatted by the Data Service according to + the data_node_mount_options config option. + * export: The export path of the share. Automatically formatted by the Data + Service with the share's ``admin_only`` export location. + * path: The path to mount the share. Automatically formatted by the Data + Serivce according to the mount_tmp_location config option. + + The default value for this config option is:: + + mount -vt %(proto)s %(options)s %(export)s %(path)s. + + +* ``share_unmount_template``: Provide the value of a string that defines the + template for the unmount command for a specific driver. The template should + contain the path of where the shares are mounted, according to the + ``mount_tmp_location`` config option, to be formatted automatically by the + Data Service. The default value for this config option is:: + + umount -v %(path)s + + +* ``protocol_access_mapping``: Provide the value of a mapping of access rule + type to protocols supported. The default value specifies IP and user based + access types mapped to NFS and CIFS respectively, which are the combinations + supported by manila. If a certain driver uses a different protocol for IP or + user access types, or is not included in the default mapping, it should be + specified in this configuration option. + +Other remarks +~~~~~~~~~~~~~ + +* There is no need to manually add any of the previously existing access rules + after a migration is complete, they will be persisted on the destination + after the migration. + +* Once migration of a share has started, the user will see the status + ``migrating`` and it will block other share actions, such as adding or + removing access rules, creating or deleting snapshots, resizing, among + others. + +* The destination share instance export locations, although it may exist from + the beginning of a host-assisted migration, are not visible nor accessible as + access rules cannot be added. + +* During a host-assisted migration, an access rule granting access to the Data + Service will be added and displayed by querying the ``access-list`` API. This + access rule should not be tampered with, it will otherwise cause migration to + fail. + +* Resources allocated are cleaned up automatically when a migration fails, + except if this failure occurs during the 2nd phase of a driver-assisted + migration. Each step in migration is saved to the field ``task_state`` + present in the Share model. If for any reason the state is not set to + ``migration_error`` during a failure, it will need to be reset using the + ``reset-task-state`` API. + +* It is advised that the node running the Data Service is well secured, since + it will be mounting shares with highest privileges, temporarily exposing user + data to whoever has access to this node. + +* The two mechanisms of migration are affected differently by service restarts: + + * If performing a host-assisted migration, all services may be restarted + except for the manila-data service when performing the copy (the + ``task_state`` field value starts with ``data_copying_``). In other steps + of the host-assisted migration, both the source and destination + manila-share services should not be restarted. + * If performing a driver-assisted migration, the migration is affected + minimally by driver restarts if the ``task_state`` is + ``migration_driver_in_progress``, while the copy is being done in the + back end. Otherwise, the source and destination manila-share services + should not be restarted. diff --git a/doc/source/admin/shared-file-systems-share-networks.rst b/doc/source/admin/shared-file-systems-share-networks.rst new file mode 100644 index 0000000000..918fc94287 --- /dev/null +++ b/doc/source/admin/shared-file-systems-share-networks.rst @@ -0,0 +1,151 @@ +.. _shared_file_systems_share_networks: + +============== +Share networks +============== + +Share network is an entity that encapsulates interaction with the OpenStack +Networking service. If the share driver that you selected runs in a mode +requiring Networking service interaction, specify the share network when +creating a new share network. + +How to create share network +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To list networks in a project, run: + +.. code-block:: console + + $ openstack network list + +--------------+---------+--------------------+ + | ID | Name | Subnets | + +--------------+---------+--------------------+ + | bee7411d-... | public | 884a6564-0f11-... | + | | | e6da81fa-5d5f-... | + | 5ed5a854-... | private | 74dcfb5a-b4d7-... | + | | | cc297be2-5213-... | + +--------------+---------+--------------------+ + +A share network stores network information that share servers can use where +shares are hosted. You can associate a share with a single share network. +When you create or update a share, you can optionally specify the ID of a share +network through which instances can access the share. + +When you create a share network, you can specify only one type of network: + +- OpenStack Networking (neutron). Specify a network ID and subnet ID. + In this case ``manila.network.nova_network_plugin.NeutronNetworkPlugin`` + will be used. + +- Legacy networking (nova-network). Specify a network ID. + In this case ``manila.network.nova_network_plugin.NoveNetworkPlugin`` + will be used. + +For more information about supported plug-ins for share networks, see +:ref:`shared_file_systems_network_plugins`. + +A share network has these attributes: + +- The IP block in Classless Inter-Domain Routing (CIDR) notation from which to + allocate the network. + +- The IP version of the network. + +- The network type, which is `vlan`, `vxlan`, `gre`, or `flat`. + +If the network uses segmentation, a segmentation identifier. For example, VLAN, +VXLAN, and GRE networks use segmentation. + +To create a share network with private network and subnetwork, run: + +.. code-block:: console + + $ manila share-network-create --neutron-net-id 5ed5a854-21dc-4ed3-870a-117b7064eb21 \ + --neutron-subnet-id 74dcfb5a-b4d7-4855-86f5-a669729428dc --name my_share_net --description "My first share network" + +-------------------+--------------------------------------+ + | Property | Value | + +-------------------+--------------------------------------+ + | name | my_share_net | + | segmentation_id | None | + | created_at | 2015-09-24T12:06:32.602174 | + | neutron_subnet_id | 74dcfb5a-b4d7-4855-86f5-a669729428dc | + | updated_at | None | + | network_type | None | + | neutron_net_id | 5ed5a854-21dc-4ed3-870a-117b7064eb21 | + | ip_version | None | + | nova_net_id | None | + | cidr | None | + | project_id | 20787a7ba11946adad976463b57d8a2f | + | id | 5c3cbabb-f4da-465f-bc7f-fadbe047b85a | + | description | My first share network | + +-------------------+--------------------------------------+ + +The ``segmentation_id``, ``cidr``, ``ip_version``, and ``network_type`` +share network attributes are automatically set to the values determined by the +network provider. + +To check the network list, run: + +.. code-block:: console + + $ manila share-network-list + +--------------------------------------+--------------+ + | id | name | + +--------------------------------------+--------------+ + | 5c3cbabb-f4da-465f-bc7f-fadbe047b85a | my_share_net | + +--------------------------------------+--------------+ + +If you configured the generic driver with ``driver_handles_share_servers = +True`` (with the share servers) and already had previous operations in the Shared +File Systems service, you can see ``manila_service_network`` in the neutron +list of networks. This network was created by the generic driver for internal +use. + +.. code-block:: console + + $ openstack network list + +--------------+------------------------+--------------------+ + | ID | Name | Subnets | + +--------------+------------------------+--------------------+ + | 3b5a629a-e...| manila_service_network | 4f366100-50... | + | bee7411d-... | public | 884a6564-0f11-... | + | | | e6da81fa-5d5f-... | + | 5ed5a854-... | private | 74dcfb5a-b4d7-... | + | | | cc297be2-5213-... | + +--------------+------------------------+--------------------+ + +You also can see detailed information about the share network including +``network_type``, and ``segmentation_id`` fields: + +.. code-block:: console + + $ openstack network show manila_service_network + +---------------------------+--------------------------------------+ + | Field | Value | + +---------------------------+--------------------------------------+ + | admin_state_up | UP | + | availability_zone_hints | | + | availability_zones | nova | + | created_at | 2016-12-13T09:31:30Z | + | description | | + | id | 3b5a629a-e7a1-46a3-afb2-ab666fb884bc | + | ipv4_address_scope | None | + | ipv6_address_scope | None | + | mtu | 1450 | + | name | manila_service_network | + | port_security_enabled | True | + | project_id | f6ac448a469b45e888050cf837b6e628 | + | provider:network_type | vxlan | + | provider:physical_network | None | + | provider:segmentation_id | 73 | + | revision_number | 7 | + | router:external | Internal | + | shared | False | + | status | ACTIVE | + | subnets | 682e3329-60b0-440f-8749-83ef53dd8544 | + | tags | [] | + | updated_at | 2016-12-13T09:31:36Z | + +---------------------------+--------------------------------------+ + +You also can add and remove the security services from the share network. +For more detail, see :ref:`shared_file_systems_security_services`. diff --git a/doc/source/admin/shared-file-systems-share-replication.rst b/doc/source/admin/shared-file-systems-share-replication.rst new file mode 100644 index 0000000000..b641424f9f --- /dev/null +++ b/doc/source/admin/shared-file-systems-share-replication.rst @@ -0,0 +1,601 @@ +.. _shared_file_systems_share_replication: + +================= +Share replication +================= + + +Replication of data has a number of use cases in the cloud. One use case is +High Availability of the data in a shared file system, used for example, to +support a production database. Another use case is ensuring Data Protection; +i.e being prepared for a disaster by having a replication location that will be +ready to back up your primary data source. + +The Shared File System service supports user facing APIs that allow users to +create shares that support replication, add and remove share replicas and +manage their snapshots and access rules. Three replication types are currently +supported and they vary in the semantics associated with the primary share and +the secondary copies. + +.. important:: + + **Share replication** is an **experimental** Shared File Systems API in + the Mitaka release. Contributors can change or remove the experimental + part of the Shared File Systems API in further releases without maintaining + backward compatibility. Experimental APIs have an + ``X-OpenStack-Manila-API-Experimental: true`` header in their HTTP requests. + + +Replication types supported +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Before using share replication, make sure the Shared File System driver that +you are running supports this feature. You can check it in the +``manila-scheduler`` service reports. The ``replication_type`` capability +reported can have one of the following values: + +writable + The driver supports creating ``writable`` share replicas. All share replicas + can be accorded read/write access and would be synchronously mirrored. +readable + The driver supports creating ``read-only`` share replicas. All secondary + share replicas can be accorded read access. Only the primary (or ``active`` + share replica) can be written into. +dr + The driver supports creating ``dr`` (abbreviated from Disaster Recovery) + share replicas. A secondary share replica is inaccessible until after a + ``promotion``. +None + The driver does not support Share Replication. + + +.. note:: + + The term ``active`` share replica refers to the ``primary`` share. In + ``writable`` style of replication, all share replicas are ``active``, and + there could be no distinction of a ``primary`` share. In ``readable`` and + ``dr`` styles of replication, a ``secondary`` share replica may be referred + to as ``passive``, ``non-active`` or simply, ``replica``. + + +Configuration +~~~~~~~~~~~~~ + +Two new configuration options have been introduced to support Share +Replication. + +replica_state_update_interval + Specify this option in the ``DEFAULT`` section of your ``manila.conf``. + The Shared File Systems service requests periodic update of the + `replica_state` of all ``non-active`` share replicas. The update occurs with + respect to an interval corresponding to this option. If it is not specified, + it defaults to 300 seconds. + +replication_domain + Specify this option in the backend stanza when using a multi-backend style + configuration. The value can be any ASCII string. Two backends that can + replicate between each other would have the same ``replication_domain``. + This comes from the premise that the Shared File Systems service expects + Share Replication to be performed between symmetric backends. This option + is *required* for using the Share Replication feature. + + +Health of a share replica +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Apart from the ``status`` attribute, share replicas have the +``replica_state`` attribute to denote the state of data replication on the +storage backend. The ``primary`` share replica will have it's `replica_state` +attribute set to `active`. The ``secondary`` share replicas may have one of +the following as their ``replica_state``: + +in_sync + The share replica is up to date with the ``active`` share replica (possibly + within a backend-specific ``recovery point objective``). +out_of_sync + The share replica is out of date (all new share replicas start out in + this ``replica_state``). +error + When the scheduler fails to schedule this share replica or some potentially + irrecoverable error occurred with regard to updating data for this replica. + + +Promotion or failover +~~~~~~~~~~~~~~~~~~~~~ + +For ``readable`` and ``dr`` types of replication, we refer to the task +of switching a `non-active` share replica with the ``active`` replica as +`promotion`. For the ``writable`` style of replication, promotion does +not make sense since all share replicas are ``active`` (or writable) at all +times. + +The `status` attribute of the non-active replica being promoted will be +set to ``replication_change`` during its promotion. This has been classified as +a ``busy`` state and thus API interactions with the share are restricted +while one of its share replicas is in this state. + + +Share replication workflows +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following examples have been implemented with the ZFSonLinux driver that +is a reference implementation in the Shared File Systems service. It operates +in ``driver_handles_share_servers=False`` mode and supports the ``readable`` +type of replication. In the example, we assume a configuration of two +Availability Zones (configuration option: ``storage_availability_zone``), +called `availability_zone_1` and `availability_zone_2`. + +Multiple availability zones are not necessary to use the replication feature. +However, the use of an availability zone as a ``failure domain`` is encouraged. + +Pay attention to the network configuration for the ZFS driver. Here, we assume +a configuration of ``zfs_service_ip`` and ``zfs_share_export_ip`` from two +separate networks. The service network is reachable from the host where the +``manila-share`` service is running. The share export IP is from a network that +allows user access. + +See `Configuring the ZFSonLinux driver `_ +for information on how to set up the ZFSonLinux driver. + + +Creating a share that supports replication +------------------------------------------ + +Create a new share type and specify the `replication_type` as an extra-spec +within the share-type being used. + + +Use the :command:`manila type-create` command to create a new share type. +Specify the name and the value for the extra-spec +``driver_handles_share_servers``. + +.. code-block:: console + + $ manila type-create readable_type_replication False + +----------------------+--------------------------------------+ + | Property | Value | + +----------------------+--------------------------------------+ + | required_extra_specs | driver_handles_share_servers : False | + | Name | readable_type_replication | + | Visibility | public | + | is_default | - | + | ID | 3b3ee3f7-6e43-4aa1-859d-0b0511c43074 | + | optional_extra_specs | snapshot_support : True | + +----------------------+--------------------------------------+ + +Use the :command:`manila type-key` command to set an extra-spec to the +share type. + +.. code-block:: console + + $ manila type-key readable_type_replication set replication_type=readable + +.. note:: + This command has no output. To verify the extra-spec, use the + :command:`manila extra-specs-list` command and specify the share type's name + or ID as a parameter. + +Create a share with the share type + +Use the :command:`manila create` command to create a share. Specify the share +protocol, size and the availability zone. + +.. code-block:: console + + $ manila create NFS 1 --share_type readable_type_replication --name my_share --description "This share will have replicas" --az availability_zone_1 + +-----------------------------+--------------------------------------+ + | Property | Value | + +-----------------------------+--------------------------------------+ + | status | creating | + | share_type_name | readable_type_replication | + | description | This share will have replicas | + | availability_zone | availability_zone_1 | + | share_network_id | None | + | share_server_id | None | + | host | | + | access_rules_status | active | + | snapshot_id | None | + | is_public | False | + | task_state | None | + | snapshot_support | True | + | id | e496ed61-8f2e-436b-b299-32c3e90991cc | + | size | 1 | + | name | my_share | + | share_type | 3b3ee3f7-6e43-4aa1-859d-0b0511c43074 | + | has_replicas | False | + | replication_type | readable | + | created_at | 2016-03-29T20:22:18.000000 | + | share_proto | NFS | + | consistency_group_id | None | + | source_cgsnapshot_member_id | None | + | project_id | 48a5ca76ac69405e99dc1c13c5195186 | + | metadata | {} | + +-----------------------------+--------------------------------------+ + +Use the :command:`manila show` command to retrieve details of the share. +Specify the share ID or name as a parameter. + +.. code-block:: console + + $ manila show my_share + +-----------------------------+--------------------------------------------------------------------+ + | Property | Value | + +-----------------------------+--------------------------------------------------------------------+ + | status | available | + | share_type_name | readable_type_replication | + | description | This share will have replicas | + | availability_zone | availability_zone_1 | + | share_network_id | None | + | export_locations | | + | | path = | + | |10.32.62.26:/alpha/manila_share_38efc042_50c2_4825_a6d8_cba2a8277b28| + | | preferred = False | + | | is_admin_only = False | + | | id = e1d754b5-ec06-42d2-afff-3e98c0013faf | + | | share_instance_id = 38efc042-50c2-4825-a6d8-cba2a8277b28 | + | | path = | + | |172.21.0.23:/alpha/manila_share_38efc042_50c2_4825_a6d8_cba2a8277b28| + | | preferred = False | + | | is_admin_only = True | + | | id = 6f843ecd-a7ea-4939-86de-e1e01d9e8672 | + | | share_instance_id = 38efc042-50c2-4825-a6d8-cba2a8277b28 | + | share_server_id | None | + | host | openstack4@zfsonlinux_1#alpha | + | access_rules_status | active | + | snapshot_id | None | + | is_public | False | + | task_state | None | + | snapshot_support | True | + | id | e496ed61-8f2e-436b-b299-32c3e90991cc | + | size | 1 | + | name | my_share | + | share_type | 3b3ee3f7-6e43-4aa1-859d-0b0511c43074 | + | has_replicas | False | + | replication_type | readable | + | created_at | 2016-03-29T20:22:18.000000 | + | share_proto | NFS | + | consistency_group_id | None | + | source_cgsnapshot_member_id | None | + | project_id | 48a5ca76ac69405e99dc1c13c5195186 | + | metadata | {} | + +-----------------------------+--------------------------------------------------------------------+ + + +.. note:: + When you create a share that supports replication, an ``active`` replica is + created for you. You can verify this with the + :command:`manila share-replica-list` command. + + +Creating and promoting share replicas +------------------------------------- + +Create a share replica + +Use the :command:`manila share-replica-create` command to create a share +replica. Specify the share ID or name as a parameter. You may +optionally provide the `availability_zone` and `share_network_id`. In the +example below, `share_network_id` is not used since the ZFSonLinux driver +does not support it. + +.. code-block:: console + + $ manila share-replica-create my_share --az availability_zone_2 + +-------------------+--------------------------------------+ + | Property | Value | + +-------------------+--------------------------------------+ + | status | creating | + | share_id | e496ed61-8f2e-436b-b299-32c3e90991cc | + | availability_zone | availability_zone_2 | + | created_at | 2016-03-29T20:24:53.148992 | + | updated_at | None | + | share_network_id | None | + | share_server_id | None | + | host | | + | replica_state | None | + | id | 78a5ef96-6c36-42e0-b50b-44efe7c1807e | + +-------------------+--------------------------------------+ + +See details of the newly created share replica + +Use the :command:`manila share-replica-show` command to see details +of the newly created share replica. Specify the share replica's ID as a +parameter. + +.. code-block:: console + + $ manila share-replica-show 78a5ef96-6c36-42e0-b50b-44efe7c1807e + +-------------------+--------------------------------------+ + | Property | Value | + +-------------------+--------------------------------------+ + | status | available | + | share_id | e496ed61-8f2e-436b-b299-32c3e90991cc | + | availability_zone | availability_zone_2 | + | created_at | 2016-03-29T20:24:53.000000 | + | updated_at | 2016-03-29T20:24:58.000000 | + | share_network_id | None | + | share_server_id | None | + | host | openstack4@zfsonlinux_2#beta | + | replica_state | in_sync | + | id | 78a5ef96-6c36-42e0-b50b-44efe7c1807e | + +-------------------+--------------------------------------+ + +See all replicas of the share + +Use the :command:`manila share-replica-list` command to see all the replicas +of the share. Specify the share ID or name as an optional parameter. + +.. code-block:: console + + $ manila share-replica-list --share-id my_share + +--------------------------------------+-----------+---------------+--------------------------------------+-------------------------------+---------------------+----------------------------+ + | ID | Status | Replica State | Share ID | Host | Availability Zone | Updated At | + +--------------------------------------+-----------+---------------+--------------------------------------+-------------------------------+---------------------+----------------------------+ + | 38efc042-50c2-4825-a6d8-cba2a8277b28 | available | active | e496ed61-8f2e-436b-b299-32c3e90991cc | openstack4@zfsonlinux_1#alpha | availability_zone_1 | 2016-03-29T20:22:19.000000 | + | 78a5ef96-6c36-42e0-b50b-44efe7c1807e | available | in_sync | e496ed61-8f2e-436b-b299-32c3e90991cc | openstack4@zfsonlinux_2#beta | availability_zone_2 | 2016-03-29T20:24:58.000000 | + +--------------------------------------+-----------+---------------+--------------------------------------+-------------------------------+---------------------+----------------------------+ + +Promote the secondary share replica to be the new active replica + +Use the :command:`manila share-replica-promote` command to promote a +non-active share replica to become the ``active`` replica. Specify the +non-active replica's ID as a parameter. + +.. code-block:: console + + $ manila share-replica-promote 78a5ef96-6c36-42e0-b50b-44efe7c1807e + +.. note:: + This command has no output. + +The promotion may take time. During the promotion, the ``replica_state`` +attribute of the share replica being promoted will be set to +``replication_change``. + +.. code-block:: console + + $ manila share-replica-list --share-id my_share + +--------------------------------------+-----------+--------------------+--------------------------------------+-------------------------------+---------------------+----------------------------+ + | ID | Status | Replica State | Share ID | Host | Availability Zone | Updated At | + +--------------------------------------+-----------+--------------------+--------------------------------------+-------------------------------+---------------------+----------------------------+ + | 38efc042-50c2-4825-a6d8-cba2a8277b28 | available | active | e496ed61-8f2e-436b-b299-32c3e90991cc | openstack4@zfsonlinux_1#alpha | availability_zone_1 | 2016-03-29T20:32:19.000000 | + | 78a5ef96-6c36-42e0-b50b-44efe7c1807e | available | replication_change | e496ed61-8f2e-436b-b299-32c3e90991cc | openstack4@zfsonlinux_2#beta | availability_zone_2 | 2016-03-29T20:32:19.000000 | + +--------------------------------------+-----------+--------------------+--------------------------------------+-------------------------------+---------------------+----------------------------+ + +Once the promotion is complete, the ``replica_state`` will be set to +``active``. + +.. code-block:: console + + $ manila share-replica-list --share-id my_share + +--------------------------------------+-----------+---------------+--------------------------------------+-------------------------------+---------------------+----------------------------+ + | ID | Status | Replica State | Share ID | Host | Availability Zone | Updated At | + +--------------------------------------+-----------+---------------+--------------------------------------+-------------------------------+---------------------+----------------------------+ + | 38efc042-50c2-4825-a6d8-cba2a8277b28 | available | in_sync | e496ed61-8f2e-436b-b299-32c3e90991cc | openstack4@zfsonlinux_1#alpha | availability_zone_1 | 2016-03-29T20:32:19.000000 | + | 78a5ef96-6c36-42e0-b50b-44efe7c1807e | available | active | e496ed61-8f2e-436b-b299-32c3e90991cc | openstack4@zfsonlinux_2#beta | availability_zone_2 | 2016-03-29T20:32:19.000000 | + +--------------------------------------+-----------+---------------+--------------------------------------+-------------------------------+---------------------+----------------------------+ + + +Access rules +------------ + +Create an IP access rule for the share + +Use the :command:`manila access-allow` command to add an access rule. +Specify the share ID or name, protocol and the target as parameters. + +.. code-block:: console + + $ manila access-allow my_share ip 0.0.0.0/0 --access-level rw + +--------------+--------------------------------------+ + | Property | Value | + +--------------+--------------------------------------+ + | share_id | e496ed61-8f2e-436b-b299-32c3e90991cc | + | access_type | ip | + | access_to | 0.0.0.0/0 | + | access_level | rw | + | state | new | + | id | 8b339cdc-c1e0-448f-bf6d-f068ee6e8f45 | + +--------------+--------------------------------------+ + +.. note:: + Access rules are not meant to be different across the replicas of the share. + However, as per the type of replication, drivers may choose to modify the + access level prescribed. In the above example, even though read/write access + was requested for the share, the driver will provide read-only access to + the non-active replica to the same target, because of the semantics of + the replication type: ``readable``. However, the target will have read/write + access to the (currently) non-active replica when it is promoted to + become the ``active`` replica. + +The :command:`manila access-deny` command can be used to remove a previously +applied access rule. + +List the export locations of the share + +Use the :command:`manila share-export-locations-list` command to list the +export locations of a share. + +.. code-block:: console + + $ manila share-export-location-list my_share + +--------------------------------------+---------------------------------------------------------------------------+-----------+ + | ID | Path | Preferred | + +--------------------------------------+---------------------------------------------------------------------------+-----------+ + | 3ed3fbf5-2fa1-4dc0-8440-a0af72398cb6 | 10.32.62.21:/beta/subdir/manila_share_78a5ef96_6c36_42e0_b50b_44efe7c1807e| False | + | 6f843ecd-a7ea-4939-86de-e1e01d9e8672 | 172.21.0.23:/alpha/manila_share_38efc042_50c2_4825_a6d8_cba2a8277b28 | False | + | e1d754b5-ec06-42d2-afff-3e98c0013faf | 10.32.62.26:/alpha/manila_share_38efc042_50c2_4825_a6d8_cba2a8277b28 | False | + | f3c5585f-c2f7-4264-91a7-a4a1e754e686 | 172.21.0.29:/beta/subdir/manila_share_78a5ef96_6c36_42e0_b50b_44efe7c1807e| False | + +--------------------------------------+---------------------------------------------------------------------------+-----------+ + +Identify the export location corresponding to the share replica on the user +accessible network and you may mount it on the target node. + +.. note:: + As an administrator, you can list the export locations for a particular + share replica by using the + :command:`manila share-instance-export-location-list` command and + specifying the share replica's ID as a parameter. + + +Snapshots +--------- + +Create a snapshot of the share + +Use the :command:`manila snapshot-create` command to create a snapshot +of the share. Specify the share ID or name as a parameter. + +.. code-block:: console + + $ manila snapshot-create my_share --name "my_snapshot" + +-------------------+--------------------------------------+ + | Property | Value | + +-------------------+--------------------------------------+ + | status | creating | + | share_id | e496ed61-8f2e-436b-b299-32c3e90991cc | + | description | None | + | created_at | 2016-03-29T21:14:03.000000 | + | share_proto | NFS | + | provider_location | None | + | id | 06cdccaf-93a0-4e57-9a39-79fb1929c649 | + | size | 1 | + | share_size | 1 | + | name | my_snapshot | + +-------------------+--------------------------------------+ + + +Show the details of the snapshot + +Use the :command:`manila snapshot-show` to view details of a snapshot. +Specify the snapshot ID or name as a parameter. + +.. code-block:: console + + $ manila snapshot-show my_snapshot + +-------------------+--------------------------------------+ + | Property | Value | + +-------------------+--------------------------------------+ + | status | available | + | share_id | e496ed61-8f2e-436b-b299-32c3e90991cc | + | description | None | + | created_at | 2016-03-29T21:14:03.000000 | + | share_proto | NFS | + | provider_location | None | + | id | 06cdccaf-93a0-4e57-9a39-79fb1929c649 | + | size | 1 | + | share_size | 1 | + | name | my_snapshot | + +-------------------+--------------------------------------+ + +.. note:: + The ``status`` attribute of a snapshot will transition from ``creating`` + to ``available`` only when it is present on all the share replicas that have + their ``replica_state`` attribute set to ``active`` or ``in_sync``. + + Likewise, the ``replica_state`` attribute of a share replica will + transition from ``out_of_sync`` to ``in_sync`` only when all ``available`` + snapshots are present on it. + + +Planned failovers +----------------- + +As an administrator, you can use the :command:`manila share-replica-resync` +command to attempt to sync data between ``active`` and ``non-active`` share +replicas of a share before promotion. This will ensure that share replicas have +the most up-to-date data and their relationships can be safely switched. + +.. code-block:: console + + $ manila share-replica-resync 38efc042-50c2-4825-a6d8-cba2a8277b28 + +.. note:: + This command has no output. + + +Updating attributes +------------------- +If an error occurs while updating data or replication relationships (during +a ``promotion``), the Shared File Systems service may not be able to determine +the consistency or health of a share replica. It may require administrator +intervention to make any fixes on the storage backend as necessary. In such a +situation, state correction within the Shared File Systems service is possible. + +As an administrator, you can: + +Reset the ``status`` attribute of a share replica + +Use the :command:`manila share-replica-reset-state` command to reset +the ``status`` attribute. Specify the share replica's ID as a parameter +and use the ``--state`` option to specify the state intended. + +.. code-block:: console + + $ manila share-replica-reset-state 38efc042-50c2-4825-a6d8-cba2a8277b28 --state=available + +.. note:: + This command has no output. + + +Reset the ``replica_state`` attribute + +Use the :command:`manila share-replica-reset-replica-state` command to +reset the ``replica_state`` attribute. Specify the share replica's ID +and use the ``--state`` option to specify the state intended. + +.. code-block:: console + + $ manila share-replica-reset-replica-state 38efc042-50c2-4825-a6d8-cba2a8277b28 --state=out_of_sync + +.. note:: + This command has no output. + +Force delete a specified share replica in any state + +Use the :command:`manila share-replica-delete` command with the +'--force' key to remove the share replica, regardless of the state it is in. + +.. code-block:: console + + $ manila share-replica-show 9513de5d-0384-4528-89fb-957dd9b57680 + +-------------------+--------------------------------------+ + | Property | Value | + +-------------------+--------------------------------------+ + | status | error | + | share_id | e496ed61-8f2e-436b-b299-32c3e90991cc | + | availability_zone | availability_zone_1 | + | created_at | 2016-03-30T01:32:47.000000 | + | updated_at | 2016-03-30T01:34:25.000000 | + | share_network_id | None | + | share_server_id | None | + | host | openstack4@zfsonlinux_1#alpha | + | replica_state | out_of_sync | + | id | 38efc042-50c2-4825-a6d8-cba2a8277b28 | + +-------------------+--------------------------------------+ + + $ manila share-replica-delete --force 38efc042-50c2-4825-a6d8-cba2a8277b28 + +.. note:: + This command has no output. + +Use the ``policy.json`` file to grant permissions for these actions to other +roles. + + +Deleting share replicas +----------------------- + +Use the :command:`manila share-replica-delete` command with the share +replica's ID to delete a share replica. + +.. code-block:: console + + $ manila share-replica-delete 38efc042-50c2-4825-a6d8-cba2a8277b28 + +.. note:: + This command has no output. + +.. note:: + You cannot delete the last ``active`` replica with this command. You should + use the :command:`manila delete` command to remove the share. diff --git a/doc/source/admin/shared-file-systems-share-resize.rst b/doc/source/admin/shared-file-systems-share-resize.rst new file mode 100644 index 0000000000..0f20a68444 --- /dev/null +++ b/doc/source/admin/shared-file-systems-share-resize.rst @@ -0,0 +1,111 @@ +.. _shared_file_systems_share_resize: + +============ +Resize share +============ + +To change file share size, use the :command:`manila extend` command and +the :command:`manila shrink` command. For most drivers it is safe +operation. If you want to be sure that your data is safe, you can make +a share back up by creating a snapshot of it. + +You can extend and shrink the share with the :command:`manila extend` and +:command:`manila shrink` commands respectively, and specify the share +with the new size that does not exceed the quota. For details, see +:ref:`Quotas and Limits `. You also cannot shrink +share size to 0 or to a greater value than the current share size. + +While extending, the share has an ``extending`` status. This means that +the increase share size request was issued successfully. + +To extend the share and check the result, run: + +.. code-block:: console + + $ manila extend docs_resize 2 + $ manila show docs_resize + +----------------------+--------------------------------------------------------------------------+ + | Property | Value | + +----------------------+--------------------------------------------------------------------------+ + | status | available | + | share_type_name | my_type | + | description | None | + | availability_zone | nova | + | share_network_id | None | + | export_locations | | + | | path = 1.0.0.4:/shares/manila_share_b8afc508_8487_442b_b170_ea65b07074a8 | + | | preferred = False | + | | is_admin_only = False | + | | id = 3ffb76f4-92b9-4639-83fd-025bc3e302ff | + | | share_instance_id = b8afc508-8487-442b-b170-ea65b07074a8 | + | | path = 2.0.0.3:/shares/manila_share_b8afc508_8487_442b_b170_ea65b07074a8 | + | | preferred = False | + | | is_admin_only = True | + | | id = 1f0e263f-370d-47d3-95f6-1be64088b9da | + | | share_instance_id = b8afc508-8487-442b-b170-ea65b07074a8 | + | share_server_id | None | + | host | manila@paris#shares | + | access_rules_status | active | + | snapshot_id | None | + | is_public | False | + | task_state | None | + | snapshot_support | True | + | id | b07dbebe-a328-403c-b402-c8871c89e3d1 | + | size | 2 | + | name | docs_resize | + | share_type | 14ee8575-aac2-44af-8392-d9c9d344f392 | + | has_replicas | False | + | replication_type | None | + | created_at | 2016-03-25T15:33:18.000000 | + | share_proto | NFS | + | consistency_group_id | None | + | project_id | 907004508ef4447397ce6741a8f037c1 | + | metadata | {} | + +----------------------+--------------------------------------------------------------------------+ + +While shrinking, the share has a ``shrinking`` status. This means that the +decrease share size request was issued successfully. To shrink the share and +check the result, run: + +.. code-block:: console + + $ manila shrink docs_resize 1 + $ manila show docs_resize + +----------------------+--------------------------------------------------------------------------+ + | Property | Value | + +----------------------+--------------------------------------------------------------------------+ + | status | available | + | share_type_name | my_type | + | description | None | + | availability_zone | nova | + | share_network_id | None | + | export_locations | | + | | path = 1.0.0.4:/shares/manila_share_b8afc508_8487_442b_b170_ea65b07074a8 | + | | preferred = False | + | | is_admin_only = False | + | | id = 3ffb76f4-92b9-4639-83fd-025bc3e302ff | + | | share_instance_id = b8afc508-8487-442b-b170-ea65b07074a8 | + | | path = 2.0.0.3:/shares/manila_share_b8afc508_8487_442b_b170_ea65b07074a8 | + | | preferred = False | + | | is_admin_only = True | + | | id = 1f0e263f-370d-47d3-95f6-1be64088b9da | + | | share_instance_id = b8afc508-8487-442b-b170-ea65b07074a8 | + | share_server_id | None | + | host | manila@paris#shares | + | access_rules_status | active | + | snapshot_id | None | + | is_public | False | + | task_state | None | + | snapshot_support | True | + | id | b07dbebe-a328-403c-b402-c8871c89e3d1 | + | size | 1 | + | name | docs_resize | + | share_type | 14ee8575-aac2-44af-8392-d9c9d344f392 | + | has_replicas | False | + | replication_type | None | + | created_at | 2016-03-25T15:33:18.000000 | + | share_proto | NFS | + | consistency_group_id | None | + | project_id | 907004508ef4447397ce6741a8f037c1 | + | metadata | {} | + +----------------------+--------------------------------------------------------------------------+ diff --git a/doc/source/admin/shared-file-systems-share-types.rst b/doc/source/admin/shared-file-systems-share-types.rst new file mode 100644 index 0000000000..fa260b6ef7 --- /dev/null +++ b/doc/source/admin/shared-file-systems-share-types.rst @@ -0,0 +1,179 @@ +.. _shared_file_systems_share_types: + +=========== +Share types +=========== + +A share type enables you to filter or choose back ends before you create a +share and to set data for the share driver. A share type behaves in the same +way as a Block Storage volume type behaves. + +In the Shared File Systems configuration file ``manila.conf``, the +administrator can set the share type used by default for the share creation +and then create a default share type. + +To create a share type, use :command:`manila type-create` command as: + +.. code-block:: console + + manila type-create [--snapshot_support ] + [--is_public ] + + +where the ``name`` is the share type name, ``--is_public`` defines the level of +the visibility for the share type, ``snapshot_support`` and +``spec_driver_handles_share_servers`` are the extra specifications used to +filter back ends. Administrators can create share types with these extra +specifications for the back ends filtering: + +- ``driver_handles_share_servers``. Required. Defines the driver mode for share + server lifecycle management. Valid values are ``true``/``1`` and + ``false``/``0``. + Set to True when the share driver can manage, or handle, the share server + lifecycle. + Set to False when an administrator, rather than a share driver, manages + the bare metal storage with some net interface instead of the presence + of the share servers. + +- ``snapshot_support``. Filters back ends by whether they do or do not support + share snapshots. Default is ``True``. + Set to True to find back ends that support share snapshots. + Set to False to find back ends that do not support share snapshots. + +.. note:: + + The extra specifications set in the share types are operated in the + :ref:`shared_file_systems_scheduling`. + +Administrators can also set additional extra specifications for a share type +for the following purposes: + +- *Filter back ends*. Unqualified extra specifications written in + this format: ``extra_spec=value``. For example, **netapp_raid_type=raid4**. + +- *Set data for the driver*. Qualified extra specifications always written + with the prefix with a colon, except for the special ``capabilities`` + prefix, in this format: ``vendor:extra_spec=value``. For example, + **netapp:thin_provisioned=true**. + +The scheduler uses the special capabilities prefix for filtering. The scheduler +can only create a share on a back end that reports capabilities matching the +un-scoped extra-spec keys for the share type. For details, see `Capabilities +and Extra-Specs `_. + +Each driver implementation determines which extra specification keys it uses. +For details, see the documentation for the driver. + +An administrator can use the ``policy.json`` file to grant permissions for +share type creation with extra specifications to other roles. + +You set a share type to private or public and +:ref:`manage the access` to the private share types. By +default a share type is created as publicly accessible. Set +``--is_public`` to ``False`` to make the share type private. + +Share type operations +--------------------- + +To create a new share type you need to specify the name of the new share +type. You also require an extra spec ``driver_handles_share_servers``. +The new share type can also be public. + +.. code-block:: console + + $ manila type-create netapp1 False --is_public True + + $ manila type-list + +-----+--------+-----------+-----------+-----------------------------------+-----------------------+ + | ID | Name | Visibility| is_default| required_extra_specs | optional_extra_specs | + +-----+--------+-----------+-----------+-----------------------------------+-----------------------+ + | c0..| netapp1| public | - | driver_handles_share_servers:False| snapshot_support:True | + +-----+--------+-----------+-----------+-----------------------------------+-----------------------+ + +You can set or unset extra specifications for a share type +using **manila type-key set ** command. Since it is up +to each driver what extra specification keys it uses, see the documentation +for the specified driver. + +.. code-block:: console + + $ manila type-key netapp1 set thin_provisioned=True + +It is also possible to view a list of current share types and extra +specifications: + +.. code-block:: console + + $ manila extra-specs-list + +-------------+---------+-------------------------------------+ + | ID | Name | all_extra_specs | + +-------------+---------+-------------------------------------+ + | c0086582-...| netapp1 | snapshot_support : True | + | | | thin_provisioned : True | + | | | driver_handles_share_servers : True | + +-------------+---------+-------------------------------------+ + +Use :command:`manila type-key unset ` to unset an extra +specification. + +The public or private share type can be deleted with the +:command:`manila type-delete ` command. + +.. _share_type_access: + +Share type access +----------------- + +You can manage access to a private share type for different projects. +Administrators can provide access, remove access, and retrieve +information about access for a specified private share. + +Create a private type: + +.. code-block:: console + + $ manila type-create my_type1 True --is_public False + +----------------------+--------------------------------------+ + | Property | Value | + +----------------------+--------------------------------------+ + | required_extra_specs | driver_handles_share_servers : True | + | Name | my_type1 | + | Visibility | private | + | is_default | - | + | ID | 06793be5-9a79-4516-89fe-61188cad4d6c | + | optional_extra_specs | snapshot_support : True | + +----------------------+--------------------------------------+ + +.. note:: + + If you run :command:`manila type-list` only public share types appear. + To see private share types, run :command:`manila type-list` with + ``--all`` optional argument. + +Grant access to created private type for a demo and alt_demo projects +by providing their IDs: + +.. code-block:: console + + $ manila type-access-add my_type1 d8f9af6915404114ae4f30668a4f5ba7 + $ manila type-access-add my_type1 e4970f57f1824faab2701db61ee7efdf + +To view information about access for a private share, type ``my_type1``: + +.. code-block:: console + + $ manila type-access-list my_type1 + +----------------------------------+ + | Project_ID | + +----------------------------------+ + | d8f9af6915404114ae4f30668a4f5ba7 | + | e4970f57f1824faab2701db61ee7efdf | + +----------------------------------+ + +After granting access to the share, the target project +can see the share type in the list, and create private +shares. + +To deny access for a specified project, use +:command:`manila type-access-remove ` command. diff --git a/doc/source/admin/shared-file-systems-snapshots.rst b/doc/source/admin/shared-file-systems-snapshots.rst new file mode 100644 index 0000000000..6aab59aa50 --- /dev/null +++ b/doc/source/admin/shared-file-systems-snapshots.rst @@ -0,0 +1,140 @@ +.. _shared_file_systems_snapshots: + +=============== +Share snapshots +=============== + +The Shared File Systems service provides a snapshot mechanism to help users +restore data by running the :command:`manila snapshot-create` command. + +To export a snapshot, create a share from it, then mount the new share +to an instance. Copy files from the attached share into the archive. + +To import a snapshot, create a new share with appropriate size, attach it to +instance, and then copy a file from the archive to the attached file +system. + +.. note:: + + You cannot delete a share while it has saved dependent snapshots. + +Create a snapshot from the share: + +.. code-block:: console + + $ manila snapshot-create Share1 --name Snapshot1 --description "Snapshot of Share1" + +-------------+--------------------------------------+ + | Property | Value | + +-------------+--------------------------------------+ + | status | creating | + | share_id | aca648eb-8c03-4394-a5cc-755066b7eb66 | + | name | Snapshot1 | + | created_at | 2015-09-25T05:27:38.862040 | + | share_proto | NFS | + | id | 962e8126-35c3-47bb-8c00-f0ee37f42ddd | + | size | 1 | + | share_size | 1 | + | description | Snapshot of Share1 | + +-------------+--------------------------------------+ + +Update snapshot name or description if needed: + +.. code-block:: console + + $ manila snapshot-rename Snapshot1 Snapshot_1 --description "Snapshot of Share1. Updated." + +Check that status of a snapshot is ``available``: + +.. code-block:: console + + $ manila snapshot-show Snapshot1 + +-------------+--------------------------------------+ + | Property | Value | + +-------------+--------------------------------------+ + | status | available | + | share_id | aca648eb-8c03-4394-a5cc-755066b7eb66 | + | name | Snapshot1 | + | created_at | 2015-09-25T05:27:38.000000 | + | share_proto | NFS | + | id | 962e8126-35c3-47bb-8c00-f0ee37f42ddd | + | size | 1 | + | share_size | 1 | + | description | Snapshot of Share1 | + +-------------+--------------------------------------+ + +To restore your data from a snapshot, use :command:`manila create` with +key ``--snapshot-id``. This creates a new share from an +existing snapshot. Create a share from a snapshot and check whether +it is available: + +.. code-block:: console + + $ manila create nfs 1 --name Share2 --metadata source=snapshot --description "Share from a snapshot." --snapshot-id 962e8126-35c3-47bb-8c00-f0ee37f42ddd + +-----------------------------+--------------------------------------+ + | Property | Value | + +-----------------------------+--------------------------------------+ + | status | None | + | share_type_name | default | + | description | Share from a snapshot. | + | availability_zone | None | + | share_network_id | None | + | export_locations | [] | + | share_server_id | None | + | host | None | + | snapshot_id | 962e8126-35c3-47bb-8c00-f0ee37f42ddd | + | is_public | False | + | task_state | None | + | snapshot_support | True | + | id | b6b0617c-ea51-4450-848e-e7cff69238c7 | + | size | 1 | + | name | Share2 | + | share_type | c0086582-30a6-4060-b096-a42ec9d66b86 | + | created_at | 2015-09-25T06:25:50.240417 | + | export_location | None | + | share_proto | NFS | + | consistency_group_id | None | + | source_cgsnapshot_member_id | None | + | project_id | 20787a7ba11946adad976463b57d8a2f | + | metadata | {u'source': u'snapshot'} | + +-----------------------------+--------------------------------------+ + + $ manila show Share2 + +-----------------------------+-------------------------------------------+ + | Property | Value | + +-----------------------------+-------------------------------------------+ + | status | available | + | share_type_name | default | + | description | Share from a snapshot. | + | availability_zone | nova | + | share_network_id | 5c3cbabb-f4da-465f-bc7f-fadbe047b85a | + | export_locations | 10.254.0.3:/shares/share-1dc2a471-3d47-...| + | share_server_id | 41b7829d-7f6b-4c96-aea5-d106c2959961 | + | host | manila@generic1#GENERIC1 | + | snapshot_id | 962e8126-35c3-47bb-8c00-f0ee37f42ddd | + | is_public | False | + | task_state | None | + | snapshot_support | True | + | id | b6b0617c-ea51-4450-848e-e7cff69238c7 | + | size | 1 | + | name | Share2 | + | share_type | c0086582-30a6-4060-b096-a42ec9d66b86 | + | created_at | 2015-09-25T06:25:50.000000 | + | share_proto | NFS | + | consistency_group_id | None | + | source_cgsnapshot_member_id | None | + | project_id | 20787a7ba11946adad976463b57d8a2f | + | metadata | {u'source': u'snapshot'} | + +-----------------------------+-------------------------------------------+ + +You can soft-delete a snapshot using :command:`manila snapshot-delete +`. If a snapshot is in busy state, and during +the delete an ``error_deleting`` status appeared, administrator can +force-delete it or explicitly reset the state. + +Use :command:`snapshot-reset-state [--state ] ` to update +the state of a snapshot explicitly. A valid value of a status are +``available``, ``error``, ``creating``, ``deleting``, ``error_deleting``. +If no state is provided, the ``available`` state will be used. + +Use :command:`manila snapshot-force-delete ` to force-delete +a specified share snapshot in any state. diff --git a/doc/source/admin/shared-file-systems-troubleshoot.rst b/doc/source/admin/shared-file-systems-troubleshoot.rst new file mode 100644 index 0000000000..fe5bdb8a87 --- /dev/null +++ b/doc/source/admin/shared-file-systems-troubleshoot.rst @@ -0,0 +1,107 @@ +.. _shared_file_systems_troubleshoot: + +======================================== +Troubleshoot Shared File Systems service +======================================== + +Failures in Share File Systems service during a share creation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Problem +------- + +New shares can enter ``error`` state during the creation process. + +Solution +-------- + +#. Make sure, that share services are running in debug mode. If the debug mode + is not set, you will not get any tips from logs how to fix your issue. + +#. Find what share service holds a specified share. To do that, run command + :command:`manila show ` and find a share host in the + output. Host uniquely identifies what share service holds the broken share. + +#. Look thought logs of this share service. Usually, it can be found at + ``/etc/var/log/manila-share.log``. This log should contain kind of + traceback with extra information to help you to find the origin of issues. + +No valid host was found +~~~~~~~~~~~~~~~~~~~~~~~ + +Problem +------- + +If a share type contains invalid extra specs, the scheduler will not be +able to locate a valid host for the shares. + +Solution +-------- + +To diagnose this issue, make sure that scheduler service is running in +debug mode. Try to create a new share and look for message ``Failed to +schedule create_share: No valid host was found.`` in +``/etc/var/log/manila-scheduler.log``. + +To solve this issue look carefully through the list of extra specs in +the share type, and the list of share services reported capabilities. +Make sure that extra specs are pointed in the right way. + +Created share is unreachable +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Problem +------- + +By default, a new share does not have any active access rules. + +Solution +-------- + +To provide access to new share, you need to create +appropriate access rule with the right value. +The value must defines access. + +Service becomes unavailable after upgrade +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Problem +------- + +After upgrading the Shared File Systems service from version v1 to version +v2.x, you must update the service endpoint in the OpenStack Identity service. +Otherwise, the service may become unavailable. + +Solution +-------- + +#. To get the service type related to the Shared File Systems service, run: + + .. code-block:: console + + # openstack endpoint list + + # openstack endpoint show + + You will get the endpoints expected from running the Shared File Systems + service. + +#. Make sure that these endpoints are updated. Otherwise, delete the outdated + endpoints and create new ones. + +Failures during management of internal resources +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Problem +------- + +The Shared File System service manages internal resources effectively. +Administrators may need to manually adjust internal resources to +handle failures. + +Solution +-------- + +Some drivers in the Shared File Systems service can create service entities, +like servers and networks. If it is necessary, you can log in to +project ``service`` and take manual control over it. diff --git a/doc/source/index.rst b/doc/source/index.rst index b4627e5926..6f187bd40b 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -49,7 +49,7 @@ Admin Docs .. toctree:: :maxdepth: 1 - admin/index + admin/shared-file-systems-intro.rst Contributor/Developer Docs ==========================