Workload Interfaces

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

Workload Interfaces Methods

Functionality	HTTP	URI
Request the list of the workload_interfaces (outside of the workloads or VENs scope). The `href` property in the API response is deprecated.	`GET`	`[api_version][workload_href]/interfaces`
Get an instance for the workload interface using 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 and update the automatic network detection. (DEPRECATED)	`PUT`	`[api_version][workload_href]/interfaces/ :name/network`

Get Workload Network Interface

This API lets you 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

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

Workload Interfaces Reference

This topic contains properties and examples for workload interfaces.

GET Properties for workload interfaces

Property	Description	Type	Required
`name`	Interface name.	String	Yes
`address`	The IP address is 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`: The state of the interface is unknown.	String, Null	Yes
`network_detection _mode`	Network Detection Mode	String, Null	Yes
`friendly_name`	A user-friendly name is given to the interface.	String, Null	Yes
`network`	A network that the interface belongs to	Object, Null	Yes
`href`	DEPRECATED WITH NO REPLACEMENT	String	No

POST properties for workload interfaces

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`: The 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`	User-friendly name 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 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"
}

The 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 24.2.20 and 24.2.10