openstack/manila
Code Issues Proposed changes
0c4d1e3398
manila/api-ref/source/share-networks.inc
silvacarloss de62a36e3f Add api-ref for share network subnets 
This patch updates the API reference to fit into the changes that
were done in order to implement share networks with multiple
subnets.

Change-Id: I667a26cbf9ea93509718b71dadc8fb304fbca855
Partial-Bug: #1843953
2020-08-06 21:58:37 +00:00

560 lines
12 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/{project_id}/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
- name: name
Response example
----------------
.. literalinclude:: samples/share-networks-list-response.json
:language: javascript
List share networks with details
================================
.. rest_method:: GET /v2/{project_id}/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
- 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
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/{project_id}/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
- 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
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/{project_id}/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
- 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
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/{project_id}/share-networks/{share_network_id}/action
Adds a security service to a share network.
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
- 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
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/{project_id}/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
- 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
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/{project_id}/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
- 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
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/{project_id}/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
View Git Blame Copy Permalink