Illumio Core REST API in 22.2.0

The Illumio Core REST API v2 has changed in 22.2.0 in the following ways.

New Public APIs

New Schema to Workload Notifications

Customers asked to be able to control when they get alerted about missing agents, as well as to have this control be separate from the policy offline timer. They might have a relatively high offline timer but a short warning threshold.

This change allows the customers to set explicit thresholds when they want a warning sent as well as its severity.

settings_workload_notifications.schema.json: This new schema has additional properties: info and error.

Here is the new schema part that defines warning and error:

["end_user_private_perm"]
	},
	"warning": {
	  "description": "Workload disconnect warning timeout",
	  "type": "integer",
	  "minimum": -1,
	  "maximum": 2147483647
	},
	"error": {
	  "description": "Workload disconnect error timeout",
	  "type": "integer",
	  "minimum": -1,
	  "maximum": 2147483647,
"expose_to": ["end_user_private_perm"]

Changed Public APIs

SAML Configuration Changes

GET /api/v2/authentication_settings_saml_config

Changes to this API apply to two properties, where issuer_url was deleted and replaced with the issuer property.

"properties": {
	"issuer": {
	description": "The URL for the Illumio login server. 
	Some identity providers might need this to establish the 
	identity of the service source requesting authentication.",
	"type": "string"

The two properties have the same meaning.

Reports Changes

The APIs for the endpoints

/api/v2/orgs/:xorg_id/report_schedules
/api/v2/orgs/:xorg_id/reports

have been changed for saved query explorer reports as follows:

GET /api/v2/report_schedules

This API has two new properties:

scheduled_at: which provides the timestamp to return the scheduled time.
send_by_email: which defines whether to send the report via email.

Here are the two new properties:

{
	"properties": {
	"scheduled_at": {
	  "description": "Timestamp in UTC for report generation",
	  "type": "string",
	  "format": "date-time"
	},
	"send_by_email": {
	  "description": "Flag for whether to send user report by email",
	  "type": "boolean"
	}
}

POST /api/v2/report_schedules

This API has three new properties:

send_by_email: defines whether to use email)
cheduled_at: timestamp for report generation at a specific time
report_generation_frequency: in addition to daily, weekly, monthly, and quarterly reports, you can schedule to receive the report only once.

Here are the new properties:

properties": {
	"send_by_email": {
	"description": "Flag for whether to send user report by email",
	"type": "boolean"
	},
	"scheduled_at": {
	"description": "Timestamp in UTC for report generation",
	"type": "string",
	"format": "date-time"
	},
	"report_generation_frequency": {
	"enum": [
	..............................
	"once"
	]
    ]
}

GET /api/v2/reports

and

POST /api/v2/reports

These two APIs have a new property send_by_email, which defines whether to use email for sending reports.

Here is the new property:

{
	"properties": {
	"send_by_email": {
	"description": "Flag for whether to send 
user report by email",
	"type": "boolean"
	}
}

Security Policy Changes

Enable or Disable Enforcement Boundaries

Security policy APIs have an additional property that enables or disables updating of a request executed against the specific enforcement boundary object. These changes provide an ability to enable/disable an enforcement boundary rule, which is used for troubleshooting and to add a baseline capability for pre-packaged boundary rules.

The following schema files are updated by adding a description for the new enabled boolean field.

/api/v2/orgs/:xorg_id/sec_policy/:version/enforcement_boundaries
/api/v2/orgs/:xorg_id/sec_policy/:version/enforcement_boundaries/:id

The only change is the additional enabled field in the response.

POST /api/v2/orgs/:xorg_id/sec_policy/:version/enforcement_boundaries

The optional enabled boolean field can be provided in the payload. If it is not provided, the newly created enforcement boundary object is enabled by default.

PUT /api/v2/orgs/:xorg_id/sec_policy/:version/enforcement_boundaries/:id

A single change to provide the optional boolean value for the enabled field in the payload is: "enabled": true

The new property enabled looks as follows:

{
	"properties": {
	"enabled": {
	"description": "Enabled flag",
	"type": "boolean"
	}
}

Settings Changes

settings_get.schema.json

settings_put.schema.json

These APIs have been changed so that a new property advanced_ruleset_display was added, which can display rulesets in advanced mode.

{
	"properties": {
	"advanced_ruleset_display": {
	"description": "When true, the UI will display rulesets 
in advanced mode. This means that scopes will be displayed 
for any unscoped rulesets, including newly added rulesets.",
		"type": "boolean",
		"default": true
		}
	}
}

settings_workloads_get.schema.json

settings_workloads_put.schema.json

These APIs have been changed so that a new property workload_disconnected_notification_seconds was added:

{
	"properties": {
	"workload_disconnected_notification_seconds": {
	"$ref": "settings_workload_notifications.schema.json"
	}
    }
}

Other Changed APIs

slbs_get.schema.json

A new property status was added, which describes the SLB status that can be error, pending connection, or active.

The SLB get_collection API can be filtered by the following:

name
description
has_virtual_server
status: this is a new property that can be active, pending, or error.
For the HA pair case, if either one device is in error, then the SLB has the status error. If neither device is in error and one device is pending, the SLB has the status pending. The SLB has the status active if neither device is in error or pending connection state.
device type - this is a dynamic list of values (requires facet API)

number of devices

{
	"properties": {
	"status: {
	"description": "Status of the SLB: error, pending 
connection, or active. In an HA pair, the status will be 
pending connection or error if either device is pending 
connection or error.",
	"type": "string"
	}
    }
}

resource_canonical_representations.schema.json

Three new properties have been added to describe LOG_INFO level notification, LOG_WARNING level notification, and LOG_ERR level notification for workloads going offline.

When a VEN does not contact the PCE within a set time interval, it is marked as being offline. Previously, before that happened, a notification was created when the VEN was AWOL (missing) for 25% of the offline time.

These three new optional settings generate different levels of notifications at different intervals so the user can customize the timing and levels of notification.

{
"oneOf": [
..........................................
	{
	"workload_setting": {
	"type": "object",
	"properties": {
	"workload_disconnected_timeout_seconds": 
{
	"description": "Disconnected timeout in seconds",
	"type": "integer"
	},
	"workload_goodbye_timeout_seconds": {
	"description": "Goodbye timeout in seconds",
	type": "integer"
	},
	"workload_disconnect_notification_info": {
	"description": "Threshold in seconds for LOG_INFO 
level notification of a workload going offline",
	"type": "integer"
	},
	"workload_disconnect_notification_warning": {
	"description": "Threshold in seconds for LOG_WARNING 
level notification of a workload going offline",
	"type": "integer"
	},
	"workload_disconnect_notification_error": {
	"description": "Threshold in seconds for LOG_ERR 
level notification of a workload going offline",
	"type": "integer"
	}
   }
}		
...........................................

Illumio Core What's New and Release Notes 22.2