Workload Operations

The Public Stable API for workloads allows you to perform workload operations, such as create an unmanaged workload, update workload information, unpair a workload, and delete a workload.

Managed vs. Unmanaged Workloads

A workload represents a single OS instance in your environment.

If no Illumio VEN is installed on the workload, it is considered to be an unmanaged workload.
A workload that has a VEN installed on it is called a managed workload. To "pair" a workload with the PCE, install the Illumio VEN on it so that the VEN can manage the workload's native host firewall. Only managed workloads can be unpaired.

Workloads API Methods

Workloads represent single OS instances in your environment.

Use the Workload API methods to manage individual workloads or workload collections, such as to list, create, update, unpair, and delete them, and to mark a VEN as suspended or unsuspended.

Workload Method	HTTP	URI
Get a collection of workloads	`GET`	`[api_version][org_href]/workloads`
Get an individual workload	`GET`	`[api_version][workload_href]`
Create an unmanaged workload	`POST`	`[api_version][org_href]/workloads`
Update workload information	`PUT`	`[api_version][workload_href]`
Unpair a workload	`PUT`	`[api_version][org_href]/workloads/unpair`
Mark a VEN as suspended or unsuspended	`PUT`	`[api_version][workload_href]`
Delete a workload record (unmanaged workloads only)	`DELETE`	`[api_version][workload_href]`

Getting Workloads

This API returns detailed information about a single workload or a collection of workloads.

By default, the maximum number of workloads returned in a GET collection of workloads is 500. If you want to get more than 500 workloads, use an Asynchronous GET Collection.

URI to Get a Collection of Workloads

GET [api_version][org_href]/workloads

When you get a collection of workloads, none of the services running on the workloads is returned because a workload could have dozens of services running, and if you have thousands of workloads, this could cause performance issues with the PCE. However, when you get one workload, all of that workload's services are returned.

URI to Get a Single Workload

GET [api_version][workload_href]

Query Parameters

All query parameters for filtering the workload information are optional except for the org_id, or the ID of the organization which you are searching to get a collection of workloads or a single workload.

Parameter	Description	Type
`container_clusters`	List of container cluster URIs, encoded as a JSON string	string
`description`	Description of workloads to return. Supports partial matches.	String
`external_data_reference`	A unique identifier within the external data source. For example, if this workload's information is stored in an external database.	String
`external_data_set`	The data source from which the resource originates. For example, if this workload's information is stored in an external database.	String
`hostname`	Hostnames of workloads to return. Supports partial matches.	String
`include_deleted`	Include unmanaged workloads that have been deleted as a result of being unpaired.	Boolean
`ip_address`	IP addresses of workloads to return. Supports partial matches.	String
`labels`	Include a list of lists of label URIs, encoded as a JSON string. Filtering workloads using the “labels” query parameter returns different results depending on how you construct the query parameter as a JSON array. If you define the `labels` query parameter as two JSON arrays when you perform a GET: `GET /workloads?labels=[["/orgs/1/labels/123"],["/orgs/1/labels/124"]]` The PCE interprets this as either `"/orgs/1/labels/123`" OR "`/orgs/1/labels/124`'. In other words, it will perform an OR operation. However, if you define the `labels` query parameter as a single JSON array when you perform a GET: `GET /workloads?labels=[["/orgs/1/labels/123","/orgs/1/labels/124"]]` The PCE interprets this as both `/orgs/1/labels/123` AND `/orgs/1/labels/123`. (That is, the workload needs to have both labels present). In other words, it will perform an AND operation. `GET /workloads?labels=[["/orgs/1/labels/123","/orgs/1/labels/124"],["/orgs/1/labels/125","/orgs/1/labels/126"]]` means find workloads with labels 123 and 124 or labels 125 and 126. Get a workload without a label of type Role: `GET /workloads?labels= [[ "/orgs/:org_id/labels/1", "/orgs/:org_id/labels/2", "/orgs/:org_id/labels?key=role&exists=false"]]` Request all workloads with label 1 and label 2 (assuming that /api/v1/orgs/:org_id/labels/1 is a label with key 'env' and /api/v1/orgs/:org_id/labels/2 is a label with key 'loc') and any app label and no role label.	String
`last_heartbeat_on[lte]` `last_heartbeat_on[gte]`	Search for workloads whose last heartbeat to the PCE occurred before or after a specific point in time, or during a time range, using these two parameters: `[lte]`: Less than or equal to. `[gte]`: Greater than or equal to. When the `last_heartbeat_on` filter is used, `GET /workloads` returns only local region workloads. If you don't include the filter, the API still returns all workloads. In this example, you can get all workloads whose last heartbeat to the PCE was before May 25, 2018, at 8:00 pm: `GET [api_version][org_href]/workloads?last_heartbeat_on[lte]=2018-05-25T19:20:00+02:00` You can easily change the same query to '`[gte]`' to get all workloads whose last heartbeat to the PCE was after May 25th, 2018 at 8:00 pm: `GET [api_version][org_href]/workloads?last_heartbeat_on[gte]=2018-05-25T19:20:00+02:00` You can also combine the two parameters to specify a date range. For example, you want to get all workloads whose last heartbeat was sent between April 25th and May 25th: `GET [api_version][org_href]/workloads?last_heartbeat_on[lte]=2018-04-25T19:20:00+02:00&[gte]=2018-04-25T19:20:00+02:00`	String (Timestamp in RFC 3339)
`log_traffic` (deprecated)	If set to true, includes logged traffic for the workload	Boolean
`managed`	When set to false, the GET collection returns unmanaged workloads (no VEN installed). When 'managed' query parameter is not used, both managed and unmanaged workloads are returned.	String
`max_results`	The maximum number of results you want to return when using the GET method. The maximum limit for returned workloads is 500.	Integer
`mode`	The policy state of the workload: `idle`: A state in which the VEN does not take control of the workload’s iptables (Linux) or Windows firewall (Windows), but rather provides the PCE relevant details about the workload, such as the workload IP address, operating system, and geographical location. `iIlluminated`: The Illuminated policy state has two variations: Build and Test. Build is a state in which the VEN introspects all open ports on a workload and reports the flow of traffic between it and other workloads to the PCE. The PCE displays the flow of traffic to and from the workload, providing insight into the datacenter and the applications running in it. No traffic is blocked in this state. Test is a state which allows you to apply all rules and visualize all of the traffic that would be blocked if you placed the workloads into the Enforced policy state. No traffic is blocked in this state. `enforced`: A state in which all rule definitions and restrictions are enacted on the workload.	String
`name`	Names of workloads to return. Supports partial matches.	String
`online`	Get a collection of either online or offline workloads: Online workloads are connected to the network and can communicate with the PCE. (`?online=true`) Offline workload are not connected to the network and cannot communicate with the PCE. (`?online=false`)	Boolean
`os_id`	Operating systems of workloads to return. Supports partial matches	String
`policy_health`	Health policy of workloads to return. In the PCE web console, this is referred to as VEN health, which relates to the current state of VEN connectivity, the most recently provisioned policy changes that affect the workload, any unwanted changed to the workload's firewall settings, and any issues related to SecureConnect functionality. Valid values: `active`: The most recent policy provisioning was successful, no unwanted changes to the workload's firewall have been reported, and none of the SecureConnect connections are in an erroneous state (if configured). `warning`: At least one of SecureConnect connection is in an erroneous state, and either the most recent policy provisioning was successful or no unwanted changes to the workload's firewall have been reported. `error`: The most recent policy provisioning has failed or unwanted changes to the workload's firewall has been reported. SecureConnect status does not apply to this state. `suspended`: Returns those workloads with suspended VENs. This parameter can also be used with `max_results`.	String
`security_policy_sync_state`	Gets a collection of workloads based on their current policy sync state of staged. `staged`: Policy update has been scheduled for the workload but has not yet been applied. Requires a query parameter with a value of "true." Examples: `GET /workloads?staged=true` `GET /workloads/{workload_id}?staged=true`	String
`security_policy_update_mode`	Allows you to search workloads by the type of Policy Update mode, either static or adaptive: `static`: Apply policy change immediately when provisioning. `adaptive`: Stage but to not apply provisioned changes until a later time.	String
`soft_deleted`	DEPRECATED WITH NO REPLACEMENT: Only soft-deleted workloads	Boolean

Curl Command to Get Collection of Workloads

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/7/workloads -H "Accept: application/json" -u $KEY:$TOKEN

Response Body

Each workload returned has a unique URI in the form of the HREF path property. For example: href: "/orgs/2/workoads/3063". You can use the workload HREF if you want to get, or update, information for a single workload.

The response for getting a collection of workloads is the same as for getting a single workload, except that the call returns all of the workloads in an organization.

NOTE:

When you get a collection of workloads, none of the running services on the collection of workloads is returned. The reason for this is that given that some workloads can have many services running, and your PCE could have thousand of workloads, getting all services for all workloads could impact the performance of the PCE.

However, a workload's services are returned when you get an individual workload instance.

Curl Command to Get a Single Workload

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/7/workloads/xxxxx6cf-25b6-4af5-9b97-e6ec2ebe7e18 -H "Accept: application/json" -u $KEY:$TOKEN

Response Body - Managed Workload

This example shows the response of a managed workload. The workload has a VEN installed on it and is paired with the PCE. The VEN is represented by the workload property named agent with the sub-property href. If there is no HREF path defined for the workload agent property, then no VEN is installed, and the workload is an unmanaged workload.

In the response, the "services" property is empty {} on a GET collection (this is for performance reasons, given the high number of services that can run on a workload). Also, this example shows the response for getting a single instance of a workload, but in a mass collection, you would see multiple workloads.

Curl Command to Get an Unmanaged Workload

curl -i -X GET 'https://pce.my-company.com:8443/api/v2/orgs/7/workloads?managed=false&max_results=1' -H "Accept: application/json" -u $KEY:$TOKEN

GET response bodies return vulnerability summary information, detected vulnerabilities, and the vulnerability report for each workload.

{
    "href": "/orgs/2/workloads/3e3e17ce-XXXX-42b4-XXXX-1d4d3328b342",
    "deleted": false,
    "name": standalone_dev,
    "description": null,
    "hostname": "hrm-db-prod1",
    "service_principal_name": null,
    "public_ip": "192.0.2.10",
    "distinguished_name": null,
    "external_data_set": null,
    "external_data_reference": null,
    "interfaces": [
      {
        "name": "eth0",
        "cidr_block": 24,
        "link_state": null,
        "network_detection_mode": "single_private_brn",
        "friendly_name": null,
        "network": {
          "href": "/orgs/1/networks/xxxxxxxx-183d-4f36-90b3-9885eb271ecb"
        },
        "address": "xxx.0.243.1",
        "default_gateway_address": "xxx.0.0.1"
      }
    ]
    "ignored_interface_names": [],
    "service_provider": null,
    "data_center": null,
    "data_center_zone": null,
    "os_id": null,
    "os_detail": null,
    "online": true,
    "labels": [
      {"href": "/orgs/1/labels/205"},
      {"href": "/orgs/1/labels/20"},
      {"href": "/orgs/1/labels/21"},
      {"href": "/orgs/1/labels/202"}
    ],
    "services": {},
        "vulnerabilities_summary": {
      "num_vulnerabilities": 0,
      "vulnerable_port_exposure": null,
      "vulnerable_port_wide_exposure": {
        "any": null,
        "ip_list": null
      },
      "vulnerability_exposure_score": null,
      "vulnerability_score": 0,
      "max_vulnerability_score": 0
    },
    "detected_vulnerabilities": [
      {
        "ip_address": "string",
        "port": 0,
        "proto": 0,
        "port_exposure": null,
        "port_wide_exposure": {
          "any": null,
          "ip_list": null
        },
        "workload": {
          "href": "string"
        },
        "vulnerability": {
          "href": "string",
          "score": 0,
          "name": "string"
        },
        "vulnerability_report": {
          "href": "string"
         }
       }
    ]
..........................
},

Response Body - Unmanaged Workload

This example shows the response of an unmanaged workload, which means the workload does not have a VEN installed on it, and the workload has not been paired with the PCE.

Curl Command to Get a Managed Workload

curl -i -X GET 'https://pce.my-company.com:8443/api/v2/orgs/7/workloads?managed=true&max_results=1' -H "Accept: application/json" -u $KEY:$TOKEN

GET response bodies return vulnerability summary information, detected vulnerabilities, and the vulnerability report for each workload.

[
   {
    "href": "/orgs/7/workloads/aed3b241-0098-4ac4-bb26-222e247060e5",
    "deleted": false,
    "name": "web-2050-dev0",
    "description": null,
    "hostname": "web-2050-dev0",
    "service_principal_name": null,
    "public_ip": "10.10.10.10",
    "external_data_set": null,
    "external_data_reference": null,
    "interfaces": [],
    "ignored_interface_names": [],
    "service_provider": null,
    "data_center": "usa",
    "data_center_zone": null,
    "os_id": "linux",
    "os_detail": null,
    "online": true,
    "labels": [
      {"href": "/orgs/7/labels/82"},
      {"href": "/orgs/7/labels/100"},
      {"href": "/orgs/7/labels/88"},
      {"href": "/orgs/7/labels/92"}
    ],
    "services": {},
    "vulnerabilities_summary": {
      "num_vulnerabilities": 0,
      "vulnerable_port_exposure": null,
      "vulnerable_port_wide_exposure": {
        "any": null,
        "ip_list": null
      },
      "vulnerability_exposure_score": null,
      "vulnerability_score": 0,
      "max_vulnerability_score": 0
    },
    "detected_vulnerabilities": [
      {
        "ip_address": "string",
        "port": 0,
        "proto": 0,
        "port_exposure": null,
        "port_wide_exposure": {
          "any": null,
          "ip_list": null
        },
        "workload": {
          "href": "string"
        },
        "vulnerability": {
          "href": "string",
          "score": 0,
          "name": "string"
        },
        "vulnerability_report": {
          "href": "string"
        }
      }
    ],
.................

Curl Command to Get Workloads with a Specific Label

To get a collection of workloads that have a specific label applied to them, you can take a label string that was returned when you got a collection of workloads, and then add a query parameter to GET all workloads with that specific label.

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/2/workloads?labels="[[/orgs/2/labels/1642]]" -H "Accept: application/json" -u $KEY:$TOKEN

This returns all workloads that have the specified label.

Curl Command Using Other Query Parameters

You can also use query parameters to restrict the type of workloads you want returned and set a limit on how many results you want returned.

For example, you might want to get a collection of no more than 50 workloads running CentOS 6.3 that are in the policy state (mode) of enforced.

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/2/workloads?os_id=centos-x86_64-6.3&max_results=50&mode=enforced -H "Accept: application/json" -u $KEY:$TOKEN

Creating Unmanaged Workloads

The Unmanaged Workload API enables you to create a workload without installing the VEN on it. This API is commonly used if you are using Kerberos authentication between the VEN and the PCE.

URI to Create an Unmanaged Workload

POST [api_version][org_href]/workloads

Request Body

Property	Description	Type	Required
`name`	Short, friendly name of the workload.	String	Yes
`description`	Long description of the workload.	String	No
`external_data_set`	An external data set identifier. For example, if this workload information is stored in an external database.	String	No
`external_data_reference`	An external data set reference path. For example, if this workload information is stored in an external database.	String	No
`hostname`	The hostname reported by the workload.	String	Yes
`service_principal_name`	The Kerberos Service Principal Name (SPN). This property is only relevant if you have configured Kerberos in your environment to authenticate VEN-to-PCE communication.	String	No
`distinguished_name`	The X.509 Subject distinguished name, used if you want this workload to use machine authentication between VENs and other hosts. NOTE: This property has an API exposure level of Public Experimental, which means it is not intended for production use and might change in future releases. For more information, see API Classification and Version.	String	No
`public_ip`	The public IP address of the workload.	String	No
`interfaces`	List of all functioning network interfaces on the workload. Properties for workload network interfaces: `name`: The interface name with a string data type `link state`: The state of the interface connection with a string data type; one of three values: `up`: Interface is communicating. `down`: Interface is not communicating. `unknown`: State of the interface is unknown. `address`: The IP address assigned to the interface with a string data type `cidr_block`: The number of bits in the subnet (for example, /24 is 255.255.255.0) with an integer data type `default_gateway_address`: The default IP address of the default gateway, either IPv4 or IPv6 with an integer data type `friendly_name`: The friendly name given to the interface with a string data type	Array	No
`service_provider`	Name of the service provider that is hosting the workload.	String	No
`data_center`	The name of the data center where the workload is being hosted.
`data_center_zone`	The zone inside the data center hosting the workload.	String	No
`os_id`	Unique OS identifier given by Illumio to the workload.	String	No
`os_detail`	Additional descriptive information about the workload OS	String	No
`online`	Indicates whether the workload is online and can communicate with the PCE.	Boolean.	No
`labels`	Labels that are attached to the workload.	Array.	No
VEN properties hash:
`mode`	This property defines one of the three policy states of the VEN: `idle`: A state in which the VEN does not take control of the workload’s iptables (Linux) or Windows firewall (Windows), but rather provides the PCE relevant details about the workload, such as the workload IP address, operating system, and geographical location. `illuminated`: The Illuminated policy state has two variations: Build and Test (configurable in the PCE web console): Build is a state in which the VEN introspects all open ports on a workload and reports the flow of traffic between it and other workloads to the PCE. In this state, the PCE displays the flow of traffic to and from the workload, providing insight into the datacenter and the applications running in it. No traffic is blocked in this state. Test is a state which allows you to apply all rules and visualize all the traffic that would be blocked if you placed the workloads into the enforced policy state. No traffic is blocked in this state. `enforced`: A state in which all rules definitions and restrictions are enforced.	String	No
`log_traffic`	If set to True, then traffic flows from the VEN are logged.	Boolean	No
`visibility_level`	The amount of data the VEN collects and reports to the PCE from a workload in the enforced mode (policy state), so you can control resource demands on workloads. The higher levels of detail are useful for visualizing traffic flows in the Illumination map inside the PCE web console. If this parameter is not set, then VEN visibility level is set to `flow_summary`. `flow_summary`: (“High Detail” in the PCE web console) The VEN collects traffic connection details (source IP, destination IP, protocol, and source and destination port) for both allowed and blocked connections. This option creates traffic links in the Illumination map and is typically used during the building and testing phase of your security policy. `flow_drops`: (“Less Detail” in the PCE web console.) The VEN only collects traffic connection details (source IP, destination IP, protocol, and source and destination port) for blocked connections. This option provides less detail for Illumination but demands less system resources from a workload and is typically used for policy enforcement. `flow_off`: (“No Detail” in the PCE web console.) The VEN does not collect any details about traffic connections. This option provides no Illumination detail and demands the least amount of resources from workloads. This mode is useful when you are satisfied with the rules that have been created and do not need additional overhead from observing workload communication.

Example Payload

For example, to create an unmanaged workload by providing a name, hostname, public IP address, and its Kerberos Service Principal Name, construct the JSON payload as follows:

{      "name":"web_tier1", 
     "hostname":"web_workload1.example.com", 
     "public_ip":"10.10.10.10",     
"service_principal_name":"my_company-device-auth/web_workload1.example.com", 
}

Curl Command to Create Unmanaged Workload

curl -i -X POST https://pce.my-company.com:8443/api/v2/orgs/4/workloads -H "Content-Type: application/json" -u $KEY:$TOKEN -d '{"name":"web_tier1", "hostname":"web_workload1.example.com","public_ip": "10.10.10.10","service_principal_name":"my_company-device-auth/web_workload1.example.com"}'

Updating Workload Information

This API allows you to update information about a workload. To make this call, you need the URI of the workload you want to update, which is returned in the form of an HREF path when you get either a single or a collection of workloads in an organization.

URI to Update an Individual Workload's Information

PUT [api_version][workload_href]

The workloads_put.schema has the referenced schema files already included in the build, and only a few fields are added or deleted. There are two referenced schema files that are used to validate the input. Choose the appropriate file based on the state of the workload being updated:

When invoked on an unmanaged workload, use workloads_without_ven_put.
When invoked on a managed workload, use workloads_with_ven_put.

Curl Commands to Update Workloads

A workload state can be build, test, or enforced. This example shows how to use curl to update a workload policy state from its current state to enforced.

This example assumes that you want to update the state of a single workload in an organization. You can obtain an organization ID when you use the Users API to log in a user to Illumio.

Update a workload with VEN

This curl command to update the mode is relevant for a managed workload (with VEN). In the agent section, it defiunes the configuration as {"config":{"mode":"enforced","log_traffic":true}.

curl -i -X PUT https://pce.my-company.com/api/v2/orgs/3/workloads/043902c883d133fa -H "Content-Type:application/json" -u $KEY:$TOKEN -d '{"agent":{"config":{"mode":"enforced","log_traffic":true}}}'

Update a workload without VEN

This curl command the is for an unmanaged workload,workload_without_ven_put. The added field is interfaces, for which you can construct a request body like the following: {"interfaces": [{"name": "eth0", "link_state": "up", "address": "10.1.3.42", "cidr_block": 24, "default_gateway_address": "10.1.3.1"}]}.

curl -i -X PUT https://pce.my-company.com/api/v2/orgs/3/workloads/043902c883d133fa -H "Content-Type:application/json" -u $KEY:$TOKEN -d '{"interfaces": [{"name": "eth0", "link_state": "up", "address": "10.1.3.42", "cidr_block": 24, "default_gateway_address": "10.1.3.1"}]}'

Unpairing Workloads

This API allows you to unpair workloads from the PCE by uninstalling the Illumio VEN from each workload. You can unpair up to 1,000 workloads at a time.

Pairing a workload installs the Illumio VEN on a workload. Unpairing a workload uninstalls the VEN from the workload so that the workload no longer reports any information to the PCE and the workload can no longer receive any policy information.

When you unpair workloads with this API, you can set the state for the workloadʼs iptables (Linux) or WFP (Windows) configuration.

NOTE:
Instead of unpairing or suspending a workload, use the new VEN API as explained in Curl Commands for Unpairing and Suspending VENs

URI to Unpair Workloads

PUT [api_version][org_href]/workloads/unpair

Request Body

Property Description Type Required

Property	Description	Type	Required
`workloads`	Defines the list of workloads you want to unpair. You must specify at least one workload to unpair by defining the workload HREF. You can define up to 1,000 workloads to unpair with this API.	Array	Yes
`href`	URI of the workload to unpair.	String	Yes
`ip_table_restore`	This property allows you to determine the state of the workload iptables (Linux) or WFP (Windows) configuration after the workload is unpaired. Options include: `saved`: Revert the iptables on the workload to the configuration before the VEN was installed. However, depending on how old the iptables or WFP configuration was on the workload, VEN removal could adversely impact security. `default`: Apply the recommended policy, which is to uninstall the VEN and allow only port 22 SSH connections to the workload. Safest from a security viewpoint, but if this workload is running a production application, it could break because this workload will no longer allow any connections to it. `disable`: Uninstall the VEN and leave all port connections on the workload open. This is the least safe from a security viewpoint. If iptables or WFP configuration or Illumio were the only security being used for this workload, the workload would be opened up to anyone and become vulnerable to attack.	String	Yes

workloads

Defines the list of workloads you want to unpair. You must specify at least one workload to unpair by defining the workload HREF. You can define up to 1,000 workloads to unpair with this API.

Array

Yes

href URI of the workload to unpair. String Yes

ip_table_restore

This property allows you to determine the state of the workload iptables (Linux) or WFP (Windows) configuration after the workload is unpaired.

Options include:

saved: Revert the iptables on the workload to the configuration before the VEN was installed. However, depending on how old the iptables or WFP configuration was on the workload, VEN removal could adversely impact security.
default: Apply the recommended policy, which is to uninstall the VEN and allow only port 22 SSH connections to the workload. Safest from a security viewpoint, but if this workload is running a production application, it could break because this workload will no longer allow any connections to it.
disable: Uninstall the VEN and leave all port connections on the workload open. This is the least safe from a security viewpoint. If iptables or WFP configuration or Illumio were the only security being used for this workload, the workload would be opened up to anyone and become vulnerable to attack.

String

Yes

Example Payload for Unpairing Workloads

{
    "workloads": [
      {"href":"/orgs/7/workloads/XXXXXXXx-9611-44aa-ae06-fXXX8903db65"},
      {"href":"/orgs/7/workloads/xxxxxxxx-9611-xxxx-ae06-f7bXXX03db71"}
    ],
    "ip_table_restore":"saved"
 }

Curl Command for Unpairing Workload

curl -i -X PUT https://pce.my-company.com/api/v2/orgs/3/workloads/unpair -H "Content-Type:application/json" -u $KEY:$TOKEN -d '{"workloads": [{"href": "/orgs/7/workloads/xxxxxxxx-9611-44aa-ae06-fXXX8903db65", "href": "/orgs/7/workloads/xxxxxxxx-9611-xxxx-ae06-f7bXXX03db71"}], "ip_table_restore": "default"}'

Marking Workload VENs as Suspended

You can use this API to mark a workload VEN as either suspended or unsuspended.

NOTE:
Instead of unpairing or suspending a workload, use the new VEN API as explained in Curl Commands for Unpairing and Suspending VENs

URI to Mark a Workload VEN as Suspended or Unsuspended

PUT [api_version][workload_href]

Example Payload

This example shows what the JSON payload looks like for marking a workload VEN as suspended, with the status property for the agentset to suspended.

NOTE:

To mark a workload VEN as unsuspended, use the same JSON body but replace suspend with unsuspend.

{
  "agent": {    
    "status": {
      "status": "suspended"
    }
  }
}

Curl Command to Mark Workload as Suspended

This example shows you how to use curl to mark a workload VEN as suspended.

This example assumes that you want to mark a single workload VEN as suspended. You can obtain an organization ID when you use the Users API to log in a user to Illumio.

curl -i -X PUT https://pce.my-company.com/api/v2/orgs/3/workloads/043902c883d133 -H "Content-Type:application/json" -u $KEY:$TOKEN -d '{"agent":{"status":{"status":"suspended"}}}'

Deleting Workload Records

If you have unpaired a workload, you can use this API to delete the workload's record from the PCE.

URI to Delete a Workload Record

DELETE [api_version][workload_href]