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.

Update 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]

Request Properties

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
"`agent`" (VEN) properties hash:
`mode`	This property defines the policy state of the workload's VEN. There are three possible states: `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. The PCE provides insight into the data center 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`(deprecated)	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 fewer 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

This example shows what the JSON payload looks like for changing the policy state (called mode in the API) of a workload from its current state to enforced.

{"agent":{"config":{"mode":"enforced","log_traffic":true}}}

Curl Command to Update Workload

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.

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}}}'

Unpair 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.

URI to Unpair Workloads

PUT [api_version][org_href]/workloads/unpair

Request Body

Property Description Type Req

Property	Description	Type	Req
`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
`firewall_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

firewall_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"}
    ],
    "firewall_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"}], "firewall_restore": "default"}'

Mark Workload as Suspended

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

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 agent (the VEN) set 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"}}}'

Create an Unmanaged Workload

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
"`agent`" (VEN) properties hash:
`mode`	This property defines the policy state of the workload's VEN. There are three possible states: `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. The PCE provides insight into the data center 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`(deprecated)	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 fewer 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"}'

Delete a Workload Record

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]