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

api-ref/source/common/share-network-span-multiple-subnets-note.rst

@@ -0,0 +1,6 @@
+.. 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 response will look like the
+   below example.

api-ref/source/index.rst

@@ -16,6 +16,7 @@ Shared File Systems API
 .. include:: snapshots.inc
 .. include:: snapshot-instances.inc
 .. include:: share-networks.inc
+.. include:: share-network-subnets.inc
 .. include:: security-services.inc
 .. include:: share-servers.inc
 .. include:: share-instances.inc

api-ref/source/parameters.yaml

@@ -105,6 +105,12 @@ share_network_id_path:
   in: path
   required: true
   type: string
+share_network_subnet_id_path:
+  description: |
+    The UUID of the share network subnet.
+  in: path
+  required: true
+  type: string
 share_replica_id_path:
   description: |
     The UUID of the share replica.
@@ -650,6 +656,12 @@ availability_zone_name:
   in: body
   required: true
   type: string
+availability_zone_request:
+  description: |
+    The UUID or name of an availability zone for the share network subnet.
+  in: body
+  required: false
+  type: string
 availability_zones:
   description: |
     Top level response body element.
@@ -778,12 +790,6 @@ capability_vendor_name:
   required: true
   type: string
 cidr:
-  description: |
-    The CIDR.
-  in: body
-  required: true
-  type: string
-cidr_1:
   description: |
     The IP block from which to allocate the network,
     in CIDR notation. For example, ``172.16.0.0/24`` or
@@ -792,6 +798,7 @@ cidr_1:
   in: body
   required: true
   type: string
+  max_version: 2.50
 consistent_snapshot_support:
   description: |
     The consistency snapshot support.
@@ -1170,13 +1177,6 @@ identifier:
   required: true
   type: string
 ip_version:
-  description: |
-    The IP version of the network. A valid value is
-    ``4`` or ``6``.
-  in: body
-  required: true
-  type: integer
-ip_version_1:
   description: |
     The IP version of the network. A valid value is
     ``4`` or ``6``. This parameter is automatically set to a value
@@ -1184,6 +1184,7 @@ ip_version_1:
   in: body
   required: true
   type: integer
+  max_version: 2.50
 is_auto_deletable:
   description: |
     Defines if a share server can be deleted automatically by  the service.
@@ -1471,13 +1472,6 @@ name_request:
   required: false
   type: string
 network_type:
-  description: |
-    The network type. A valid value is ``VLAN``,
-    ``VXLAN``, ``GRE``, or ``flat``.
-  in: body
-  required: true
-  type: string
-network_type_1:
   description: |
     The network type. A valid value is ``VLAN``,
     ``VXLAN``, ``GRE``, or ``flat``. This parameter is automatically
@@ -1485,16 +1479,18 @@ network_type_1:
   in: body
   required: true
   type: string
+  max_version: 2.50
 neutron_net_id:
   description: |
     The neutron network ID.
   in: body
   required: true
   type: string
+  max_version: 2.50
 neutron_net_id_request:
   description: |
     The UUID of a neutron network when setting up or updating a share
-    network with neutron.  Specify both a neutron network and a neutron
+    network subnet with neutron. Specify both a neutron network and a neutron
     subnet that belongs to that neutron network.
   in: body
   required: false
@@ -1505,10 +1501,11 @@ neutron_subnet_id:
   in: body
   required: true
   type: string
+  max_version: 2.50
 neutron_subnet_id_request:
   description: |
     The UUID of the neutron subnet when setting up or updating a share
-    network with neutron.  Specify both a neutron network and a neutron
+    network subnet with neutron. Specify both a neutron network and a neutron
     subnet that belongs to that neutron network.
   in: body
   required: false
@@ -2032,12 +2029,6 @@ security_service_user_request:
   required: false
   type: string
 segmentation_id:
-  description: |
-    The segmentation ID.
-  in: body
-  required: true
-  type: integer
-segmentation_id_1:
   description: |
     The segmentation ID. This parameter is
     automatically set to a value determined by the network provider.
@@ -2047,6 +2038,7 @@ segmentation_id_1:
   in: body
   required: true
   type: integer
+  max_version: 2.50
 service_binary_response:
   description: |
     The service binary name. Default is the base name
@@ -2263,6 +2255,13 @@ share_instance_id_1:
   in: body
   required: true
   type: string
+share_network_availability_zone_request:
+  description: |
+    The UUID or name of an availability zone for the share network subnet.
+  in: body
+  required: false
+  type: string
+  min_version: 2.51
 share_network_gateway:
   description: |
     The gateway of a share network.
@@ -2270,6 +2269,7 @@ share_network_gateway:
   required: true
   type: string
   min_version: 2.18
+  max_version: 2.50
 share_network_id:
   description: |
     The share network ID.
@@ -2313,6 +2313,7 @@ share_network_mtu:
   required: true
   type: integer
   min_version: 2.20
+  max_version: 2.50
 share_network_name:
   description: |
     The name of a share network that is associated
@@ -2327,6 +2328,118 @@ share_network_security_service_id:
   in: body
   required: true
   type: string
+share_network_share_network_subnets:
+  description: |
+    A list of share network subnets that pertain to the related share network.
+  in: body
+  required: true
+  type: array
+  min_version: 2.51
+share_network_subnet_availability_zone:
+  description: |
+    The name of the availability zone that the share network subnet belongs to.
+  in: body
+  required: true
+  type: string
+share_network_subnet_cidr:
+  description: |
+    The IP block from which to allocate the network,
+    in CIDR notation. For example, ``172.16.0.0/24`` or
+    ``2001:DB8::/64``. This parameter is automatically set to a value
+    determined by the network provider.
+  in: body
+  required: true
+  type: string
+share_network_subnet_gateway:
+  description: |
+    The gateway of a share network subnet.
+  in: body
+  required: true
+  type: string
+share_network_subnet_id:
+  description: |
+    The UUID of the share network subnet.
+  in: body
+  required: true
+  type: string
+share_network_subnet_id_manage_server_body:
+  description: |
+    The UUID of the share network subnet that the share server pertain to.
+  in: body
+  required: true
+  type: string
+  min_version: 2.51
+share_network_subnet_id_manage_server_request:
+  description: |
+    The UUID of the share network subnet that the share server will pertain to.
+    If not specified, the share network's default subnet UUID will be used.
+  in: body
+  required: false
+  type: string
+  min_version: 2.51
+share_network_subnet_id_share_server_body:
+  description: |
+    The UUID of the share network subnet that the share server pertains to.
+  in: body
+  required: true
+  type: string
+  min_version: 2.51
+share_network_subnet_ip_version:
+  description: |
+    The IP version of the network. A valid value is
+    ``4`` or ``6``. This parameter is automatically set to a value
+    determined by the network provider.
+  in: body
+  required: true
+  type: integer
+share_network_subnet_mtu:
+  description: |
+    The MTU of a share network subnet.
+  in: body
+  required: true
+  type: string
+share_network_subnet_network_type:
+  description: |
+    The network type. A valid value is ``VLAN``,
+    ``VXLAN``, ``GRE``, or ``flat``. This parameter is automatically
+    set to a value determined by the network provider.
+  in: body
+  required: true
+  type: string
+share_network_subnet_neutron_net_id:
+  description: |
+    The neutron network ID.
+  in: body
+  required: true
+  type: string
+share_network_subnet_neutron_subnet_id:
+  description: |
+    The neutron subnet ID.
+  in: body
+  required: true
+  type: string
+share_network_subnet_segmentation_id:
+  description: |
+    The segmentation ID. This parameter is
+    automatically set to a value determined by the network provider.
+    For VLAN, this value is an integer from 1 to 4094.  For VXLAN,
+    this value is an integer from 1 to 16777215.  For GRE, this value
+    is an integer from 1 to 4294967295.
+  in: body
+  required: true
+  type: integer
+share_network_subnet_share_network_id:
+  description: |
+    The UUID of the share network that the share network subnet belongs to.
+  in: body
+  required: true
+  type: string
+share_network_subnet_share_network_name:
+  description: |
+    The name of the share network that the share network subnet belongs to.
+  in: body
+  required: true
+  type: string
 share_new_size:
   description: |
     New size of the share, in GBs.

api-ref/source/samples/share-network-add-security-service-response-with-subnets.json

@@ -0,0 +1,26 @@
+{
+    "share_network": {
+        "name": "net2",
+        "created_at": "2019-11-10T12:31:12.000000",
+        "updated_at": null,
+        "id": "d8ae6799-2567-4a89-aafb-fa4424350d2b",
+        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
+        "description": null,
+        "share_network_subnets": [
+            {
+                "id": "e4db03dc-6041-4c6a-a8f9-80bb4141a1eb",
+                "availability_zone": null,
+                "created_at": "2019-11-10T12:31:12.000000",
+                "updated_at": "2019-11-10T12:31:12.000000",
+                "segmentation_id": null,
+                "neutron_net_id": "62187648-6617-4509-a780-ffc973a7fe43",
+                "neutron_subnet_id": "2276888a-27c1-47c2-82a0-ea33050128b5",
+                "ip_version": 4,
+                "cidr": "172.24.5.0/24",
+                "network_type": "flat",
+                "mtu": 1500,
+                "gateway": "172.24.5.1"
+            }
+        ]
+    }
+}

api-ref/source/samples/share-network-create-request.json

@@ -3,6 +3,7 @@
         "neutron_net_id": "998b42ee-2cee-4d36-8b95-67b5ca1f2109",
         "neutron_subnet_id": "53482b62-2c84-4a53-b6ab-30d9d9800d06",
         "name": "my_network",
-        "description": "This is my share network"
+        "description": "This is my share network",
+        "availability_zone": "manila-zone-0"
     }
 }

api-ref/source/samples/share-network-create-response-with-subnets.json

@@ -0,0 +1,26 @@
+{
+    "share_network": {
+        "name": "my_network",
+        "created_at": "2019-09-07T14:37:00.583656",
+        "updated_at": null,
+        "id": "77eb3421-4549-4789-ac39-0d5185d68c29",
+        "project_id": "e10a683c20da41248cfd5e1ab3d88c62",
+        "description": "This is my share network",
+        "share_network_subnets": [
+            {
+                "id": "91cc63b5-6c61-4078-b054-560923709654",
+                "availability_zone": "manila-zone-0",
+                "created_at": "2019-10-04T20:49:11.000000",
+                "updated_at": null,
+                "segmentation_id": null,
+                "neutron_net_id": "998b42ee-2cee-4d36-8b95-67b5ca1f2109",
+                "neutron_subnet_id": "53482b62-2c84-4a53-b6ab-30d9d9800d06",
+                "ip_version": null,
+                "cidr": null,
+                "network_type": null,
+                "mtu": null,
+                "gateway": null
+            }
+        ]
+    }
+}

api-ref/source/samples/share-network-remove-security-service-response-with-subnets.json

@@ -0,0 +1,26 @@
+{
+    "share_network": {
+        "name": "net2",
+        "created_at": "2019-11-07T12:31:12.000000",
+        "updated_at": null,
+        "id": "d8ae6799-2567-4a89-aafb-fa4424350d2b",
+        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
+        "description": null,
+        "share_network_subnets": [
+            {
+                "id": "e4db03dc-6041-4c6a-a8f9-80bb4141a1eb",
+                "availability_zone": null,
+                "created_at": "2019-11-07T12:31:12.000000",
+                "updated_at": "2019-12-12T12:31:12.000000",
+                "segmentation_id": null,
+                "neutron_net_id": "62187648-6617-4509-a780-ffc973a7fe43",
+                "neutron_subnet_id": "2276888a-27c1-47c2-82a0-ea33050128b5",
+                "ip_version": 4,
+                "cidr": "172.24.5.0/24",
+                "network_type": "flat",
+                "mtu": 1500,
+                "gateway": "172.24.5.1"
+            }
+        ]
+    }
+}

api-ref/source/samples/share-network-show-response-with-subnets.json

@@ -0,0 +1,25 @@
+{
+    "share_network": {
+        "id": "1324e7d3-fba8-45e4-bb37-b59c12eb06dc",
+        "name": "net_my1",
+        "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
+        "created_at": "2019-10-02T17:49:43.000000",
+        "description": null,
+        "share_network_subnets": [
+            {
+                "id": "e4db03dc-6041-4c6a-a8f9-80bb4141a1eb",
+                "availability_zone": null,
+                "created_at": "2019-10-02T17:49:43.000000",
+                "updated_at": "2019-10-03T12:17:39.000000",
+                "segmentation_id": null,
+                "neutron_net_id": "62187648-6617-4509-a780-ffc973a7fe43",
+                "neutron_subnet_id": "2276888a-27c1-47c2-82a0-ea33050128b5",
+                "ip_version": 4,
+                "cidr": "172.24.5.0/24",
+                "network_type": "flat",
+                "mtu": 1500,
+                "gateway": "172.24.5.1"
+            }
+        ]
+    }
+}

api-ref/source/samples/share-network-subnet-create-request.json

@@ -0,0 +1,7 @@
+{
+    "share-network-subnet": {
+        "neutron_net_id": "62187648-6617-4509-a780-ffc973a7fe43",
+        "neutron_subnet_id": "2276888a-27c1-47c2-82a0-ea33050128b5",
+        "availability_zone": "manila-zone-0"
+    }
+}

api-ref/source/samples/share-network-subnet-create-response.json

@@ -0,0 +1,18 @@
+{
+    "share_network_subnet": {
+        "id": "8ebe964d-ac48-4e43-93ed-b1768148f8f4",
+        "availability_zone": "manila-zone-0",
+        "share_network_id": "1324e7d3-fba8-45e4-bb37-b59c12eb06dc",
+        "share_network_name": "net_my1",
+        "created_at": "2019-10-03T02:25:12.000000",
+        "segmentation_id": null,
+        "neutron_subnet_id": "2276888a-27c1-47c2-82a0-ea33050128b5",
+        "updated_at": null,
+        "neutron_net_id": "62187648-6617-4509-a780-ffc973a7fe43",
+        "ip_version": null,
+        "cidr": null,
+        "network_type": null,
+        "mtu": null,
+        "gateway": null
+    }
+}

api-ref/source/samples/share-network-subnet-list-response.json

@@ -0,0 +1,36 @@
+{
+    "share_network_subnets": [
+    {
+        "id": "a7507a16-98bb-476c-ba90-487e4b4775fa",
+        "availability_zone": null,
+        "share_network_id": "8bc488d8-52f7-46cb-91b1-89dd92cae972",
+        "share_network_name": "sn_test",
+        "created_at": "2019-10-03T18:30:15.000000",
+        "segmentation_id": null,
+        "neutron_subnet_id": "dc0a37f0-81b0-4eb5-aad8-deffda5ff4ca",
+        "updated_at": null,
+        "neutron_net_id": "70bc8f03-525c-4334-a51b-261a024681c5",
+        "ip_version": 4,
+        "cidr": "10.190.5.0/24",
+        "network_type": "flat",
+        "mtu": 1500,
+        "gateway": "10.190.5.1"
+    },
+    {
+        "id": "8ebe964d-ac48-4e43-93ed-b1768148f8f4",
+        "availability_zone": "manila-zone-0",
+        "share_network_id": "8bc488d8-52f7-46cb-91b1-89dd92cae972",
+        "share_network_name": "sn_test",
+        "created_at": "2019-10-02T01:35:10.000000",
+        "segmentation_id": null,
+        "neutron_subnet_id": "2276888a-27c1-47c2-82a0-ea33050128b5",
+        "updated_at": null,
+        "neutron_net_id": "62187648-6617-4509-a780-ffc973a7fe43",
+        "ip_version": 4,
+        "cidr": "172.24.5.0/24",
+        "network_type": "flat",
+        "mtu": 1500,
+        "gateway": "172.24.5.1"
+    }
+    ]
+}

api-ref/source/samples/share-network-subnet-show-response.json

@@ -0,0 +1,18 @@
+{
+    "share_network_subnet": {
+        "id": "e4db03dc-6041-4c6a-a8f9-80bb4141a1eb",
+        "availability_zone": null,
+        "share_network_id":"1324e7d3-fba8-45e4-bb37-b59c12eb06dc",
+        "share_network_name": "net_my1",
+        "created_at": "2019-10-01T17:49:43.000000",
+        "segmentation_id": null,
+        "neutron_subnet_id": "2276888a-27c1-47c2-82a0-ea33050128b5",
+        "updated_at": "2019-11-02T12:17:39.000000",
+        "neutron_net_id": "62187648-6617-4509-a780-ffc973a7fe43",
+        "ip_version": 4,
+        "cidr": "172.24.5.0/24",
+        "network_type": "flat",
+        "mtu": 1500,
+        "gateway": "172.24.5.1"
+    }
+}

api-ref/source/samples/share-network-update-response-with-subnets.json

@@ -0,0 +1,26 @@
+{
+    "share_network":{
+        "id": "2b33cd3a-3049-4f36-a2fd-f7a211eb9202",
+        "name": "update my network",
+        "project_id": "79ed3be75dbb4d03afd687b758fcc2c0",
+        "created_at": "2019-11-12T17:18:10.000000",
+        "updated_at": null,
+        "description": "i'm adding a description",
+        "share_network_subnets": [
+            {
+                "id": "687ab361-5c40-406e-945c-6326254782d4",
+                "availability_zone": null,
+                "created_at": "2019-11-13T17:18:10.000000",
+                "updated_at": "2019-11-13T17:18:56.000000",
+                "segmentation_id": null,
+                "neutron_net_id": "998b42ee-2cee-4d36-8b95-67b5ca1f2109",
+                "neutron_subnet_id": "53482b62-2c84-4a53-b6ab-30d9d9800d06",
+                "ip_version": 4,
+                "cidr": "172.24.5.0/24",
+                "network_type": "flat",
+                "mtu": 1500,
+                "gateway": "172.24.5.1"
+            }
+        ]
+    }
+}

api-ref/source/samples/share-networks-list-detailed-response-with-subnets.json

@@ -0,0 +1,66 @@
+{
+    "share_networks": [
+        {
+            "id": "03987b5f-cb79-4f5f-a590-f6936b91b49e",
+            "name": "net_my1",
+            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
+            "created_at": "2019-10-02T12:33:36.000000",
+            "updated_at": null,
+            "description": null,
+            "share_network_subnets": [
+                {
+                    "id": "022aa495-845e-42a6-9d83-a38f164053c9",
+                    "availability_zone": null,
+                    "created_at": "2019-10-02T12:33:36.000000",
+                    "updated_at": null,
+                    "segmentation_id": null,
+                    "neutron_net_id": "f00732aa-7721-455d-ba14-ec37619ea13f",
+                    "neutron_subnet_id": "eb7adcf8-ce71-43e3-b4c2-cf81da9f89a",
+                    "ip_version": null,
+                    "cidr": null,
+                    "network_type": null,
+                    "mtu": null,
+                    "gateway": null
+                }
+            ]
+        },
+        {
+            "id": "1324e7d3-fba8-45e4-bb37-b59c12eb06dc",
+            "name": "net_my2",
+            "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
+            "created_at": "2019-07-01T17:49:43.000000",
+            "updated_at": "2019-07-02T12:17:39.000000",
+            "description": null,
+            "share_network_subnets": [
+                {
+                    "id": "8ebe964d-ac48-4e43-93ed-b1768148f8f4",
+                    "availability_zone": "manila-zone-0",
+                    "created_at": "2019-10-03T02:25:12.000000",
+                    "updated_at": null,
+                    "segmentation_id": null,
+                    "neutron_net_id": "62187648-6617-4509-a780-ffc973a7fe43",
+                    "neutron_subnet_id": "2276888a-27c1-47c2-82a0-ea3050128b5",
+                    "ip_version": null,
+                    "cidr": null,
+                    "network_type": null,
+                    "mtu": null,
+                    "gateway": null
+                },
+                {
+                    "id": "e4db03dc-6041-4c6a-a8f9-80bb4141a1eb",
+                    "availability_zone": null,
+                    "created_at": "2019-07-01T17:49:43.000000",
+                    "updated_at": "2019-07-02T12:17:39.000000",
+                    "segmentation_id": null,
+                    "neutron_net_id": "62187648-6617-4509-a780-ffc973a7fe43",
+                    "neutron_subnet_id": "2276888a-27c1-47c2-820-ea33050128b5",
+                    "ip_version": 4,
+                    "cidr": "172.24.5.0/24",
+                    "network_type": "flat",
+                    "mtu": 1500,
+                    "gateway": "172.24.5.1"
+                }
+            ]
+        }
+    ]
+}

api-ref/source/samples/share-replica-create-request.json

@@ -1,7 +1,6 @@
 {
     "share_replica": {
         "share_id": "50a6a566-6bac-475c-ad69-5035c86696c0",
-        "availability_zone": "nova",
+        "availability_zone": "nova"
-        "share_network_id": "f5a55875-e33a-4888-be52-7cd75b72294b"
     }
 }

api-ref/source/samples/share-server-manage-request.json

@@ -2,6 +2,7 @@
     "share_server": {
         "host": "myhost@mybackend",
         "share_network_id": "78cef6eb-648a-4bbd-9ae1-d2eaaf594cc0",
+        "share_network_subnet_id": "f53252f0-c2a9-4d7c-af41-1c6f3cfb3af3",
         "identifier": "4ef3507e-0513-4140-beda-f619ab30d424",
         "driver_options": {
             "opt1": "opt1_value"

api-ref/source/samples/share-server-manage-response.json

@@ -7,6 +7,7 @@
         "host": "myhost@mybackend",
         "share_network_name": "share-net-name",
         "share_network_id": "78cef6eb-648a-4bbd-9ae1-d2eaaf594cc0",
+        "share_network_subnet_id": "f53252f0-c2a9-4d7c-af41-1c6f3cfb3af3",
         "created_at": "2019-03-06T11:59:41.000000",
         "backend_details": {},
         "is_auto_deletable": false,

api-ref/source/samples/share-server-show-response.json

@@ -16,6 +16,7 @@
         "share_network_name": "net_my",
         "host": "manila2@generic1",
         "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
+        "share_network_subnet_id": "f53252f0-c2a9-4d7c-af41-1c6f3cfb3af3",
         "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
         "id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73"
     }

api-ref/source/samples/share-servers-list-response.json

@@ -6,6 +6,7 @@
             "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
             "host": "manila2@generic1",
             "share_network_name": "net_my",
+            "share_network_subnet_id": "f53252f0-c2a9-4d7c-af41-1c6f3cfb3af3",
             "project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
             "id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73"
         }

api-ref/source/share-network-subnets.inc

@@ -0,0 +1,264 @@
+.. -*- rst -*-
+
+=======================================
+Share network subnets (since API v2.51)
+=======================================
+
+A share network subnet stores network information to create and manage share
+servers.
+
+You can list all subnets that pertain to a share network, also
+create, delete and view a share network subnet.
+
+When you create a share network, you may optionally specify an associated
+neutron network, subnetwork and an availability zone. If you do not specify an
+availability zone, the subnet you are creating will have the availability
+zone field empty and this subnet will be considered default. The default subnet
+is recognized by the Shared File Systems service as a subnet that spans all
+the available storage availability zones.
+
+.. note::
+   A share network can have only one default subnet. Likewise, a share network
+   cannot have more than one subnet in a given availability zone.
+
+For more information about supported plug-ins for share network subnets,
+see `Manila Network Plugins <https://docs.openstack.org/manila/latest/
+admin/shared-file-systems-network-plugins.html>`_.
+
+A share network subnet 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.
+
+- The availability zone, when ``null`` signifies that the share network subnet
+  is available across all storage availability zones known to the Shared File
+  Systems Service.
+
+
+List share network subnets
+==========================
+
+.. rest_method::  GET /v2/{project_id}/share-networks/{share_network_id}/subnets
+
+.. versionadded:: 2.51
+
+Lists all share network subnets in the given share network.
+
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 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_subnet_id
+   - availability_zone: share_network_subnet_availability_zone
+   - share_network_id: share_network_subnet_share_network_id
+   - share_network_name: share_network_subnet_share_network_name
+   - created_at: created_at
+   - updated_at: updated_at
+   - segmentation_id: share_network_subnet_segmentation_id
+   - neutron_net_id: share_network_subnet_neutron_net_id
+   - neutron_subnet_id: share_network_subnet_neutron_subnet_id
+   - ip_version: share_network_subnet_ip_version
+   - cidr: share_network_subnet_cidr
+   - network_type: share_network_subnet_network_type
+   - gateway: share_network_subnet_gateway
+   - mtu: share_network_subnet_mtu
+
+Response example
+----------------
+
+.. literalinclude:: samples/share-network-subnet-list-response.json
+   :language: javascript
+
+
+Show share network subnet details
+=================================
+
+.. rest_method::  GET /v2/{project_id}/share-networks/{share_network_id}/subnets/{share_network_subnet_id}
+
+.. versionadded:: 2.51
+
+Shows details of a share network subnet.
+
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - share_network_id: share_network_id_path
+   - share_network_subnet_id: share_network_subnet_id_path
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: share_network_subnet_id
+   - neutron_net_id: share_network_subnet_neutron_net_id
+   - neutron_subnet_id: share_network_subnet_neutron_subnet_id
+   - network_type: share_network_subnet_network_type
+   - segmentation_id: share_network_subnet_segmentation_id
+   - cidr: share_network_subnet_cidr
+   - ip_version: share_network_subnet_ip_version
+   - created_at: created_at
+   - updated_at: updated_at
+   - gateway: share_network_subnet_gateway
+   - mtu: share_network_subnet_mtu
+   - availability_zone: share_network_subnet_availability_zone
+   - share_network_id: share_network_subnet_share_network_id
+   - share_network_name: share_network_subnet_share_network_name
+
+Response example
+----------------
+
+.. literalinclude:: samples/share-network-subnet-show-response.json
+   :language: javascript
+
+
+Create share network subnet
+===========================
+
+.. rest_method::  POST /v2/{project_id}/share-networks/{share_network_id}/subnets
+
+.. versionadded:: 2.51
+
+Creates a share network subnet in the given share network.
+
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 202
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 404
+   - 409
+   - 500
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - share_network_id: share_network_id_path
+   - neutron_net_id: neutron_net_id_request
+   - neutron_subnet_id: neutron_subnet_id_request
+   - availability_zone: availability_zone_request
+
+Request example
+---------------
+
+.. literalinclude:: samples/share-network-subnet-create-request.json
+   :language: javascript
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: share_network_id
+   - neutron_net_id: share_network_subnet_neutron_net_id
+   - neutron_subnet_id: share_network_subnet_neutron_subnet_id
+   - network_type: share_network_subnet_network_type
+   - segmentation_id: share_network_subnet_segmentation_id
+   - cidr: share_network_subnet_cidr
+   - ip_version: share_network_subnet_ip_version
+   - created_at: created_at
+   - updated_at: updated_at
+   - gateway: share_network_subnet_gateway
+   - mtu: share_network_subnet_mtu
+   - availability_zone: share_network_subnet_availability_zone
+   - share_network_id: share_network_subnet_share_network_id
+   - share_network_name: share_network_subnet_share_network_name
+
+Response example
+----------------
+
+.. literalinclude:: samples/share-network-subnet-create-response.json
+   :language: javascript
+
+
+Delete share network subnet
+===========================
+
+.. rest_method::  DELETE /v2/{project_id}/share-networks/{share_network_id}/subnets/{share_network_subnet_id}
+
+.. versionadded:: 2.51
+
+Deletes a share network subnet.
+
+Preconditions
+
+- You cannot delete a share network subnet if it has shares created/exported
+  on it.
+
+- You cannot delete a share network subnet if it has share servers with the
+  flag ``is_auto_deletable`` set to False.
+
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 202
+
+.. rest_status_code:: error status.yaml
+
+   - 404
+   - 409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - share_network_id: share_network_id_path
+   - share_network_subnet_id: share_network_subnet_id_path

api-ref/source/share-networks.inc

@@ -32,6 +32,14 @@ A share network resource has these attributes:
 
 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
 ===================
 
@@ -128,6 +136,7 @@ Response parameters
    - updated_at: updated_at
    - gateway: share_network_gateway
    - mtu: share_network_mtu
+   - share_network_subnets: share_network_share_network_subnets
 
 Response example
 ----------------
@@ -135,6 +144,11 @@ 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
 ==========================
@@ -184,6 +198,7 @@ Response parameters
    - updated_at: updated_at
    - gateway: share_network_gateway
    - mtu: share_network_mtu
+   - share_network_subnets: share_network_share_network_subnets
 
 Response example
 ----------------
@@ -191,6 +206,11 @@ 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
 ====================
@@ -214,6 +234,7 @@ Response codes
    - 403
    - 413
    - 422
+   - 500
 
 Request
 -------
@@ -225,6 +246,7 @@ Request
    - neutron_subnet_id: neutron_subnet_id_request
    - name: name_request
    - description: description_request
+   - availability_zone: share_network_availability_zone_request
 
 Request example
 ---------------
@@ -232,6 +254,15 @@ 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
 -------------------
 
@@ -241,16 +272,17 @@ Response parameters
    - project_id: project_id
    - neutron_net_id: neutron_net_id
    - neutron_subnet_id: neutron_subnet_id
-   - network_type: network_type_1
+   - network_type: network_type
-   - segmentation_id: segmentation_id_1
+   - segmentation_id: segmentation_id
-   - cidr: cidr_1
+   - cidr: cidr
-   - ip_version: ip_version_1
+   - 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
 ----------------
@@ -258,6 +290,14 @@ 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
 =====================================
@@ -316,6 +356,7 @@ Response parameters
    - updated_at: updated_at
    - gateway: share_network_gateway
    - mtu: share_network_mtu
+   - share_network_subnets: share_network_share_network_subnets
 
 Response example
 ----------------
@@ -323,6 +364,11 @@ 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
 ==========================================
@@ -388,6 +434,11 @@ 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
 ====================
@@ -399,6 +450,10 @@ 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
 --------------
 
@@ -458,6 +513,11 @@ 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
 ====================
@@ -472,6 +532,9 @@ Preconditions
 
 - 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
 --------------
 

api-ref/source/share-replicas.inc

@@ -91,6 +91,14 @@ Request example
 .. literalinclude:: samples/share-replica-create-request.json
    :language: javascript
 
+.. note::
+   Since API version 2.51, the parameter ``share_network_id``
+   is deprecated. It will be inherited from its parent share, and the
+   Shared File Systems service will automatically choose which share network
+   subnet your share replica will be placed, according to the specified
+   availability zone.
+
+
 Response parameters
 -------------------
 

api-ref/source/share-servers.inc

@@ -79,6 +79,7 @@ Response parameters
    - share_network_name: share_network_name
    - host: host_share_server_body
    - updated_at: updated_at
+   - share_network_subnet_id: share_network_subnet_id_share_server_body
 
 Response example
 ----------------
@@ -132,6 +133,7 @@ Response parameters
   - updated_at: updated_at
   - identifier: share_server_show_identifier
   - is_auto_deletable: share_server_show_is_auto_deletable
+  - share_network_subnet_id: share_network_subnet_id_share_server_body
 
 Response example
 ----------------
@@ -252,6 +254,7 @@ Request
     - identifier: identifier
     - share_network: share_network_id
     - driver_options: driver_options
+    - share_network_subnet_id: share_network_subnet_id_manage_server_request
 
 Request example
 ---------------
@@ -275,6 +278,8 @@ Response parameters
     - backend_details: backend_details
     - is_auto_deletable: is_auto_deletable
     - identifier: identifier
+    - share_network_subnet_id: share_network_subnet_id_manage_server_body
+
 
 Response examples
 -----------------