Host network mapping

Edit online

Use the REST APIs to create, read, and update Shared Ethernet Adapter network mappings for PowerVC. This REST API does not affect Single Root I/O Virtualization (SR-IOV) or Open vSwitch (OVS) networks.

Network mapping API options

Note: The PUT operation, in general, behaves the same as the POST operation. However, the key difference is that PUT updates an existing mapping and POST creates a mapping for the first time.
Table 1. REST API options for network mapping
Method URI Description

POST

/v2.1/{tenant_id}/host-network-mapping

Creates the network mapping for a set of hosts on the tenant ID that is provided.

GET

/v2.1/{tenant_id}/host-network-mapping

Lists network mapping for all hosts.

PUT

/v2.1/{tenant_id}/host-network-mapping

Edits the network mapping for a set of hosts on the tenant ID that is provided.

GET

/v2.1/{tenant_id}/host-network-mapping/{host_name}

Lists the network mapping for the host that is provided.

Create network mapping

This operation requires a REST body. If the request body is empty or if the request body does not contain a host with a network ID with at least one Shared Ethernet Adapter entry, the operation gives a Bad Request (400) response. Multiple hosts can be included on a single POST request by listing each host in the request body. This API, by using external tool, can overwrite manual configurations that are established by the user. If the API detects that an overwrite is about to happen, returns a Conflict (409) with details in the response body. The conflict information is presented in PowerVC, and you confirm the overwrite. When you confirm the overwrite, PowerVC calls the API again with the force=true URL parameter. The API returns the following warning messages on a Conflict (409) response:
  • A Shared Ethernet Adapter is being removed from the default adapter status, and this action results in network downtime.
  • There are multiple networks on the same VLAN. Changing a network results in a change to the other networks.
This REST API checks for a request header Locale and translates the returned message, if possible. A message ID is also returned, by allowing the client to use a separate message bundle. When the data is valid, the API returns a response 200 OK with a blank body.

The following example contain a request to create the network mappings for two hosts for the tenant e9a2464cf00f4bc98eb2d02c534f47b7. The body of the request contains the information to set for the network mappings. As the data is valid, the API returns a response 200 OK with a blank body.

For more details, see these sections:
Response Codes
  • Normal Response Code: 200
  • Error Response Codes:
    • Bad Request (400)
    • Unauthorized (401)
    • Not Found (404)
    • Conflict (409)
Request parameters:
Table 2. Parameters in the request for creating a network mapping
Name In Type Description

host_name

body

String

Name of the host that is used by OpenStack configuration. The host name is not the same as the host name of a networking concept that is used for Domain Name Service.

network_id

body

String

The ID for the network that is used by OpenStack configuration.

primary_sea

body

String

The primary Shared Ethernet Adapter that traffic flows through for the specified host and the specified network.

lpar_id

body

Integer

The ID for the Virtual I/O Server logical partition that owns the specified Shared Ethernet Adapter. The ID is typically a positive integer.

name

body

String

The name of the Shared Ethernet Adapter.

force

query

Boolean

Optional. Valid values are True or False. Default value is False. Specify?force=true in the URI to create the network mapping for a set of hosts and force an override of any previous 409 conflict errors.
Example:
POST 
/v2.1/{tenant_id}/host-network-mapping
Content-Type: application/json
Accept: application/json

{
	"host-network-mapping": [
		{
			"host_name": "host1",
			"networks": [
				{
					"network_id": "ade3c5e807ff479c9ed1ad43",
					"primary_sea": {
						"lpar_id": 1,
						"name": "ent10"
					}
				}
			]
		},
		{
			"host_name": "host2",
			"networks": [
				{
					"network_id": "bde3c5e807ff479c9ed1ad44",
					"primary_sea": "not-applicable"
				}
			]
		}
	]
}

Response JSON:

200 (OK)

View details of existing network mapping

The following is an example of a GET operation, which is a request to get the details of network mappings without specifying the host or a network ID. The HTTP request gets all network mappings for a tenant. The response body contains network mapping details of two hosts. host1 has a network with the ID ade3c5e807ff479c9ed1ad43. The network has a list of Shared Ethernet Adapters, and the list contains a single Shared Ethernet Adapter named ent10. The VIOS for host1 is not configured for high availability so the HA attributes of the Shared Ethernet Adapter are null. The VIOS LPAR ID is available as a property of the SEA. host2 with a second network is also returned. The Shared Ethernet Adapters list for the second host is set to not-applicable as host2 does not have a mapping for network1. host2 is still a viable host, but when PowerVC places a virtual machine on the host, a default value is selected. The response data has a host that contains a set of networks that contains a set of Shared Ethernet Adapters.

Response Codes
  • Normal Response Code: 200
  • Error Response Codes:
    • Bad Request (400)
    • Unauthorized (401)
    • Not Found (404)
Request parameters:
Table 3. Parameters in the request for viewing details of an network mapping
Name In Type Description

network_id

query

String

Optional. The ID for the network that is used by OpenStack configuration. To filter the returned list by a network ID, specify ?network_id={network_id} in the URI.
Example:
GET 
/v2.1/{tenant_id}/host-network-mapping
Content-Type: application/json
Accept: application/json

Response JSON:

Table 4. Parameters in the response for viewing details of an existing network mapping
Name In Type Description

host_name

body

String

Name of the host that is used by OpenStack configuration. The host name is not the same as the host name of a networking concept that is used for Domain Name Service.

network_id

body

String

The ID for the network that is used by OpenStack configuration.

primary_sea

body

String

The primary Shared Ethernet Adapter that traffic flows through for the specified host and the specified network.

lpar_id

body

Integer

The ID for the Virtual I/O Server logical partition that owns the specified Shared Ethernet Adapter. The ID is typically a positive integer.

name

body

String

The name of the Shared Ethernet Adapter.
Example:
200 (OK)
Content-Type: application/json
{
	"host-network-mapping": [
		{
			"host_name": "host1",
			"networks": [
				{
					"network_id": "ade3c5e807ff479c9ed1ad43",
					"primary_sea": {
						"lpar_id": 1,
						"name": "ent10"
					}
				}
			]
		},
		{
			"host_name": "host2",
			"networks": [
				{
					"network_id": "bde3c5e807ff479c9ed1ad44",
					"primary_sea": "not-applicable"
				}
			]
		}
	]
}

Update existing network mapping

The following example is a request to update the network mappings for host1 for the tenant e9a2464cf00f4bc98eb2d02c534f47b7. The body of the request contains the information to set for the network mapping. If the data is valid, the response is 200 OK with a blank body.

Request parameters:
Table 5. Parameters in the request for updating an existing network mapping
Name In Type Description

host_name

body

String

Name of the host that is used by OpenStack configuration. The host name is not the same as the host name of a networking concept that is used for Domain Name Service.

network_id

body

String

The ID for the network that is used by OpenStack configuration.

primary_sea

body

String

The primary Shared Ethernet Adapter that traffic flows through for the specified host and the specified network.

lpar_id

body

Integer

The ID for the Virtual I/O Server logical partition that owns the specified Shared Ethernet Adapter. The ID is typically a positive integer.

name

body

String

The name of the Shared Ethernet Adapter.

force

query

Boolean

Optional. Valid values are True or False. Default value is False. Specify?force=true in the URI to create the network mapping for a set of hosts and force an override of any previous 409 conflict errors.
Example:
PUT 
/v2.1/{tenant_id}/host-network-mapping
Content-Type: application/json
Accept: application/json


{
	"host-network-mapping": [
		{
			"host_name": "host1",
			"networks": [
				{
					"network_id": " ade3c5e807ff479c9ed1ad43",
					"primary_sea": {
						"lpar_id": 1,
						"name": "ent10"
					}
				}
			]
		}
	]
}

Response JSON:

200 (OK)

View details of existing network mapping of a specific host

The following is an example of a GET operation, which is a request to get the details of network mappings for a host. In the example, the request is for a specific host c45cfd902403492f8c1c417, and only the network mapping for the host is included in the response.

Response Codes
  • Normal Response Code: 200
  • Error Response Codes:
    • Bad Request (400)
    • Unauthorized (401)
    • Not Found (404)
Request parameters:
Table 6. Parameters in the request for viewing details of an network mapping
Name In Type Description

network_id

query

String

Optional. The ID for the network that is used by OpenStack configuration. To filter the returned list by a network ID, specify ?network_id={network_id} in the URI.
Example:
GET 
/v2.1/{tenant_id}/host-network-mapping/{host_name}
Content-Type: application/json
Accept: application/json

Response JSON:

Table 7. Parameters in the response for viewing details of an existing network mapping for a specific host
Name In Type Description

host_name

body

String

Name of the host that is used by OpenStack configuration. The host name is not the same as the host name of a networking concept that is used for Domain Name Service.

network_id

body

String

The ID for the network that is used by OpenStack configuration.

primary_sea

body

String

The primary Shared Ethernet Adapter that traffic flows through for the specified host and the specified network.

lpar_id

body

Integer

The ID for the Virtual I/O Server logical partition that owns the specified Shared Ethernet Adapter. The ID is typically a positive integer.

name

body

String

The name of the Shared Ethernet Adapter.
Example:
200 (OK)
Content-Type: application/json
{
	"host-network-mapping": [
		{
			"host_name": "host1",
			"networks": [
				{
					"network_id": "ade3c5e807ff479c9ed1ad43",
					"primary_sea": {
						"lpar_id": 1,
						"name": "ent10"
					}
				}
			]
		}
	]
}