openstack/manila
Code Issues Proposed changes

Human readable export location documentation

Browse Source 
Human readable export location admin and user
documentation.

Closes-Bug: #2057702
Change-Id: I33d5609baf5c88b0cc71ed7dc5b6685a907162b2
This commit is contained in:
jayaanand borra 2024-03-19 14:37:23 -04:00
parent 551bbe366e
commit d11e6b7176
3 changed files with 213 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -62,6 +62,7 @@ deployment.
shared-file-systems-upgrades.rst
shared-file-systems-share-revert-to-snapshot.rst
shared-file-systems-share-server-migration.rst
share_mount_point_name.rst
share_back_ends_feature_support_mapping
capabilities_and_extra_specs
group_capabilities_and_extra_specs

73
doc/source/admin/share_mount_point_name.rst Normal file
View File

@ -0,0 +1,73 @@
.. _shared_mount_point_name:
Mount Point Name Support
========================
The Shared File Systems service supports user defined mount point names.
This feature allows users to specify a custom `mount_point_name` during
share creation, which will be reflected in the share's export location.
However, for this feature to be available to users, administrators must
enable an extra-spec in the share type, `mount_point_name_support`, and
set an extra-spec named `provisioning:mount_point_prefix`.
If the `provisioning:mount_point_prefix` extra-spec is not set, the
`project_id` from the `RequestContext` is used as a fallback. However,
using the `project_id` as a prefix can restrict the transfer of share
ownership, and manual action required to facilitate the transfer.
.. note::
- In order to use this feature, the available backend in your deployment
must have support for it. The list of backends that support this feature
in the manila can be found in the
:doc:`share_back_ends_feature_support_mapping`.
- This feature is only available in API version 2.84 and beyond.
- The extra-spec type `mount_point_name_support` required for
this feature to work.
- When the `project_id` is used as a prefix due to the absence of the
`provisioning:mount_point_prefix` extra-spec, the transfer of share
ownership may be restricted, and manual action may be required.
Administrator Guide
===================
1. **Configuring `mount_point_name_support` and
`provisioning:mount_point_prefix`**
.. code-block:: bash
openstack share type set <share_type> --extra-spec \
mount_point_name_support="<is> True"
provisioning:mount_point_prefix=<prefix>
Replace `<share_type>` with the name of the share type you are configuring,
and `<prefix>` with the desired prefix. The `<prefix>` should be a string
containing ASCII alphabets and optionally, the underscore character.
2. **Default Behavior and Security Considerations**
If `provisioning:mount_point_prefix` is not set, the system will use the
`project_id` as the default prefix for the `mount_point_name`. However, be
aware that setting `provisioning:mount_point_prefix` to a constant string
and sharing the share type with multiple projects could potentially leak
information about the existence of other shares. This could be considered a
security hole and should be avoided.
3. **Share Transfer**
During a share transfer, if `provisioning:mount_point_prefix` contains a
`project_id`, the system will refuse to perform the transfer and return an
HTTP 400 error. This indicates that the share has some project identity
that requires administrator intervention. To perform the transfer,
administrators will need to unmanage the share from the current project and
manage it into the target project.
4. **Constructing `mount_point_name`**
The `mount_point_name` is constructed by combining the prefix from the
share type (set by `provisioning:mount_point_prefix`) and the suffix
provided by the user. This combined string must be ASCII alphanumeric,
allowing only underscores as special characters. If this validation fails,
the system will log an error and return a message indicating that the
`mount_point_name` is not appropriate.

139
doc/source/user/create-and-manage-shares.rst
View File

@ -61,6 +61,10 @@ important terms:
| availability_zones | a list of one or | shares are limited to these availability zones |
| | more availability zones | |
+------------------------------------+-------------------------+---------------------------------------------------------+
| mount_point_name_support | true or false | share can or cannot have customized export location |
+------------------------------------+-------------------------+---------------------------------------------------------+
| provisioning:mount_point_prefix | string | prefix used for custom export location |
+------------------------------------+-------------------------+---------------------------------------------------------+
.. note::
@ -69,6 +73,8 @@ important terms:
- When the ``availability_zones`` extra specification is not present in
the share type, the share type can be used in all availability zones of
the cloud.
- When ``mount_point_name_support`` extra specification is not present in the
share type, or is set to False, you cannot customize the export location.
- ``status`` of resources: Resources that you create or modify with manila
may not be "available" immediately. The API service is designed to respond
@ -366,6 +372,139 @@ Create a share
| 40de4f4c-4588-4d9c-844b-f74d8951053a | myshare2 | 1 | NFS | available | False | default | nosb-devstack@lisboa#LISBOA | nova |
+--------------------------------------+-----------+------+-------------+-----------+-----------+-----------------+-----------------------------+-------------------+
* Create a share using `mount_point_name`.
When `mount_point_name_support` is enabled by your administrator, you
can specify a custom mount point name during share creation. This name
will be used in conjunction with the prefix set by the administrator
to form the share's export location.
The general workflow for using `mount_point_name`:
- ``Creating a new share``: Specify a custom `mount_point_name` using the
`--mount-point-name` flag. The `mount_point_name` should not exceed 255
characters in length.
.. code-block:: bash
openstack share create NFS 1 --share-type gold_provisioning_prefix \
--name MyShare --mount-point-name mount_abc1 \
--share-network 19d78275-55cb-4684-81f2-ec9c07701563
+---------------------------------------+--------------------------------------+
| Field | Value |
+=======================================+======================================+
| access_rules_status | active |
+---------------------------------------+--------------------------------------+
| availability_zone | None |
+---------------------------------------+--------------------------------------+
| create_share_from_snapshot_support | False |
+---------------------------------------+--------------------------------------+
| created_at | 2024-03-20T20:32:50.819345 |
+---------------------------------------+--------------------------------------+
| description | None |
+---------------------------------------+--------------------------------------+
| has_replicas | False |
+---------------------------------------+--------------------------------------+
| host | |
+---------------------------------------+--------------------------------------+
| id | 138a6884-7a9b-4d9a-9ac1-f565701a4b83 |
+---------------------------------------+--------------------------------------+
| is_public | False |
+---------------------------------------+--------------------------------------+
| is_soft_deleted | False |
+---------------------------------------+--------------------------------------+
| metadata | {} |
+---------------------------------------+--------------------------------------+
| mount_snapshot_support | False |
+---------------------------------------+--------------------------------------+
| name | MyShare |
+---------------------------------------+--------------------------------------+
| progress | None |
+---------------------------------------+--------------------------------------+
| project_id | 44754d5c4aea4c8c8d619bb6b4ebeb17 |
+---------------------------------------+--------------------------------------+
| replication_type | None |
+---------------------------------------+--------------------------------------+
| revert_to_snapshot_support | False |
+---------------------------------------+--------------------------------------+
| scheduled_to_be_deleted_at | None |
+---------------------------------------+--------------------------------------+
| share_group_id | None |
+---------------------------------------+--------------------------------------+
| share_network_id | 19d78275-55cb-4684-81f2-ec9c07701563 |
+---------------------------------------+--------------------------------------+
| share_proto | NFS |
+---------------------------------------+--------------------------------------+
| share_server_id | None |
+---------------------------------------+--------------------------------------+
| share_type | ee1995d8-6827-4711-a58d-38ee00f24a75 |
+---------------------------------------+--------------------------------------+
| share_type_name | gold_provisioning_prefix |
+---------------------------------------+--------------------------------------+
| size | 1 |
+---------------------------------------+--------------------------------------+
| snapshot_id | None |
+---------------------------------------+--------------------------------------+
| snapshot_support | False |
+---------------------------------------+--------------------------------------+
| source_backup_id | None |
+---------------------------------------+--------------------------------------+
| source_share_group_snapshot_member_id | None |
+---------------------------------------+--------------------------------------+
| status | creating |
+---------------------------------------+--------------------------------------+
| task_state | None |
+---------------------------------------+--------------------------------------+
| user_id | fbdba3d017b2484f9773033e3fc0c6ae |
+---------------------------------------+--------------------------------------+
| volume_type | gold_provisioning_prefix |
+---------------------------------------+--------------------------------------+
* To view the details of a share created with custom mount_point_name.
.. code-block:: console
$ openstack share show 138a6884-7a9b-4d9a-9ac1-f565701a4b83
+---------------------------------------+-------------------------------------------------------------------------+
| Field | Value |
+---------------------------------------+-------------------------------------------------------------------------+
| access_rules_status | active |
| availability_zone | nova |
| create_share_from_snapshot_support | False |
| created_at | 2024-03-20T20:32:50.819345 |
| description | None |
| export_locations | |
| | id = 1f5d8a51-965e-4062-a1e1-03ca146ad277 |
| | path = <ip>:/gold_mount_abc1 |
| | preferred = True |
| | share_instance_id = 62a4d622-a3c8-4915-adca-54a7fe5789bf |
| | is_admin_only = False |
| | id = ea7c936a-d94b-47bd-8a35-4b2f1f7b5e5a |
| | path = <ip>:/gold_mount_abc1 |
| | preferred = False |
| | share_instance_id = 62a4d622-a3c8-4915-adca-54a7fe5789bf |
| | is_admin_only = False |
| has_replicas | False |
| host | host@share_server_dhss_true#AstraInfra |
| id | 138a6884-7a9b-4d9a-9ac1-f565701a4b83 |
| is_public | False |
| is_soft_deleted | False |
| mount_snapshot_support | False |
| name | MyShare |
| progress | 100% |
| project_id | 44754d5c4aea4c8c8d619bb6b4ebeb17 |
| properties | |
| replication_type | None |
| revert_to_snapshot_support | False |
| scheduled_to_be_deleted_at | None |
| share_group_id | None |
| share_network_id | 19d78275-55cb-4684-81f2-ec9c07701563 |
| share_proto | NFS |
+---------------------------------------+-------------------------------------------------------------------------+
Grant and revoke share access
-----------------------------