Skip to main content

Illumio REST APIs 25.4

Virtual Servers

A virtual server is similar to a workload. It can be assigned labels and has IP addresses, but does not report traffic to Illumio Core .Each virtual server has only one VIP. The local IP addresses are used as source IP addresses for connection to the pool members (backend servers) when the virtual server operates in SNAT or Auto mode. These IP addresses are likely to be shared by multiple virtual servers on the server load balancer.

A discovered virtual server is a server load balancer (SLB) virtual server (IP address and port(s)) that the NEN has discovered when interrogating SLBs managed by the PCE.

Virtual Server Methods

There are two groups of methods used to manage virtual servers:

  • Methods for virtual servers

  • Methods for discovering virtual servers

Functionality

HTTP

URI

Get a list of Virtual Servers.

GET

[api_version][org_href]/sec_policy/:version/virtual_servers

Get a specified Virtual Server.

GET

[api_version][org_href]/sec_policy/:version/virtual_servers/:uuid

Create a Virtual Server object.

POST

[api_version][org_href]/sec_policy/:version/virtual_servers

Modify the enforcement mode, labels, and backend/source labels of a specified Virtual Server.

PUT

[api_version][org_href]/sec_policy/:version/virtual_servers/:uuid

Discovered Virtual Servers Methods

You can use only three GET methods for discovered virtual servers.

Functionality

HTTP

URI

Get a list of Discovered Virtual Servers.

GET

[api_version][org_href]/discovered _virtual_servers

Get a specified Discovered Virtual Server.

GET

[api_version][org_href]/discovered_ virtual_servers/:uuid

Discovery

GET

[api_version][org_href]/network_enforcement_nodes/ virtual_server_discovery_jobs/:uuid

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