From 84e7f4e5426fcee5941b8e4cb6d53040be8cd0ee Mon Sep 17 00:00:00 2001 From: SolKuczala Date: Wed, 20 Mar 2019 20:56:09 +0000 Subject: [PATCH] Adding documentation for User Messages in Manila Documentation -Reference to the User Messages CLI usage at: https://docs.openstack.org/manila/latest/cli/manila.html https://docs.openstack.org/manila/latest/user/create-and-manage-shares. Closes-Bug: #1796986 Change-Id: Ia85736693d7f536766e0e0980f88805c61aa8325 --- doc/source/cli/manila.rst | 100 +++++ doc/source/user/index.rst | 1 + .../troubleshooting-asynchronous-failures.rst | 343 ++++++++++++++++++ 3 files changed, 444 insertions(+) create mode 100644 doc/source/user/troubleshooting-asynchronous-failures.rst diff --git a/doc/source/cli/manila.rst b/doc/source/cli/manila.rst index 47398bfef8..1fee58cfb0 100644 --- a/doc/source/cli/manila.rst +++ b/doc/source/cli/manila.rst @@ -110,6 +110,15 @@ manila usage ``manage`` Manage share not handled by Manila (Admin only). +``message-delete`` + Remove one or more messages. + +``message-list`` + Lists all messages. + +``message-show`` + Show message's details. + ``metadata`` Set or delete metadata on a share. @@ -982,6 +991,97 @@ Manage share not handled by Manila (Admin only). tenants are able to see it or not. Available only for microversion >= 2.8. +.. _manila_message-delete: + +manila message-delete +---------------------- + +.. code-block:: console + + usage: manila message-delete [ ...] + +Remove one or more messages. + +**Positional arguments:** + +```` + ID of the message(s). + +.. _manila_message-list: + +manila message-list +---------------------- + +.. code-block:: console + + usage: manila message-list [--resource_id ] + [--resource_type ] [--action_id ] + [--detail_id ] [--request_id ] + [--level ] [--limit ] + [--offset ] [--sort-key ] + [--sort-dir ] [--columns ] + +Lists all messages. + +**Optional arguments:** + +``--resource_id , --resource-id , --resource `` + Filters results by a resource uuid. (Default=None). + +``--resource_type , --resource-type `` + Filters results by a resource type. (Default=None). + Example: "manila message-list --resource_type share" + +``--action_id , --action-id , --action `` + Filters results by action id. (Default=None). + +``--detail_id , --detail-id , --detail `` + Filters results by detail id. (Default=None). + +``--request_id , --request-id , --request `` + Filters results by request id. (Default=None). + +``--level , --message_level , --message-level `` + Filters results by the message level. (Default=None). + Example: "manila message-list --level ERROR". + +``--limit `` + Maximum number of messages to return. (Default=None) + +``--offset `` + Start position of message listing. + +``--sort-key , --sort_key `` + Key to be sorted, available keys are ('id', + 'project_id', 'request_id', 'resource_type', + 'action_id', 'detail_id', 'resource_id', + 'message_level', 'expires_at', 'request_id', + 'created_at'). (Default=desc). + +``--sort-dir , --sort_dir `` + Sort direction, available values are ('asc', 'desc'). + OPTIONAL: Default=None. + +``--columns `` + Comma separated list of columns to be displayed + example --columns "resource_id, user_message". + +.. _manila_message-show: + +manila message-show +---------------------- + +.. code-block:: console + + usage: manila message-show + +Show details about a message. + +**Positional arguments:** + +```` + ID of the message. + .. _manila_metadata: manila metadata diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index d0fa8c225b..4e36ebe783 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -20,3 +20,4 @@ User API create-and-manage-shares + troubleshooting-asynchronous-failures diff --git a/doc/source/user/troubleshooting-asynchronous-failures.rst b/doc/source/user/troubleshooting-asynchronous-failures.rst new file mode 100644 index 0000000000..c8da0caea6 --- /dev/null +++ b/doc/source/user/troubleshooting-asynchronous-failures.rst @@ -0,0 +1,343 @@ +===================================== +Troubleshooting asynchronous failures +===================================== + +The Shared File Systems service performs many user actions asynchronously. +For example, when a new share is created, the request is immediately +acknowledged with a response containing the metadata of the share. +Users can then query the resource and check the ``status`` attribute +of the share. Usually an ``...ing`` status indicates that actions are performed +asynchronously. For example, a new share's ``status`` attribute is set to +``creating`` by the service. If these asynchronous operations fail, the +resource's status will be set to ``error``. More information about the error +can be obtained with the help of the CLI client. + +Scenario +~~~~~~~~ +In this example, the user wants to create a share to host software libraries +on several virtual machines. The example deliberately introduces two share +creation failures to illustrate how to use the command line to retrieve user +support messages. + + +#. In order to create a share, you need to specify the share type that meets + your requirements. Cloud administrators create share types; see these + available share types: + + .. code-block:: console + + clouduser1@client:~$ manila type-list + +--------------------------------------+-------------+------------+------------+--------------------------------------+--------------------------------------------+-------------+ + | ID | Name | visibility | is_default | required_extra_specs | optional_extra_specs | Description | + +--------------------------------------+-------------+------------+------------+--------------------------------------+--------------------------------------------+-------------+ + | 1cf5d45a-61b3-44d1-8ec7-89a21f51a4d4 | dhss_false | public | YES | driver_handles_share_servers : False | create_share_from_snapshot_support : True | None | + | | | | | | mount_snapshot_support : False | | + | | | | | | revert_to_snapshot_support : False | | + | | | | | | snapshot_support : True | | + | 277c1089-127f-426e-9b12-711845991ea1 | dhss_true | public | - | driver_handles_share_servers : True | create_share_from_snapshot_support : True | None | + | | | | | | mount_snapshot_support : False | | + | | | | | | revert_to_snapshot_support : False | | + | | | | | | snapshot_support : True | | + +--------------------------------------+-------------+------------+------------+--------------------------------------+--------------------------------------------+-------------+ + + + In this example, two share types are available. + + +#. To use a share type that specifies driver_handles_share_servers=True + capability, you must create a "share network" on which to export the + share. + + .. code-block:: console + + clouduser1@client:~$ openstack subnet list + +--------------------------------------+---------------------+--------------------------------------+---------------------+ + | ID | Name | Network | Subnet | + +--------------------------------------+---------------------+--------------------------------------+---------------------+ + | 78c6ac57-bba7-4922-ab81-16cde31c2d06 | private-subnet | 74d5cfb3-5dd0-43f7-b1b2-5b544cb16212 | 10.0.0.0/26 | + | a344682c-718d-4825-a87a-3622b4d3a771 | ipv6-private-subnet | 74d5cfb3-5dd0-43f7-b1b2-5b544cb16212 | fd36:18fc:a8e9::/64 | + +--------------------------------------+---------------------+--------------------------------------+---------------------+ + + + +#. Create a "share network" from a private tenant network: + + .. code-block:: console + + clouduser1@client:~$ manila share-network-create --name mynet --neutron-net-id 74d5cfb3-5dd0-43f7-b1b2-5b544cb16212 --neutron-subnet-id 78c6ac57-bba7-4922-ab81-16cde31c2d06 + +-------------------+--------------------------------------+ + | Property | Value | + +-------------------+--------------------------------------+ + | network_type | None | + | name | mynet | + | segmentation_id | None | + | created_at | 2018-10-09T21:32:22.485399 | + | neutron_subnet_id | 78c6ac57-bba7-4922-ab81-16cde31c2d06 | + | updated_at | None | + | mtu | None | + | gateway | None | + | neutron_net_id | 74d5cfb3-5dd0-43f7-b1b2-5b544cb16212 | + | ip_version | None | + | cidr | None | + | project_id | cadd7139bc3148b8973df097c0911016 | + | id | 0b0fc320-d4b5-44a1-a1ae-800c56de550c | + | description | None | + +-------------------+--------------------------------------+ + + clouduser1@client:~$ manila share-network-list + +--------------------------------------+-------+ + | id | name | + +--------------------------------------+-------+ + | 6c7ef9ef-3591-48b6-b18a-71a03059edd5 | mynet | + +--------------------------------------+-------+ + + +#. Create the share: + + .. code-block:: console + + clouduser1@client:~$ manila create nfs 1 --name software_share --share-network mynet --share-type dhss_true + +---------------------------------------+--------------------------------------+ + | Property | Value | + +---------------------------------------+--------------------------------------+ + | status | creating | + | share_type_name | dhss_true | + | description | None | + | availability_zone | None | + | share_network_id | 6c7ef9ef-3591-48b6-b18a-71a03059edd5 | + | share_server_id | None | + | share_group_id | None | + | host | | + | revert_to_snapshot_support | False | + | access_rules_status | active | + | snapshot_id | None | + | create_share_from_snapshot_support | False | + | is_public | False | + | task_state | None | + | snapshot_support | False | + | id | 243f3a51-0624-4bdd-950e-7ed190b53b67 | + | size | 1 | + | source_share_group_snapshot_member_id | None | + | user_id | 61aef4895b0b41619e67ae83fba6defe | + | name | software_share | + | share_type | 277c1089-127f-426e-9b12-711845991ea1 | + | has_replicas | False | + | replication_type | None | + | created_at | 2018-10-09T21:12:21.000000 | + | share_proto | NFS | + | mount_snapshot_support | False | + | project_id | cadd7139bc3148b8973df097c0911016 | + | metadata | {} | + +---------------------------------------+--------------------------------------+ + + +#. View the status of the share: + + .. code-block:: console + + clouduser1@client:~$ manila list + +--------------------------------------+----------------+------+-------------+--------+-----------+-----------------+------+-------------------+ + | ID | Name | Size | Share Proto | Status | Is Public | Share Type Name | Host | Availability Zone | + +--------------------------------------+----------------+------+-------------+--------+-----------+-----------------+------+-------------------+ + | 243f3a51-0624-4bdd-950e-7ed190b53b67 | software_share | 1 | NFS | error | False | dhss_true | | None | + +--------------------------------------+----------------+------+-------------+--------+-----------+-----------------+------+-------------------+ + + In this example, an error occurred during the share creation. + + +#. To view the generated user message, use the ``message-list`` command. + Use ``--resource-id`` to filter messages for a specific share + resource. + + .. code-block:: console + + clouduser1@client:~$ manila message-list + +--------------------------------------+---------------+--------------------------------------+-----------+----------------------------------------------------------------------------------------------------------+-----------+----------------------------+ + | ID | Resource Type | Resource ID | Action ID | User Message | Detail ID | Created At | + +--------------------------------------+---------------+--------------------------------------+-----------+----------------------------------------------------------------------------------------------------------+-----------+----------------------------+ + | 7d411c3c-46d9-433f-9e21-c04ca30b209c | SHARE | 243f3a51-0624-4bdd-950e-7ed190b53b67 | 001 | allocate host: No storage could be allocated for this share request, Capabilities filter didn't succeed. | 008 | 2018-10-09T21:12:21.000000 | + +--------------------------------------+---------------+--------------------------------------+-----------+----------------------------------------------------------------------------------------------------------+-----------+----------------------------+ + + In User Message column, you can see that the Shared File System service + failed to create the share because of a capabilities mismatch. + + +#. To view more information, use the ``message-show`` command, + followed by the ID of the message from the message-list command: + + .. code-block:: console + + clouduser1@client:~$ manila message-show 7d411c3c-46d9-433f-9e21-c04ca30b209c + +---------------+----------------------------------------------------------------------------------------------------------+ + | Property | Value | + +---------------+----------------------------------------------------------------------------------------------------------+ + | request_id | req-0a875292-6c52-458b-87d4-1f945556feac | + | detail_id | 008 | + | expires_at | 2018-11-08T21:12:21.000000 | + | resource_id | 243f3a51-0624-4bdd-950e-7ed190b53b67 | + | user_message | allocate host: No storage could be allocated for this share request, Capabilities filter didn't succeed. | + | created_at | 2018-10-09T21:12:21.000000 | + | message_level | ERROR | + | id | 7d411c3c-46d9-433f-9e21-c04ca30b209c | + | resource_type | SHARE | + | action_id | 001 | + +---------------+----------------------------------------------------------------------------------------------------------+ + + As the cloud user, you know the related specs your share type has, so you can + review the share types available. The difference between the two share types + is the value of driver_handles_share_servers: + + .. code-block:: console + + clouduser1@client:~$ manila type-list + +--------------------------------------+-------------+------------+------------+--------------------------------------+--------------------------------------------+-------------+ + | ID | Name | visibility | is_default | required_extra_specs | optional_extra_specs | Description | + +--------------------------------------+-------------+------------+------------+--------------------------------------+--------------------------------------------+-------------+ + | 1cf5d45a-61b3-44d1-8ec7-89a21f51a4d4 | dhss_false | public | YES | driver_handles_share_servers : False | create_share_from_snapshot_support : True | None | + | | | | | | mount_snapshot_support : False | | + | | | | | | revert_to_snapshot_support : False | | + | | | | | | snapshot_support : True | | + | 277c1089-127f-426e-9b12-711845991ea1 | dhss_true | public | - | driver_handles_share_servers : True | create_share_from_snapshot_support : True | None | + | | | | | | mount_snapshot_support : False | | + | | | | | | revert_to_snapshot_support : False | | + | | | | | | snapshot_support : True | | + +--------------------------------------+-------------+------------+------------+--------------------------------------+--------------------------------------------+-------------+ + + +#. Create a share with the other available share type: + + .. code-block:: console + + clouduser1@client:~$ manila create nfs 1 --name software_share --share-network mynet --share-type dhss_false + +---------------------------------------+--------------------------------------+ + | Property | Value | + +---------------------------------------+--------------------------------------+ + | status | creating | + | share_type_name | dhss_false | + | description | None | + | availability_zone | None | + | share_network_id | 6c7ef9ef-3591-48b6-b18a-71a03059edd5 | + | share_group_id | None | + | revert_to_snapshot_support | False | + | access_rules_status | active | + | snapshot_id | None | + | create_share_from_snapshot_support | True | + | is_public | False | + | task_state | None | + | snapshot_support | True | + | id | 2d03d480-7cba-4122-ac9d-edc59c8df698 | + | size | 1 | + | source_share_group_snapshot_member_id | None | + | user_id | 5c7bdb6eb0504d54a619acf8375c08ce | + | name | software_share | + | share_type | 1cf5d45a-61b3-44d1-8ec7-89a21f51a4d4 | + | has_replicas | False | + | replication_type | None | + | created_at | 2018-10-09T21:24:40.000000 | + | share_proto | NFS | + | mount_snapshot_support | False | + | project_id | cadd7139bc3148b8973df097c0911016 | + | metadata | {} | + +---------------------------------------+--------------------------------------+ + + In this example, the second share creation attempt fails. + + +#. View the user support message: + + .. code-block:: console + + clouduser1@client:~$ manila list + +--------------------------------------+----------------+------+-------------+--------+-----------+-----------------+------+-------------------+ + | ID | Name | Size | Share Proto | Status | Is Public | Share Type Name | Host | Availability Zone | + +--------------------------------------+----------------+------+-------------+--------+-----------+-----------------+------+-------------------+ + | 2d03d480-7cba-4122-ac9d-edc59c8df698 | software_share | 1 | NFS | error | False | dhss_false | | nova | + | 243f3a51-0624-4bdd-950e-7ed190b53b67 | software_share | 1 | NFS | error | False | dhss_true | | None | + +--------------------------------------+----------------+------+-------------+--------+-----------+-----------------+------+-------------------+ + + clouduser1@client:~$ manila message-list + +--------------------------------------+---------------+--------------------------------------+-----------+----------------------------------------------------------------------------------------------------------+-----------+----------------------------+ + | ID | Resource Type | Resource ID | Action ID | User Message | Detail ID | Created At | + +--------------------------------------+---------------+--------------------------------------+-----------+----------------------------------------------------------------------------------------------------------+-----------+----------------------------+ + | ed7e02a2-0cdb-4ff9-b64f-e4d2ec1ef069 | SHARE | 2d03d480-7cba-4122-ac9d-edc59c8df698 | 002 | create: Driver does not expect share-network to be provided with current configuration. | 003 | 2018-10-09T21:24:40.000000 | + | 7d411c3c-46d9-433f-9e21-c04ca30b209c | SHARE | 243f3a51-0624-4bdd-950e-7ed190b53b67 | 001 | allocate host: No storage could be allocated for this share request, Capabilities filter didn't succeed. | 008 | 2018-10-09T21:12:21.000000 | + +--------------------------------------+---------------+--------------------------------------+-----------+----------------------------------------------------------------------------------------------------------+-----------+----------------------------+ + + You can see that the service does not expect a share network for + the share type used. + Without consulting the administrator, you can discover that the + administrator has not made available a storage back end that supports + exporting shares directly on to your private neutron network. + + +#. Create the share without the ``--share-network`` parameter: + + .. code-block:: console + + clouduser1@client:~$ manila create nfs 1 --name software_share --share-type dhss_false + +---------------------------------------+--------------------------------------+ + | Property | Value | + +---------------------------------------+--------------------------------------+ + | status | creating | + | share_type_name | dhss_false | + | description | None | + | availability_zone | None | + | share_network_id | None | + | share_group_id | None | + | revert_to_snapshot_support | False | + | access_rules_status | active | + | snapshot_id | None | + | create_share_from_snapshot_support | True | + | is_public | False | + | task_state | None | + | snapshot_support | True | + | id | 4d3d7fcf-5fb7-4209-90eb-9e064659f46d | + | size | 1 | + | source_share_group_snapshot_member_id | None | + | user_id | 5c7bdb6eb0504d54a619acf8375c08ce | + | name | software_share | + | share_type | 1cf5d45a-61b3-44d1-8ec7-89a21f51a4d4 | + | has_replicas | False | + | replication_type | None | + | created_at | 2018-10-09T21:25:40.000000 | + | share_proto | NFS | + | mount_snapshot_support | False | + | project_id | cadd7139bc3148b8973df097c0911016 | + | metadata | {} | + +---------------------------------------+--------------------------------------+ + + +#. To ensure that the share was created successfully, use the `manila list` + command: + + .. code-block:: console + + clouduser1@client:~$ manila list + +--------------------------------------+----------------+------+-------------+-----------+-----------+-----------------+------+-------------------+ + | ID | Name | Size | Share Proto | Status | Is Public | Share Type Name | Host | Availability Zone | + +--------------------------------------+----------------+------+-------------+-----------+-----------+-----------------+------+-------------------+ + | 4d3d7fcf-5fb7-4209-90eb-9e064659f46d | software_share | 1 | NFS | available | False | dhss_false | | nova | + | 2d03d480-7cba-4122-ac9d-edc59c8df698 | software_share | 1 | NFS | error | False | dhss_false | | nova | + | 243f3a51-0624-4bdd-950e-7ed190b53b67 | software_share | 1 | NFS | error | False | dhss_true | | None | + +--------------------------------------+----------------+------+-------------+-----------+-----------+-----------------+------+-------------------+ + +#. Delete shares that failed to be created and corresponding support messages: + + .. code-block:: console + + clouduser1@client:~$ manila delete 2d03d480-7cba-4122-ac9d-edc59c8df698 243f3a51-0624-4bdd-950e-7ed190b53b67 + clouduser1@client:~$ manila message-list + +--------------------------------------+---------------+--------------------------------------+-----------+----------------------------------------------------------------------------------------------------------+-----------+----------------------------+ + | ID | Resource Type | Resource ID | Action ID | User Message | Detail ID | Created At | + +--------------------------------------+---------------+--------------------------------------+-----------+----------------------------------------------------------------------------------------------------------+-----------+----------------------------+ + | ed7e02a2-0cdb-4ff9-b64f-e4d2ec1ef069 | SHARE | 2d03d480-7cba-4122-ac9d-edc59c8df698 | 002 | create: Driver does not expect share-network to be provided with current configuration. | 003 | 2018-10-09T21:24:40.000000 | + | 7d411c3c-46d9-433f-9e21-c04ca30b209c | SHARE | 243f3a51-0624-4bdd-950e-7ed190b53b67 | 001 | allocate host: No storage could be allocated for this share request, Capabilities filter didn't succeed. | 008 | 2018-10-09T21:12:21.000000 | + +--------------------------------------+---------------+--------------------------------------+-----------+----------------------------------------------------------------------------------------------------------+-----------+----------------------------+ + + clouduser1@client:~$ manila message-delete ed7e02a2-0cdb-4ff9-b64f-e4d2ec1ef069 7d411c3c-46d9-433f-9e21-c04ca30b209c + + clouduser1@client:~$ manila message-list + +----+---------------+-------------+-----------+--------------+-----------+------------+ + | ID | Resource Type | Resource ID | Action ID | User Message | Detail ID | Created At | + +----+---------------+-------------+-----------+--------------+-----------+------------+ + +----+---------------+-------------+-----------+--------------+-----------+------------+