From 73a8f8cc145f53926ea5ac1b4b5bcad8f0055d9d Mon Sep 17 00:00:00 2001 From: ZhaoBo Date: Mon, 16 May 2016 15:56:28 +0800 Subject: [PATCH] Add bgp speaker and route advertisement doc This patch add bpg-speaker.rst and route-advertisement.rst into neutron-dynamic-routing project. Change-Id: I67ea3461402aa5395c125ac4b577901d35eaedba Partially-Implements: blueprint bgp-spinout --- doc/source/functionality/bgp-speaker.rst | 141 +++++++++++++++++- .../functionality/route-advertisement.rst | 90 ++++++++++- 2 files changed, 229 insertions(+), 2 deletions(-) diff --git a/doc/source/functionality/bgp-speaker.rst b/doc/source/functionality/bgp-speaker.rst index 5400d971..33e84ea9 100644 --- a/doc/source/functionality/bgp-speaker.rst +++ b/doc/source/functionality/bgp-speaker.rst @@ -24,5 +24,144 @@ BGP Speaker =========== +BGP Speaker acts as a route server using BGP routing protocol. It advertises +routes to the BGP peers which are added to the BGP Speaker. Now there is a +framework that allows different `BGP drivers <../design/drivers.rst>`_ +to be plugged into a `dynamic routing agent <./dynamic-routing-agent.rst>`_. -TODO: Coming Soon +Currently, BGP Speaker only advertises routes for a network to which it is associated. +A BGP Speaker requires association with a "gateway" network to determine eligible routes. +In Neutron, a "gateway" network connects Neutron routers to the upstream routers. An +external network is best for being used as a gateway network. The association builds a +list of all virtual routers with gateways on provider and self-service networks within +the same address scope. Hence, the BGP speaker advertises self-service network prefixes +with the corresponding router as the next-hop IP address. +For details refer to `Route advertisement <./route-advertisement.rst>`_. + +Address Scopes +-------------- +`Address scopes `_ +provide flexible control as well as decoupling of address overlap from tenancy, +so this kind control can provide a routable domain, the domain has itself route +and no overlap address, it means an address scope define "a L3 routing domain". + +BGP Speaker will associate the external networks and advertise the tenant's +networks routes. Those networks should reside in the same address scope. +Neutron can route the tenant network directly without NAT. Then Neutron can +host globally routable IPv4 and IPv6 tenant networks. For determining which +tenant networks prefixes should be advertised, Neutron will identify all routers +with gateway ports on the network which had been bounded with BGP Speaker, +check the address scope of the subnets on all connected networks, then begin +advertising nexthops for all tenant networks to routers on the bound network. + +BGP Peer +-------- +BGP peer defined in Neutron represents real BGP infrastructure such as +routers, route reflectors and route servers. When a BGP peer is defined and +associated with a BGP Speaker, Neutron will attempt to open a BGP peering +session with the mentioned remote peer. It is this session, using which Neutron +announces it's routes. + +How to configure a remote peer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +A remote peer can be real or virtual e.g. vRouters or real routers. +The remote peer should be configured to handle peering with Neutron in passive +mode. The peer needs to waits for the Neutron dynamic routing agent to +initiate the peering session. Also, the remote peer can be configured in active +mode, but it still can speak BGP until the complete initialization of BGP Speaker +running on Neutron dynamic routing agent. + +Configuring BGP Speaker: +One needs to ensure below points for setting a BGP connection. + +* Host running Neutron dynamic agent MUST connect to the external router. +* BGP configuration on the router should be proper. + + ``bgp router-id XX.XX.XX.XX`` + This must be an IP address, the unique identifier of BGP routers actually + and can be virtual. If one doesn't configure the router-id, it will be selected + automatically as the highest IP address configured for the local interfaces. + Just a suggestion, please make sure that it is the same as the ``peer_ip`` + which you configure in Neutron for distinguishing easily. + ``local_as`` + Autonomous System number can be same or different from the AS_id of external + BGP router. AS_id will be same for iBGP and different for eBGP sessions. + +Setting BGP peer: +:: + + neighbor A.B.C.D remote-as AS_ID + A.B.C.D is the host IP which run Neutron dynamic routing agent. + +A Sample Quagga router configuration file forming BGP peering with Neutron: +:: + + ! + password zebra + log file /var/log/quagga/bgpd.log + ! + debug bgp events + debug bgp keepalives + debug bgp updates + debug bgp fsm + debug bgp filters + ! + bgp multiple-instance + ! + router bgp view test-as + bgp router-id + neighbor remote-as + neighbor passive + ! + line vty + ! + +BGP Speaker Architecture +------------------------ +Dynamic routing project saves BGP Speaker configuration as per the defined +`_data model`_. +and pass on the configuration request to the dynamic routing agent for further processing. +The implementation of a BGP Speaker is driver specific. During the driver interface +initialization process, needed configurations are read from the configuration file +and BGP Speaker object instance is created. For details refer to +`BGP drivers <../design/drivers.rst>`_. + +BGP Speaker Life Cycle +~~~~~~~~~~~~~~~~~~~~~~ +Now we support RyuBgpDriver, BGP Speaker will be processed by Dragent. When +associating a BGP Speaker with an active Dragent, the plugin will send an RPC +message to the agent for calling driver in order to create a BGP Speaker instance. + +In RyuBgpDriver, the created instance ``BGP Speaker`` will setup by router-id +and ASN, then Ryu will setup new context with speaker configuration and listeners +which monitor whether the related peers are alive. + +Then the following operation could be done. + +* Add peers to BGP Speaker + When BGP Speaker is not associated with an active Dragent, there is no real speaker + instance, so it will be still the db operation until the speaker is associated with + dragent, and all the peers connection before will be setup by ``BGP Speaker`` + creation. If add peers into speaker which is running, Dragent will call driver + to add peer dynamically. For RyuBgpDriver, it will register a new neighbor + based on your peer configuration and try to establish a session with the peer. + +* Delete peers from BGP Speaker + The same logic with below, but it is reverse. + +If you don't want use the specific BGP Speaker anymore, you can use CLI: + ``neutron bgp-speaker-delete `` + +BGP Plugin will find all the associated Dragent and send RPC ``bgp_speaker_remove_end`` +to make the Dragents to clean the ``BGP Speaker`` instances. This is the same +with CLI: + ``neutron bgp-dragent-speaker-remove `` +BGP Plugin just send rpc ``bgp_speaker_remove_end`` to the specific Dragent. + +Advertisement +~~~~~~~~~~~~~ +For details refer to `Route Advertisement <./route-advertisement.rst>`_. + +How to work +----------- +For details refer to `Testing <../others/testing.rst>`_. \ No newline at end of file diff --git a/doc/source/functionality/route-advertisement.rst b/doc/source/functionality/route-advertisement.rst index be35f4e5..b1a068a7 100644 --- a/doc/source/functionality/route-advertisement.rst +++ b/doc/source/functionality/route-advertisement.rst @@ -24,5 +24,93 @@ Route Advertisement =================== +BGP +--- -TODO: Coming Soon +This page discusses the behavior of BGP dynamic routing about how to advertise +routes and show the routes details in the project. + +BGP dynamic routing could advertise 3 classes of routes: + +* Host routes for floating IP addresses hosted on non-DVR routers, as floatingip + address set on the router namespace, it knows how to route the message to the + correct way, so the next-hop should be the IP address of router gateway port. +* Host routes for floating IP addresses hosted on DVR routers. With DVR-enabled + routers, the floating IP can be reached directly on the compute node hosting + a given instance. As such, host routes for the floating IP address should + advertise the FIP agent gateway on the compute node as the next-hop instead of + the centralized router. This will keep inbound floating IP traffic from + encountering the bottleneck of the centralized router. +* Prefix routes for directly routable tenant networks with address scopes, the + nexthop is the centralized router, the same for DVR and CVR. BGP dynamic + routing could advertise tenant network prefixes to physical network + devices(routers which support BGP protocol), called this + ``Prefixes advertisement``. + +When distributed virtual routing (DVR) is enabled on a router, next-hops for +floating IP's and fixed IP's are not advertised as being at the centralized +router. Host routes with the next-hop set to the appropriate compute node +are advertised. + +Logical Model +~~~~~~~~~~~~~ +:: + + +--------+ 1 N +---------------------+ + | Router |---------| BgpAdvertisedRoute | + +--------+ +---------------------+ + | N + | + | 1 + +---------+ N N +------------+ N N +---------+ + | BgpPeer |-----------| BgpSpeaker |-----------| Network | + +---------+ +------------+ +---------+ + | N + | + | 1 + +--------------+ + | AddressScope | + +--------------+ + +.. note:: + A BGP Speaker only supports one address family to speak BGP. A dual-stack IPv4 + and IPv6 network needs two BGP Speakers to advertise the routes with BGP, one + for IPv4 and the other for IPv6. So A network can have N number of BGP + Speakers bound to it. + +BgpAdvertisedRoute represents derived data. As the number of +BgpAdvertisedRoutes can be quite large, storing in a database table is not +feasible. BgpAdvertisedRoute information can be derived by joining data +already available in the Neutron database. And now BGP dynamic routing project +process the Bgpadvertiseroutes which should be advertised to external Router is +basing on the exist Neutron DB tables. +Neutron looks on each of the gateway network for any routers with a gateway port +on that network. For each router identified, Neutron locates each floating IP +and tenant network accessible through the router gateway port. Neutron then +advertises each floating IP and tenant network with the IP address of the router +gateway port as the next hop. + +When BGP Plugin is started, it will register callbacks. All callbacks are used for +processing Floating IP, Router Interface and Router Gateway creation or update, this +functions listen the events of these resources for calling Dragent to change the +advertisement routes. + +Now we just focus on the resources which may cause route change, the following +callbacks does this work. + +* floatingip_update_callback + This function listens to the Floating IP's AFTER_UPDATE event, it judges whether + the associated router is changed, and changes the advertisement routes and nexthop + based on that. +* router_interface_callback + This function listens to the tenants' network routes change, it listens to AFTER_CREATE + and AFTER_DELETE events of Router Interface resource. It calls Dragent to advertise + or stop the prefix routes after a interface attach into a router. +* router_gateway_callback + This function listens to the router gateway port creation or deletion. It also focuses + on tenants' network routes change. + +You could get the advertisement routes of specific BGP Speaker like: + ``neutron bgp-speaker-advertiseroute-list `` +It does a complicated db query to generate the list of advertised routes. +For more details refer to `route advertisement db lookup `_