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.	-	-