.. -*- 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

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

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

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.

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

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

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

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