Merge "bgpvpn-routes-control extension"

api-ref/source/v2/bgpvpn-bgpvpns.inc

@@ -8,9 +8,11 @@ A new BGPVPN resource is introduced. It contains a set of parameters for a
 BGP-based VPN.
 
 A BGPVPN is created by the admin and given to a tenant who can then associate
-it to Networks or Routers.
+it to Networks, Routers or Ports (the latter when the ``bgpvpn-routes-control``
+extension is available).
 
-The BGP VPNs API lists, shows details for, creates, updates, and deletes BGP VPNs.
+The BGP VPNs API lists, shows details for, creates, updates, and deletes
+BGP VPNs.
 
 List BGP VPNs
 =============
@@ -51,6 +53,8 @@ Response Parameters
    - export_targets: bgpvpn-export_targets-required
    - networks: bgpvpn-networks-required
    - routers: bgpvpn-routers-required
+   - ports: bgpvpn-ports
+   - local_pref: bgpvpn-local_pref
    - tenant_id: project_id
    - project_id: project_id
 
@@ -82,6 +86,7 @@ Request
    - route_targets: bgpvpn-route_targets
    - import_targets: bgpvpn-import_targets
    - export_targets: bgpvpn-export_targets
+   - local_pref: bgpvpn-local_pref-request
    - tenant_id: tenant_id-request
    - project_id: project_id-request
    - type: bgpvpn-type
@@ -106,6 +111,8 @@ Response Parameters
    - export_targets: bgpvpn-export_targets-required
    - networks: bgpvpn-networks-required
    - routers: bgpvpn-routers-required
+   - ports: bgpvpn-ports
+   - local_pref: bgpvpn-local_pref
    - tenant_id: project_id
    - project_id: project_id
 
@@ -148,6 +155,8 @@ Response Parameters
    - export_targets: bgpvpn-export_targets-required
    - networks: bgpvpn-networks-required
    - routers: bgpvpn-routers-required
+   - ports: bgpvpn-ports
+   - local_pref: bgpvpn-local_pref
    - tenant_id: project_id
    - project_id: project_id
 
@@ -182,6 +191,7 @@ admin privileges.
    - route_targets: bgpvpn-route_targets
    - import_targets: bgpvpn-import_targets
    - export_targets: bgpvpn-export_targets
+   - local_pref: bgpvpn-local_pref-request
 
 Request Example
 ---------------
@@ -204,6 +214,8 @@ Response Parameters
    - export_targets: bgpvpn-export_targets-required
    - networks: bgpvpn-networks-required
    - routers: bgpvpn-routers-required
+   - ports: bgpvpn-ports
+   - local_pref: bgpvpn-local_pref
    - tenant_id: project_id
    - project_id: project_id
 
@@ -220,9 +232,9 @@ Delete BGP VPN
 
 Deletes a BGP VPN and its network and/or router associations.
 
-Normal response codes: 202
+Normal response codes: 204
 
-Error response codes: 400, 401, 403, 404
+Error response codes: 401, 403, 404
 
 Request
 -------

api-ref/source/v2/bgpvpn-network_associations.inc

@@ -139,7 +139,7 @@ Delete Network Association
 
 Deletes a network association.
 
-Normal response codes: 202, 204
+Normal response codes: 204
 
 Error response codes: 400, 401, 403, 404
 

api-ref/source/v2/bgpvpn-overview.inc

@@ -8,8 +8,8 @@ routers with Multiprotocol Label Switching (MPLS) Virtual Private
 Networks (VPNs) via Border Gateway Protocol (BGP) peering. BGP-MPLS VPNs
 are commonly provided by telecommunications service providers to
 customers in addition to or instead of Internet connectivity for Wide
-Area Networking. This API enables the interconnection of with these
+Area Networking. This API enables the interconnection with these
-WANs using *Route Targets* to indicate the desired network(s).
+WAN VPNs using *Route Targets* to indicate the desired network(s).
 
 On Route Targets
 ================
@@ -50,6 +50,36 @@ Valid strings for a Route Target or a Route Distinguisher are the following:
 - <4-byte AS#>:<16bit-number>
 - <4-byte IPv4>:<16bit-number>
 
+Control of routes advertised to BGPVPNs
+=======================================
+
+With the ``bgpvpn`` extension, when associations between networks or routers
+and BGVPNs are defined, the routes corresponding to fixed IPs of neutron ports
+will be advertised to BGPVPNs.  For router associations, extra routes of the
+router ('routes' attribute of a ``router`` resource) may also be advertised
+to BGPVPNs.
+
+To provide more flexibility, the ``bgpvpn-routes-control`` extension provides
+a way to:
+
+- advertise other routes to a BGPVPN, for instances a prefix that is reachable
+  via a neutron port, or routes leaked from another BGPVPN; this is implemented
+  thanks to the ``routes`` attribute of a BGPVPN port association
+
+- not advertise the fixed IPs of a neutron port to a BGPVPN, which can be
+  particularly relevant when other IP prefixes are reachable via the port; this
+  is implemented thanks to the ``advertise_fixed_ips`` attribute of a BGPVPN
+  port association
+
+- explictly control whether extra routes of a router are to be advertised
+  to a BGPVPN; this is implemented thanks to the ``advertise_extra_routes``
+  attribute of a BGPVPN router association
+
+- optionally control the value of the LOCAL_PREF BGP attribute of advertised
+  routes, for all routes of a BGPVPN (thanks to the ``local_pref`` attribute
+  of a BGPVPN resource) and/or per route (thanks to the ``local_pref``
+  in a port association route)
+
 ======================
 BGP - MPLS VPN Caveats
 ======================

api-ref/source/v2/bgpvpn-port_associations.inc

@@ -0,0 +1,248 @@
+=================
+Port Associations
+=================
+
+Port associations are available if the ``bgpvpn-routes-control`` extension
+is available.
+
+Associating or disassociating a BGPVPN to a Port is done by manipulating a
+Port association API resource as a sub-resource of the BGPVPN resource.
+
+The semantic behind this API call is a form of policy-based routing: the
+traffic from the given Port will be processed according to dataplane lookups
+specific to this Port. This means, in particular that Ports belonging to a
+given neutron network will possibly see a different L2 or L3 connectivity if
+they have different BGPVPN associations.
+
+When, a port association is defined for a given port, and at the same time,
+a network association is defined for the port's network, both associations are
+considered simultaneously active and the connectivity will be established
+between the port and the BGPVPNs in both associations. This is true also in
+the case where multiple associations are made, and for a router associations
+of a router connected to the port's network.
+
+Port routes
+===========
+
+Additionally to providing Port-level granularity in the definition of BGPVPN
+connectivity, port associations also provide a way to control the
+advertisement of routes other than only the fixed IPs of neutron ports.
+
+So-called static routes are defined as follows: to indicate that prefix
+20.1.0.0/16 is reachable via port A and should be advertised
+accordingly in BGPVPN X,  a port association is defined between port A
+and BGPVPN X, with the ``routes`` attribute set to ``[ {'type': 'prefix',
+'prefix': '20.1.0.0/16'} ]``.
+
+Route leaking of the routes of a given BGPVPN into another BGPVPN belonging
+to the same tenant, is supported similarily: to indicate that all the prefixes
+advertised to BGPVPN Y are reachable via port A (i.e. the routes tagged with at
+least an RT belonging to ``route_targets`` or ``import_targets`` of BGPVPN Y),
+and that they should be leaked into BGPVPN X, a port association is defined
+between port A and BGPVPN X, with the ``routes`` attribute set to
+``[ {'type': 'bgpvpn', 'bgpvpn_id': <uuid of BGPVPN Y>} ]``.
+
+Control of BGP LOCAL_PREF attribute
+===================================
+
+The BGP LOCAL_PREF for a specific route can be controlled to take a different
+value than the one defined in the BGPVPN ``local_pref`` attribute, by
+adding a ``'local_pref': VALUE`` in a route in the ``routes`` attribute (see
+example in port association Update request).
+
+List Port Associations
+======================
+
+.. rest_method::  GET /v2.0/bgpvpn/bgpvpns/{bgpvpn_id}/port_associations
+
+Lists port associations for a given BGP VPN.
+
+Use the ``fields`` query parameter to control which fields are
+returned in the response body. Additionally, you can filter results
+by using query string parameters. For information, see `Filtering
+and Column Selection <https://wiki.openstack.org/wiki/Neutron/APIv2
+-specification#Filtering_and_Column_Selection>`__.
+
+Normal response codes: 200
+
+Error response codes: 401, 403, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - bgpvpn_id: bgpvpn-id-path
+   - fields: fields
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - port_associations: bgpvpn-port_associations
+   - id: bgpvpn-port_association_id
+   - port_id: bgpvpn-port_id
+   - project_id: project_id
+   - routes: bgpvpn-routes
+   - advertise_fixed_ips: bgpvpn-advertise_fixed_ips
+
+Response Example
+----------------
+
+.. literalinclude:: samples/bgpvpn/port_associations/port_association-list-response.json
+   :language: javascript
+
+Create Port Association
+=======================
+
+.. rest_method::  POST /v2.0/bgpvpn/bgpvpns/{bgpvpn_id}/port_associations
+
+Creates a port association for a given BGP VPN
+
+Normal response codes: 201
+
+Error response codes: 400, 401, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - bgpvpn_id: bgpvpn-id-path
+   - port_association: bgpvpn-port_association
+   - port_id: bgpvpn-port_id
+   - routes: bgpvpn-routes-request
+   - advertise_fixed_ips: bgpvpn-advertise_fixed_ips-request
+
+Request Example
+---------------
+
+.. literalinclude:: samples/bgpvpn/port_associations/port_association-create-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - port_association: bgpvpn-port_association
+   - id: bgpvpn-port_association_id
+   - port_id: bgpvpn-port_id
+   - project_id: project_id
+   - routes: bgpvpn-routes
+   - advertise_fixed_ips: bgpvpn-advertise_fixed_ips
+
+Response Example
+----------------
+
+.. literalinclude:: samples/bgpvpn/port_associations/port_association-create-response.json
+   :language: javascript
+
+Show Port Association details
+=============================
+
+.. rest_method::  GET /v2.0/bgpvpn/bgpvpns/{bgpvpn_id}/port_associations/{port_association_id}
+
+Shows details for a port association.
+
+Normal response codes: 200
+
+Error response codes: 401, 403, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - bgpvpn_id: bgpvpn-id-path
+   - port_association_id: bgpvpn-port_association_id-path
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - port_association: bgpvpn-port_association
+   - id: bgpvpn-port_association_id
+   - port_id: bgpvpn-port_id
+   - project_id: project_id
+   - routes: bgpvpn-routes
+   - advertise_fixed_ips: bgpvpn-advertise_fixed_ips
+
+Response Example
+----------------
+
+.. literalinclude:: samples/bgpvpn/port_associations/port_association-show-response.json
+   :language: javascript
+
+Update a Port Association
+=========================
+
+.. rest_method::  PUT /v2.0/bgpvpn/bgpvpns/{bgpvpn_id}/port_associations/{port_association_id}
+
+Updates a port Association.
+
+Normal response codes: 201
+
+Error response codes: 400, 401, 403, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - bgpvpn_id: bgpvpn-id-path
+   - port_association_id: bgpvpn-port_association_id-path
+   - port_association: bgpvpn-port_association
+   - routes: bgpvpn-routes-request
+   - advertise_fixed_ips: bgpvpn-advertise_fixed_ips-request
+
+Request Example
+---------------
+
+.. literalinclude:: samples/bgpvpn/port_associations/port_association-update-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - port_association: bgpvpn-port_association
+   - id: bgpvpn-port_association_id
+   - port_id: bgpvpn-port_id
+   - project_id: project_id
+   - routes: bgpvpn-routes
+   - advertise_fixed_ips: bgpvpn-advertise_fixed_ips
+
+Response Example
+----------------
+
+.. literalinclude:: samples/bgpvpn/port_associations/port_association-update-response.json
+   :language: javascript
+
+
+Delete Port Association
+=======================
+
+.. rest_method::  DELETE /v2.0/bgpvpn/bgpvpns/{bgpvpn_id}/port_associations/{port_association_id}
+
+Deletes a port association.
+
+Normal response codes: 204
+
+Error response codes: 401, 403, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - bgpvpn_id: bgpvpn-id-path
+   - port_association_id: bgpvpn-port_association_id-path
+
+Response
+--------
+
+There is no body content for the response of a successful DELETE request.

api-ref/source/v2/bgpvpn-router_associations.inc

@@ -13,6 +13,22 @@ A said Router can be associated with multiple BGPVPNs.
 Associating or disassociating a BGPVPN to a Router is done by manipulating a
 Router association API resource as a sub-resource of the BGPVPN resource:
 
+Advertising router extra routes to a BGPVPN
+===========================================
+
+The ``bgpvpn-routes-control`` API extension allows to control the
+re-advertisement of a router extra routes in a BGPVPN ("extra routes" are
+routes defined in the ``routes`` attribute of a router when the ``extraroute``
+extension is available).
+
+The ``advertise_extra_routes`` attribute can in this case be set on a
+router_association:
+
+- ``true``: the extra routes defined in the ``routes`` attribute of
+  the router will be advertised to the BGPVPN (default value)
+- ``false``: the extra routes defined in the ``routes`` attribute of
+  the router will **not** be advertised to the BGPVPN
+
 List Router Associations
 =========================
 
@@ -134,6 +150,55 @@ Response Example
 .. literalinclude:: samples/bgpvpn/router_associations/router_association-show-response.json
    :language: javascript
 
+
+Update a Router Association ('bgpvpn-routes-control' extension)
+===============================================================
+
+.. note:: This operation is only available when the ``bgpvpn-routes-control``
+          API extension is enabled.
+
+.. rest_method::  PUT /v2.0/bgpvpn/bgpvpns/{bgpvpn_id}/router_associations/{router_association_id}
+
+Updates a router association.
+
+Normal response codes: 201
+
+Error response codes: 400, 401, 403, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - bgpvpn_id: bgpvpn-id-path
+   - router_association_id: bgpvpn-router_association_id-path
+   - router_association: bgpvpn-router_association
+   - advertise_extra_routes: bgpvpn-advertise_extra_routes-request
+
+Request Example
+---------------
+
+.. literalinclude:: samples/bgpvpn/router_associations/router_association-update-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - router_association: bgpvpn-router_association
+   - id: bgpvpn-router_association_id
+   - router_id: bgpvpn-router_id
+   - project_id: project_id
+   - advertise_extra_routes: bgpvpn-advertise_extra_routes
+
+Response Example
+----------------
+
+.. literalinclude:: samples/bgpvpn/router_associations/router_association-update-response.json
+   :language: javascript
+
+
 Delete Router Association
 ==========================
 
@@ -141,9 +206,9 @@ Delete Router Association
 
 Deletes a router association.
 
-Normal response codes: 202
+Normal response codes: 204
 
-Error response codes: 400, 401, 403, 404
+Error response codes: 401, 403, 404
 
 Request
 -------

api-ref/source/v2/index.rst

@@ -74,3 +74,4 @@ BGP/MPLS VPN Interconnection
 .. include:: bgpvpn-bgpvpns.inc
 .. include:: bgpvpn-network_associations.inc
 .. include:: bgpvpn-router_associations.inc
+.. include:: bgpvpn-port_associations.inc

api-ref/source/v2/parameters.yaml

@@ -13,6 +13,12 @@ bgpvpn-network_association_id-path:
   in: path
   required: true
   type: string
+bgpvpn-port_association_id-path:
+  description: |
+      The ID of an association between a port and a BGP VPN.
+  in: path
+  required: true
+  type: string
 bgpvpn-router_association_id-path:
   description: |
       The ID of an association between a router and a BGP VPN.
@@ -630,6 +636,35 @@ bgpvpn:
   in: body
   required: true
   type: object
+bgpvpn-advertise_extra_routes:
+  description: |
+      Boolean flag controlling whether or not the routes specified in the
+      ``routes`` attribute of the router will be advertised to the BGPVPN.
+  in: body
+  required: true
+  type: boolean
+bgpvpn-advertise_extra_routes-request:
+  description: |
+      Boolean flag controlling whether or not the routes specified in the
+      ``routes`` attribute of the router will be advertised to the BGPVPN
+      (default: true).
+  in: body
+  required: false
+  type: boolean
+bgpvpn-advertise_fixed_ips:
+  description: |
+      Boolean flag controlling whether or not the fixed IPs of a port will
+      be advertised to the BGPVPN.
+  in: body
+  required: true
+  type: boolean
+bgpvpn-advertise_fixed_ips-request:
+  description: |
+      Boolean flag controlling whether or not the fixed IPs of a port will
+      be advertised to the BGPVPN (default: true).
+  in: body
+  required: false
+  type: boolean
 bgpvpn-export_targets:
   description: |
       Additional Route Targets that will be used for export.
@@ -660,6 +695,20 @@ bgpvpn-import_targets-required:
   in: body
   required: true
   type: array
+bgpvpn-local_pref:
+  description: |
+      The default BGP LOCAL_PREF of routes that will be advertised to the
+      BGPVPN (unless overriden per-route).
+  in: body
+  required: true
+  type: integer
+bgpvpn-local_pref-request:
+  description: |
+      The default BGP LOCAL_PREF of routes that will be advertised to the
+      BGPVPN (unless overriden per-route).
+  in: body
+  required: false
+  type: integer
 bgpvpn-name:
   description: |
       The user meaningful name of the BGP VPN.
@@ -674,7 +723,7 @@ bgpvpn-name-required:
   type: string
 bgpvpn-network_association:
   description: |
-    A ``network_association`` object represents the binding of an MPLS network
+    A ``network_association`` object represents the binding of a BGP VPN
     to a Neutron network.
   in: body
   required: true
@@ -700,25 +749,63 @@ bgpvpn-network_id:
   type: string
 bgpvpn-networks:
   description: |
-       This read-only list of network IDs reflects the associations defined by Network association API resources.
+       This read-only list of network IDs reflects the associations defined by
+       Network association API resources.
   in: body
   required: false
   type: array
 bgpvpn-networks-required:
   description: |
-       This read-only list of network IDs reflects the associations defined by Network association API resources.
+       This read-only list of network IDs reflects the associations defined by
+       Network association API resources.
+  in: body
+  required: true
+  type: array
+bgpvpn-port_association:
+  description: |
+    A ``port_association`` object represents the binding of a BGP VPN
+    to a Neutron port.
+  in: body
+  required: true
+  type: object
+bgpvpn-port_association_id:
+  description: |
+      The ID of an association between a port and a BGP VPN.
+  in: body
+  required: true
+  type: string
+bgpvpn-port_associations:
+  description: |
+    A list of ``port_association`` objects which represent bindings
+    of MPLS networks to Neutron ports.
+  in: body
+  required: true
+  type: array
+bgpvpn-port_id:
+  description: |
+      The ID of a Neutron port with which to associate the BGP VPN.
+  in: body
+  required: true
+  type: string
+bgpvpn-ports:
+  description: |
+      This read-only list of port IDs reflects the associations defined by Port
+      association API resources (only present if the ``bgpvpn-routes-control``
+      API extension is enabled).
   in: body
   required: true
   type: array
 bgpvpn-route_distinguishers:
   description: |
-      List of route distinguisher strings. If this parameter is specified, one of these RDs will be used to advertise VPN routes.
+      List of route distinguisher strings. If this parameter is specified, one
+      of these RDs will be used to advertise VPN routes.
   in: body
   required: false
   type: array
 bgpvpn-route_distinguishers-required:
   description: |
-      List of route distinguisher strings. If this parameter is specified, one of these RDs will be used to advertise VPN routes.
+      List of route distinguisher strings. If this parameter is specified, one
+      of these RDs will be used to advertise VPN routes.
   in: body
   required: true
   type: array
@@ -736,7 +823,7 @@ bgpvpn-route_targets-required:
   type: array
 bgpvpn-router_association:
   description: |
-    A ``router_association`` object represents the binding of an MPLS network
+    A ``router_association`` object represents the binding of a BGP VPN
     to a Neutron router.
   in: body
   required: true
@@ -762,16 +849,58 @@ bgpvpn-router_id:
   type: string
 bgpvpn-routers:
   description: |
-      This read-only list of router IDs reflects the associations defined by Router association API resources.
+      This read-only list of router IDs reflects the associations defined by
+      Router association API resources.
   in: body
   required: false
   type: array
 bgpvpn-routers-required:
   description: |
-      This read-only list of router IDs reflects the associations defined by Router association API resources.
+      This read-only list of router IDs reflects the associations defined by
+      Router association API resources.
   in: body
   required: true
   type: array
+bgpvpn-routes:
+  description: |
+      List of routes, each route being a dict with at least a ``type`` key,
+      which can be ``prefix`` or ``bgpvpn``.
+
+      For the ``prefix`` type, the IP prefix (v4 or v6) to advertise
+      is specified in the ``prefix`` key.
+
+      For the ``bgpvpn`` type, the ``bgpvpn_id`` key specifies the BGPVPN from
+      which routes will be readvertised with the association port as the
+      nexthop (any route carrying an RT among ``route_targets`` or
+      ``import_targets`` of this BGPVPN, will be re-announced toward the RTs
+      of the associated BGPVPN (``export_targets`` + ``route_targets``), with
+      their next-hop/label pointing to this port).
+
+      For both types, the ``local_pref`` key can be used to control the
+      value of the BGP LOCAL_PREF of the routes that will be advertised.
+  in: body
+  required: true
+  type: array
+bgpvpn-routes-request:
+  description: |
+      List of routes, each route being a dict with at least a ``type`` key,
+      which can be ``prefix`` or ``bgpvpn``.
+
+      For the ``prefix`` type, the IP prefix (v4 or v6) to advertise
+      is specified in the ``prefix`` key.
+
+      For the ``bgpvpn`` type, the ``bgpvpn_id`` key specifies the BGPVPN from
+      which routes will be readvertised with the association port as the
+      nexthop (any route carrying an RT among ``route_targets`` or
+      ``import_targets`` of this BGPVPN, will be re-announced toward the RTs
+      of the associated BGPVPN (``export_targets`` + ``route_targets``), with
+      their next-hop/label pointing to this port).
+
+      For both types, the ``local_pref`` key can be used to control the
+      value of the BGP LOCAL_PREF of the routes that will be advertised.
+  in: body
+  required: false
+  type: array
 bgpvpn-type:
   description: |
       Selection of the type of VPN and the technology behind it. Allowed

api-ref/source/v2/samples/bgpvpn/bgpvpns/bgpvpn-create-response.json

@@ -20,6 +20,7 @@
     ],
     "type": "l3",
     "id": "0f9d472a-908f-40f5-8574-b4e8a63ccbf0",
-    "networks": []
+    "networks": [],
+    "local_pref": null
   }
 }

api-ref/source/v2/samples/bgpvpn/bgpvpns/bgpvpn-show-response.json

@@ -12,6 +12,7 @@
        "route_distinguishers": [],
        "networks": [
          "a4f2b8df-cb42-4893-a333-d0b5c36ade17"
-       ]
+       ],
+       "local_pref": null
     }
 }

api-ref/source/v2/samples/bgpvpn/bgpvpns/bgpvpn-update-response.json

@@ -11,6 +11,7 @@
     "route_targets": ["64512:1444"],
     "type": "l3",
     "id": "4d627abf-06dd-45ab-920b-8e61422bb984",
-    "networks": []
+    "networks": [],
+    "local_pref": null
   }
 }

api-ref/source/v2/samples/bgpvpn/bgpvpns/bgpvpns-list-response.json

@@ -21,7 +21,8 @@
       ],
       "type": "l3",
       "id": "0f9d472a-908f-40f5-8574-b4e8a63ccbf0",
-      "networks": []
+      "networks": [],
+      "local_pref": null
     }
   ]
 }

api-ref/source/v2/samples/bgpvpn/port_associations/port_association-create-request.json

@@ -0,0 +1,11 @@
+{
+    "port_association": {
+        "port_id": "b58a6241-6e49-4b11-87c6-8e0606dde796",
+        "routes": [
+            {
+                "type": "prefix",
+                "prefix": "20.1.0.0/16"
+            }
+        ]
+    }
+}

api-ref/source/v2/samples/bgpvpn/port_associations/port_association-create-response.json

@@ -0,0 +1,14 @@
+{
+    "port_association": {
+        "id": "c63149a0-a0b3-4ca7-aba4-9aaa1b39d7f3",
+        "port_id": "46a1a80b-7c42-4c45-88fd-b531e636969f",
+        "project_id": "b7549121395844bea941bb92feb3fad9",
+        "routes": [
+            {
+                "type": "prefix",
+                "prefix": "20.1.0.0/16"
+            }
+        ],
+        "advertise_fixed_ips": true
+    }
+}

api-ref/source/v2/samples/bgpvpn/port_associations/port_association-list-response.json

@@ -0,0 +1,16 @@
+{
+    "port_associations": [
+        {
+            "id": "95277be7-a231-4e96-9625-8f9fe41de9d6",
+            "port_id": "61222227-49eb-4dcc-b2d6-66bbfb2fdd7a",
+            "project_id": "b7549121395844bea941bb92feb3fad9",
+            "routes": [
+                {
+                    "type": "prefix",
+                    "prefix": "20.1.0.0/16"
+                }
+            ],
+            "advertise_fixed_ips": true
+        }
+    ]
+}

api-ref/source/v2/samples/bgpvpn/port_associations/port_association-show-response.json

@@ -0,0 +1,14 @@
+{
+    "port_association": {
+        "id": "c63149a0-a0b3-4ca7-aba4-9aaa1b39d7f3",
+        "port_id": "46a1a80b-7c42-4c45-88fd-b531e636969f",
+        "project_id": "b7549121395844bea941bb92feb3fad9",
+        "routes": [
+            {
+                "type": "prefix",
+                "prefix": "20.1.0.0/16"
+            }
+        ],
+        "advertise_fixed_ips": true
+    }
+}

api-ref/source/v2/samples/bgpvpn/port_associations/port_association-update-request.json

@@ -0,0 +1,13 @@
+{
+    "port_association": {
+        "port_id": "46a1a80b-7c42-4c45-88fd-b531e636969f",
+        "routes": [
+            {
+                "type": "bgpvpn",
+                "bgpvpn_id": "180630e3-9eae-4ba7-9939-d5f47966e1f0",
+                "local_pref": 111
+            }
+        ],
+        "advertise_fixed_ips": false
+    }
+}

api-ref/source/v2/samples/bgpvpn/port_associations/port_association-update-response.json

@@ -0,0 +1,15 @@
+{
+    "port_association": {
+        "id": "c63149a0-a0b3-4ca7-aba4-9aaa1b39d7f3",
+        "port_id": "46a1a80b-7c42-4c45-88fd-b531e636969f",
+        "project_id": "b7549121395844bea941bb92feb3fad9",
+        "routes": [
+            {
+                "type": "bgpvpn",
+                "bgpvpn_id": "180630e3-9eae-4ba7-9939-d5f47966e1f0",
+                "local_pref": 111
+            }
+        ],
+        "advertise_fixed_ips": false
+    }
+}

api-ref/source/v2/samples/bgpvpn/router_associations/router_association-create-response.json

@@ -3,6 +3,7 @@
     "router_id": "46a1a80b-7c42-4c45-88fd-b531e636969f",
     "tenant_id": "b7549121395844bea941bb92feb3fad9",
     "project_id": "b7549121395844bea941bb92feb3fad9",
-    "id": "c63149a0-a0b3-4ca7-aba4-9aaa1b39d7f3"
+    "id": "c63149a0-a0b3-4ca7-aba4-9aaa1b39d7f3",
+    "advertise_extra_routes": true
   }
 }

api-ref/source/v2/samples/bgpvpn/router_associations/router_association-list-response.json

@@ -4,7 +4,8 @@
       "router_id": "61222227-49eb-4dcc-b2d6-66bbfb2fdd7a",
       "tenant_id": "b7549121395844bea941bb92feb3fad9",
       "project_id": "b7549121395844bea941bb92feb3fad9",
-      "id": "95277be7-a231-4e96-9625-8f9fe41de9d6"
+      "id": "95277be7-a231-4e96-9625-8f9fe41de9d6",
+      "advertise_extra_routes": true
     }
   ]
 }

api-ref/source/v2/samples/bgpvpn/router_associations/router_association-show-response.json

@@ -1,8 +1,9 @@
 {
     "router_association": {
-          "id": "c63149a0-a0b3-4ca7-aba4-9aaa1b39d7f3",
+        "id": "c63149a0-a0b3-4ca7-aba4-9aaa1b39d7f3",
-          "router_id": "46a1a80b-7c42-4c45-88fd-b531e636969f",
+        "router_id": "46a1a80b-7c42-4c45-88fd-b531e636969f",
-          "tenant_id": "b7549121395844bea941bb92feb3fad9",
+        "tenant_id": "b7549121395844bea941bb92feb3fad9",
-          "project_id": "b7549121395844bea941bb92feb3fad9"
+        "project_id": "b7549121395844bea941bb92feb3fad9",
-       }
+        "advertise_extra_routes": true
+    }
 }

api-ref/source/v2/samples/bgpvpn/router_associations/router_association-update-request.json

@@ -0,0 +1,6 @@
+{
+    "router_association": {
+        "router_id": "46a1a80b-7c42-4c45-88fd-b531e636969f",
+        "advertise_extra_routes": false
+    }
+}

api-ref/source/v2/samples/bgpvpn/router_associations/router_association-update-response.json

@@ -0,0 +1,8 @@
+{
+    "router_association": {
+        "id": "c63149a0-a0b3-4ca7-aba4-9aaa1b39d7f3",
+        "project_id": "b7549121395844bea941bb92feb3fad9",
+        "router_id": "46a1a80b-7c42-4c45-88fd-b531e636969f",
+        "advertise_extra_routes": false
+    }
+}

neutron_lib/api/definitions/__init__.py

@@ -11,6 +11,7 @@
 # under the License.
 
 from neutron_lib.api.definitions import bgpvpn
+from neutron_lib.api.definitions import bgpvpn_routes_control
 from neutron_lib.api.definitions import data_plane_status
 from neutron_lib.api.definitions import extra_dhcp_opt
 from neutron_lib.api.definitions import fip64
@@ -33,6 +34,7 @@ from neutron_lib.api.definitions import trunk_details
 
 _ALL_API_DEFINITIONS = {
     bgpvpn,
+    bgpvpn_routes_control,
     data_plane_status,
     extra_dhcp_opt,
     fip64,

neutron_lib/api/definitions/base.py

@@ -121,6 +121,7 @@ KNOWN_EXTENSIONS = (
     'fwaasrouterinsertion',
     'fwaas_v2',
     'bgpvpn',  # https://git.openstack.org/cgit/openstack/networking-bgpvpn
+    'bgpvpn-routes-control',
 )
 
 KNOWN_KEYWORDS = (

neutron_lib/api/definitions/bgpvpn_routes_control.py

@@ -0,0 +1,168 @@
+# All rights reserved.
+#
+#    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 import converters
+from neutron_lib.api.definitions import bgpvpn
+from neutron_lib.db import constants as db_const
+
+
+# The alias of the extension.
+ALIAS = 'bgpvpn-routes-control'
+
+# The label to lookup the plugin in the plugin directory. It can match the
+# alias, as required.
+LABEL = ALIAS
+
+# Whether or not this extension is simply signaling behavior to the user
+# or it actively modifies the attribute map (mandatory).
+IS_SHIM_EXTENSION = False
+
+# Whether the extension is marking the adoption of standardattr model for
+# legacy resources, or introducing new standardattr attributes. False or
+# None if the standardattr model is adopted since the introduction of
+# resource extension (mandatory).
+# If this is True, the alias for the extension should be prefixed with
+# 'standard-attr-'.
+IS_STANDARD_ATTR_EXTENSION = False
+
+# The name of the extension (mandatory).
+NAME = 'BGPVPN Routes Control Extension'
+
+# The description of the extension (mandatory).
+DESCRIPTION = "Provides support for controlling routes advertised to a BGPVPN"
+
+# A timestamp of when the extension was introduced (mandatory).
+UPDATED_TIMESTAMP = "2017-05-20T00:00:00-00:00"
+
+# The specific resources and/or attributes for the extension (optional).
+# In case of simple extensions, with single resource, the string constants
+# RESOURCE_NAME and COLLECTION_NAME can be used, otherwise string literals
+# can be used instead.
+
+# The name of the resource introduced or being extended (later case)
+RESOURCE_NAME = bgpvpn.RESOURCE_NAME
+
+# The plural for the resource introduced or being extended (later case)
+COLLECTION_NAME = bgpvpn.COLLECTION_NAME
+
+LOCAL_PREF_KEY = 'local_pref'
+LOCAL_PREF_RANGE = [0, 2**32-1],  # RFC 4271, section 4.3 (p.18)
+
+RESOURCE_ATTRIBUTE_MAP = {
+    COLLECTION_NAME: {
+        'ports': {'allow_post': False, 'allow_put': False,
+                  'is_visible': True,
+                  'enforce_policy': True},
+        LOCAL_PREF_KEY: {
+            'allow_post': True, 'allow_put': True,
+            'is_visible': True,
+            'default': None,
+            'validate': {'type:range': LOCAL_PREF_RANGE},
+            'enforce_policy': True}
+    }
+}
+
+PORT_ASSOCIATION = 'port_association'
+PORT_ASSOCIATIONS = 'port_associations'
+
+ROUTES = 'routes'
+
+PREFIX_TYPE = 'prefix'
+BGPVPN_TYPE = 'bgpvpn'
+ROUTE_TYPES = [PREFIX_TYPE, BGPVPN_TYPE]
+
+ADV_FIXED_IPS = 'advertise_fixed_ips'
+
+TYPE = 'type'
+
+PREFIX = 'prefix'
+BGPVPN_ID = 'bgpvpn_id'
+
+ADV_EXTRA_ROUTES = 'advertise_extra_routes'
+
+LOCAL_PREF_KEY_SPEC = {'type:range': LOCAL_PREF_RANGE,
+                       'required': False}
+
+ROUTE_SPECS = EXTRA_DHCP_OPT_KEY_SPECS = [
+    {'type': {'type:values': [PREFIX_TYPE],
+              'required': True},
+     'prefix': {'type:subnet': None,
+                'required': True},
+     LOCAL_PREF_KEY: LOCAL_PREF_KEY_SPEC,
+     },
+    {'type': {'type:values': [BGPVPN_TYPE],
+              'required': True},
+     'bgpvpn_id': {'type:uuid': None,
+                   'required': True},
+     LOCAL_PREF_KEY: LOCAL_PREF_KEY_SPEC,
+     },
+]
+
+SUB_RESOURCE_ATTRIBUTE_MAP = {
+    PORT_ASSOCIATIONS: {
+        'parent': {
+            'collection_name': COLLECTION_NAME,
+            'member_name': RESOURCE_NAME},
+        'parameters': {
+            'id': {'allow_post': False, 'allow_put': False,
+                   'validate': {'type:uuid': None},
+                   'is_visible': True,
+                   'primary_key': True},
+            'project_id': {'allow_post': True, 'allow_put': False,
+                           'validate': {
+                               'type:string': db_const.PROJECT_ID_FIELD_SIZE},
+                           'required_by_policy': True,
+                           'is_visible': True,
+                           'enforce_policy': True},
+            'port_id': {'allow_post': True, 'allow_put': False,
+                        'validate': {'type:uuid': None},
+                        'is_visible': True,
+                        'enforce_policy': True},
+            ROUTES: {'allow_post': True, 'allow_put': False,
+                     'default': [],
+                     'convert_list_to': converters.convert_kvp_list_to_dict,
+                     'validate': {
+                         'type:list_of_any_key_specs_or_none': ROUTE_SPECS
+                     },
+                     'enforce_policy': True,
+                     'is_visible': True},
+            ADV_FIXED_IPS: {'allow_post': True, 'allow_put': True,
+                            'default': True,
+                            'convert_to': converters.convert_to_boolean,
+                            'is_visible': True},
+        },
+    },
+    bgpvpn.ROUTER_ASSOCIATIONS: {
+        'parent': {'collection_name': COLLECTION_NAME,
+                   'member_name': RESOURCE_NAME},
+        'parameters': {
+            ADV_EXTRA_ROUTES: {'allow_post': True, 'allow_put': True,
+                               'default': True,
+                               'convert_to': converters.convert_to_boolean,
+                               'is_visible': True},
+        }
+    }
+}
+
+
+ACTION_MAP = {
+}
+
+ACTION_STATUS = {}
+
+REQUIRED_EXTENSIONS = [
+    bgpvpn.ALIAS
+]
+
+OPTIONAL_EXTENSIONS = []

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

@@ -0,0 +1,25 @@
+#
+#    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 bgpvpn
+from neutron_lib.api.definitions import bgpvpn_routes_control
+from neutron_lib.tests.unit.api.definitions import base
+
+
+class BgpvpnRoutesControlDefinitionTestCase(base.DefinitionBaseTestCase):
+
+    extension_module = bgpvpn_routes_control
+    extension_resources = (bgpvpn.COLLECTION_NAME,)
+    extension_attributes = ('ports', 'routes', 'advertise_fixed_ips',
+                            'advertise_extra_routes', 'local_pref')
+    extension_subresources = ('port_associations', 'router_associations')

releasenotes/notes/bgpvpn-routes-control-51cd95d6ab265cb1.yaml

@@ -0,0 +1,8 @@
+---
+features:
+  - |
+    The ``bgpvpn-routes-control`` API extension is introduced to enrich the
+    base ``bgpvpn`` extension.  It allows to control BGPVPN connectivity at
+    the granularity of a port and the advertisement into a BGPVPN of routes
+    corresponding to destination reachable via a given port (static routes,
+    BGPVPN route leaking).