Workload Interfaces

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

API Methods

Functionality	HTTP	URI
Request the list of the workload_interfaces (outside of the workloads or VEs scope). The `href` property in the API response is deprecated.	`GET`	`[api_version][workload_href]/interfaces`
Get an instance for the workload interface with the name. (DEPRECATED)	`GET`	`[api_version][workload_href]/interfaces/:name`
Directly creates a workload interface. The request payload was not changed, however the `href` field in the API response is deprecated.	`POST`	`[api_version][workload_href]/interfaces`
Delete the workload interface with the name.(DEPRECATED)	`DELETE`	`[api_version][workload_href]/interfaces/:name`
Set the network manually, update the automatic network detection. (DEPRECATED)	`PUT`	`[api_version][workload_href]/interfaces/:name/network`

Get Workload Network Interface

This API allows you to get information about one or all of the interfaces on a workload. You can retrieve workload interface information such as its connectivity (up, down, unknown), interface IP address, number of bits in the subnet, the IP address of the default gateway, and the associated network.

URI to Get a Collection of a Workload's Network Interfaces

GET [api_version][workload_href]/interfaces

Properties for GET

Property	Description	Type	Required
`name`	Interface name.	String	Yes
`address`	The IP address assigned to the interface.	String	Yes
`cidr_block`	The number of bits in the subnet (for example, /24 is 255.255.255.0).	Integer, Null	Yes
`default_gateway_address`	The default IP address of the default gateway.	String, Null	Yes
`link_state`	State of the interface connection, which is one of three values: `up`: Interface is communicating. `down`: Interface is not communicating. `unknown`: State of the interface is unknown.	String, Null	Yes
`network_detection_mode`	Network Detection Mode	String, Null	Yes
`friendly_name`	User-friendly name given to the interface.	String, Null	Yes
`network`	Network that the interface belongs to	Object, Null	Yes
`href`	DEPRECATED WITH NO REPLACEMENT	String	No

Create Workload Network Interface

Directly creates a workload interface. The request payload was not changed, however the href field in the API response is deprecated.

URI to Create a Workload Network Interface Configuration

POST [api_version][workload_href]/interfaces

Properties for POST

Properties	Description	Type	Required
`name`	The short friendly name of the workload	String	Yes
`link_state`	State of the interface connection, which is one of three values: `up`: Interface is communicating. `down`: Interface is not communicating. `unknown`: State of the interface is unknown.	String	Yes
`address`	The IP address assigned to the interface. Reference to common schema `ip_address_format_validation.schema.json`	String	No
`cidr_block`	The number of bits in the subnet (for example, /24 is 255.255.255.0).	Integer	No
`default_gateway_address`	The default IP address of the default gateway. Reference to common schema `ip_address_format_validation.schema.json`	String	No
`friendly_name`	A user-friendly name is given to the interface.	String	No
`href`	DEPRECATED WITH NO REPLACEMENT	String	No

Request Body

 {
    "name": "eth0.public",
    "address": "192.0.2.0",
    "cidr_block": 32,
    "default_gateway_address": 255.255.255.0,
    "link_state": "up",         
 }

Curl Command Create Network Interface

curl -i -X POST https://pce.my-company.com:8443/api/v2/orgs/2/workloads/xxxxxxxx-c4e9-44e7-8a31-e86acf6b276c/interfaces -H "Content-Type: application/json" -u $KEY:$TOKEN -d '{"name": "eth0.public", "address": "192.0.2.0","cidr_block": "32", "default_gateway_address": "255.255.255.0", "link_state": "up"}'

Examples

Request for all workload interfaces with a specific name

Request: GET /api/v2/orgs/:org_id/workloads/:workload_id/interfaces?name=eth0.public

The response includes the deprecated href field in the response:

[
   {
	"href": "/orgs/1/workloads/561bd65e-136c-4005-8aa2-bdc8af1b3600/interfaces/eth0.public"
	"name": "eth0.public",
	"cidr_block": null,
	link_state": null,
	"network_detection_mode": null,
	"friendly_name": null,
	"network": {
		"href": "/orgs/1/networks/366ff4c1-ec60-49be-a05f-3a5ccab09c2f"
	},
	"loopback": false,
	"address": "1.1.1.1",
	"default_gateway_address": null
   },
   {
	"href": "/orgs/1/workloads/561bd65e-136c-4005-8aa2-bdc8af1b3600/interfaces/eth0.public"
	"name": "eth0.public",
	"cidr_block": null,
	"link_state": null,
	"network_detection_mode": null,
	"friendly_name": null,
	"network": {
		"href": "/orgs/1/networks/366ff4c1-ec60-49be-a05f-3a5ccab09c2f"
	},
	"loopback": false,
	"address": "2.2.2.2",
	"default_gateway_address": null
}

API request/response creating a new workload interface

Request: POST /api/v2/orgs/:org_id/workloads/:workload_id/interfaces

{
	"name": "eth1.private",
	"cidr_block": 32,
	"link_state": "up",
	"address": "99.99.99.7"
}

Response body (with the href deprecated):

{
	"href": "/orgs/1/workloads/561bd65e-136c-4005-8aa2/interfaces/eth1.private"
	"name": "eth1.private",
	"cidr_block": 32,
	"link_state": "up",
	"network_detection_mode": "single_private_brn",
	"friendly_name": null,
	"network": {
		"href": "/orgs/1/networks/5b25c11d-4e95-42d3-abd2-488506e48b02"
	},
	"loopback": false,
	"address": "99.99.99.7",
	"default_gateway_address": null
}

API request deleting multiple workload interfaces (bundle delete)

Request: PUT /api/v2/orgs/:org_id/workloads/:workload_id/interfaces/delete

Successful delete

Payload - all interfaces with the name eth0.public and only one interface with the name eth1.private are deleted.

Response code - 200

{
	"name": "eth0.public"
},
{
	"name": "eth1.private",
	"address": "10.10.10.1"
}

REST APIs for 23.5