Workload Bulk Operations

This Public Stable API supports “bulk” operations on collections of workloads. These operations create, update, or delete a collection of workloads using a single API call, instead of requiring separate API calls on individual workloads one at a time.

About Bulk Operations

When you use a bulk operations API to createa collection of workloads, a workload record is created in the PCE in the “unmanaged” state, which means that a VEN has not been installed on the workload and no policy can be applied to the workload. To apply a policy to unmanaged workloads, yu can do one of the following:

  • Pair the workloads using the pairing script located in the PCE web console

  • Install and activate the VEN on the workload using the VEN control interface.

When you use this API to update a collection of workloads, those workloads can be either managed or unmanaged.

When you use this API to delete a collection of workloads, those workloads can only be unmanaged.

Workload Bulk Operations Methods

Functionality HTTP URI
Create a collection of workloads PUT [api_version][org_href]/workloads/bulk_create
Update a collection of workloads PUT [api_version][org_href]/workloads/bulk_update
Delete a collection of workloads PUT [api_version][org_href]/workloads/bulk_delete

Caveats for Workload Bulk Operations

NOTE:

Bulk operations are rate limited to 1,000 items per operation.

Bulk operations are rate limited to 1,000 items per operation. When you create, update, or delete a collection of workloads (also referred to as “bulk” operations), you can only execute one such bulk operation at a time. This means you must wait for the first bulk operation to finish before executing a new one. If you execute a new bulk operation before the currently running operation has completed, the second operation will fail with an HTTP 429 error.

Additionally, when you perform a bulk workload operation, any policy changes caused by the operation are applied to the affected VENs after the next VEN heartbeat to the PCE.

After a bulk operation completes, all of your PCE VEN connectivity states show as Syncing until the next VEN heartbeat. Only affected VENs receive a policy update. VENs that are not affected by policy changes transition from Syncing to In Sync after the VENs heartbeat. This process can take up to 5 minutes.

External Data Reference IDs for Workloads

External data references are a way to add your own internal identifiers to new workloads, independent of Illumio PCE-created workload HREFs. You can add these entities when you create a collection of workloads using the bulk_create method, or when you create an individual workload using the public API.

External data references are useful if you want to keep a set of PCE resources in sync with your internal representation of the resources, such as a configuration management database (CMDB) that holds the “source of truth” for your workloads. Once workloads are created with these identifiers added to their properties, you can run an asynchronous query to get all workloads through an offline job, which includes the external data references in the response.

The schema for creating and updating External data references includes two properties:

  • external_data_set: Identifies the original data source of the resource.
  • external_data_reference: A unique identifier within that data source.

These properties are UTF-8 strings with a maximum length of 255 characters each. The contents must form a unique composite key, meaning that both values of these properties are treated as a unique key. These two properties together are recognized as a unique key even if one of them is left blank or set to zero.

Create a Collection of Workloads

URI to Create a Collection of Workloads

PUT [api_version][org_href]/workloads/bulk_create

Request Body

When you create a collection of workloads, you need to pass a JSON object request body that describes the workload details.

Although this example illustrates the request body for a single workload, you can add as many workloads as you want.

For example:


  {
    "name": "workload 0",
    "description": "workload desc 0",
    "service_principal_name": "spn 0",
    "hostname": "workload-0.example.com",
    "public_ip": "24.1.1.1",
    "external_data_set": "cmdb",
    "external_data_reference": "0",
    "interfaces": [
      {
        "name": "eth0",
        "link_state": "up",
        "address": "10.0.0.2",
        "cidr_block": 24,
        "ip_version": 4,
        "default_gateway_address": "10.0.0.1",
        "friendly_name": "wan"
      }
    ],
    "labels": [
      {
        "href": "/orgs/2/labels/1"
      },
      {
        "href": "/orgs/2/labels/9"
      }
    ],
    "service_provider": "service provider",
    "data_center": "central data center",
    "os_id": "os id 0",
    "os_detail": "os detail 0",
    "online": true,
    "agent": {
      "config": {
        "enforcement_mode": "full",
        "visibility_level": "flow_summary"
      }
    }
  }

Curl Command to Use Bulk Create

This curl example illustrates how to create two workloads using the bulk_create API.

curl -i -X PUT https://pce.my-company.com:8443/api/v2/orgs/2/workloads/bulk_create -H "Content-Type:application/json" -u $KEY:$TOKEN -d '[{"name":"web_app1","description":"workload desc 0","service_principal_name":"spn 0", "hostname":"workload-0.example.com","public_ip":"24.1.0.1","external_data_set":"cmdb", "external_data_reference":"0","interfaces":[{"name":"eth0","link_state":"up","address":"10.0.0.2", "cidr_block":24,"ip_version":4,"default_gateway_address":"10.0.0.1","friendly_name":"wan"}], "labels":[{"href":"/orgs/2/labels/1"},{"href":"/orgs/2/labels/9"}],"service_provider": "service provider","data_center":"central data center","os_id":"os id 0","os_detail":"os detail 0", "online":true,"agent":{"config":{"enforcement_mode":"visibility_only", "visibility_level":"flow_summary"}}}]

Update Collection of Workloads

This method allows you to update information about a collection of workloads. To update workload information, construct the JSON object for each workload exactly as you would for modifying one workload, but modify the properties as needed.

URI to Update a Collection of Workloads

PUT [api_version][org_href]/workloads/bulk_update

Curl Command to Bulk Update Workloads

This example shows how to update two workloads with the Bulk Update API.

curl -i -X PUT https://pce.my-company.com:8443/api/v2/orgs/2/workloads/bulk_update -H "Content-Type:application/json" -u $KEY:$TOKEN -d '[{"name":"web_app1","description":"workload desc 0","service_principal_name":”spn 0","hostname":"workload-0.example.com","public_ip":"24.1.2.1","external_data_set":"cmdb","external_data_reference":"0",”interfaces":[{"name":"eth0","link_state":"up","address":"10.0.0.2","cidr_block":24,“ip_version":4,"default_gateway_address":"10.0.0.1","friendly_name":"wan”}],”labels":[{"href":"/orgs/2/labels/1"},{"href":"/orgs/2/labels/9”}],”service_provider":"service provider","data_center":"central data center","os_id":"os id 0",”os_detail":"os detail 0","online":true,"agent":{"config":{"enforcement_mode":"visibility_only","visibility_level":"flow_summary"}}},{“name":"web_app2 0","description":"workload desc 0","service_principal_name":”spn 0","hostname":"workload-0.example.com","public_ip":"24.1.3.1",”external_data_set":"cmdb","external_data_reference":"0",”interfaces":[{"name":"eth0","link_state":"up","address":"10.0.0.2","cidr_block":24,”ip_version":4,"default_gateway_address":"10.0.0.1","friendly_name":"wan"}],”labels":[{"href":"/orgs/2/labels/1"},{"href":"/orgs/2/labels/9"}],”service_provider":"service provider","data_center":"central data center","os_id":"os id 0",”os_detail":"os detail 0","online":true,"agent":{"config":{"enforcement_mode":"full", ”visibility_level":"flow_summary"}}}]'

Delete a Collection of Workloads

You can use this Public Experimental API to delete a collection of unmanaged workloads.

When you call this method, you identify each unmanaged workload to delete by its HREF. For example:

/orgs/7/workloads/XXXXXXX-9611-44aa-ae06-fXXX8903db65

If an unmanaged workload has the following two properties: 

  • external_data_set=cmdb
  • external_data_reference=25

you can construct the HREF as a query parameter that matches the values of these two properties as they are defined on the target workload. For example: 

/orgs/1/workloads?external_data_set=cmdb&external_data_reference=25
NOTE:

Both query parameters must match for the exact same parameters on the workload for the delete operation to succeed.

URI to Delete a Collection of Workloads

PUT [api_version][org_href]/workloads/bulk_delete

Request Properties

Property Description Type Required
href The HREF of a specific workload or unmanaged workload using the external_data_set and external_data_reference query parameters. String Yes

Request Body

[
 {"href": "/orgs/1/workloads/92f4a252-68d1-40ef-8cf0-b46e4ec551r"},
 {"href": "/orgs/1/workloads/92f4a252-68d1-40ef-8cf0-b46e4ecd642ix"},
 {"href": "/orgs/1/workloads?external_data_set=cmdb&external_data_reference=25"},
 {href": "/orgs/1/workloads/92f4a252-74d1-40ef-5af0-b46a4acd333dt"}
]

Curl Command to Delete Collection of Workloads

curl -i -X PUT https://pce.my-company.com:8443/api/v2/orgs/3/workloads/bulk_delete -H "Accept: application/json" -u $KEY:$TOKEN '[{ "href": "/orgs/1/workloads/92f4a252-68d1-40ef-8cf0-b46e4ec551rse" },{"href": "/orgs/1/workloads/92f4a252-68d1-40ef-8cf0-b46e4ecd642ix" }, {"href": "/orgs/1/workloads/92f4a252-68d1-40ef-8cf0-b46e4ecd5421q" }, {"href": "/orgs/1/workloads/92f4a252-68d1-40ef-8cf0-b46e4ecd214dt" }, {"href": "/orgs/1/workloads/c20efa40-c615-4fa7-b8a1-badbadbadbad" },]'

Response

A successful response returns an HTTP 200 message and an array of status objects, one for each workload and each workload that failed to be deleted as requested. If all unmanaged workloads are successfully deleted, an empty array is returned.

For example, two errors are shown—one where the operation was not allowed (due to lack of permissions) and one where the workload did not exist. 

[
  {
    "href": "/orgs/1/workloads/c20efa40-c615-4fa7-b8a1-c3af4d34c5f5",
    "errors": [{"token": "method_not_allowed_error", "message": "Not allowed"}]
  },
  {
    "href": "/orgs/1/workloads/c20efa40-c615-4fa7-b8a1-badbadbadbad",
    "errors": [{"token": "not_found_error", "message": "Not found"}]
  }
]