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`

Get Workload Settings

Query Parameters for GET

Parameter	Description	Type	Requiured
`org_id`	Organization ID	Integer	Yes
`info`	Shows the state of workload timeout notification threshold		No
`error`	Shows the state of workload timeout notification threshold		No

Two properties, info and error, are used to to display state of workload timeout notification thresholds. They are provided to assist customers who want to control when they will get alerted about missing agents, and also that such a control be separate from the policy offline timer. Therefore, these properties are useful when a customer has a relatively high offline timer and short warning threshold.

Using info and error, customers can set explicit thresholds and configure when a warning is sent as well as its severity.

Response parameters for GET

Parameter	Description	Type	Requiured
`workload_disconnected_timeout_seconds`	If the VEN doesn't send a heartbeat to the PCE within the value specified in `workload_disconnected_timeout_seconds`, the workload associated with the VEN is considered to be offline. Contains: `scope` `value`: in seconds, such as 3600 To disable, set the its value to `-1`.	Object String Integer	Yes Yes Yes
`workload_goodbye_timeout_seconds`	If the VEN goes down, it sends a goodbye message to the PCE. The PCE then waits for the value set in `workload_goodbye_timeout_seconds` before setting the workload to offline. Contains: `scope` `value`: in seconds, such as 3600 To disable, set the its value to `-1`.		No
`ven_uninstall_timeout_hours`	Allow customers to see the length of their ven uninstall timeout in the case that the host is down for an extended period of time		No
`workload_disconnected_notification_seconds`	Added property to set state of workload timeout notification thresholds. Contains: `error` `info` `scope` `warning`

Example of a CURL command for GET /api/v2/orgs/:xorg_id/settings/workloads

curl -X GET \
	-u api_13468b9c1eb030e6a:4d664456bb8893ee9ba013356887a1993b74870b0bb7f09ab3a84b61e8300022 \
	-s \
	-H 'Accept: application/json' \
	-H 'Content-type: application/json' \
	https://test.lab.io:8443/api/v2/orgs/1/settings/workloads | python -m json.tool
{
	"href": "/orgs/1/settings/workloads",
	"workload_disconnected_notification_seconds": [
		{
			"error": 2700,
			"info": 900,
			"scope": [],
			"warning": 1800
		}
	],
	"workload_disconnected_timeout_seconds": [
		{
			"scope": [],
			"value": 3600
		}
	],
		"workload_goodbye_timeout_seconds": [
		{
			"scope": [],
			"value": 900
		}
	]
}

Example Reply for GET /api/v2/orgs/:xorg_id/settings/workloads

{
	"href": "/orgs/1/settings/workloads",
	"workload_disconnected_timeout_seconds": [{
		"scope": [],
		"value": 3600
	}],
	"workload_goodbye_timeout_seconds": [{
		"scope": [],
		"value": 900
	}],
	"ven_uninstall_timeout_hours": [{
		"scope": [],
		"value": 168
	}],
	"workload_disconnected_notification_seconds": [{
		"info": -1,
		"warning": -1,
		"error": -1,
		"scope": []
	}]
}

Update Workload Settings

This API updates workload settings.

Query Parameters for PUT

Parameter	Description	Type	Requiured
`org_id`	Organization ID	Integer	Yes
`workload_disconnected_timeout_seconds`	If the VEN doesn't send a heartbeat to the PCE within the value specified in `workload_disconnected_timeout_seconds`, the workload associated with the VEN is considered to be offline. Contains: `scope` `value`: in seconds, such as 3600 To disable, set the its value to `-1`.	Object String Integer	No
`workload_goodbye_timeout_seconds`	If the VEN goes down, it sends a goodbye message to the PCE. The PCE then waits for the value set in `workload_goodbye_timeout_seconds` before setting the workload to offline. Contains: `scope` `value`: in seconds, such as 3600 To disable, set the its value to `-1`.		No
`ven_uninstall_timeout_hours`	Allow customers to configure the length of their ven uninstall timeout in the case that the host is down for an extended period of time.		No
`workload_disconnected_notification_seconds`	Added property to set state of workload timeout notification thresholds. Contains: `error` `info` `scope` `warning`		No

Example JSON Request Body to Update Both Workload Settings

{
  "workload_disconnected_timeout_seconds": [
    {
      "scope": [ ], # Empty scope is the default. Each setting must have a default.
      "value": 3600 # customer-supplied default
    }
  ],
  "workload_goodbye_timeout_seconds": [
    {
      "scope": [
        { "href": "/api/v2/orgs/1/labels/1" },
        { "href": "/api/v2/orgs/1/labels/3" }
      ],
      "value": 1800
    },
    {
      "scope": [
        { "href": "/api/v2/orgs/1/labels/2" },
        { "href": "/api/v2/orgs/1/labels/4" }
      ],
      "value": 60
    },
    {
      "scope": [ ], # Empty scope is the default. Each setting must have a default.
      "value": 0    # customer-supplied default
    }
  ]
}

Example JSON Request Body to Update One Workload Setting

{
  "workload_goodbye_timeout_seconds": [
    {
      "scope": [
        { "href": "/api/v2/orgs/1/labels/2" },
        { "href": "/api/v2/orgs/1/labels/4" }
      ],
      "value": 120
    },
    {
      "scope": [ ], # Empty scope is the default. Each setting must have a default.
      "value": 0    # customer-supplied default.
    }
  ]
}

REST APIs for 22.5