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
Get a collection of all network interfaces for a workload	`GET`	`[api_version][workload_href]/interfaces`
Get information about an individual network interface for a workload	`GET`	`[api_version][workload_href]/interfaces/:name`
Create a network interface configuration for an individual workload	`POST`	`[api_version][workload_href]/interfaces`
Delete a workload network interface configuration	`DELETE`	`[api_version][workload_href]/interfaces/:name`

Workload HREF and Interface Names

Before you can get network interface information for a workload, you need to know the workload's HREF, and then the name of the interface. To obtain a workload's HREF, use the workloads API to get a collection of workloads.

In the response for getting workloads, each workload is identified by an HREF, and each network interfac is identified by its name:

{
    "href": "/orgs/2/workloads/3e3e17ce-XXXX-42b4-XXXX-1d4d3328b342",
    "deleted": false,
    "name": standalone_dev,
    "description": null,
    "hostname": "hrm-db-prod1",
    "service_principal_name": null,
    "public_ip": "xxx.0.2.10",
    "external_data_set": null,
    "external_data_reference": null,
    "interfaces": [
      {
        "name": "eth0.public",
        "address": "xxx.0.2.10",
        "cidr_block": 32,
        "default_gateway_address": null,
        "link_state": "up",
        "network_id": 3,
        "network_detection_mode": "manual",
        "friendly_name": null
      },
      {
        "name": "eth0",
        "address": "xx.10.10.10",
        "cidr_block": null,
        "default_gateway_address": "xx.0.10.10",
        "link_state": "up",
        "network_id": 3,
        "network_detection_mode": "single_private_brn",
        "friendly_name": "Friendly eth0"
      }
    ],
    ....

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

URI to Get an Individual Workload Network Interface

GET [api_version][workload_href]/interfaces/:name

Query Parameters

Parameter	Description	Type	Requiured
`name`	Name of the network interface on 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	`link_state`
`address`	The IP address assigned to the interface.	String	`address`
`cidr_block`	The number of bits in the subnet (for example, /24 is 255.255.255.0).	Integer	`cidr_block`
`default_gateway_address`	The default IP address of the default gateway.	Integer	`default_gateway_address`
`network`	Network object used in workloads and workload interfaces	Object	No
`network_detection_mode`	Network Detection Mode	String	Yes
`friendly_name`	User-friendly name for interface	String	Yes

Request Body 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	Yes
`ip_version`	IP version		Yes
`default_gateway_address`	The default IP address of the default gateway.	Integer	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
`network`	Network that the interface belongs to Reference to `workloads_interfaces_network.schema.json`	Object	Yes
`network_detection_mode`	Network Detection Mode	String	Yes
`friendly_name`	Friendly name given to the interface.	String	Yes

Curl Command Get Collection of Interface Statuses

curl -i -X GET https://pce.my-company.com:8443/api/v2/3/workloads/12/interface_statuses -H "Accept: application/json" -u $KEY:$TOKEN

Create Workload Network Interface

After you have obtained a workload's HREF, you can use that HREF to make an API call that creates a new network interface configuration for the workload.

URI to Create a Workload Network Interface Configuration

POST [api_version][workload_href]/interfaces

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"}'

Delete Workload Network Interface

To delete a workload's network interface, you need the workload HREF and the name of the workload's network interface. Both values can be obtained in the response when you get an individual workload or a collection of workloads.

Once you have obtained a workload's HREF and the network interface name, you can use those values to make an API call that deletes the specified network interface from the workload.

Request Parameters for DELETE

Parameter	Description	Type	Required
`name`	Name of the network interface on the workload.	String	Yes
`org_id`	Organization	Integer	Yes
`workload_id`	Workload UUIUD	String	Yes

URI to Delete a Workload Network Interface Configuration

DELETE [api_version][workload_href]/interfaces/:name

Curl Command Delete Network Interface

curl -i -X DELETE https://pce.my-company.com:8443/api/v2/orgs/2/workloads/xxxxxxxx-c4e9-44e7-8a31-e86acf6b276c/interfaces/eth0 -H "Accept: application/json" -u $KEY:$TOKEN

REST APIs for 22.5