Overview of VEN Suspension
The VEN Update API (PUT [api-version][ven-href]) allows you to mark a VEN as either suspended or unsuspended in the PCE. It does not, however, actually suspend or unsuspend the VEN.
To suspend a VEN, use the illumio-ven-ctl command-line tool, which isolates a VEN on a workload so that you can troubleshoot issues and determine if the VEN is the cause of any anomalous behavior.
When you suspend a VEN, the VEN informs the PCE that it is in suspended mode.
However, if the PCE does not receive this notification, you must mark the VEN as "Suspended" in the PCE web console (select the VEN and click Edit), or you can use this API to mark the VEN as suspended.
When you don't mark the VEN as suspended in the PCE, after one hour, the PCE assumes that the workload is offline and removes it from the policy. When you mark the VEN as suspended, that VEN’s workload is still included in the policy of other workloads.
When a VEN is suspended:
- The VEN still appears in the PCE in the VEN list page.
- The VEN's host cannot be unpaired.
- An organization event (
server_suspended) is logged. This event is exportable to CEF/LEEF and has the severity of WARNING. -
Heartbeats or other communications are not expected, but when received, all communications are logged by the PCE.
-
If the PCE is rebooted, the VEN remains suspended.
-
Any custom iptables rules are removed, and you need to reconfigure them manually.
When a VEN is unsuspended:
- The PCE is informed that the VEN is no longer suspended and is able to receive policy from the PCE. If existing rules affect the unsuspended workload, the PCE reprograms those rules.
- An organization event (
server_unsuspended) is logged. This event is exportable to CEF/LEEF and has the severity of WARNING. - The workload reverts to the policy state it had before it was suspended.
- Custom iptables rules are configured back into the iptables.
VEN API Methods
In addition to a new page in the PCE web console that lists all VENs and shows the details of a single VEN, Illumio Core includes a Public Experimental API for getting VEN collections and VEN instances. Other new APIs support VEN filtering in the PCE web console, and update and unpair VENs.
| VEN Methods | HTTP and URI |
|---|---|
| Get the collection of all VENs |
|
| Get details on a VEN instance | GET [api_version][org_href]/vens/ven_id
|
| Support VEN filtering in the PCE web console | GET [api_version][org_href]/vens/autocomplete
|
|
To set the |
PUT [api_version][org_href]/vens/ven_id
|
| Update a VEN |
|
|
Unpair a VEN: trigger the unpairing of one or more VENs Uses the same schema as |
|
Query Parameters for GET
The Organization ID (xorg_id) is required, and the other query parameters are optional.
| Parameter | Description | Type |
|---|---|---|
name
|
Name of VEN(s) to return. Supports partial matches. | String |
hostname
|
Hostname of VEN(s) to return. Supports partial matches. | String |
description
|
Description of VEN(s) to return. Supports partial matches | |
os_id
|
Operating System of workload(s) to return. Supports partial matches. | String |
version
|
The release version that the VEN is using. Supports partial matches | String |
status
|
The current status of the VEN. Options are: "active", "suspended", "uninstalled" | String |
activation_type
|
The method by which the VEN was activated. Options are: "pairing_key", "kerberos", "certificate" | String |
active_pce_fqdn
|
The FQDN of the PCE that the VEN last connected to | String |
target_pce_fqdn
|
The FQDN of the PCE that the VEN uses for future connections | String |
labels
|
2D Array of label URIs, encoded as a JSON string version 20.1.0. |
String |
ip_address
|
IP address of VEN(s) to return. Supports partial matches | String |
container_cluster
|
Array of container cluster URIs, encoded as a JSON string | String |
last_heartbeat_at
|
Timestamp of the VENs last heartbeat. Using this filter will result in region-specific VENs only. | Hash |
last_hearbeat_at[gte]
|
Greater than or equal to value for last heartbeat timestamp | Null |
last_hearbeat_at[lte]
|
Less than or equal to value for last heartbeat timestamp | Null |
last_goodbye_at
|
Timestamp of the VENs last goodbye | Hash |
last_goodbye_at[gte]
|
Greater than or equal to value for last goodbye at timestamp | Null |
last_goodbye_at[lte]
|
Greater than or equal to value for last goodbye at timestamp | Null |
max_results
|
Maximum number of VENs to return. | Integer |
Curl Commands for Getting VENs
To get a collection of VENs that have a specific label applied to them, take a label string that was returned when you got a collection of VENs, and then add a query parameter to GET all VENs with that specific label.
Curl Command to Get VENs with a Specific Label
curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/2/vens?labels="[[/orgs/2/labels/1642]]" -H "Accept: application/json" -u $KEY:$TOKEN
To restrict the type of VENs you want returned and set a limit on how many results you want returned, use the relevant query parameters. For example, you might want to get a collection of no more than 50 VENs running CentOS 6.3 that have an active status.
Curl Command to Get VENs using other Query Parameters
curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/2/vens?os_id=centos-x86_64-6.3&max_results=50&status=active -H "Accept: application/json"-u $KEY:$TOKENCurl Commands for Unpairing and Suspending VENs
Instead of unpairing and suspending workloads, use the new VEN APIs to unpair and suspend VENs.
Curl Command for Unpairing VENs
curl -i -X PUT https://pce.my-company.com/api/v2/orgs/3/vens/unpair -H "Content -Type:application/json" -u $KEY:$TOKEN -d '{"vens": [{"href": "/orgs/7/vens/xxxxxxxx-9611-44aa-ae06-fXXX8903db65"}, {"href": "/orgs/7/vens/xxxxxxxx-9611-xxxx-ae06-f7bXXX03db71"}], "firewall_restore": "default"}'Curl Command to Mark VEN as Suspended
curl -i -X PUT https://pce.my-company.com/api/v2/orgs/3/vens/xxxxxxxx-9611-xxxx-ae06-f7bXXX03db71 -H "Content-Type:application/json" -u $KEY:$TOKEN -d'{"status":"suspended"}'