openstack/manila
Code Issues Proposed changes
ac672387ab
manila/api-ref/source/share-networks.inc
silvacarloss 40da25f286 Add api-ref for security service update 
Updates the API reference to fit into the changes merged in the
add/update security service in share networks feature.

Change-Id: Id7dd45dc23c41c1ade28b042f87b216142b8a062
2021-12-06 19:07:13 -03:00

832 lines
20 KiB
ReStructuredText
Raw Blame History

.. -*- rst -*-
==============
Share networks
==============
A share network resource stores network information to create and manage
share servers. Shares created with share networks are exported on these
networks with the help of share servers.
You can create, update, view, and delete a share network.
When you create a share network, you may optionally specify an associated
neutron network and subnetwork.
For more information about supported plug-ins for share networks,
see `Manila Network Plugins <https://docs.openstack.org/manila/latest/
admin/shared-file-systems-network-plugins.html>`_.
A share network resource 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.
A share network resource can also have a user defined name and description.
.. note::
Since API version 2.51, a share network is allowed to span multiple subnets
and the fields ``neutron_net_id``, ``neutron_subnet_id``, ``network_type``,
``cidr``, ``ip_version``, ``gateway``, ``segmentation_id`` and ``mtu`` were
moved from the share network to the subnet. The share network subnet also
contains a an attribute called ``availability_zone``.
List share networks
===================
.. rest_method:: GET /v2/share-networks
Lists all share networks.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- all_tenants: all_tenants_query
- name~: name_inexact_query
- description~: description_inexact_query
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: share_network_id_share_networks_response
- name: name
Response example
----------------
.. literalinclude:: samples/share-networks-list-response.json
:language: javascript
List share networks with details
================================
.. rest_method:: GET /v2/share-networks/detail
Lists all share networks with details.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- all_tenants: all_tenants_query
- name~: name_inexact_query
- description~: description_inexact_query
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: share_network_id_share_networks_response
- project_id: project_id
- neutron_net_id: neutron_net_id
- neutron_subnet_id: neutron_subnet_id
- network_type: network_type
- segmentation_id: segmentation_id
- cidr: cidr
- ip_version: ip_version
- name: name
- description: description
- created_at: created_at
- updated_at: updated_at
- gateway: share_network_gateway
- mtu: share_network_mtu
- share_network_subnets: share_network_share_network_subnets
- security_service_update_support: share_network_security_service_update_support
- status: share_network_status
Response example
----------------
.. literalinclude:: samples/share-networks-list-detailed-response.json
:language: javascript
.. include:: common/share-network-span-multiple-subnets-note.rst
.. literalinclude:: samples/share-networks-list-detailed-response-with-subnets.json
:language: javascript
Show share network details
==========================
.. rest_method:: GET /v2/share-networks/{share_network_id}
Shows details for a share network.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_network_id: share_network_id_path
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: share_network_id_share_networks_response
- project_id: project_id
- neutron_net_id: neutron_net_id
- neutron_subnet_id: neutron_subnet_id
- network_type: network_type
- segmentation_id: segmentation_id
- cidr: cidr
- ip_version: ip_version
- name: name
- description: description
- created_at: created_at
- updated_at: updated_at
- gateway: share_network_gateway
- mtu: share_network_mtu
- share_network_subnets: share_network_share_network_subnets
- security_service_update_support: share_network_security_service_update_support
- status: share_network_status
Response example
----------------
.. literalinclude:: samples/share-network-show-response.json
:language: javascript
.. include:: common/share-network-span-multiple-subnets-note.rst
.. literalinclude:: samples/share-network-show-response-with-subnets.json
:language: javascript
Create share network
====================
.. rest_method:: POST /v2/share-networks
Creates a share network.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 413
- 422
- 500
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- neutron_net_id: neutron_net_id_request
- neutron_subnet_id: neutron_subnet_id_request
- name: name_request
- description: description_request
- availability_zone: share_network_availability_zone_request
Request example
---------------
.. literalinclude:: samples/share-network-create-request.json
:language: javascript
.. note::
Since API version 2.51, an ``availability_zone`` can be specified with the
share network creation request. In case you do not specify an avaiability
zone, this field will be set to null and the subnet created will be
considered a ``default`` subnet by the Shared File Systems service. You can
have only one default subnet per share network. If you attempt to create
another default subnet in a share network that already has a default one,
the Shared File Systems Service will deny the operation.
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: share_network_id_share_networks_response
- project_id: project_id
- neutron_net_id: neutron_net_id
- neutron_subnet_id: neutron_subnet_id
- network_type: network_type
- segmentation_id: segmentation_id
- cidr: cidr
- ip_version: ip_version
- name: name
- description: description
- created_at: created_at
- updated_at: updated_at
- gateway: share_network_gateway
- mtu: share_network_mtu
- share_network_subnets: share_network_share_network_subnets
- security_service_update_support: share_network_security_service_update_support
- status: share_network_status
Response example
----------------
.. literalinclude:: samples/share-network-create-response.json
:language: javascript
.. note::
Since API version 2.51, share networks are able to span multiple subnets, so
when creating a share network, a new subnet will automatically be created by
the Shared File Systems service and attached into the share network.
.. literalinclude:: samples/share-network-create-response-with-subnets.json
:language: javascript
Add security service to share network
=====================================
.. rest_method:: POST /v2/share-networks/{share_network_id}/action
Adds a security service to a share network.
.. note::
As of API version 2.63, manila allows adding security services to share
networks that are being used if supported by the share backends. Before
requesting to add a security service to a share network that is in use,
make sure to use the `check add API
<https://docs.openstack.org/api-ref/shared-file-system/#check-share-network-security-service-add-since-api-v2-63>`_.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
- 409
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id
- share_network_id: share_network_id_path
- security_service_id: security_service_id
Request example
---------------
.. literalinclude:: samples/share-network-add-security-service-request.json
:language: javascript
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: share_network_id_share_networks_response
- project_id: project_id
- neutron_net_id: neutron_net_id
- neutron_subnet_id: neutron_subnet_id
- network_type: network_type
- segmentation_id: segmentation_id
- cidr: cidr
- ip_version: ip_version
- name: name
- description: description
- created_at: created_at
- updated_at: updated_at
- gateway: share_network_gateway
- mtu: share_network_mtu
- share_network_subnets: share_network_share_network_subnets
- security_service_update_support: share_network_security_service_update_support
- status: share_network_status
Response example
----------------
.. literalinclude:: samples/share-network-add-security-service-response.json
:language: javascript
.. include:: common/share-network-span-multiple-subnets-note.rst
.. literalinclude:: samples/share-network-add-security-service-response-with-subnets.json
:language: javascript
Remove security service from share network
==========================================
.. rest_method:: POST /v2/share-networks/{share_network_id}/action
Removes a security service from a share network.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_network_id: share_network_id_path
- security_service_id: share_network_security_service_id
Request example
---------------
.. literalinclude:: samples/share-network-remove-security-service-request.json
:language: javascript
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: share_network_id_share_networks_response
- project_id: project_id
- neutron_net_id: neutron_net_id
- neutron_subnet_id: neutron_subnet_id
- network_type: network_type
- segmentation_id: segmentation_id
- cidr: cidr
- ip_version: ip_version
- name: name
- description: description
- created_at: created_at
- updated_at: updated_at
- gateway: share_network_gateway
- mtu: share_network_mtu
- security_service_update_support: share_network_security_service_update_support
- status: share_network_status
Response example
----------------
.. literalinclude:: samples/share-network-remove-security-service-response.json
:language: javascript
.. include:: common/share-network-span-multiple-subnets-note.rst
.. literalinclude:: samples/share-network-remove-security-service-response-with-subnets.json
:language: javascript
Update share network
====================
.. rest_method:: PUT /v2/share-networks/{share_network_id}
Updates a share network.
Note that if the share network is used by any share server, you can
update only the ``name`` and ``description`` attributes.
.. note::
Since API version 2.51, can only able to update the ``neutron_net_id``
and ``neutron_subnet_id`` of the default subnet.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
- 422
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_network_id: share_network_id_path
- name: name_request
- description: description_request
- neutron_net_id: neutron_net_id_request
- neutron_subnet_id: neutron_subnet_id_request
Request example
---------------
.. literalinclude:: samples/share-network-update-request.json
:language: javascript
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: share_network_id_share_networks_response
- project_id: project_id
- neutron_net_id: neutron_net_id
- neutron_subnet_id: neutron_subnet_id
- network_type: network_type
- segmentation_id: segmentation_id
- cidr: cidr
- ip_version: ip_version
- name: name
- description: description
- created_at: created_at
- updated_at: updated_at
- gateway: share_network_gateway
- mtu: share_network_mtu
- security_service_update_support: share_network_security_service_update_support
- status: share_network_status
Response example
----------------
.. literalinclude:: samples/share-network-update-response.json
:language: javascript
.. include:: common/share-network-span-multiple-subnets-note.rst
.. literalinclude:: samples/share-network-update-response-with-subnets.json
:language: javascript
Delete share network
====================
.. rest_method:: DELETE /v2/share-networks/{share_network_id}
Deletes a share network.
Preconditions
- You cannot delete a share network if it has shares created/exported on it.
- You cannot delete a share network if it has share groups created on it.
- You cannot delete a share network if it has more than one share network
subnet on it (since API version 2.51).
Response codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
- 409
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_network_id: share_network_id_path
Update share network security service (since API v2.63)
=======================================================
.. rest_method:: POST /v2/share-networks/{share_network_id}/action
.. versionadded:: 2.63
Replaces a security service in a share network. Both current and the new
security service must have the same type and must have the
``security_service_update_support`` capability set to ``True``.
.. important::
Before calling the update share network security service API, make sure
to check if the share backends within the share network can hold the
operation, through the `check update API
<https://docs.openstack.org/api-ref/shared-file-system/#check-share-network-security-service-update-since-api-v2-63>`_.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
- 409
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_network_id: share_network_id_path
- current_security_service: current_share_network_security_service_id
- new_security_service: new_share_network_security_service_id
Request example
---------------
.. literalinclude:: samples/share-network-update-security-service-request.json
:language: javascript
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: share_network_id
- project_id: project_id
- neutron_net_id: neutron_net_id
- neutron_subnet_id: neutron_subnet_id
- network_type: network_type
- segmentation_id: segmentation_id
- cidr: cidr
- ip_version: ip_version
- name: name
- description: description
- created_at: created_at
- updated_at: updated_at
- gateway: share_network_gateway
- mtu: share_network_mtu
- share_network_subnets: share_network_share_network_subnets
- security_service_update_support: share_network_security_service_update_support
- status: share_network_status
Response example
----------------
.. literalinclude:: samples/share-network-update-security-service-response.json
:language: javascript
.. _share-net-sec-service-update-check:
Check share network security service update (since API v2.63)
=============================================================
.. rest_method:: POST /v2/share-networks/{share_network_id}/action
.. versionadded:: 2.63
Checks if an existing security service can be replaced on a share network that
is in use. This operation must be triggered before an actual request to update
a share network security service is requested.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
- 409
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_network_id: share_network_id_path
- current_service_id: current_share_network_security_service_id
- new_service_id: new_share_network_security_service_id
- reset_operation: reset_operation
Request example
---------------
.. literalinclude:: samples/share-network-update-security-service-check-request.json
:language: javascript
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- operation: requested_operation_name
- current_security_service: current_share_network_security_service_id
- new_security_service: new_share_network_security_service_id
- compatible: operation_is_compatible
- requested_operation: requested_check_operation
- hosts_check_result: hosts_check_result
Response example
----------------
.. literalinclude:: samples/share-network-update-security-service-check-response.json
:language: javascript
Check share network security service add (since API v2.63)
==========================================================
.. rest_method:: POST /v2/share-networks/{share_network_id}/action
.. versionadded:: 2.63
Checks if a new security service can be added to a share network that's already
in use. This operation must be triggered before an actual request to add a
security service to an in use share network.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
- 409
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_network_id: share_network_id_path
- security_service_id: current_share_network_security_service_id
- reset_operation: reset_operation
Request example
---------------
.. literalinclude:: samples/share-network-add-security-service-check-request.json
:language: javascript
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- operation: requested_operation_name
- current_security_service: current_share_network_security_service_id
- new_security_service: new_share_network_security_service_id
- compatible: operation_is_compatible
- requested_operation: requested_operation
- hosts_check_result: hosts_check_result
Response example
----------------
.. literalinclude:: samples/share-network-add-security-service-check-response.json
:language: javascript
Reset status (since API v2.63)
==============================
.. rest_method:: POST /v2/share-networks/{share_network_id}/action
.. versionadded:: 2.63
Resets a share network status.
Administrator only. Explicitly updates the state of a share network.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request parameters
------------------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_network_id: share_network_id_path
- status: share_network_status
Request example
---------------
.. literalinclude:: samples/share-network-reset-state-request.json
:language: javascript
Response parameters
-------------------
There is no body content for the response.
View Git Blame Copy Permalink