Skip to main content

REST APIs for 24.2.20 and 24.2.10

Virtual Server Filtering

Filtering of the discovered virtual servers and draft virtual server endpoints makes it easier to manage large numbers of virtual servers.

The existing Public Experimental API endpoints for virtual servers have been changed to support the required filters and associated UI operations. You can now filter a discovered virtual server collection by:

  • name

  • SLB (API uses href as per conventions)

  • VIP: IP, proto, port (any or all)

  • virtual server href

Virtual Server Endpoints

New filters have been added for the following existing endpoints:

  • GET /orgs/:xorg_id/discovered_virtual_servers

  • GET /orgs/:xorg_id/sec_policy/:pversion/virtual_servers

Note

These Interface endpoints are available only for API version V2.

Virtual Server Discoveries

Virtual server discovery happens passively once the Server Load Balancer (SLB) is configured and the Network Enforcement Node (NEN) receives the SLB configuration changes. However, users might want to be able to run virtual server discovery on demand.

The new schema network_enforcement_nodes_virtual_server_discovery_jobs_put.schema.json is used to create a virtual server discovery job request that contains the slb_name, the virtual server ip_address, and the port. NEN picks up the request, launches the discovery of the virtual server information, and posts the results back.

Discovery Job On-demand

Use the following API:

POST /api/v2/orgs/1/network_enforcement_nodes/virtual_server_discovery_jobs

where the required properties are:

slb_name

  • Description: Name of the SLB to interrogate.

  • Format: String

virtual_server_infos

  • Description: An array of virtual_server_info objects consisting of virtual_server port and IP address

  • Format: Array of Objects

Check the Status of Discovery Job

To find out the results of the discovery request use the following command:

GET /api/v2/orgs/1/network_enforcement_nodes/virtual_server_discovery_jobs/:job_uuid
Discovered Virtual Servers

Filter

URI Example

Notes

name

/discovered_virtual_servers?name

Supports partial and incomplete matches

slb

/discovered_virtual_servers?slb= /orgs/1/slbs/<uuid>

vip

/discovered_virtual_servers ? vip=10.1

Supports suffix matches, e.g. 10.1 matches any IP address that starts with "10.1", "10.100", ... but not "110.x"

vip-proto

/discovered_virtual_servers? vip_proto=6

vip_port

/discovered_virtual_servers? vip_port=80

has_virtual_server

/discovered_virtual_servers?has_virtual_server=true

The virtual_server_mode and virtual_server_labels MUST be used with has_virtual_server=true, otherwise an error will be raised.

virtual_ server_mode

/discovered_virtual_servers?virtual_server_mode=enforced

Options for this filter are "unmanaged" or "enforced"

virtual_ server_labels

/discovered_virtual_servers? virtual_server_ labels=[[/orgs/1/labels/2, /orgs/1/labels/3], [/orgs/1/labels/4]]

(JSON encoded array of arrays)

virtual_ server

/discovered_virtual _ servers ? virtual_ server = /orgs/1/sec_policy/draft/virtual_servers/<uuid>

Virtual Servers

Filter

URI Example

Notes

name

/virtual_servers?name=myvip

Supports partial and incomplete matches

slb

/virtual_servers?slb=/orgs/1/slbs/<uuid>

vip

/virtual_servers?vip=10.1

Supports suffix matches, e.g., 10.1 matches any IP address that starts with "10.1", "10.100", ... but not "110.x"

vip-proto

/virtual_servers?vip_proto=6

vip_port

/virtual_servers?vip_port=80

mode

/virtual_servers?mode=enforced

Options for this filter are "unmanaged" or "enforced"

labels

/virtual_servers?[[/orgs/1/labels/2, /orgs/1/labels/3], [/orgs/1/labels/4]] (JSON encoded array of arrays)

discovered_virtual_server

/virtual_servers?discovered_virtual_server =/orgs/1/discovered_virtual _servers/<uuid>

Schema Changes

discovered_virtual_servers

The following object has been added to the schema:

{
[... existing fields ...]
"virtual_server" : {
      "href": "/orgs/1/sec_policy/draft/virtual_servers/fbae7cd2-04c3-4d7b-a628-2d69a9d64a71" ,
      "update_type" : "create", # or "update", "delete", null
      "mode": "enforced", # or "unmanaged"
      "labels" [
           { "href": "/orgs/1/labels/2", "key": "role", "value": "database"},
           { "href": "/orgs/1/label/12", "key": "env", "value": "production"}
      ]
    }
}

virtual_servers

The "mode" and "vip_port" fields have been added to the "discovered_virtual_server sub-object" to reflect the filtering result.

{
    [... existing fields ...] 
    "discovered_virtual_server" : {
        "dvs_identifier" :  "5111ecf75c61544720d800cce97a624d" ,
        "href" :  "/orgs/1/discovered_virtual_servers/c1cd1f00-7b48-4c43-a099-f758ac1a9b40" ,  
        "mode" :  "snat" ,
        "name" :  "Common/vip1" ,
        "vip_port" : {
            "port" :  "80" ,
            "protocol" :  6 ,
            "vip" :  "10.0.0.109"
        }
    }
}

slb_config

This schema has been deprecated. It was used for nfc (Network Function Controller), which is now deprecated.

Virtual Server Filtering Reference

This topic covers examples of virtual server filtering.

Examples

Curl Command for Discovered Virtual Servers

curl -i -u api_1bbac8b7295e9b512:343461267jks009651245343461267jks00965124b27074fa181f1edb3bb4a3 https://2x2testvc27.ilabs.io:8443/api/v2/orgs/1/discovered_virtual_servers

Response Body

[{
    "href": "/orgs/1/discovered_virtual_servers/52044aea-14db-4510-a1c6-00231230034",
	"dvs_identifier": "96803bd07185cd093dd800231230034",
	"name": "Common/QL_VIP_1",
	"nfc": {
		"href": "/orgs/1/nfcs/0bcf6c3d-f588-44c7-a269-00231230034"
		},
	"slb": {
		"href": "/orgs/1/slbs/84a1cd93-142f-480d-b9f8-00231230034"
		},
	"vip_port": {
		"vip": "172.16.27.88",
		"protocol": 6,
		"port": "8080"
		},
	"local_ips": ["172.16.26.18", "172.16.27.18"],
	"mode": "snat",
	"snat_type": "snat_pool",
	"snat_pool_ips": ["172.16.26.27", "172.16.26.18", "172.16.27.18"],
	"service_checks": [{
		"protocol": 1
		}],
	"created_at": "2021-02-26T08:32:02.131Z",
	"updated_at": "2021-02-26T08:32:02.131Z",
	"created_by": {
		"href": "/orgs/1/nfcs/0bcf6c3d-f588-44c7-a269-00231230034"
		},
	"updated_by": {
		"href": "/orgs/1/nfcs/0bcf6c3d-f588-44c7-a269-00231230034"
		}
		}, {
	"href": "/orgs/1/discovered_virtual_servers/073c40ec-7357-44f4-a66d-002312300349",
	"dvs_identifier": "b679034796cdde929a000231230034",
	"name": "Common/QL_VIP_2",
	"nfc": {
		"href": "/orgs/1/nfcs/0bcf6c3d-f588-44c7-a269-00231230034"
		},
	"slb": {
		"href": "/orgs/1/slbs/84a1cd93-142f-480d-b9f8-00231230034"
		},
	"vip_port": {
		"vip": "172.16.27.71",
		"protocol": 6,
		"port": "8080"
		},
	"local_ips": ["172.16.26.18", "172.16.27.18"],
	"mode": "snat",
	"snat_type": "snat_pool",
	"snat_pool_ips": ["172.16.26.28", "172.16.26.18", "172.16.27.18"],
	"service_checks": [{
		"protocol": 1
		}],
	"created_at": "2021-02-26T08:32:02.177Z",
	"updated_at": "2021-02-26T08:32:02.177Z",
	"created_by": {
		"href": "/orgs/1/nfcs/0bcf6c3d-f588-44c7-a269-00231230034"
				},
	"updated_by": {
		"href": "/orgs/1/nfcs/0bcf6c3d-f588-44c7-a269-00231230034"
		}
	}
]

Response Body, another example

[
   {
	"href": "/orgs/1/discovered_virtual_servers/5db1ce10-263a-44fb-8c0c-a2312dfb2e6a",
	"dvs_identifier": "the_test_dvs-1",
	"name": "Test DVS No. 1",
	"vip_port": {
		"vip": "30.55.148.143",
		"protocol": 6,
		"port": "8001"
	},
	"local_ips": [
		"10.0.0.1"
	],
	"mode": "snat",
	"slb": {
		"href": "/orgs/1/slbs/8798cea8-1fd4-40e3-a2f1-adae6f094766"
	},
	"nfc": {
		"href": "/orgs/1/nfcs/7c6ae23f-5532-41b0-9b1e-cf9c689de0ae"
	},
	"network_enforcement_node": {
		"href": "/orgs/1/network_enforcement_nodes/7c6ae23f-5532-41b0-9b1e-cf9c689de0ae"
	},
	"snat_type": "snat_local_ips",
	"service_checks": [],
	"created_at": "2022-09-09T22:19:49.915Z",
	"updated_at": "2022-09-09T22:19:49.915Z",
	"created_by": {
		"href": "/users/0"
	},
	"updated_by": {
		"href": "/users/0"
	},
	"virtual_server": {
		"href": "/orgs/1/sec_policy/draft/virtual_servers/ba700305-29b9-4d6a-8bed-c8476753c327",
		"update_type": null,
		"mode": "enforced",
		"labels": [
		{
		   "href": "/orgs/1/labels/14",
		   "key": "role",
		   "value": "LBL-ROLE-1"
		},
		{
		   "href": "/orgs/1/labels/15",
		   "key": "loc",
		   "value": "LBL-LOC-1"
		}
	]
}
{
	"href": "/orgs/1/discovered_virtual_servers/de5f454e-e95b-40c8-a128-fc27a1bed840",
	"dvs_identifier": "the_test_dvs-2",
	"name": "Test DVS No. 2",
	"vip_port": {
		"vip": "34.92.48.237",
		"protocol": 6,
		"port": "8002"
		},
	"local_ips": [
		"10.0.0.2"
	],
	"mode": "snat",
	"slb": {
		"href": "/orgs/1/slbs/8798cea8-1fd4-40e3-a2f1-adae6f094766"
	},
	"nfc": {
		href": "/orgs/1/nfcs/7c6ae23f-5532-41b0-9b1e-cf9c689de0ae"
	},
	"network_enforcement_node": {
		"href": "/orgs/1/network_enforcement_nodes/7c6ae23f-5532-41b0-9b1e-cf9c689de0ae"
	},
	"snat_type": "snat_local_ips",
	"service_checks": [],
	"created_at": "2022-09-09T22:19:49.919Z",
	"updated_at": "2022-09-09T22:19:49.919Z",
	"created_by": {
		"href": "/users/0"
	},
	"updated_by": {
		"href": "/users/0"
	},
	"virtual_server": {
		"href": "/orgs/1/sec_policy/draft/virtual_servers/e1502bf3-0992-4167-b84f-eaebd73cc2d7",
		"update_type": null,
		"mode": "enforced",
		"labels": [
		{
			"href": "/orgs/1/labels/28",
			"key": "role",
			"value": "LBL-ROLE-2"
			},
			{
			"href": "/orgs/1/labels/29",
			"key": "loc",
			"value": "LBL-LOC-2"
		}
	     ] 
       }
 }

Curl Command for Virtual Servers

curl -i -u api_1bcab8b7295e9b512:343461267jks00965124500jkjdmnwe00231230034dfd256124fa181f1edb3bb4a3 https://2x2testvc27.ilabs.io:8443/api/v2/orgs/1/sec_policy/draft/virtual_servers

Response Body

[{    
    "href": "/orgs/1/sec_policy/draft/virtual_servers/5c7aeb96-56e2-4af8-8b4e-00231230034",
	"created_at": "2021-02-26T08:38:15.298Z",
	"updated_at": "2021-02-26T08:39:21.676Z",
	"deleted_at": null,
	"created_by": {
		"href": "/users/1"
		},
	"updated_by": {
		"href": "/users/1"
		},
	"deleted_by": null,
	"update_type": null,
	"name": "Common/QL_VIP_1",
	"description": "",
	"discovered_virtual_server": {
            "href": "/orgs/1/discovered_virtual_servers/52044aea-14db-4510-a1c6-00231230034"
            },
	"dvs_name": "Common/QL_VIP_1",
	"dvs_identifier": "96803bd07185cd093dd800231230034",
	"labels": [{
		"href": "/orgs/1/labels/1185",
		"key": "role",
		"value": "Database_VIP_1"
	}, {
		"href": "/orgs/1/labels/1178",
		"key": "app",
		"value": "Application_1"
	}, {
		"href": "/orgs/1/labels/1176",
		"key": "loc",
		"value": "test_place_1"
	}, {
		"href": "/orgs/1/labels/1174",
		"key": "env",
		"value": "Production"
	}],
	"service": {
		"href": "/orgs/1/sec_policy/draft/services/1"
		},
	"providers": [{
		"label": {
			"href": "/orgs/1/labels/1183",
			"key": "role",
			"value": "Web"
		}
	}, {
		"label": {
			"href": "/orgs/1/labels/1178",
			"key": "app",
			"value": "Application_1"
		}
	}, {
		"label": {
			"href": "/orgs/1/labels/1176",
			"key": "loc",
			"value": "test_place_1"
		}
	}, {
		"label": {
			"href": "/orgs/1/labels/1174",
			"key": "env",
			"value": "Production"
		}
	}],
	"mode": "unmanaged"
}]

Virtual Server discoveries: example for request

{
	"$schema": "http://json-schema.org/draft-04/schema#",	
	"description": "Details of Virtual Servers to discover",	
	"type": "object",
	"additionalProperties": false,
	"required": ["slb_name", "virtual_server_infos"],
	"properties": {
	"slb_name": {
	"description": "Name of SLB to interrogate"
	"type": "string"
},
	"virtual_server_infos": {
	"description": "IP address and port info of Virtual Servers to discover",
	"type": "array",
	"additonalProperties": false,
	"minItems": 1,
	"items": {
	"type": "object",
	"required": ["ip_address", "port"],
	"properties": {
		"ip_address": {
		"description": "Virtual Server IP address",
		"type": "string"
	},
	"port": {
		"description": "Virtual Server port",
		"type": "integer"
		}
	}
}

Sample Response

{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Details of Virtual Servers discovery job",
"type": "object",
"additionalProperties": false,
"properties": {
	"href": {
	"description": "URI of Virtual Servers discovery job",
	"type": "string"
	}
}
{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"description": "Details of Virtual Servers discovery job",
	"type": "object",
	"additionalProperties": false,
	"required": ["status", "created_at", "created_by"],
	"properties": {
            "href": {
            "description": "URI of the requested discovery job",
            "type": "string"   
            }
            "status": {
            "description": "The current state of the request", 
            "type": "string",
            "enum": ["pending", "running", "done"]
            },
            "created_at": {
            "description": "The time (rfc3339 timestamp) at which this job was created",
            "type": "string",
            "format": "date-time"
            },
            "completed_at": {
            "description": "The time (rfc3339 timestamp) at which this job was completed",
            "type": "string",
            "format": "date-time"
            },
            "created_by": {
            type": "object",
		"required": ["href"],
		"properties": {
		"href": {
		"description": "User who originally created this Virtual Server discovery job",
		"type": "string"
		}
          }
      },
     "connection_state": {
        "description": "Status of most recent connection to the SLB device",
        "type": "string",
        "enum": ["pending", "successful", "cannot_resolve", "cannot_connect", "bad_credentials", "bad_certificate", "bad_request", "dup_device"]
	},
    "virtual_server_infos": {
        "description": "Information of individual virtual server discovered",
        "type": "array",
        "minItems": 1,
        "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
        "ip_address": {
		"description": "Virtual server IP address",
		"type": "string"
	},
	"port": {
		"description": "Virtual server port",
		"type": "integer"
		},
        "discovered_virtual_server": {
		"description": "Discovered Virtual Server. Null indicates not found",
		"type": "object",
		"required": ["href"],
		"properties": {
		"href": {
		"description": "URI of Discovered Virtual Server",
		"type": "string"
	    }
      }
}

If a virtual server is discovered, the response might look as follows:

{
	"status" : "done",
	"created_at" : "2021-7-19T07:20:50.52Z",
	"created_by" : {
		"href" : "api/v2/orgs/1/users/1"
	},
	"connection_state" : "successful",
	"completed_at : "2021-7-19T07:20:54.97Z",
	"virtual_server_infos" : [
	    { "ip_address" : "10.2.4.54",
	    "port" : 443,
	    "discovered_virtual_server" : {
	    "href" : "api/v2/orgs/1/discovered_virtual_servers/7a597ef0-6609-4927-9eee-ce403517d850"
	    { "ip_address" : "10.23.23.2",
	    "port" : 8443,
	    discovered_virtual_server" : {
	    "href" : "api/v2/orgs/1/discovered_virtual_servers/6a597ef0-6609-4927-9eee-ce403517d850"
	    } 
      ]
}

If the connection was not established, the response might look as follows:

{
	"status" : "done",
	"connection_state" : "cannot_connect",
	"created_at" : "2021-7-19T07:20:50.52Z",
	"completed_at : "2021-7-19T07:20:54.97Z",
	"created_by" : {
		"href" : "api/v2/orgs/1/users/1"
	}
}
See also: