Human readable export location documentation
Human readable export location admin and user documentation. Closes-Bug: #2057702 Change-Id: I33d5609baf5c88b0cc71ed7dc5b6685a907162b2
This commit is contained in:
parent
551bbe366e
commit
d11e6b7176
@ -62,6 +62,7 @@ deployment.
|
|||||||
shared-file-systems-upgrades.rst
|
shared-file-systems-upgrades.rst
|
||||||
shared-file-systems-share-revert-to-snapshot.rst
|
shared-file-systems-share-revert-to-snapshot.rst
|
||||||
shared-file-systems-share-server-migration.rst
|
shared-file-systems-share-server-migration.rst
|
||||||
|
share_mount_point_name.rst
|
||||||
share_back_ends_feature_support_mapping
|
share_back_ends_feature_support_mapping
|
||||||
capabilities_and_extra_specs
|
capabilities_and_extra_specs
|
||||||
group_capabilities_and_extra_specs
|
group_capabilities_and_extra_specs
|
||||||
|
73
doc/source/admin/share_mount_point_name.rst
Normal file
73
doc/source/admin/share_mount_point_name.rst
Normal 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.
|
@ -61,6 +61,10 @@ important terms:
|
|||||||
| availability_zones | a list of one or | shares are limited to these availability zones |
|
| availability_zones | a list of one or | shares are limited to these availability zones |
|
||||||
| | more 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::
|
.. note::
|
||||||
|
|
||||||
@ -69,6 +73,8 @@ important terms:
|
|||||||
- When the ``availability_zones`` extra specification is not present in
|
- 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 share type, the share type can be used in all availability zones of
|
||||||
the cloud.
|
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
|
- ``status`` of resources: Resources that you create or modify with manila
|
||||||
may not be "available" immediately. The API service is designed to respond
|
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 |
|
| 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
|
Grant and revoke share access
|
||||||
-----------------------------
|
-----------------------------
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user