Proposal: load-balancing API extensions for Quantum

Alex Gosse, Product Specialist, Riverbed Technology

Table of contents

Table of contents

Overview

High-level flow

Concepts

Device

Device pool

Service

Service Extension

API Operations

Administrative Operations

Show LB Device Pools

Create LB Device Pool

Update LB Device Pool

Delete LB Device Pool

List LB Devices

Show LB Device

Create LB Device

Update LB Device

Tenant Operations

List LB services

Create LB service

Show LB service

Update LB service

Overview

In the interest of uniformity the extensions proposed in this document are based as much as possible on the Quantum v2.0 API design specification.  The text in red indicates additional steps added by the balancer extensions.

High-level flow

Concepts

The Balancer API manages a number of entities:

All entities, discussed in detail in the rest of this chapter, support the basic CRUD operations with POST/GET/PUT/DELETE verbs, and have and auto-generated unique identifier.

Device

A device represents a single load-balancing device that is capable of providing load-balancing functionality.  Some load-balancing technology is monolithic, in that a single physical appliance may be used to provide load-balancing services to a number of different tenants.  In this case, a load-balancing device may need to be shared so that multiple tenants can deploy services to it.  The goal of creating a device would be to register it, perhaps providing an API endpoint and a set of credentials that can be used to control the device.

Conversely, a load-balancing device may be a software instance running on top of a vm.  In this case, the goal of creating a device might include provisioning a device (ie. via Nova) and getting the credentials back as a part of that provisioning process.

Attribute

Type

Required

CRUD

Default Value

Validation Constraints

Explanation and Notes

id

uuid-str

n/a

CR

Generated

UUID_PATTERN

UUID representing the load balancing device

name

String

No

CRU

N/A

N/A

Human-readable name for the load balancing device.  Might not be unique.

driver

String

No

CRU

HA Proxy

N/A

Sets the driver to use for this device; essentially the precise device type.

driver_params

StringArray

No

CRU

N/A

N/A

A list of configuration parameters that are passed to the driver.  Because this is merely an interface, it's up to the driver to throw exceptions when the arguments are inappropriate.

status

String

N/A

R

N/A

N/A

Indicates whether the device is currently operational.  Possible values include "ACTIVE", "DOWN", "BUILD", and "ERROR", but plugins might define additional values.

shared

Bool

No

CRU

True

{ True | False  }

Specifies whether the load balancing device can be accessed by any tenant or not.

tenant_id

uuid-str

No

CR

N/A

N/A

Owner of the load balancing device.  Only admin users can specify a tenant_id other than its own.

Device pool

A device pool is a logical grouping of load-balancing devices that acts as an abstraction layer for applying user permissions, and for deploying services to in an opaque manner.  For example: In cases where there is a monolithic group of load-balancing devices that all tenants share, a single device pool can decide which load-balancing device(s) a service should be deployed to, based on a deployment algorithm.

Where a load-balancing technology supports HA using virtual IP addresses,  those IP addresses may be applied to an LB device pool.

Attribute

Type

Required

CRUD

Default Value

Validation Constraints

Explanation and Notes

id

uuid-str

N/A

CR

N/A

A unique ID assigned to the pool when it is created.

name

String

Yes

CRU

N/A

A logical name for the device pool.  This might correspond to a cluster of traffic managers, for example.

devices

list

Yes

CRU

N/A

A list of devices that belong in this device pool.

is_elastic

Bool

No

CRU

False

Whether or not this device pool can "burst".

shared

Bool

No

CRU

True

Whether or not this device pool is shared between tenants.

tenant_id

uuid-str

No

CRU

N/A

The ID of the tenant that this device pool belongs to.

Service

A service describes the manner in which traffic is delivered from the floating IP addresses that it listens on to the origin servers that provide the application.  At a minimum, it contains the information required to provision a service that delivers application data, whatever the use-case may be.

In a shared environment, the tenant should not be concerned with the infrastructure, and any attempt made by the tenant to specify a value for a device or a device_pool should be ignored by the balancer API.  In a truly multi-tenant environment ( one where each tenant can create virtualized devices ),  each tenant may wish to decide which devices or device_pools host which services, but they should not be forced to make a decision ( balancer should decide for them using an algorithm ).

As with devices, a tenant's ability to select specific IP addresses for their service is something that a provider should be able to moderate.  At the same time, if the tenant has the ability to select from a set of IP addresses, they should be able to do so.

Attribute

Type

Required

CRUD

Default Value

Validation Constraints

Explanation and Notes

id

uuid-str

N/A

CR

N/A

A unique id assigned to the service when it is created.

name

String

Yes

CRU

N/A

A logical name for the service (perhaps a domain or application name)

port

String

Yes

CRU

N/A

A set of ports that the service should listen on.

devices

list

No

CRU

N/A

A list of devices that this service is or should be deployed on.

device_pools

list

No

CRU

N/A

A list of device_pools that this service is to should be deployed on.

floating_ips

list

No

CRU

N/A

A list of floating IP addresses that this service is or should be listening on.

algorithm

String

Yes

CRU

RR

The load-balancing algorithm that should be used to distribute traffic to the nodes.

nodes

OrderedList

Yes

CRU

N/A

The list of ip[-range]:port[-range] that traffic should be distributed to.

extensions

OrderedList

No

CRU

N/A

A list of extensions that should be applied to this service.

Service Extension

Given that any functionality above and beyond basic load balancing is going to vary from deployment to deployment, it makes sense to refer to that functionality as an extension of a service.  Certain functionality may be supported by and common to several different vendors and not by others (rate shaping and bandwidth management as examples).  As vendors add support for new features, new functionality made available by new driver versions.  For example, a team of engineers employed by a provider may wish to use a sophisticated application delivery platform to produce their own unique service offerings that are not provided out of the box by any particular vendor (a custom rule written in TrafficScript or iRules, perhaps).

In order to accommodate this diversity, the service extension entity should provide an intuitive and flexible interface for exposing vendor and provider specific functionality.  It should be possible for a provider to moderate the extensions are visible/accessible to each tenant (perhaps the device driver instance is the correct place to do this?).

Where required, there should be an interface for an extension to allow the tenant to convey requisite parameters to the extension.  Presentation of these parameters should be handled by the driver, since it's feasible that different drivers providing similar functionality will require different information[1].  

Attribute

Type

Required

CRUD

Default Value

Validation Constraints

Explanation and Notes

id

uuid-str

N/A

CR

N/A

A unique ID that is assigned to the extension when it is created.

name

String

Yes

CRU

N/A

The name of the extension.

description

String

Yes

CRU

N/A

A description of what the extension actually does.

requirements

list

Yes

CRU

N/A

A list of capabilities that must be supported by the driver of at least one device in order to be accessible to the tenant.

parameters

StringArray

No

CRU

N/A

A list of parameters to pass to the extension.

API Operations

This model draws heavily from existing API specification for Atlas-LB and Mirantis’ LBaaS documents.  The key differences are that this does not define any application-specific functionality - ie. it does not require the end-users explicitly configure load balancing as a service.  It also tries to address questions as to how different load-balancing technologies are deployed and how they fit in with Quantum.

Administrative Operations

Show LB Device Pools

Returns a summary of the LB device pools that the user has access to.

Create LB Device Pool

Returns the ID of a new device pool.  A list of devices that should belong to this pool can be optionally provided, using POST data.

Update LB Device Pool

Can be used to change the configuration of an LB device pool.  This may be frequently used to add or remove different LB devices from the pool in a scaling operation.

Delete LB Device Pool

Is used to delete the device pool.

List LB Devices

Verb

URI

Description

GET

/balancer/devices

Returns a summary of all load balancing devices accessible to the tenant

Show LB Device

This operation returns a summary of the registered load balancing devices accessible to the user.

Verb

URI

Description

GET

/balancer/device/<device_id>

Returns a summary of all load balancing devices accessible to the tenant

Create LB Device

This operation is used to create a new load balancing device.  A number of parameters are supplied as POST data, and the ID of a new load balancing device is returned.  

Verb

URI

Description

POST

/balancer/devices

Creates a new LB device.  This can be used to either register an existing device, or provision a new one through nova (if working with software devices).

Update LB Device

Verb

URI

Description

PUT

/balancer/device/<device_id>

Updates the details

Tenant Operations

List LB services

This operation returns a list of lb services that the tenant has access to.  Filtering criteria can be provided using a querystring.

Verb

URI

Description

GET

/balancer/services

Returns a list of lb services that the tenant has access to.

Create LB service

Takes number of parameters as POST data, and returns the ID of a new LB service.

Verb

URI

Description

POST

/balancer/service

Updates the details

{

    service: {

        protocol: "HTTP",

        port: "80",

        nodes: [

            "192.168.37.10:80",

            "192.168.37.11:80",

            "192.168.37.12:80";

        ],

        monitors: [

            "PING",

            "HTTP"

        ],

        request_rules: [

            "URL Aliases",

            "Authentication offload";

        ],

        afm_enabled: true,

        afm_policy: [

            "Cookiejar handler",

            "URL encrypter",

            "Baseline protection";

        ];

    };

};

Show LB service

Verb

URI

Description

GET

/balancer/service/<service_id>

Returns detailed information about the configuration of a service that has been deployed to a number of load-balancing devices and/or device pools.

{

     balancer: {

        devices: [

 

            device: {

                id: 14242,

                name: "Foo",

                admin_public_ports: [

                    "https://public.lbname.zonename.tenantname.spname.com:9090"

                ],

                admin_private_ports: [

                    "https://private.lbname.zonename.tenantname.spname.com:9090"

                ],

        ],

        "devicepools": [

           "",

           "",

           ""

        ];

    };

}

Update LB service

Verb

URI

Description

PUT

/balancer/device/<device_id>

Updates the details


[1] A simple JSON entity that can be translated into an HTML form (or similar) would seem suitable for this purpose.