New api-def: extraroute-atomic

Change-Id: Ib0338bb00652fb6a03c50f204ce8f19cf4d38352
Partial-Bug: #1826396 (rfe)
Related-Change: https://review.opendev.org/655680 (spec)

api-ref/source/v2/routers.inc

@@ -22,6 +22,17 @@ Extra routes extension
 The extra route extension (``extraroute``) extends ``router`` resources adding
 a ``routes`` attribute that contains an array of route objects. Each route
 object has a ``destination`` and ``nexthop`` attribute representing the route.
+When the ``extraroute-atomic`` extension is also available you can add
+or remove a set of extra routes atomically on the server side. For details
+please see below.
+
+Extra routes (atomic) extension
+===============================
+
+The extra route atomic extension (``extraroute-atomic``) extends the
+``router`` resource by adding two member actions (``add_extraroutes`` /
+``remove_extraroutes``) to edit the set of extra routes atomically on
+the server side.
 
 HA capability for router extension (``l3-ha``)
 =======================================================
@@ -579,3 +590,143 @@ Response Example
 .. literalinclude:: samples/routers/router-remove-interface-response.json
    :language: javascript
 
+Add extra routes to router
+==========================
+
+.. rest_method::  PUT /v2.0/routers/{router_id}/add_extraroutes
+
+Atomically adds a set of extra routes to the router's already existing
+extra routes.
+
+This operation is a variation on updating the router's ``routes``
+parameter.  In all ways it works the same, except the extra routes sent
+in the request body do not replace the existing set of extra routes.
+Instead the extra routes sent are added to the existing set of
+extra routes.
+
+The use of the add_extraroutes/remove_extraroutes member actions
+is preferred to updating the ``routes`` attribute in all cases when
+concurrent updates to the set of extra routes are possible.
+
+The addition's corner cases behave the following way:
+
+* When (destinationA, nexthopA) is to be added but it is already present
+  that is accepted and the request succeeds.
+
+* Two or more routes with the same destination but with different
+  nexthops are all accepted.
+
+* A route whose destination overlaps the destination of existing routes
+  (e.g. ``192.168.1.0/24`` and ``192.168.1.0/22``) can be added and
+  existing routes are left untouched.
+
+The format of the request body is the same as the format of a PUT
+request to the router changing the ``routes`` parameter only.
+
+The response codes and response body are the same as to the update of
+the ``routes`` parameter. That is the whole router object is returned
+including the ``routes`` parameter which represents the result of the
+addition.
+
+Normal response codes: 200
+
+Error response codes: 400, 401, 404, 412
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - router_id: router_id
+   - routes: router-routes
+
+Request Example
+---------------
+
+.. literalinclude:: samples/routers/router-add-extraroutes-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: router-id-body
+   - name: router_name
+   - routes: router-routes
+
+Response Example
+----------------
+
+.. literalinclude:: samples/routers/router-add-extraroutes-response.json
+   :language: javascript
+
+Remove extra routes from router
+===============================
+
+.. rest_method::  PUT /v2.0/routers/{router_id}/remove_extraroutes
+
+Atomically removes a set of extra routes from the router's already
+existing extra routes.
+
+This operation is a variation on updating the router's ``routes``
+parameter.  In all ways it works the same, except the extra routes sent
+in the request body do not replace the existing set of extra routes.
+Instead the the extra routes sent are removed from the existing set of
+extra routes.
+
+The use of the add_extraroutes/remove_extraroutes member actions
+is preferred to updating the ``routes`` attribute in all cases when
+concurrent updates to the set of extra routes are possible.
+
+The removal's corner cases behave the following way:
+
+* An extra route is only removed if there is an exact match (including the
+  ``destination`` and ``nexthop``) between the route sent and the route
+  already present.
+
+* When (destinationA, nexthopA) is to be removed but it is already missing
+  that is accepted and the request succeeds.
+
+The format of the request body is the same as the format of a PUT
+request to the router changing the ``routes`` parameter only. However
+the routes sent are not meant to overwrite the whole ``routes``
+parameter, but they are meant to be removed from the existing set.
+
+The response codes and response body are the same as to the update of
+the ``routes`` parameter. That is the whole router object is returned
+including the ``routes`` parameter which represents the result of the
+removal.
+
+Normal response codes: 200
+
+Error response codes: 400, 401, 404, 412
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - router_id: router_id
+   - routes: router-routes
+
+Request Example
+---------------
+
+.. literalinclude:: samples/routers/router-remove-extraroutes-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: router-id-body
+   - name: router_name
+   - routes: router-routes
+
+Response Example
+----------------
+
+.. literalinclude:: samples/routers/router-remove-extraroutes-response.json
+   :language: javascript

api-ref/source/v2/samples/routers/router-add-extraroutes-request.json

@@ -0,0 +1,8 @@
+{
+   "router" : {
+      "routes" : [
+         { "destination" : "10.0.3.0/24", "nexthop" : "10.0.0.13" },
+         { "destination" : "10.0.4.0/24", "nexthop" : "10.0.0.14" }
+      ]
+   }
+}

api-ref/source/v2/samples/routers/router-add-extraroutes-response.json

@@ -0,0 +1,12 @@
+{
+   "router" : {
+      "id" : "64e339bb-1a6c-47bd-9ee7-a0cf81a35172",
+      "name" : "router1",
+      "routes" : [
+         { "destination" : "10.0.1.0/24", "nexthop" : "10.0.0.11" },
+         { "destination" : "10.0.2.0/24", "nexthop" : "10.0.0.12" },
+         { "destination" : "10.0.3.0/24", "nexthop" : "10.0.0.13" },
+         { "destination" : "10.0.4.0/24", "nexthop" : "10.0.0.14" }
+      ]
+   }
+}

api-ref/source/v2/samples/routers/router-remove-extraroutes-request.json

@@ -0,0 +1,8 @@
+{
+   "router" : {
+      "routes" : [
+         { "destination" : "10.0.3.0/24", "nexthop" : "10.0.0.13" },
+         { "destination" : "10.0.4.0/24", "nexthop" : "10.0.0.14" }
+      ]
+   }
+}

api-ref/source/v2/samples/routers/router-remove-extraroutes-response.json

@@ -0,0 +1,10 @@
+{
+   "router" : {
+      "id" : "64e339bb-1a6c-47bd-9ee7-a0cf81a35172",
+      "name" : "router1",
+      "routes" : [
+         { "destination" : "10.0.1.0/24", "nexthop" : "10.0.0.11" },
+         { "destination" : "10.0.2.0/24", "nexthop" : "10.0.0.12" }
+      ]
+   }
+}

neutron_lib/api/definitions/__init__.py

@@ -36,6 +36,7 @@ from neutron_lib.api.definitions import expose_port_forwarding_in_fip
 from neutron_lib.api.definitions import external_net
 from neutron_lib.api.definitions import extra_dhcp_opt
 from neutron_lib.api.definitions import extraroute
+from neutron_lib.api.definitions import extraroute_atomic
 from neutron_lib.api.definitions import filter_validation
 from neutron_lib.api.definitions import fip64
 from neutron_lib.api.definitions import fip_port_details
@@ -142,6 +143,7 @@ _ALL_API_DEFINITIONS = {
     external_net,
     extra_dhcp_opt,
     extraroute,
+    extraroute_atomic,
     filter_validation,
     fip64,
     firewall,

neutron_lib/api/definitions/base.py

@@ -97,6 +97,7 @@ KNOWN_EXTENSIONS = (
     'external-net',
     'extra_dhcp_opt',
     'extraroute',
+    'extraroute-atomic',
     'filter-validation',
     'fip-port-details',
     'flavors',

neutron_lib/api/definitions/extraroute_atomic.py

@@ -0,0 +1,38 @@
+# Copyright 2019 Ericsson Software Technology
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+from neutron_lib.api.definitions import extraroute
+from neutron_lib.api.definitions import l3
+
+
+ALIAS = 'extraroute-atomic'
+IS_SHIM_EXTENSION = False
+IS_STANDARD_ATTR_EXTENSION = False
+NAME = 'Atomically add/remove extra routes'
+DESCRIPTION = ('Edit extra routes of a router on server side by atomically '
+               'adding/removing extra routes')
+UPDATED_TIMESTAMP = '2019-07-10T00:00:00+00:00'
+RESOURCE_ATTRIBUTE_MAP = {
+    l3.ROUTERS: {}
+}
+SUB_RESOURCE_ATTRIBUTE_MAP = None
+ACTION_MAP = {
+    l3.ROUTER: {
+        'add_extraroutes': 'PUT',
+        'remove_extraroutes': 'PUT',
+    }
+}
+REQUIRED_EXTENSIONS = [l3.ALIAS, extraroute.ALIAS]
+OPTIONAL_EXTENSIONS = []
+ACTION_STATUS = {}

neutron_lib/tests/unit/api/definitions/test_extraroute_atomic.py

@@ -0,0 +1,20 @@
+# Copyright 2019 Ericsson Software Technology
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+from neutron_lib.api.definitions import extraroute_atomic
+from neutron_lib.tests.unit.api.definitions import base
+
+
+class ExtrarouteAtomicDefinitionTestCase(base.DefinitionBaseTestCase):
+    extension_module = extraroute_atomic

releasenotes/notes/extraroute-atomic-apidef-80a7c6d4a773c701.yaml

@@ -0,0 +1,4 @@
+---
+features:
+  - |
+    New API definition: ``extraroute-atomic``.