REST APIs for 23.5

Bulk operations are rate-limited to 1,000 items per operation. When you create, update, or delete a collection of workloads (also called “bulk” operations), you can only execute one such 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 been 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 unaffected by policy changes transition from Syncing to In Sync after the VENs heartbeat. This process can take up to 5 minutes.

External data references can 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 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:

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. Together, these two properties are recognized as unique keys, even if one of them is left blank or set to zero.

URI to Create a Collection of Workloads

PUT [api_version][org_href]/workloads/bulk_create

Request Body

When creating a collection of workloads, you must pass a JSON object request body that describes the workload details.

This example illustrates the request body for a single managed 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"}}}] 

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

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:

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

URI to Delete a Collection of Workloads

PUT [api_version][org_href]/workloads/bulk_delete

Request Properties

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 one 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"}]
  }
]

This new API is used to update workloads using a CSV file, and the only allowed input type is 'text/csv'.

We recommend users to export a CSV file from the workloads page before they use this import function, so that they can just modify the CSV file they exported with the labels they would like to assign to the workloads.