Lbaas (Iv.) neutron/lbaas/api__openstack

Directory 1 OpenStack Lbaas API 1.0 1.1 Overview 1.1.1 intended audience 1.1.2 Document Change History 1.1.3 Resources 1.2 Chapter 1. Overview 1.2.1 High-level Task flow 1.2.2 Concepts 1.2.2.1 VIP 1.2.2.2 Pool 1.2.2.3 Pool member 1.2.2.4 Health Monitori ng 1.2.2.5 Session Persistence 1.2.2.6 Connection Limits 1.3 Chapter 2. General API Information 1.3.1 Authentication and Authorization 1.3.2 Request/response Types 1.3.3 Filtering and Column Sel Ection 1.3.4 Synchronous versus asynchronous Plugin Behavior 1.3.5 Bulk Create Operations 1.3.6 Quotas 1.3.7 Notifications 1.3.8 Extensions 1.3.9 faults 1.4 Chapter 3. API Operations 1.4.1 VIPs 1.4.1.1 List all VIPs 1.4.1.2 a Retrieve VIP specific Create a VIP 1.4.1.3 Update a VIP 1.4.1.5 Remove a VIP 1.4.2 pools 1.4.2.1 List All pools 1.4.2.2 the Retrieve a specific pool 1.4.2.3 Create a pool 1.4.2.4 Upd Ate a pool 1.4.2.5 Remove a pool 1.4.3 Pool members 1.4.3.1 list all Members 1.4.3.2 list all members of a specific pool 1 .4.3.3 Retrieve a specific MEmber 1.4.3.4 Bulk Create members 1.4.3.5 Update A's 1.4.3.6 Remove a member 1.4.4 Health monitors 1.4.4.1 Create a P ING Health Monitor 1.4.4.2 Create a TCP Health monitor 1.4.4.3 Create an HTTP or a HTTPS Health Monitor 1.4.4.4 Associate and dissociate Health monitors with pools 1.4.4.4.1 List-all Health monitors associated with a Pool 1.4.4.4.2 associate H Ealth monitors with a pool 1.4.4.4.3 dissociate Health monitors from a pool 1.4.5 Statistics 1.4.5.1 List Traffic Statisti CS of a pool 1.4.6 protocols 1.4.6.1 List supported Load balancing Protocols 1.4.7 LB Methods 1.4.7.1 Listing supported Lo Ad balancing Methods OpenStack Lbaas API 1.0 Overview intended audience

Intended audience

This guide is for software developers who create applications by using the Lbaas API v1.0. To use this information, your should have a general understanding of the OpenStack Lbaas service, the OpenStack Quantum Vice, and the integration between the two.

You should also is familiar with:restful Web services http/1.1 JSON serialization format Document change History

This version of the Developer Guide replaces and obsoletes all previous versions. The most recent changes are described in the table below:

Revision Date

OCT, 25 2012

Resources

Use the following to conjunction with this guide:

Resource

tbd

Chapter 1. Overview

The Lbaas project provides a load balancing service to enable OpenStack tenants to load balance to traffic VMs.

Th capabilities provided by the Lbaas service are:

<tbd>

high-level Task Flow

The high-level task flow for using Lbaas APIs to configure load balancing is as follows:the tenant a pool, creates I s initially empty the tenant create one or several members in the pool the tenant create one or several health Th e Tenant associates The health monitors with the pool the tenant creates a VIP with the pool concepts

To use OpenStack Lbaas APIs effectively, you should understand several key concepts: VIP

A VIP is the primary load balancing configuration object, specifies the virtual IP address and port on which client TR Affic is received, as as and other details such as the "load balancing" to be-use, protocol, etc. This entity was sometimes known in LB products under the name of a "virtual server", a "vserver" or a "listener". Pool

A load balancing pool is a logical set of devices, such as Web servers, which you group together to receive and process tra Ffic. The Loadbalancing function chooses a member of the "pool according to" Configured load Balancing method to handle the NE W requests or connections received on the VIP address. There is only one pool for a VIP. Pool Member

A Pool member represents the application running on backend server. Health Monitoring

A health monitor is used to determine whether or not back-end members of the VIP's pool are usable for processing a reques T. A Pool can have several health monitors associated with it. There are different types of health monitors supported by the OpenStack Lbaas and PING the members service:PING:used G ICMP. Tcp:used to connect to the members using TCP. http:used to send a HTTP request to the member. https:used to send a secure HTTP request to the member. Session Persistence

The

Session persistence is a feature the load balancing service. It attempts to force connections or requests in the same sessions to being processed by the same member as long as it's ative . The OpenStack Lbaas service supports three types of persistence:SOURCE_IP:With this persistence mode, all connections or Iginating from the same source IP address, 'll is handled by the same member of the pool. Http_cookie:with This persistence mode, the LoadBalancer'll create a COOKIE on the the the the the "a" client. Subsequent requests containing the same cookie value is handled by the same member of the pool. App_cookie:with This persistence mode, the LoadBalancer would rely on a COOKIE established by the backend application. All requests carrying the same cookie value is handled by the same member of the pool. Connection Limits

To control incoming traffic in the VIP address as as as the traffic for a specific member of a pool, can set a connectio N limit beyond which the load balancing function would refuse client requests or connections. This can is used to the thwart DoS attacks and to allow each member to continue to work the its within.

For HTTP and HTTPS protocols, since several HTTP requests can is multiplexed on the same TCP connection, the connection Li MIT value is interpreted as the maximum number of requests allowed. Chapter 2. General API Information

Sections in this chapter describe operations and guidelines the are to all common APIs, and OpenStack not are to The Load balancing API. Authentication and Authorization

The Lbaas API v1.0 uses the Keystone Identity service as the default authentication service. When Keystone are enabled, users that submit requests to the Lbaas service must provide a authentication token in X-au Th-token request header. You are obtain the token by authenticating to the Keystone endpoint. For more information about Keystone, the OpenStack Identity Developer Guide.

The default authorization settings allow only administrative users to create resources on behalf of a different tenant.

Lbaas uses information received from Keystone to authorize user requests. Lbaas handles the following types of authorization policies:

operation-based Policies

Specify access criteria for specific operations, possibly with fine-grained control over specific attributes.

resource-based Policies

Access a specific resource. Permissions might or might is granted depending on the Permissions for the configured. Request/response Types

The Lbaas API v1.0 supports the JSON data serialization format. This means which is contain a body, the Content-type header must is set to the MIME Type value application/ JSON ". Also, clients must accept JSON serialized responses by specifying the accept header with the MIME type value "application/ JSON "or adding". JSON "extension to the resource name.

Example:

#!highlight JavaScript numbers=disable
Get/v1.0/vips.json

Or

#!highlight javascript numbers=disable
get/v1.0/vips
Accept:application/json

filtering and Column Selection

The Lbaas API v1.0 supports filtering based on "All" level attributes of a resource. Filters are applicable to all list requests.

For example, the following request returns all networks named Foobar:

#!highlight JavaScript numbers=disable
Get/v1.0/vips?name=foobar

When your specify multiple filters, the Lbaas API v1.0 returns only objects this meet all filtering criteria. The operation applies an and condition among the filters.

#!wiki Caution Note Lbaas does does not offer a

OR mechanism for filters.

Alternatively, you can issue a distinct request for each filter and build a response set from the received on th E client-side.

By default, the Lbaas returns all attributes to call to any show or list. The Lbaas API v1.0 has a mechanism to limit the set of attributes returned. For example, return ID.

You can use the fields query parameter to the attributes returned from the Lbaas API v1.0.

For example, the following request returns only Id,name,network_id,address and port for each VIP:

#!highlight JavaScript numbers=disable
get/v1.0/vips.json?fields=id&fields=name&fields=network_id &fields=address&fields=port

synchronous versus asynchronous Plugin Behavior

The Lbaas API v1.0 presents a logical load balancing configuration consisting of VIPs, pools, and members. It is the Lbaas plugin to communicate with the underlying infrastructure to ensure load balancing are consistent with The logical model. A plugin might perform these operations asynchronously.

When a API client modifies the logical model by issuing a HTTP POST, put, or DELETE request, the API call might return B Efore The plugin modifies underlying virtual and physical switching. However, an API client is guaranteed so all subsequent API calls properly reflect the changed model.

For example, if a client issues of HTTP put request to add a \ to a pool, there is no guarantee this member can R Eceive traffic when the HTTP call returns. However, it is guaranteed this a subsequent HTTP GET request to view the members on the pool returns a list that would con Tain the added member.

can use the status attribute of the VIP, the pool, the member or the Health Monitor to determine whether the Lbaas PLU Gin has successfully completed the configuration of the resource. Bulk Create Operations

The Lbaas API v1.0 enables you to create several objects of the same type in the same API request. Bulk Create operations use exactly the same API syntax as single create operations except this you specify a list of objec TS rather than a single object in the request body.

Bulk operations are always performed atomically, meaning that either all or none of the "objects in the" Request body are CR Eated. If a particular plugin does not support atomic operations, the Lbaas API v1.0 emulates the atomic behavior so users C An expect the same behavior regardless of the particular plugin running in the background.

The Lbaas service might be deployed without support for bulk operations and when the client attempts a bulk create Operati On, a bad Request error is returned.

For information about you to submit bulk requests to the Lbaas API v1.0, and the "called Create members" bulk Ion. Quotas

[TBD] Notifications

[TBD] Extensions

The Lbaas API v1.0 is extensible.

The purpose of Lbaas API v1.0 extensions is to:introduce new features to the API without requiring a version change. Introduce vendor-specific niche functionality. Act as a proving ground for experimental functionalities that might is included in a future version of the API.

To programmatically determine which extensions are available, issue a GET request on The/v1.0/extensions URI.

To query extensions individually by the unique alias, issue a GET request on The/v1.0/extensions/alias_name URI. Use the to easily determine if a extension is available. If the extension is isn't available, a 404 Not Found response is returned.

You can extend existing core APIs with new actions or extra attributes. Also, can add new resources as extensions. Extensions usually have tags that prevent conflicts and other Extensions then define attributes or resources with the SAM e names, and with core and attributes. Because an extension might is supported by-all plugins, the availability of a extension varies with deployments and t He specific plugin. So, make sure that your extension are available on the deployed Lbaas service before making by use of it extra features. faults

The Lbaas API v1.0 returns a error response if a failure occurs while processing a request. Lbaas uses only standard HTTP error codes. 4xx errors indicate problems in the particular request being sent from the client.

Error	Description
400	Bad Request
404	Not Found
409	Conflict
413	Over limit
422	Immutable
500	Internal Server Error
503	Service unavailable

The Users submitting requests to the Lbaas API v1.0 might also receive the following errors:

401 Unauthorized-if Invalid credentials are provided.

403 Forbidden-if The user cannot access a specific resource or perform the requested.

The response body would contain richer information about the cause of the error. An error response follows the format illustrated by the following example:

#!highlight JavaScript numbers=disable
409 Conflict
content-type:application/json
content-lentgh:78

{
   "errorcode": 409,
   "errormessage": "Pool is already used by a existing VIP"
}

Chapter 3. API Operations

This chapter explains specific API operations. For ideas relevant to all API operations, click "General API Information" chapter. VIPs

Use the Lbaas API v1.0 to manage network

Verb	Rr.
Get	/v1.0/vips/
Get	/v1.0/vips/vip_id
POST	/v1.0/vips
Put	/v1.0/vips/vip_id
DELETE	/v1.0/vips/vip_id

List all VIPs

Verb	Rr.	Description
Get	/v1.0/vips/

Normal Response Code (s): 202

Error Response Code (s): 401 (Unauthorized), (Internal server Error), 503 (Service unavailable)

This operation returns the "list of all" VIPs associated with your account. If if you have a admin role, then this request returns all the VIPs to all tenants.

This operation does isn't require a request body.

This is operation returns a response body. It returns a (potentially empty) list, each element in the ' list is ' a VIP that can contain the following attributes:id ant_id Name Description network_id address Port Lbmethod protocol pool_id session_persistence Connection_limit Admin_stat E_UP status

Example. List VIPs

JSON Request:

#!highlight javascript numbers=disable
get/v1.0/vips
host:lbaas-service.cloudx.com:8651
Accept: Application/json
x-auth-token:887665443383838

JSON Response:

 #!highlight javascript numbers=disable ok content-type:application/json content-length:384 {"VIPs": [ {"id": "db902c0c-d5ff-4753-b465-668ad9656918", "tenant_id": "310df60f-2a10-4ee5-9554-98393092194 C "," Name ":" WEB_VIP "," description ":" lb config for the Web tier "," network_id ":" 96a438 6a-f8c3-42ed-afce-d7954eee77b3 "," Address " :" 10.30.176.47 "," protocol ":" HTTP "," PO
           RT ":", "Lb_method": "Round_robin", "pool_id"  : "cfc6589d-f949-4c66-99d2-c2da56ef3764", ' Admin_state_up ': true, ' status ': ' ACTIVE '}, {' id ': ' 36e08a3e-a78f-4b40-a22 9-1e7e23eee1ab "," tenant_id ":" 310df60f-2a10-4ee5-9554-98393092194c "," name ":" Db_vip "," network_id ":" 9cedb85d-0759-4898-8a4b-fa5a5ea10086&q