Neutron/LBaaS/Architecture

= Scope =

This document describes the internal architecture of LBaaS and workflows.

Modules Decomposition
LBaaS architecture is based on advanced services introduced into Quantum. The structure is following:




 * LBaaS Quantum Extension - is responsible for handling REST API calls (BP: lbaas-restapi-tenant)
 * LBaaS Quantum AdvSvc Plugin - is a core of service, it is responsible for: (BP: lbaas-plugin-api-crud)
 * DB storage
 * Request validation
 * Scheduling of load balancing services (deployment to LB devices)
 * LBaaS Agent - is stand-alone service that manages drivers (BP: lbaas-agent-and-rpc)
 * Driver - is a module that transforms LBaaS object model into vendor-specific model and deploys configuration onto load-balancing device (BP: lbaas-driver-api)

Workflow
LBaaS management is performed via REST API. If the call involves DB only (read, name update) then it is done synchronous way, all other calls (like status retrieval, write operations) are done asynchronously. See Quantum/LBaaS/REST API for more details.

There are two types of locks:
 * Object-level lock is done on an instance (vip, pool, member) and restricts concurrent changes. The lock is achieved by moving object into one of PENDING_* states.
 * Device-level lock is done to lock the whole configuration and disallow concurrent changes. Since this is a restrictive policy, requests are actually put into queue and then processed by driver one-by-one. The queue may be implemented completely as Python code or be an external MQ.

The following diagram shows 2 concurrent update requests, 'alt' blocks show processing alternatives for requests.



Ordinary update workflow is:
 * 1) REST API request is accepted by Quantum and routed to the corresponding Extension and Plugin.
 * 2) Plugin performs validation of request (schema conformance, values and references check, etc). If validation fails one of 40x codes is returned (depending on reason).
 * 3) DB object is updated and object is moved to PENDING_UPDATE state.
 * 4) Request is transformed into task and pushed into queue.
 * 5) Plugin responses user with HTTP 202 reply. Steps 1-5 are done synchronously.
 * 6) Agent picks message from the queue and forwards it to Driver. Driver changes configuration of load balancing device. Once completed the response message is pushed into Plugin's queue.
 * 7) Plugin retrieves message and updates DB with either "ACTIVE" or "ERROR" status

Data model should be resistant to different failures and crash of modules:
 * If crash in 1), 2) or 3) all changes are lost, HTTP 500 error is returned to user.
 * If crash in 4) or 5) then Plugin handles it and moves object into ERROR state, HTTP 500 error is returned.
 * If crash in 6) or 7) the object remains in "PENDING_" state. The Plugin will move the object into ERROR state after some preconfigured time or after restart.

Driver API
See Quantum/LBaaS/DriverAPI for details.