openstack
/
manila
Code Issues Proposed changes

Merge "Add admin ref for manage/unmanage servers DHSS=True"

This commit is contained in:
Zuul 2019-06-25 22:21:25 +00:00 committed by Gerrit Code Review
parent 1709fd7fc2 408348b5a4
commit 8fa8bad8cf
3 changed files with 220 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/source/admin/index.rst
View File

@ -45,6 +45,7 @@ deployment.
shared-file-systems-key-concepts.rst
shared-file-systems-share-management.rst
shared-file-systems-share-server-management.rst
shared-file-systems-share-migration.rst
shared-file-systems-share-types.rst
shared-file-systems-snapshots.rst

52
doc/source/admin/shared-file-systems-manage-and-unmanage-share.rst
View File

@ -19,16 +19,25 @@ status if needed.
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.
.. note::
To unmanage managed share, run the :command:`manila unmanage <share>`
command. Then try to print the information about the share. The
returned result should indicate that Shared File Systems service won't
The ``unmanage`` operation is not supported for shares that were created on
top of share servers and created with share networks until Shared File
Systems API version ``2.49`` (Stein/Manila 8.0.0 release).
.. important::
Shares that have dependent snapshots or share replicas cannot be removed
from the Shared File Systems service unless the snapshots have been removed
or unmanaged and the share replicas have been removed.
Unmanaging a share removes it from the management of the Shared File Systems
service without deleting the share. It is a non-disruptive operation and
existing clients are not disconnected, and the functionality is aimed at aiding
infrastructure operations and maintenance workflows. To unmanage a share,
run the :command:`manila unmanage <share>` 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
@ -41,6 +50,11 @@ find the share:
Manage a share
--------------
.. note::
The ``manage`` operation is not supported for shares that are exported on
share servers via share networks until Shared File Systems API version
``2.49`` (Stein/Manila 8.0.0 release).
To register the non-managed share in the File System service, run the
:command:`manila manage` command:
@ -48,6 +62,7 @@ To register the non-managed share in the File System service, run the
manila manage [--name <name>] [--description <description>]
[--share_type <share-type>]
[--share-server-id <share_server_id>]
[--driver_options [<key=value> [<key=value> ...]]]
<service_host> <protocol> <export_path>
@ -74,10 +89,21 @@ The positional arguments are:
- MAPRFS. maprfs:///share-0 -C -Z -N foo.
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.
The optional arguments are:
- name. The name of the share that is being managed.
- share_type. The share type of the share that is being managed. If not
specified, the service will try to manage the share with the configured
default share type.
- share_server_id. must be provided to manage shares within share networks.
This argument can only be used with File Systems API version ``2.49``
(Stein/Manila 8.0.0 release) and beyond.
- driver_options. An optional set of one or more key and value pairs that
describe driver options. As a result, a special share type named
``for_managing`` was used in example.
To manage share, run:

180
doc/source/admin/shared-file-systems-share-server-management.rst Normal file
View File

@ -0,0 +1,180 @@
.. _shared_file_systems_share_server_management:
=============
Share servers
=============
A share server is a resource created by the Shared File Systems service when
the driver is operating in the `driver_handles_share_servers = True` mode.
A share server exports users' shares, manages their exports and access rules.
Share servers are abstracted away from end users. Drivers operating in
`driver_handles_share_servers = True` mode manage the lifecycle of these share
servers automatically. Administrators can however remove the share servers from
the management of the Shared File Systems service without destroying them. They
can also bring in existing share servers under the Shared File Systems service.
They can list all available share servers and update their status attribute.
They can delete an specific share server if it has no dependent shares.
=======================
Share server management
=======================
To ``manage`` a share server means that when the driver is operating in the
``driver_handles_share_servers = True`` mode, the administrator can bring a
pre-existing share server under the management of the Shared File Systems
service.
To ``unmanage`` means that the administrator is able to unregister an existing
share server from the Shared File Systems service without deleting it from the
storage back end. To be unmanaged, the referred share server cannot have any
shares known to the Shared File Systems service.
Manage a share server
---------------------
To bring a share server under the Shared File System service, use the
:command:`manila share-server-manage` command:
.. code-block:: console
manila share-server-manage
[--driver_options [<key=value> [<key=value> ...]]]
<host> <share_network> <identifier>
The positional arguments are:
- host. The manage-share service host in ``host@backend`` format, which
consists of the host name for the back end and the name of the back end.
- share_network. The share network where the share server is contained.
- identifier. The identifier of the share server on the back end storage.
The ``driver_options`` is an optional set of one or more driver-specific
metadata items as key and value pairs. The specific key-value pairs necessary
vary from driver to driver. Consult the driver-specific documentation to
determine if any specific parameters must be supplied. Ensure that the share
type has the ``driver_handles_share_servers = True`` extra-spec.
If using an OpenStack Networking (Neutron) based plugin, ensure that:
- There are some ports created, which correspond to the share server
interfaces.
- The correct IP addresses are allocated to these ports.
- ``manila:share`` is set as the owner of these ports.
To manage a share server, run:
.. code-block:: console
$ manila share-server-manage \
manila@paris \
share_net_test \
backend_server_1 \
+--------------------+------------------------------------------+
| Property | Value |
+--------------------+------------------------------------------+
| id | 441d806f-f0e0-4c90-b7e2-a553c6aa76b2 |
| project_id | 907004508ef4447397ce6741a8f037c1 |
| updated_at | None |
| status | manage_starting |
| host | manila@paris |
| share_network_name | share_net_test |
| share_network_id | c895fe26-92be-4152-9e6c-f2ad230efb13 |
| created_at | 2019-04-25T18:25:23.000000 |
| backend_details | {} |
| is_auto_deletable | False |
| identifier | backend_server_1 |
+--------------------+------------------------------------------+
.. note::
The ``is_auto_deletable`` property is used by the Shared File Systems
service to identify a share server that can be deleted by internal
routines.
The service can automatically delete share servers if there are no
shares associated with them. To delete a share server when the last
share is deleted, set the option: ``delete_share_server_with_last_share``.
If a scheduled cleanup is desired instead,
``automatic_share_server_cleanup`` and
``unused_share_server_cleanup_interval`` options can be set. Only one of
the cleanup methods can be used at one time.
Any share server that has a share unmanaged from it cannot be
automatically deleted by the Shared File Systems service. The same is true
for share servers that have been managed into the service. Cloud
administrators can delete such share servers manually if desired.
Unmanage a share server
-----------------------
To ``unmanage`` a share server, run
:command:`manila share-server-unmanage <share-server>`.
.. code-block:: console
$ manila share-server-unmanage 441d806f-f0e0-4c90-b7e2-a553c6aa76b2
$ manila share-server-show 441d806f-f0e0-4c90-b7e2-a553c6aa76b2
ERROR: Share server 441d806f-f0e0-4c90-b7e2-a553c6aa76b2 could not be
found.
Reset the share server state
----------------------------
As administrator you are able to reset a share server state. To reset the state
of a share server, run
:command:`manila share-server-reset-state <share-server> --state <state>`.
The positional arguments are:
- share-server. The share server name or id.
- state. The state to be assigned to the share server. The options are:
- ``active``
- ``error``
- ``deleting``
- ``creating``
- ``managing``
- ``unmanaging``
- ``unmanage_error``
- ``manage_error``
List share servers
------------------
To list share servers, run
:command:`manila share-server-list` command:
.. code-block:: console
manila share-server-list [--host <hostname>] [--status <status>]
[--share-network <share_network>]
[--project-id <project_id>]
[--columns <columns>]
All the arguments above are optional. They can ben used to filter share
servers. The options to filter:
- host. Shows all the share servers pertaining to the specified host.
- status. Shows all the share servers that are in the specified status.
- share_network. Shows all the share servers that pertain in the same share
network.
- project_id. Shows all the share servers pertaining to the same project.
- columns. The administrator specifies which columns to display in the result
of the list operation.
.. code-block:: console
$ manila share-server-list
+--------------------------------------+--------------+--------+----------------+----------------------------------+------------+
| Id | Host | Status | Share Network | Project Id | Updated_at |
+--------------------------------------+--------------+--------+----------------+----------------------------------+------------+
| 441d806f-f0e0-4c90-b7e2-a553c6aa76b2 | manila@paris | active | share_net_test | fd6d30efa5ff4c99834dc0d13f96e8eb | None |
+--------------------------------------+--------------+--------+----------------+----------------------------------+------------+