Revert "Withdraw doc for bgpvpn-routes-control API extension"

This reverts commit 5732e95f5d.

There is one thing changed: addition of a note saying that
the feature is in development in the Queens cycle (as discussed
during the PTG in Denver).

Change-Id: I70e3bcd39527ba39a3c957956705148f77f7530a
This commit is contained in:
Thomas Morin 2017-09-13 15:06:44 +00:00 committed by Thomas Morin
parent 5732e95f5d
commit 8ba7edb18d
21 changed files with 598 additions and 12 deletions

View File

@ -8,7 +8,8 @@ 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.
@ -52,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
@ -83,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
@ -107,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
@ -149,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
@ -183,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
---------------
@ -205,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

View File

@ -50,6 +50,38 @@ 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
=======================================
.. note:: this feature is under development in the Queens release
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
======================

View File

@ -0,0 +1,250 @@
=================
Port Associations
=================
.. note:: this feature is under development in the Queens release
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.

View File

@ -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
==========================

View File

@ -75,6 +75,7 @@ BGP/MPLS VPN Interconnection
.. include:: bgpvpn-bgpvpns.inc
.. include:: bgpvpn-network_associations.inc
.. include:: bgpvpn-router_associations.inc
.. include:: bgpvpn-port_associations.inc
#######
Logging
#######

View File

@ -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.
@ -642,6 +648,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.
@ -672,6 +707,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). Defaults to ``null``.
in: body
required: false
type: integer
bgpvpn-name:
description: |
The user meaningful name of the BGP VPN.
@ -724,6 +773,40 @@ bgpvpn-networks-required:
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
@ -790,6 +873,46 @@ bgpvpn-routers-required:
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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

@ -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
}
}

View File

@ -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
}
]
}

View File

@ -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
}
}

View File

@ -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
}
}

View File

@ -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
}
}

View File

@ -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
}
}

View File

@ -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
}
]
}

View File

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

View File

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

View File

@ -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
}
}