BGP dynamic routing api documentation

This is for how to use the BGP dynamic routing API.

Change-Id: I235e2def28c307cd5b4ba10374674a166a953e3a
Partially-Implements: blueprint bgp-spinout
Partial-Bug: #156000
This commit is contained in:
yuyangbj 2016-05-17 14:56:08 +08:00
parent 6217344e28
commit 3644441146
1 changed files with 462 additions and 1 deletions

View File

@ -25,4 +25,465 @@
API API
=== ===
TODO: Coming Soon Introduction
------------
Neutron dynamic routing project adds the support for dynamic routing protocols
in neutron. Using the ReST interface, a cloud administrator can define routing
peers and advertise neutron routes outside the OpenStack domain.
.. note::
Currently, only the support for BGP dynamic routing protocol is available.
Data Model
----------
New data models are defined for supporting routing protocols. Below models are defined for
different protocols.
BGP
~~~
BGP Speaker
+++++++++++
* ``id``
The uuid of BGP Speaker.
* ``name``
The name of BGP Speaker.
* ``local_as``
The local AS value, ranges from 1 to 65535.
* ``ip_version``
The ip address version for BGP Speaker. 4 by default.
* ``peers``
The remote peer connection which supports BGP.
* ``networks``
The tenant networks connected to the BGP Speaker.
* ``advertise_floating_ip_host_routes``
Whether to enable or disable the advertisement of floating ip host routes by
the BGP Speaker. True by default.
* ``advertise_tenant_networks``
Whether to enable or disable the advertisement of tenant network routes by
the BGP Speaker. True by default.
BGP Peer
++++++++
* ``id``
The uuid of BGP peer.
* ``name``
The name of BGP peer.
* ``peer_ip``
The IP address of BGP peer.
* ``remote_as``
The remote AS value, ranges from 1 to 65535.
* ``auth_type``
The authentication algorithm. Supported algorithms: none and md5, none by
default.
* ``password``
The authentication password for the specified authentication type.
ReST Interface
--------------
Different ReST interface are exposed for realizing different dynamic protocol
functionality.
.. note::
Only an administrator have the access to the exposed API's.
BGP
~~~
BGP Speaker
+++++++++++
Create
''''''
Issue a ``POST`` request to ``/v2.0/bgp-speakers`` with following JSON-encoded
data to create a BGP Speaker: ::
{
"bgp_speaker":{
"ip_version":4,
"local_as":"1000",
"name":"bgp-speaker"
}
}
Response body:
{
"bgp_speaker":{
"peers":[
],
"name":"bgp-speaker",
"tenant_id":"34a6e17a48cf414ebc890367bf42266b",
"local_as":1000,
"advertise_tenant_networks":true,
"networks":[
],
"ip_version":4,
"advertise_floating_ip_host_routes":true,
"id":"5e08db80-db77-4b5c-a56d-dbca0b284f2c"
}
}
Return code: 201
List
''''
Issue a ``GET`` request to ``/v2.0/bgp-speakers`` to retrieve this list of available
BGP Speakers. ::
Response body:
{
"bgp_speakers":[
{
"peers":[
],
"name":"bgp-speaker-1",
"tenant_id":"34a6e17a48cf414ebc890367bf42266b",
"local_as":1001,
"advertise_tenant_networks":true,
"networks":[
],
"ip_version":4,
"advertise_floating_ip_host_routes":true,
"id":"5e08db80-db77-4b5c-a56d-dbca0b284f2c"
},
{
"peers":[
],
"name":"bgp-speaker",
"tenant_id":"34a6e17a48cf414ebc890367bf42266b",
"local_as":1000,
"advertise_tenant_networks":true,
"networks":[
],
"ip_version":4,
"advertise_floating_ip_host_routes":true,
"id":"b759b2a1-27f4-4a6b-bb61-f2c9a22c9902"
}
]
}
Return code: 200
Show
''''
Issue a ``GET`` request to ``/v2.0/bgp-speakers/<bgp-speaker-id>`` to retrieve the
detail about a specific BGP Speaker. ::
Response body:
{
"bgp_speaker":{
"peers":[
],
"name":"bgp-speaker",
"tenant_id":"34a6e17a48cf414ebc890367bf42266b",
"local_as":1000,
"advertise_tenant_networks":true,
"networks":[
],
"ip_version":4,
"advertise_floating_ip_host_routes":true,
"id":"b759b2a1-27f4-4a6b-bb61-f2c9a22c9902"
}
}
Return code: 200
Update
''''''
Issue ``PUT`` request to ``/v2.0/bgp-speakers/<bgp-speaker-id>`` to update a
specific BGP Speaker. Following attributes can be updated.
* ``name``
The name of BGP Speaker.
* ``advertise_floating_ip_host_routes``
Whether to enable or disable the advertisement of floating ip host routes by
the BGP Speaker. True by default.
* ``advertise_tenant_networks``
Whether to enable or disable the advertisement of tenant network routes by
the BGP Speaker. True by default.
Delete
''''''
Issue ``DELETE`` request to ``/v2.0/bgp-speakers/<bgp-speaker-id>`` to delete
a specific BGP Speaker. ::
No reponse body
Return code: 204
BGP Peer
++++++++
Create
''''''
Issue a ``POST`` request to ``/v2.0/bgp-peers`` with following JSON-encoded data
to create a BGP peer: ::
{
"bgp_peer":{
"auth_type":"none",
"remote_as":"1001",
"name":"bgp-peer",
"peer_ip":"10.0.0.3"
}
}
Response body:
{
"bgp_peer":{
"auth_type":"none",
"remote_as":"1001",
"name":"bgp-peer",
"tenant_id":"34a6e17a48cf414ebc890367bf42266b",
"peer_ip":"10.0.0.3",
"id":"a7193581-a31c-4ea5-8218-b3052758461f"
}
}
Return code: 201
List
''''
Issue a ``GET`` request to ``/v2.0/bgp-peers`` to retrieve the list of available
BGP peers. ::
Response body:
{
"bgp_peers":[
{
"auth_type":"none",
"remote_as":1001,
"name":"bgp-peer",
"tenant_id":"34a6e17a48cf414ebc890367bf42266b",
"peer_ip":"10.0.0.3",
"id":"a7193581-a31c-4ea5-8218-b3052758461f"
}
]
}
Return code: 200
Show
''''
Issue a ``GET`` request to ``/v2.0/bgp-peers/<bgp-peer-id>`` to retrieve the detail about a
specific BGP peer. ::
Reponse body:
{
"bgp_peer":{
"auth_type":"none",
"remote_as":1001,
"name":"bgp-peer",
"tenant_id":"34a6e17a48cf414ebc890367bf42266b",
"peer_ip":"10.0.0.3",
"id":"a7193581-a31c-4ea5-8218-b3052758461f"
}
}
Return code: 200
Update
''''''
Issue ``PUT`` request to ``/v2.0/bgp-peers/<bgp-peer-id>`` to update
a specific BGP peer. Following attributes can be updated.
* ``name``
The name of BGP peer.
* ``password``
The authentication password.
Delete
''''''
Issue ``DELETE`` request to ``/v2.0/bgp-peers/<bgp-peer-id>`` to delete
a specific BGP peer. ::
No response body
Return code: 204
BGP Speaker and Peer binding
++++++++++++++++++++++++++++
Add BGP Peer to a BGP Speaker
'''''''''''''''''''''''''''''
Issue a ``PUT`` request to ``/v2.0/bgp-speakers/<bgp-speaker-id>/add-bgp-peer``
to bind the BGP peer to the specified BGP Seaker with following JSON-encoded data: ::
{
"bgp_peer_id":"a7193581-a31c-4ea5-8218-b3052758461f"
}
Response body: ::
{
"bgp_peer_id":"a7193581-a31c-4ea5-8218-b3052758461f"
}
Return code: 200
Remove BGP Peer from a BGP Speaker
''''''''''''''''''''''''''''''''''
Issue a ``DELETE`` request with following data to ``/v2.0/bgp-speakers/<bgp-speaker-id>/remove-bgp-peer``
to unbind the BGP peer: ::
{
"bgp_peer_id":"a7193581-a31c-4ea5-8218-b3052758461f"
}
No response body
Return code: 200
BGP Speaker and Network binding
+++++++++++++++++++++++++++++++
Add Network to a BGP Speaker
''''''''''''''''''''''''''''
Issue a ``PUT`` request with following data to ``/v2.0/bgp-speakers/<bgp-speaker-id>/add_gateway_network``
to add a network to the specified BGP speaker: ::
{
"network_id":"f2269b61-6755-4174-8f64-5e318617b204"
}
Response body:
{
"network_id":"f2269b61-6755-4174-8f64-5e318617b204"
}
Return code: 200
Delete Network from a BGP Speaker
'''''''''''''''''''''''''''''''''
Issue a ``DELETE`` request with following data to ``/v2.0/bgp-speakers/<bgp-speaker-id>/remove_gateway_network``
to delete a network from a specified BGP speaker. ::
No response body
Return code: 200
BGP Speaker Advertised Routes
+++++++++++++++++++++++++++++
List routes advertised by a BGP Speaker
'''''''''''''''''''''''''''''''''''''''
Issue ``GET`` request to ```/v2.0/bgp-speakers/<bgp-speaker-id>/get_advertised_routes``
to list all routes advertised by the specified BGP Speaker. ::
Response body:
{
"advertised_routes":[
{
"cidr":"192.168.10.0/24",
"nexthop":"10.0.0.1"
}
]
}
Return code: 200
BGP Speaker and Dynamic Routing Agent interaction
+++++++++++++++++++++++++++++++++++++++++++++++++
Add BGP Speaker to a Dynamic Routing Agent
''''''''''''''''''''''''''''''''''''''''''
Issue a ``POST`` request to ``/v2.0/agents/<bgp-agent-id>/bgp-drinstances`` to
add a BGP Speaker to the specified dynamic routing agent. The following is
the request body: ::
{
"bgp_speaker_id": "5639072c-49eb-480a-9f11-953386589bc8"
}
No response body
Return code: 201
List BGP speakers hosted by a Dynamic Routing Agent
'''''''''''''''''''''''''''''''''''''''''''''''''''
Issue a ``GET`` request to ``/v2.0/agents/<bgp-dragent-id>/bgp-drinstances`` to
list all BGP Seakers hosted on the specified dynamic routing agent. ::
Response body:
{
"bgp_speakers":[
{
"peers":[
],
"name":"bgp-speaker",
"tenant_id":"34a6e17a48cf414ebc890367bf42266b",
"local_as":1000,
"advertise_tenant_networks":true,
"networks":[
],
"ip_version":4,
"advertise_floating_ip_host_routes":true,
"id":"b759b2a1-27f4-4a6b-bb61-f2c9a22c9902"
}
]
}
Return code: 200
List Dynamic Routing Agents hosting a specific BGP Speaker
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Issue a ``GET`` request to ``/v2.0/bgp-speakers/<bgp-speaker-id>/bgp-dragents``
to list all BGP dynamic agents which are hosting the specified BGP Speaker. ::
Response body:
{
"agents":[
{
"binary":"neutron-bgp-dragent",
"description":null,
"admin_state_up":true,
"heartbeat_timestamp":"2016-05-17 03:05:12",
"availability_zone":null,
"alive":true,
"topic":"bgp_dragent",
"host":"yangyubj-virtual-machine",
"agent_type":"BGP dynamic routing agent",
"resource_versions":{
},
"created_at":"2016-05-09 07:38:00",
"started_at":"2016-05-11 09:06:13",
"id":"af216618-29d3-4ee7-acab-725bdc90e614",
"configurations":{
"advertise_routes":0,
"bgp_peers":0,
"bgp_speakers":1
}
}
]
}
Return code: 200
Delete BGP Speaker from a Dynamic Routing Agent
'''''''''''''''''''''''''''''''''''''''''''''''
Issue a ``DELETE`` request to ``/v2.0/agents/<bgp-agent-id>/bgp-drinstances/<bgp-speaker-id>``
to delete the BGP Speaker hosted by the specified dynamic routing agent. ::
No response body
Return code: 204
Reference
---------
None