diff --git a/doc/source/design/api.rst b/doc/source/design/api.rst index fb8c2062..44927a75 100644 --- a/doc/source/design/api.rst +++ b/doc/source/design/api.rst @@ -25,4 +25,465 @@ 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/`` 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/`` 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/`` 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/`` 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/`` 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/`` 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//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//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//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//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//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-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-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-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-drinstances/`` +to delete the BGP Speaker hosted by the specified dynamic routing agent. :: + + No response body + + Return code: 204 + +Reference +--------- +None \ No newline at end of file