This section explains the usage of HTTP PATCH method.
NSX Advanced Load Balancer supports use of PATCH to perform the following operations:
Update scalar fields (string, bool, int32, etc.).
Add a new entry to a list in an object.
Update an entry in a list in an object.
Unset scalar fields - This causes the fields to be reset to their default values, if applicable.
Delete an entry from a list in an object - According to section 5.1.1 of RFC2616, “The Method token indicates the method to be performed on the resource identified by the Request-URI. The method is case-sensitive.” So spell it “PATCH” to avoid “400 bad request” errors from NSX Advanced Load Balancer when executing the HTTP PATCH request.
Editing Nested Fields
In the current release, editing nested fields using PATCH is supported only to a field depth of 1. PATCH is not supported for editing objects with deep nesting characteristics. To accomplish an edit to a nested field, PATCH expects the data to be in the following form:
{
"add": {
}
}
or
{
"replace": {
}
}
or
{
"delete": {
}
}
For scalar fields, add or replace are equivalent as they replace the value of the scalar field with the value provided. In case of a list, add indicates that the specified set of entries needs to be added to the list and replace indicates that the list itself is replaced with what is specified in the request. Action delete is used to remove specified entries from the list.
Examples
The following examples use PATCH to update server information in a pool. The pool is identified by its UUID.
Add Servers to a Pool- This request to the NSX Advanced Load Balancer API adds two new servers (1.1.1.1 and 1.1.1.2) to an existing pool.
API: /api/pool/pool_uuid
Data:
{
"add": {
"servers": [
{
"ip": {
"addr": "1.1.1.1",
"type": "V4"
}
},
{
"ip": {
"addr": "1.1.1.2",
"type": "V4"
}
}
]
}
}
Update Server Information in a Pool - This request to the NSX Advanced Load Balancer API updates one of the servers in an existing pool.
API: /api/pool/pool_uuid
Data:
{
"add": {
"servers": [
{
"ip": {
"addr": "1.1.1.1",
"type": "V4"
},
"ratio": 10
}
]
}
}
If a field is an array of structures, each structure is typically identified by a key (combination of the fields within the structure). This is used to identify the element in the list to update. In the case of pool servers, the server key is identified by ip, port.
Replace Servers in a Pool with a new set of Servers - This request replaces the entire server list with a new server list. The other fields of the pool remain intact.
API: /api/pool/pool_uuid
Data:
{
"replace": {
"servers": [
{
"ip": {
"addr": "3.3.3.3",
"type": "V4"
},
},
{
"ip": {
"addr": "3.3.3.4",
"type": "V4"
},
}
]
}
}
Delete a Server from a Pool- This request deletes one of the servers from an existing pool.
API: /api/pool/pool_uuid
Data:
{
"delete": {
"servers": [
{
"hostname": "www.example.com",
"ip": {
"addr": "3.3.3.3",
"type": "V4"
},
"resolve_server_by_dns": true
}
]
}
}
Updating Scalar Fields - The examples in this section set some scalar fields. The following request enables HTTP request queuing and sets the default server port to 8080.
API: /api/pool/pool_uuid
Data:
{
"delete": {
"default_server_port": 8080
}
}
The following request resets the default server port to the system default, by deleting its explicit setting from the pool.
API: /api/pool/pool_uuid
Data:
{
"replace": {
"request_queue_enabled": True,
"default_server_port": 8080
}
}
Supported Objects
PATCH is officially supported for the following objects and fields:
Object |
Fields |
|---|---|
Cloud |
linuxserver.hosts |
GslbService |
enabled |
IpAddrGroup |
addrs |
prefixes |
|
ranges |
|
MicroServiceGroup |
service_refs |
Pool |
health_monitor_refs |
servers |
|
StringGroup |
kv |
type |
|
SystemConfiguration |
dns_virtualservice_refs |
global_tenant_config |
|
snmp_configuration.community |
|
VirtualService |
http_policies |
Asynchronous Patch
Adding pools and deleting pools at a high rate requires applying patches at a high rate. The size of the deployment often adds more load on the Controller and increases the latency.
The Asynchronous Patch feature allows patch requests to be queued, consolidated in fixed intervals, and updated together with minimal latency.
This feature is recommended only in case of large deployment size.
When async_patch_merge_period is 0 in Controller properties all PATCH calls on pool with ?async_mode=true are converted into synchronous call and 200 response is returned.
Using the Asynchronous Patch Update
By default, this feature is disabled. To enable asynchronous patch:
Change the async_patch_merge_period in the Controller properties from 0 (default value) to the required interval (30-120 seconds).
Pass the async_mode as a query parameter in the patch request. For example, PATCH /api/pool/<pool-uuid>?async_mode. The response displays a unique patch_id, which can be used to view the status of the request. The patch consolidation is initiated, thereby merging the pending requests in the queue.
Review the status using a GET request on /api/pool-async/status/<patch_id>. The status is displayed as follows:
{
"uuid": <uuid of the pool>,
"status": "QUEUED | IN_PROGRESS | SUCCESS | FAIL",
"created": <timestamp of request creation>,
"error_message": <error message in case of failure>,
"status_code": <status code for server PATCH>
}
Caveats
Currently, this feature is available only for the servers field (with IP4) in the pool object.
This feature is limited to only adding or deleting servers in a pool
All patch requests to the Controller within an async_patch_merge_period must have the same API version (HTTP_X_AVI_VERSION)
Patch updates are not installed until the next update cycle, as defined in the time interval. So the patch updates are not real time.
