Neutron/LBaaS/Agent

= Quantum Agent for LoadBalancing service =

Scope of the document
This document describes Agent component of the Quantum's Loadbalancing service, defines requrements, architecture and some implementation details.

Requirements
Service agent is needed to add several important features to a service which operations are potentially time consuming such as:

Plugin is notified by agent when requested operation is complete. There could be serveral agents listening for quantum server messages thus in large deployments it allows splitting workload to several hosts.
 * 1) Asynchronous execution.
 * 1) Workload balancing.

Architecture
1.1. Calling agent Plugin packs all required information in the json message and sends it over AMQP to durable message queue. The message is consumed by one of the running agents and corresponding call is made via one of the drivers in synchronous manner. After driver call completes agent sends message to the plugin with status information for modified object.
 * 1) Plugin part

1.2. Receiving response Plugin should wait on another queue where responses are posted by the agent. Information in response should allow plugin to uniquely identify object for which status of operation is returned. Plugin consumes response messages in synchronous manner one by one since their processing is not a time consuming operation.

Agent should be able to consume messages in multithreaded manner. E.g. agent should allow execution of several operations at once. One technical difficulty of this is device sharing. Consider the case when several operations go for the same device. Such operations should be executed sequentially rather than concurrently.
 * 1) Agent part

Agent doesn't perform authentication of received requests, nor the requests contain any authentication information. It's presumed that authentication was done on the plugin part so caller has access to the device it is configuring.
 * 1) Authentication.

Brief Component/Workflow diagram:



Implementation
One of the most important issues of plugin-agent-driver architecture is device sharing/locking. Since Agent can process requests from plugin concurrently, it's important to preserve atomicity of access to the same device so different calls for the same device would not break its configuration. Consider the following use case:
 * 1) Agent Part

Tenant creates a vip object and then creates members. Depending on how those actions are packed as requests to agent it could result that agent may start executing member creation requests before pool creation is finished. The solution for this problem is that agent should internally queue the requests for the device. E.g. requests dedicated to the same device are processed sequentially.

Also, Agent is responsible for detecting timed out operations and sending a message with appropriate reason to plugin's response consumer.

Plugin is also responsible for assuring atomic device access. There could be two approaches to this:
 * 1) Plugin part
 * 1) Plugin locks object in the DB, replying with some HTTP error to concurrent call for the same resource and thus putting responsibility to client to handle it.
 * 2) Plugin queues request as usual and lets Agent to queue requests for specific device to execute them sequentially.

The second approach may preferable from client perspective.

How to run the code on DevStack
The detailed instaruction is given here: Quantum/LBaaS/HowToRun