Workload Settings

This Public Stable API lets you get network interface information from a workload for all interfaces on a workload or an individual interface. You can also configure (create) or delete a network interface configuration.

Workload Settings Methods

Functionality	HTTP	URI
Get agent timeout notifications.	`GET`	`[api_version][org_href]/settings/workloads`
Update agent timeout notifications.	`PUT`	`[api_version][org_href]/settings/workloads`

Endpoint Offline Timer

The Endpoint Offline Timer was introduced to overcome the 24-hour limitation that was hard-coded for the endpoint's heartbeating.

If the endpoints did not heartbeat for 24 hours, they were marked as offline, and the endpoint timer was hard-coded to 24 hours. However, the 24-hour limit was found to be limiting, so it was adjusted to allow for endpoint mobility and usability.

The existing two APIs have been changed:

GET /api/v2/orgs/:xorg_id/settings/workloads: Added properties to reflect the endpoint timeout values: disconnect.
PUT /api/v2/orgs/:xorg_id/settings/workloads: Updated offline endpoint, heartbeat, disconnect, and quarantine warning timeout values.

The three workload timeout setting fields have been updated:

Workload Timeout Setting Fields

Field	Description	Required
`workload_disconnected_ timeout_seconds`	Timer setting triggered if the server or endpoint has not heartbeaten to the PCE. Referencing the schema `settings_workload_detailed.schema.json`	Yes
`workload_goodbye_timeout_seconds`	The timer setting is triggered if the server or endpoint operation is performed (stop, disable, etc.). Referencing the schema `settings_workload_detailed.schema.json`	Yes
`workload_disconnected_ notification_seconds`	Period to wait with no heartbeat before a warning is emitted. Referencing the schema `settings_workload_notifications.schema.json`	Yes
`ven_uninstall_timeout_hours`	Defines the period (in hours) to wait before uninstalling a VEN. Referencing the schema `settings_workload.schema.json`	Yes

Schemas that Support the Endpoint Offline Timer

settings_workload_notifications

This schema file was updated and now has an additional property ven_type to support the VEN type by the referenced timeout fields.

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"type": "array",
	"items": {
		"type": "object",
		"additionalPropertes": false,
		"required": [
			"scope",
			"warning"
		],
		"properties": {
			"scope": {
			"$ref": "labels.schema.json"
		},
		"warning": {
		"description": "Workload disconnect warning timeout",
		"type": "integer",
			"minimum": -1,
			"maximum": 2147483647
		},
		"ven_type": {
		"description": "The ven type that this property is applicable to",
		"type": [
			"string",
			"null"
		],"enum": [
			"server",
			"endpoint"
		]
	   }
	}
   },
	"uniqueitems": true
}

settings_workload_detailed

The new schema settings_workload_detailed is expanded from the previous schema settings_workload so that additional information about the ven_type was added.

To ensure backend compatibility, the new field ven_type is specified as optional. If it is missing in the request, the parameter is considered to be of a server type.

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"type": "array",
	"items": {
		"type": "object",
		"additionalProperties": false,
		"required": [
			"scope",
			"value"
		],
		"properties": {
			"scope": {
			"$ref": "labels.schema.json"
		},
		"value": {
		"description": "Property value associated with the scope",
		"type": "integer",
			"minimum": -1,
			"maximum": 2147483647
		},
		"ven_type": {
		"description": "The ven type that this property is applicable to",
		"type": [
			"string",
			"null"
			],
		"enum": [
			"server",
			"endpoint",
			null
		]
          }
     }
   },
  "uniqueItems": true
}

Workload Settings Reference

This reference provides examples of workload settings.

Examples

The example below represents the complete JSON string returned by the GET /api/v2/orgs/:xorg_id/settings/workloads request:

{
	"href": "/orgs/1/settings/workloads",
	"workload_disconnected_timeout_seconds": [
	{
		"scope": [],
		"value": 10800,
		"ven_type": "server"
	},
	{
		"scope": [],
		"value": 3600,
		"ven_type": "endpoint"
	},
	],
	"workload_goodbye_timeout_seconds": [
	{
		"scope": [],
		"value": 12000,
		"ven_type": "server"
	},
	{
		"scope": [],
		"value": 7200,
		"ven_type": "endpoint"
	}
	],
	"workload_disconnected_notification_seconds": [
	{
	{
		"scope": [],
		"info": 1800,
		"warning": 3600,
		"error": 5400,
		"ven_type": "server
	},
	{
		"scope": [],
		"info": 1801,
		"warning": 3602,
		"error": 5403,
		"ven_type": "server
	}
	}
	],
	"ven_uninstall_timeout_hours": [
	{
		"scope": [],
		"value"=>300
		}
	]
}

The following example shows how to set all four workload timeout setting properties via the PUT /api/v2/orgs/:xorg_id/settings/workloads request:

{
	"workload_disconnected_timeout_seconds": [
	{
		"scope": [],
		"value": 10800,
		"ven_type": "server"
	},
	{
		"scope": [],
		"value": 3600,
		"ven_type": "endpoint"
	},
	],
	"workload_goodbye_timeout_seconds": [
	{
		"scope": [],
		"value": 12000,
		"ven_type": "server"
	},
	{
		"scope": [],
		"value": 7200,
		"ven_type": "endpoint"
	}
	],
	"workload_disconnected_notification_seconds": [
	{
	{
		"scope": [],
		"info": 1800,
		"warning": 3600,
		"error": 5400,
		"ven_type": "server"
	},
	{
		"scope": [],
		"info": 1801,
		"warning": 3602,
		"error": 5403,
		"ven_type": "endpoint"
	        }
	     }
	],
	"ven_uninstall_timeout_hours": [
	{
		"scope": [],
		"value"=>300
		}
	]
}

REST APIs 25.1 Developer Guide