VMware Avi Load Balancer Api

VMware Avi Load Balancer Api

Overview

This manual covers VMware Avi Load Balancer RESTful Application Programming Interface (API) guide.

HTTP Headers

Avi Controller REST APIs uses HTTP Headers and cookies for authentication, denoting content type, ordering, filtering, pagination, etc.

Request Headers


Name Mandatory Description Usage
Content-Type Yes Content format. Should be application/json Content-Type: application/json
X-Avi-Version Yes API version to use for the API call. Avi controller supports all the API version which is less than equal to the version of the Controller. In order to use a feature that is released in a version, eg. 17.2.7, the API version should be greater than or equal to 17.2.7. It is important to remember that API version determines the version of the API data. As best practice, users once users have performed integration with a controller and API version then they should keep using it till they tested integration with the new API Version. X-Avi-Version: 18.1.2
X-Avi-Tenant No Tenant context. If not present, default tenant for user is used X-Avi-Tenant: acme
Authorization Yes Encoded Auth credentials in Base64 or authenticated sessionid cookie is mandatory Authorization: Basic yjfsdnj984498
X-CSRFToken Yes CSRF Token for POST/PUT. Use from csrftoken cookie X-CSRFToken: hdsbf84r34FFI39nvd398
Referer Yes NB: Mandatory for POST only Parent page Referer: http://10.10.10.10/
Accept-Encoding Yes NB: Mandatory for GET only Requested content format. Should be application/json Accept-Encoding: application/json

 

Response Headers


Name Description Format
Content-Type Content format. Should be application/json Content-Type: application/json

 

Response Cookies


Name Description Format
csrftoken Auth Token for session csrftoken: HF48348nvdvvdhh8
sessionid Session ID sessionid: fdsh734FG578b

 

Authentication

Avi Controller allows REST API usage using both Basic Authentication (over https) and Session Authentication.

Basic authentication

Auth credentials are encoded as Base 64 and sent as the Authorization header in every request. The following example retrieves the cluster version using basic authentication using the requests python library. resp = requests.get(‘https://10.10.1.101/api/cluster/version’, verify=False, auth=(‘admin’,‘adminpassword’))

Session authentication

The client performs a login to the controller. After authentication, a session is established and the sessionid is passed back to the client as a cookie. The client returns the sessionid cookie for subsequent requests. To end the session, the client performs a logout to the controller with the CSRFToken and controller IP in the headers. The following example retrieves the cluster version after session establishment, and then terminates the session.

login = requests.post('https://10.10.1.101/login', verify=False, data={'username': 'admin', 'password': 'adminpassword'})
resp = requests.get('https://10.10.1.101/api/cluster/version', verify=False, cookies=dict(sessionid= login.cookies['sessionid']))
logout = requests.post('https://10.10.1.101/logout', verify=False, headers={'X-CSRFToken': login.cookies['csrftoken'], 'Referer':'https://10.10.1.101'}, cookies=login.cookies)
 

Object Tenancy

A tenant is associated with every object. ‘admin’ tenant is the default tenant that exists from the beginning.

Users can just access tenants where they have been assigned a role. Each user has a default tenant. ‘admin’ user is automatically assigned a role in all tenants. The default tenant for ‘admin’ user is ‘admin’ tenant.

In order to perform an operation in a tenant that’s different from the default tenant for that user, use the extension header ‘X-Avi-Tenant’ to specify the tenant. If ‘X-Avi-Tenant’ isn’t specified, the operation is performed in the default tenant for that user.

For e.g., when the ‘admin’ user performs a GET on /api/pool, without specifying ‘X-Avi-Tenant’, all pools under the ‘admin’ tenant are retrieved. When the ‘admin’ user performs a GET on /api/pool specifying ‘X-Avi-Tenant’ as ’tenant1’, all pools under ’tenant1’ tenant are retrieved.

Object management

REST methods can be used for managing objects in the Avi Controller.

Object retrieval

Use the GET method to retrieve one or more objects.

To retrieve all tenants:

GET /api/tenant
{
    count: 1,
    results: [
        {
            “description”: "",
            “url”: "https://10.10.5.27/api/tenant/admin",
            “uuid”: "admin",
            “name”: "admin",
            “local”: true,
            “config_settings”: {
                “tenant_vrf”: false,
                “tenant_default_profiles”: false
            }
        }
    ]
}
 

To retrieve tenants with uuid ‘admin’:

GET /api/tenant/admin

{
    "description": "", 
    "url": "https://10.10.5.27/api/tenant/admin", 
    "uuid": "admin", 
    "name": "admin", 
    "local": true, 
    "config_settings": {
        "tenant_vrf": false, 
        "tenant_default_profiles": false
    }
}
 

Object creation

Use the POST method to create an object.

To create a pool:

POST /api/pool
{
            "description": "my pool",
            "name": "pool1",
            "servers": [
                {
                    "ip": {
                        "addr": "10.10.1.10",
                        "type": "V4"
                    },
                    "port": 80,
                }
            ],
}
 

Object modification

Use the PUT method to modify an object.

To modify a pool with uuid ‘pool-13df5490-cb95-47f8-b414-c2b37c897ca7’:

PUT /api/pool/pool-13df5490-cb95-47f8-b414-c2b37c897ca7
{
      "uuid": "pool-13df5490-cb95-47f8-b414-c2b37c897ca7",
      "name": "p1",
      "tenant_ref": "https://10.10.1.101/api/tenant/admin",
      "servers": [
        {
            "ip": {
                "type": "V4",
                "addr": "10.10.10.10"
            },
            "enabled": true
        },
        {
            "ip": {
                "type": "V4",
                "addr": "10.10.10.11"
            },
            "enabled": true
        }
    ]
}
 

Object deletion

Use the DELETE method to delete an object.

To delete a pool with uuid ‘pool-13df5490-cb95-47f8-b414-c2b37c897ca7’:

DELETE /api/pool/pool-13df5490-cb95-47f8-b414-c2b37c897ca7
 

Response codes

Avi Controller returns the following response codes.

2xx response codes

These response codes are associated with a successful operation.

Response code Description
200 OK - Success
201 CREATED – Successful object creation
204 NO CONTENT – Successfully completed

3xx response codes

These response codes are used for redirection.

Response code Description
302 REDIRECT – Indicates client should use new URL

4xx response codes

These response codes indicate an error.

Response code Description
400 BAD REQUEST – Content is incorrect
401 NOT AUTHORIZED – Authentication failure
404 NOT FOUND – Object doesn’t exist
405 METHOD NOT ALLOWED – Incorrect method on object

5xx response codes

These response codes indicate a server error.

Response code Description
500 SERVER ERROR – Internal server error
503 INITIALIZING – Avi Controller is not ready

 

Filtering, sorting, paging

The following sections explain how to filter, sort and page objects.

Filtering

To filter a pool by name:

GET /api/pool?name=pool1
{
    "count": 1,
    "results": [
        {
            "url": "https://10.10.1.101/api/pool/pool-4afa32c7-6835-4c46-b602-de6d1e9e4d7c",
            "uuid": "pool-4afa32c7-6835-4c46-b602-de6d1e9e4d7c",
            "name": "pool1",
            "server_count": 1,
            "tenant_ref": "https://10.10.1.101/api/tenant/admin",
            "lb_algorithm": "LB_ALGORITHM_LEAST_CONNECTIONS",
            "use_service_port": false,
            "inline_health_monitor": true,
            "default_server_port": 80,
            "max_concurrent_connections_per_server": 0,
            "graceful_disable_timeout": 1,
            "connection_ramp_duration": 10,
            "servers": [
                {
                    "hostname": "10.10.10.10",
                    "ratio": 1,
                    "ip": {
                        "type": "V4",
                        "addr": "10.10.10.10"
                    },
                    "enabled": true,
                }
            ],
            "pd_action_type": "POOL_DOWN_ACTION_CLOSE_CONN",
        }
    ]
}
 

Sorting

To sort a pool by name (in ascending order):

GET /api/pool?sort=name
{
    "count": 1,
    "results": [
        {
            "url": "https://10.10.1.101/api/pool/pool-4afa32c7-6835-4c46-b602-de6d1e9e4d7c",
            "uuid": "pool-4afa32c7-6835-4c46-b602-de6d1e9e4d7c",
            "name": "pool1",
            "server_count": 1,
            "tenant_ref": "https://10.10.1.101/api/tenant/admin",
            "lb_algorithm": "LB_ALGORITHM_LEAST_CONNECTIONS",
            "use_service_port": false,
            "inline_health_monitor": true,
            "default_server_port": 80,
            "max_concurrent_connections_per_server": 0,
            "graceful_disable_timeout": 1,
            "connection_ramp_duration": 10,
            "servers": [
                {
                    "hostname": "10.10.10.10",
                    "ratio": 1,
                    "ip": {
                        "type": "V4",
                        "addr": "10.10.10.10"
                    },
                    "enabled": true,
                }
            ],
            "pd_action_type": "POOL_DOWN_ACTION_CLOSE_CONN",
        }
    ]
}
 

To sort a pool by name (in descending order):

GET /api/pool?sort=-name
 

Paging

To retrive pools in a specific page with a specific page size:

GET /api/pool?page_size=1&page=2
{
    "count": 10,
    "next": "https://10.10.1.101/api/pool?page=3&page_size=1",
    "results": [
        {
            "url": "https://10.10.1.101/api/pool/pool-4afa32c7-6835-4c46-b602-de6d1e9e4d7c",
            "uuid": "pool-4afa32c7-6835-4c46-b602-de6d1e9e4d7c",
            "name": "pool1",
            "server_count": 1,
            "tenant_ref": "https://10.10.1.101/api/tenant/admin",
            "lb_algorithm": "LB_ALGORITHM_LEAST_CONNECTIONS",
            "use_service_port": false,
            "inline_health_monitor": true,
            "default_server_port": 80,
            "max_concurrent_connections_per_server": 0,
            "graceful_disable_timeout": 1,
            "connection_ramp_duration": 10,
            "servers": [
                {
                    "hostname": "10.10.10.10",
                    "ratio": 1,
                    "ip": {
                        "type": "V4",
                        "addr": "10.10.10.10"
                    },
                    "enabled": true,
                }
            ],
            "pd_action_type": "POOL_DOWN_ACTION_CLOSE_CONN",
        }
    ]
}
 

Retrieving specific fields

To retrieve specific fields in the response, use query ‘?fields=field1,field2,field3’.

GET /api/pool?fields=name,servers,lb_algorithm
{
    "count": 10,
    "results": [
        {
            "name": "pool1",
           "lb_algorithm": "LB_ALGORITHM_LEAST_CONNECTIONS",
          "servers": [
                {
                    "hostname": "10.10.10.10",
                    "ratio": 1,
                    "ip": {
                        "type": "V4",
                        "addr": "10.10.10.10"
                    },
                    "enabled": true,
                }
            ],
        }
    ]
}
 

Filters

Filter Description

Example

Response
Based on field value The objects can be queried after applying a filter based on the value of a particular field of the object. .(dot) can be used for fields that are nested in other fields. This filter is most commonly used for fetching an object based on its name. Multiple fields can be searched using &. /api/pool?fail_action.type=FAIL_ACTION_CLOSE_CONN Pool objects with fail_action as {type: "FAIL_ACTION_CLOSE_CONN"}

name.contains

This filter returns the objects with name that contains the parameter. This is a case sensitive search. /api/pool?name.contains=pool- Pool objects that contain pool- in their name (like mypool-01).

name.icontains

This filter returns the objects with name that contains the parameter. This is a case insensitive search /api/pool?name.icontains=pool- Pool objects that contain pool- in their name (like MyPool-01) (case insensitive).

name.in

This filter returns the objects with name that contains the parameter. Each value for this parameter is to comma separated. /api/pool?name.in=pool-1,pool-12

Pool objects with name pool-1 or pool-12.

uuid.in

This filter returns the objects with uuid that contains the parameter. Each value for this parameter is to comma separated. /api/pool?uuid.in=<uuid-1>,<uuid-2>

Pool objects with uuid <uuid-1> or <uuid-2>.

search

 

This filter returns all objects that contains the search string as value for any of its fields. /api/pool?search=LEAST_CONN All Pool objects with LEAST_CONN appearing anywhere in any of their fields.

The search filter can also be used to search under a specific field. This is achieved by sending the parameter in the format: ?search=(<field>,<value>)|(<field>,<value>). Incremental search is available for the value part.

/api/pool?search=(name,vs-pool-) All Pool objects with name starting with vs-pool-
The search filter can also be used to filter depending on the existence of a field. This follows the above pattern with the second item of the tuple left empty: ?search=(<field>,)|(<field>,) /api/pool?search=(server_count,) Pools that have the field server_count with them.
isearch This filter is used to search case insensitive values under a specific field. This is achieved by sending the parameter in the format: ?isearch=(<field>,<value>)|(<field>,<value>). Incremental search is available for the value part. /api/pool?isearch=(name,Vs-Pool-) All Pool objects with name starting with all case permutations of vs-pool-
referred_by This filter returns all objects that are referred by the given objects in parameters. The parameter needs to be sent as ?referred_by=<obj_type>:<obj_uuid>,<obj_type>:<obj_uuid>. Special parameters 'any'/'none' can be used as obj_uuid to filter at least one/no refs of obj_type.
Also 'any:none'/'any:any' can be used to get objects being referred by no objects/referred by at least one object of any type.
/api/pool?referred_by=virtualservice:<uuid> Pools that are referred by the vs with uuid <uuid>
refers_to This filter returns all objects that refers to the given objects in parameters. The parameter needs to be sent as ?refers_to=<obj_type>:<obj_uuid>,<obj_type>:<obj_uuid>. Add depth parameter to specify the depth to which the relation needs to be checked. Special parameters 'any'/'none' can be used as obj_uuid to filter at least one/no refs of obj_type.
Also 'any:none'/'any:any' can be used to get objects referring to no objects/referring to at least one object of any type.
/api/virtualservice?refers_to=pool:<uuid>&depth=1 VS objects that directly refers to pool with uuid <uuid>

cloud_ref.uuid

This filter is used to filter objects with their cloud ref. /api/pool?cloud_ref.uuid=<uuid> Pool objects with their cloud ref uuid as <uuid>.
limit_by This filter the number of objects in the response data. /api/pool?limit_by=3

First three pool objects from the queryset.

exclude
This filter excludes the uuid(s) contained in the parameter. 
/api/pool?uuid.in=<uuid-1>,<uuid-2>&exclude=uuid.in
All the pool objects except those in uuid.in
label_key This filters filters the response wrt GRBAC marker (label) keys. /api/pool/?label_key=app All pools with GRBAC labels having key as "app"
label_value This filter filters the response wrt GRBAC marker (label) values. /api/pool/?label_value=green All pools with GRBAC labels having "green" as one of the values.

 

Additional Parameters

Parameter Description Example Response

sort

This parameter is used to sort the results w.r.t a field. /api/pool?sort=name All pool objects with pools appearing in alphabetic order

fields

This filter allows user to specify the fields that need to be fetched by the request. If multiple fields are required, they need to be comma separated. /api/pool?fields=fail_action,cloud_ref All pool objects with fail_action and cloud_ref fields along with other general fields (uuid, name, url, ..).
include_name If this parameter is set, all referred fields will have their name appended as <object>_ref:<uuid>#<name> /api/pool?include_name All pool objects with referred fields with name appended to it.

skip_default

This parameter can be used to skip fields with value same as its default value. /api/pool?skip_default=True

All pool objects without fields that are holding their default values.

Parameters for Pagination

page_size is used to specify the maximum number of results to be returned per page. It can be any integer from 1 to 200. page specifies the index of the page for displaying paginated results. - -