From 104627a9336c2cff6808dc0024c43c6b0a7a723c Mon Sep 17 00:00:00 2001 From: Bence Romsics Date: Wed, 10 Jul 2019 14:37:58 +0200 Subject: [PATCH] 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 | 151 ++++++++++++++++++ .../router-add-extraroutes-request.json | 8 + .../router-add-extraroutes-response.json | 12 ++ .../router-remove-extraroutes-request.json | 8 + .../router-remove-extraroutes-response.json | 10 ++ neutron_lib/api/definitions/__init__.py | 2 + neutron_lib/api/definitions/base.py | 1 + .../api/definitions/extraroute_atomic.py | 38 +++++ .../api/definitions/test_extraroute_atomic.py | 20 +++ ...aroute-atomic-apidef-80a7c6d4a773c701.yaml | 4 + 10 files changed, 254 insertions(+) create mode 100644 api-ref/source/v2/samples/routers/router-add-extraroutes-request.json create mode 100644 api-ref/source/v2/samples/routers/router-add-extraroutes-response.json create mode 100644 api-ref/source/v2/samples/routers/router-remove-extraroutes-request.json create mode 100644 api-ref/source/v2/samples/routers/router-remove-extraroutes-response.json create mode 100644 neutron_lib/api/definitions/extraroute_atomic.py create mode 100644 neutron_lib/tests/unit/api/definitions/test_extraroute_atomic.py create mode 100644 releasenotes/notes/extraroute-atomic-apidef-80a7c6d4a773c701.yaml diff --git a/api-ref/source/v2/routers.inc b/api-ref/source/v2/routers.inc index 6c3444f47..32869f13c 100644 --- a/api-ref/source/v2/routers.inc +++ b/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 diff --git a/api-ref/source/v2/samples/routers/router-add-extraroutes-request.json b/api-ref/source/v2/samples/routers/router-add-extraroutes-request.json new file mode 100644 index 000000000..ab94c6b33 --- /dev/null +++ b/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" } + ] + } +} diff --git a/api-ref/source/v2/samples/routers/router-add-extraroutes-response.json b/api-ref/source/v2/samples/routers/router-add-extraroutes-response.json new file mode 100644 index 000000000..f3ec0a4c5 --- /dev/null +++ b/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" } + ] + } +} diff --git a/api-ref/source/v2/samples/routers/router-remove-extraroutes-request.json b/api-ref/source/v2/samples/routers/router-remove-extraroutes-request.json new file mode 100644 index 000000000..ab94c6b33 --- /dev/null +++ b/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" } + ] + } +} diff --git a/api-ref/source/v2/samples/routers/router-remove-extraroutes-response.json b/api-ref/source/v2/samples/routers/router-remove-extraroutes-response.json new file mode 100644 index 000000000..a05bab457 --- /dev/null +++ b/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" } + ] + } +} diff --git a/neutron_lib/api/definitions/__init__.py b/neutron_lib/api/definitions/__init__.py index 345ca66c1..a504a90d4 100644 --- a/neutron_lib/api/definitions/__init__.py +++ b/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, diff --git a/neutron_lib/api/definitions/base.py b/neutron_lib/api/definitions/base.py index 94affd7e8..5897a3c05 100644 --- a/neutron_lib/api/definitions/base.py +++ b/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', diff --git a/neutron_lib/api/definitions/extraroute_atomic.py b/neutron_lib/api/definitions/extraroute_atomic.py new file mode 100644 index 000000000..73f63b718 --- /dev/null +++ b/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 = {} diff --git a/neutron_lib/tests/unit/api/definitions/test_extraroute_atomic.py b/neutron_lib/tests/unit/api/definitions/test_extraroute_atomic.py new file mode 100644 index 000000000..72ac74c51 --- /dev/null +++ b/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 diff --git a/releasenotes/notes/extraroute-atomic-apidef-80a7c6d4a773c701.yaml b/releasenotes/notes/extraroute-atomic-apidef-80a7c6d4a773c701.yaml new file mode 100644 index 000000000..b84e1fae6 --- /dev/null +++ b/releasenotes/notes/extraroute-atomic-apidef-80a7c6d4a773c701.yaml @@ -0,0 +1,4 @@ +--- +features: + - | + New API definition: ``extraroute-atomic``.