Workload Settings

This Public Stable API allows you to get network interface information from a workload, for either all interfaces on a workload or an individual interface. You can also configure (create) or delete an individual 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 endpoints heart beating.

If the endpoints did not heartbeat for 24 hours, they were marked as being 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 the endpoint offline, heartbeat, and 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 heart beaten to the PCE. Referencing the schema `settings_workload_detailed.schema.json`	Yes
`workload_goodbye_timeout_seconds`	Timer setting triggered if the server or endpoint operation is performed (stop, disable, ...). Referencing the schema `settings_workload_detailed.schema.json`	Yes
`workload_disconnected_notification_seconds`	Time 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.

{
	"$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
}

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

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 for 23.5