Browse Source

New api-def: extraroute-atomic

Change-Id: Ib0338bb00652fb6a03c50f204ce8f19cf4d38352
Partial-Bug: #1826396 (rfe)
Related-Change: https://review.opendev.org/655680 (spec)
tags/1.29.0^0
Bence Romsics 2 months ago
parent
commit
104627a933

+ 151
- 0
api-ref/source/v2/routers.inc View File

@@ -22,6 +22,17 @@ Extra routes extension
22 22
 The extra route extension (``extraroute``) extends ``router`` resources adding
23 23
 a ``routes`` attribute that contains an array of route objects. Each route
24 24
 object has a ``destination`` and ``nexthop`` attribute representing the route.
25
+When the ``extraroute-atomic`` extension is also available you can add
26
+or remove a set of extra routes atomically on the server side. For details
27
+please see below.
28
+
29
+Extra routes (atomic) extension
30
+===============================
31
+
32
+The extra route atomic extension (``extraroute-atomic``) extends the
33
+``router`` resource by adding two member actions (``add_extraroutes`` /
34
+``remove_extraroutes``) to edit the set of extra routes atomically on
35
+the server side.
25 36
 
26 37
 HA capability for router extension (``l3-ha``)
27 38
 =======================================================
@@ -579,3 +590,143 @@ Response Example
579 590
 .. literalinclude:: samples/routers/router-remove-interface-response.json
580 591
    :language: javascript
581 592
 
593
+Add extra routes to router
594
+==========================
595
+
596
+.. rest_method::  PUT /v2.0/routers/{router_id}/add_extraroutes
597
+
598
+Atomically adds a set of extra routes to the router's already existing
599
+extra routes.
600
+
601
+This operation is a variation on updating the router's ``routes``
602
+parameter.  In all ways it works the same, except the extra routes sent
603
+in the request body do not replace the existing set of extra routes.
604
+Instead the extra routes sent are added to the existing set of
605
+extra routes.
606
+
607
+The use of the add_extraroutes/remove_extraroutes member actions
608
+is preferred to updating the ``routes`` attribute in all cases when
609
+concurrent updates to the set of extra routes are possible.
610
+
611
+The addition's corner cases behave the following way:
612
+
613
+* When (destinationA, nexthopA) is to be added but it is already present
614
+  that is accepted and the request succeeds.
615
+
616
+* Two or more routes with the same destination but with different
617
+  nexthops are all accepted.
618
+
619
+* A route whose destination overlaps the destination of existing routes
620
+  (e.g. ``192.168.1.0/24`` and ``192.168.1.0/22``) can be added and
621
+  existing routes are left untouched.
622
+
623
+The format of the request body is the same as the format of a PUT
624
+request to the router changing the ``routes`` parameter only.
625
+
626
+The response codes and response body are the same as to the update of
627
+the ``routes`` parameter. That is the whole router object is returned
628
+including the ``routes`` parameter which represents the result of the
629
+addition.
630
+
631
+Normal response codes: 200
632
+
633
+Error response codes: 400, 401, 404, 412
634
+
635
+Request
636
+-------
637
+
638
+.. rest_parameters:: parameters.yaml
639
+
640
+   - router_id: router_id
641
+   - routes: router-routes
642
+
643
+Request Example
644
+---------------
645
+
646
+.. literalinclude:: samples/routers/router-add-extraroutes-request.json
647
+   :language: javascript
648
+
649
+Response Parameters
650
+-------------------
651
+
652
+.. rest_parameters:: parameters.yaml
653
+
654
+   - id: router-id-body
655
+   - name: router_name
656
+   - routes: router-routes
657
+
658
+Response Example
659
+----------------
660
+
661
+.. literalinclude:: samples/routers/router-add-extraroutes-response.json
662
+   :language: javascript
663
+
664
+Remove extra routes from router
665
+===============================
666
+
667
+.. rest_method::  PUT /v2.0/routers/{router_id}/remove_extraroutes
668
+
669
+Atomically removes a set of extra routes from the router's already
670
+existing extra routes.
671
+
672
+This operation is a variation on updating the router's ``routes``
673
+parameter.  In all ways it works the same, except the extra routes sent
674
+in the request body do not replace the existing set of extra routes.
675
+Instead the the extra routes sent are removed from the existing set of
676
+extra routes.
677
+
678
+The use of the add_extraroutes/remove_extraroutes member actions
679
+is preferred to updating the ``routes`` attribute in all cases when
680
+concurrent updates to the set of extra routes are possible.
681
+
682
+The removal's corner cases behave the following way:
683
+
684
+* An extra route is only removed if there is an exact match (including the
685
+  ``destination`` and ``nexthop``) between the route sent and the route
686
+  already present.
687
+
688
+* When (destinationA, nexthopA) is to be removed but it is already missing
689
+  that is accepted and the request succeeds.
690
+
691
+The format of the request body is the same as the format of a PUT
692
+request to the router changing the ``routes`` parameter only. However
693
+the routes sent are not meant to overwrite the whole ``routes``
694
+parameter, but they are meant to be removed from the existing set.
695
+
696
+The response codes and response body are the same as to the update of
697
+the ``routes`` parameter. That is the whole router object is returned
698
+including the ``routes`` parameter which represents the result of the
699
+removal.
700
+
701
+Normal response codes: 200
702
+
703
+Error response codes: 400, 401, 404, 412
704
+
705
+Request
706
+-------
707
+
708
+.. rest_parameters:: parameters.yaml
709
+
710
+   - router_id: router_id
711
+   - routes: router-routes
712
+
713
+Request Example
714
+---------------
715
+
716
+.. literalinclude:: samples/routers/router-remove-extraroutes-request.json
717
+   :language: javascript
718
+
719
+Response Parameters
720
+-------------------
721
+
722
+.. rest_parameters:: parameters.yaml
723
+
724
+   - id: router-id-body
725
+   - name: router_name
726
+   - routes: router-routes
727
+
728
+Response Example
729
+----------------
730
+
731
+.. literalinclude:: samples/routers/router-remove-extraroutes-response.json
732
+   :language: javascript

+ 8
- 0
api-ref/source/v2/samples/routers/router-add-extraroutes-request.json View File

@@ -0,0 +1,8 @@
1
+{
2
+   "router" : {
3
+      "routes" : [
4
+         { "destination" : "10.0.3.0/24", "nexthop" : "10.0.0.13" },
5
+         { "destination" : "10.0.4.0/24", "nexthop" : "10.0.0.14" }
6
+      ]
7
+   }
8
+}

+ 12
- 0
api-ref/source/v2/samples/routers/router-add-extraroutes-response.json View File

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

+ 8
- 0
api-ref/source/v2/samples/routers/router-remove-extraroutes-request.json View File

@@ -0,0 +1,8 @@
1
+{
2
+   "router" : {
3
+      "routes" : [
4
+         { "destination" : "10.0.3.0/24", "nexthop" : "10.0.0.13" },
5
+         { "destination" : "10.0.4.0/24", "nexthop" : "10.0.0.14" }
6
+      ]
7
+   }
8
+}

+ 10
- 0
api-ref/source/v2/samples/routers/router-remove-extraroutes-response.json View File

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

+ 2
- 0
neutron_lib/api/definitions/__init__.py View File

@@ -36,6 +36,7 @@ from neutron_lib.api.definitions import expose_port_forwarding_in_fip
36 36
 from neutron_lib.api.definitions import external_net
37 37
 from neutron_lib.api.definitions import extra_dhcp_opt
38 38
 from neutron_lib.api.definitions import extraroute
39
+from neutron_lib.api.definitions import extraroute_atomic
39 40
 from neutron_lib.api.definitions import filter_validation
40 41
 from neutron_lib.api.definitions import fip64
41 42
 from neutron_lib.api.definitions import fip_port_details
@@ -142,6 +143,7 @@ _ALL_API_DEFINITIONS = {
142 143
     external_net,
143 144
     extra_dhcp_opt,
144 145
     extraroute,
146
+    extraroute_atomic,
145 147
     filter_validation,
146 148
     fip64,
147 149
     firewall,

+ 1
- 0
neutron_lib/api/definitions/base.py View File

@@ -97,6 +97,7 @@ KNOWN_EXTENSIONS = (
97 97
     'external-net',
98 98
     'extra_dhcp_opt',
99 99
     'extraroute',
100
+    'extraroute-atomic',
100 101
     'filter-validation',
101 102
     'fip-port-details',
102 103
     'flavors',

+ 38
- 0
neutron_lib/api/definitions/extraroute_atomic.py View File

@@ -0,0 +1,38 @@
1
+# Copyright 2019 Ericsson Software Technology
2
+#
3
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
4
+#    not use this file except in compliance with the License. You may obtain
5
+#    a copy of the License at
6
+#
7
+#         http://www.apache.org/licenses/LICENSE-2.0
8
+#
9
+#    Unless required by applicable law or agreed to in writing, software
10
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12
+#    License for the specific language governing permissions and limitations
13
+#    under the License.
14
+
15
+from neutron_lib.api.definitions import extraroute
16
+from neutron_lib.api.definitions import l3
17
+
18
+
19
+ALIAS = 'extraroute-atomic'
20
+IS_SHIM_EXTENSION = False
21
+IS_STANDARD_ATTR_EXTENSION = False
22
+NAME = 'Atomically add/remove extra routes'
23
+DESCRIPTION = ('Edit extra routes of a router on server side by atomically '
24
+               'adding/removing extra routes')
25
+UPDATED_TIMESTAMP = '2019-07-10T00:00:00+00:00'
26
+RESOURCE_ATTRIBUTE_MAP = {
27
+    l3.ROUTERS: {}
28
+}
29
+SUB_RESOURCE_ATTRIBUTE_MAP = None
30
+ACTION_MAP = {
31
+    l3.ROUTER: {
32
+        'add_extraroutes': 'PUT',
33
+        'remove_extraroutes': 'PUT',
34
+    }
35
+}
36
+REQUIRED_EXTENSIONS = [l3.ALIAS, extraroute.ALIAS]
37
+OPTIONAL_EXTENSIONS = []
38
+ACTION_STATUS = {}

+ 20
- 0
neutron_lib/tests/unit/api/definitions/test_extraroute_atomic.py View File

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

+ 4
- 0
releasenotes/notes/extraroute-atomic-apidef-80a7c6d4a773c701.yaml View File

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

Loading…
Cancel
Save