Additional storage connectivity group APIs and extensions

API variations for additional storage connectivity group functions and related extensions.

Return host storage topologies

Request

Table 2. Parameters in the request for viewing host storage topologies

Name	Style	Type	Description
host_name	query	string	Optional. Use the query parameter to limit the topology data to the single host that is specified. The host name is the hypervisor host name, which is an MTMS name and not the display name of the host.
port_tag	query	string	Optional. Use the query parameter to constrain the counts of Fibre Channel ports and Virtual I/O Servers to those that match the specified tag.
provider_check_type	query	string	Optional. If this query parameter is provided, then Virtual I/O Servers will NOT be considered storage_ready if the backend storage provider is in error state. If the option is not given, then VIOS storage readiness need not depend on storage provider readiness. If this option is not provided, the API becomes backwards compatible with 1.2.0.x. The values that are allowed are: cluster: If a VIOS is a member of a cluster, then that cluster must not be in error state for the VIOS to be storage_ready. external: There must be at least one registered SAN provider that is not in error state for the VIOS to be considered storage_ready. This value aligns with NPIV-only connectivity. any: If either the cluster provider or any SAN provider is not in error state, then the VIOS can be storage_ready, provided the VIOS passes the other checks.

Example request

GET	
/v2.1/{tenant_id}/host-storage-topologies
Content-Type: application/json
Accept: application/json
X-Auth-Token : 16ac964aae06430aa4c8e1588c3740b3

Response

Table 3. Parameters in the response for returning host storage topology information

Name	Body Parameter	Type	Description
host_list	root	list of objects	Each set represents the storage topology information for each registered host, or the single host that is specified by the optional host_name request parameter.
name	host_list entry	string	The host name of the compute host. This is the same value that is returned from the os-hosts command.
hmc_uuid	host_list entry	string	The UUID of the HMC that is used to get the host topology information.
vios_ready_count	host_list_entry	integer	The value is the number of Virtual I/O Servers that are storage_ready for this compute host. storage_ready is determined differently for different values of the provider_check_type and port_tag query parameters.
vios_list	host_list_entry	list of objects	Contains an entry for each defined Virtual I/O Server partition under the parent compute host.
name	vios_list_entry	string	The name of the Virtual I/O Server.
lpar_id	vios_list entry	integer	The ID of the Virtual I/O Server logical partition. The ID is typically a positive integer.
id	vios_list entry	string	The ID that PowerVC uses to manage the Virtual I/O Server that is a member of this storage connectivity group. This value is unique across all managed Virtual I/O Server entries.
state	vios_list entry	string	The state of the Virtual I/O Server logical partition. For the Virtual I/O Server to be storage_ready, this state must be running. Possible values include running, error, not activated, not available, open firmware, shutting down, starting, hardware discovery, migrating not active, migrating running, suspended, suspending, resuming, Unknown. However, not all values might be applicable to VIOS partitions.
rmc_state	vios_list entry	string	The state of the Resource Monitoring and Control component of the Virtual I/O Server. For the VIOS to be storage_ready, the rmc_state must be active or busy. Possible values include active, inactive, none, unknown, and busy.
storage_ready	vios_list entry	boolean	Whether the VIOS can be used for storage connectivity. The VIOS state and rmc_state parameters affect this value and also storage provider states and Fibre Channel port information. storage_ready is determined differently for different values of the provider_check_type query parameter.
total_fcport_count	vios_list entry	integer	The total number of Fibre Channel ports that are owned by this VIOS entry.
port_ready_counts	vios_list entry	object	The number of ports that are considered storage_ready for each connectivity type that is available on this VIOS. The key can be pv_vscsi, npiv, or ibm_ssp.
cluster_provider_name	vios_list entry	string	Optional. The name of the shared storage pool provider that the VIOS is a member of. It is the same name as the storage_hostname property that is returned by the Cinder storage-providers REST API. This property is not returned if the VIOS is not active in a cluster. Even if it is returned, the VIOS might not be currently active in the cluster due to partition state or a communications issue within the cluster or between the HMC and the VIOS.
cluster_provider_display_name	vios_list entry	string	Optional. The display name of the shared storage pool provider service that is associated with the storage connectivity group. It is the same name as the host_display_name property that is returned by the Cinder storage-providers REST API. This property is not returned if the VIOS is not active in a cluster.
cluster_provider_state	vios_list entry	string	Optional. The shared storage pool provider state that is associated with the storage connectivity group. It is the same state as the state that is returned by the Cinder storage-providers REST API. This property is not returned if this VIOS is not active in a cluster.
fcport_list	vios_list entry	list of objects	Contains an entry for each Fibre Channel port that is owned by the VIOS. See the VIOS port_ready_counts description for details.
name	fcport_list entry	string	The name of the Fibre Channel port. For example, fcs0.
id	fcport_list entry	string	The ID of the Fibre Channel port. This ID is used to refer to the port by other APIs.
wwpn	fcport_list entry	string	The worldwide port name. Generally a unique hexadecimal string.
adapter_id	fcport_list entry	string	The parent Fibre Channel adapter ID.
fabric	fcport_list entry	string	The fabric identifier, which is managed by PowerVC, that the Fibre Channel port is logged in to. Valid values are A, B, or None. PowerVC supports a maximum of two redundant fabrics. A value of None means that the port is not cabled to a fabric or the fabric switch is not registered, or PowerVC did not determine the fabric yet.
enabled	fcport_list entry	boolean	enabled is an administrator defined property and defaults to true. If enabled the port is allowed to be used by PowerVC for storage volume attachments, including the boot ephemeral disk on a deployment. If not enabled, then future operations skip the port when you create virtual Fibre Channel connections from a virtual machine. Changing the setting to false, does not affect existing virtual Fibre Channel storage connections for any virtual machines. Nor does it restrict share storage pool connectivity over Fibre Channel.
fc_protocol	fcport_list entry	string	Optional. This is only valid when enabled is set to true. The type of Fibre Channel attachment that this port will be used for. Allowed values are npiv, vscsi, and any. The default is any. Fibre Channel attachment protocol for a port on a Virtual I/O Server impact future deploys and Live Partition Mobility operations.
port_tag	fcport_list entry	string	Optional. port_tag is an administrator defined value. The property is not returned unless a port_tag is set on the port. The port tag value is used to match port tags that are defined for storage connectivity groups. If a storage connectivity group has a port tag set, then the port is not applicable unless its port_tag matches with the port_tag that is set on the storage connectivity group.
status	fcport_list entry	string	The status of the Fibre Channel port. These are the possible values: OK: The Fibre Channel port can be used for storage connectivity. Offline: The port cannot be used because it does not seem to be cabled to a supported switch fabric. Unknown: PowerVC could not obtain status information about the port.
npiv_status	fcport_list entry	string	The NPIV status of the Fibre Channel port. These are the possible values: OK: The Fibre Channel port can be used for NPIV storage connectivity. A port with any other npiv_status value is not a candidate for NPIV volume attachments. Offline: The port does not seem to be cabled. Full: No more NPIV connections are allowed through this port. Unknown_fabric: At least one fabric is registered with PowerVC but the port does not seem to be logged in to any of the registered fabrics. Unknown: PowerVC could not obtain status information about the port. Unsupported_adapter: The port is on an adapter that does not seem to support NPIV connectivity.
available_connections	fcport_list entry	integer	The number of available virtual connections on the Fibre Channel port. Virtual machines that are connected to storage through this Fibre Channel port might use connections that are available.

Response codes

• Normal response code: 200 (OK)
• Error Response Codes: Bad Request (400), Unauthorized (401), Not Found (404), Forbidden (403)

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Connection: keep-alive

{
"host_list": [
  {
   "vios_ready_count": 2,
   "name": "8231E2D_109EFET",
   "port_ready_count": {
     "npiv": 4,
     "pv_vscsi": 8
    },
   "hmc_uuid": "230cd59c-fa61-3c1c-b621-e62645120bf3",
   "vios_list": [
	{
	 "id": "8231E2D_109EFET##2",
	 "cluster_provider_name": "22d22e9ac88d0111e3b6e900006cae8b02",
	 "cluster_provider_display_name": "p730_SSP_B",
	 "name": "vios2230_2",
	 "storage_ready": true,
	 "lpar_id": 2,
	 "total_fcport_count": 2,
	 "state": "running",
	 "rmc_state": "active",
	 "port_ready_count": {
     "npiv": 4,
     "pv_vscsi": 8
    },
	 "cluster_provider_state": "running",
	 "fcport_list": [
	  {
	   "status": "OK",
     "npiv_status": "OK",
	   "fabric": "A",
	   "vio_server": "vios2230_2",
	   "available_connections": 64,
	   "enabled": true,
     "fc_protocol":'npiv',
	   "adapter_id": "U78AB.001.WZSJMPP-P1-C4",
	   "wwpn": "10000090FA2A4E00",
	   "id": "1aU78AB.001.WZSJMPP-P1-C4-T1",
	   "name": "fcs0"
	  },
	  {
	   "status": "OK",
	   "npiv_status": "OK",
     "fabric": "B",
	   "vio_server": "vios2230_2",
	   "available_connections": 64,
	   "enabled": true,
     "fc_protocol":'any',
	   "adapter_id": "U78AB.001.WZSJMPP-P1-C4",
	   "wwpn": "10000090FA2A4E01",
	   "id": "1aU78AB.001.WZSJMPP-P1-C4-T2",
	   "name": "fcs1",
	   "port_tag": "development"
	  }
	 ]
	},
	{
	 "id": "8231E2D_109EFET##1",
	 "cluster_provider_name": "226da740207fa311e391ee00006cae8b02",
	 "cluster_provider_display_name": "PVC_p730_A",
	 "name": "vios2230_1",
	 "storage_ready": true,
	 "lpar_id": 1,
	 "total_fcport_count": 2,
	 "state": "running",
	 "rmc_state": "active",
	 "port_ready_count": {
     "npiv": 4,
     "pv_vscsi": 8
    },
	 "cluster_provider_state": "running",
	 "fcport_list": [
	  {
	   "status": "OK",
	   "npiv_status": "OK",
     "fabric": "B",
	   "vio_server": "vios2230_1",
	   "available_connections": 64,
	   "enabled": true,
     "fc_protocol":'npiv',
	   "adapter_id": "U78AB.001.WZSJMPP-P1-C2",
	   "wwpn": "10000090FA2A550D",
	   "id": "1aU78AB.001.WZSJMPP-P1-C2-T2",
	   "name": "fcs1",
	   "port_tag": "development"
	  },
	  {
	   "status": "OK",
	   "npiv_status": "OK",
     "fabric": "A",
	   "vio_server": "vios2230_1",
	   "available_connections": 64,
	   "enabled": true,
     "fc_protocol":'npiv',
	   "adapter_id": "U78AB.001.WZSJMPP-P1-C2",
	   "wwpn": "10000090FA2A550C",
	   "id": "1aU78AB.001.WZSJMPP-P1-C2-T1",
	   "name": "fcs0"
	  }
	 ]
	}
   ]
  }
 ]
}

Set topology Fibre Channel port metadata

Request

Table 4. Parameters in request for setting topology Fibre Channel port metadata

Name	Style	Type	Description
fcport_list	body	list of objects	Each element contains Fibre Channel port metadata for each port to update.
id	body	string	The ID of the Fibre Channel port to update the metadata for.
enabled	body	boolean	Optional. If enabled the port is allowed to be used by PowerVC for storage volume attachments, including the boot ephemeral disk on a deployment. If not enabled, then future operations skip the port when you create vFC (virtual Fibre Channel) connections from a virtual machine. Changing the setting to false, does not affect existing vFC storage connections for any virtual machines.
port_tag	body	string	Optional. The port tag value is used to match port tags that are defined for storage connectivity groups. If a storage connectivity group has a port tag set, then the port is not applicable unless its port_tag matches the port_tag that is set on the storage connectivity group. If storage connectivity groups do not specify port tags, then this value can be skipped or passed as None or null.
fc_protocol	body	string	Optional. This is only valid when enabled is set to true. The type of Fibre Channel attachment that this port will be used for. Allowed values are npiv, vscsi, and any. The default is any. Fibre Channel attachment protocol for a port on a Virtual I/O Server impact future deploys and Live Partition Mobility operations.
fabric	body	string	Optional. The fabric identifier, which is managed by PowerVC, that the Fibre Channel port is logged in to. Valid values are A, B, or None. PowerVC supports a maximum of two redundant fabrics. A value of None means that the port is not cabled to a fabric or the fabric switch is not registered, or PowerVC did not determine the fabric yet. In PowerVC 1.2.1 and later releases, the fabric designation is automatically determined for registered fabric switches. However, the administrator can still override the automatic setting for the case where PowerVC cannot determine the value, the value is set to None. In most cases, do not modify the value if it is automatically set to A or B since it will likely be set back the way it was, the next time the fabric information is synchronized with the ports.

Example request

POST 
/v2.1/{tenant_id}/host-storage-topologies
X-Auth-Token: 13ed281f782b4409ba5bc41032fc7a4b
Content-Type: application/json
Accept: application/json
User-Agent: powervc-httpclient

Body:
{
 "fcport_list": [
  {
   "enabled": false,
   "port_tag": "newtag",
   "fc_protocol":'npiv',
   "id": "1aU789D.001.DQD50G3-P1-C1-T1",
   "fabric": "A"
  }
 ]
} 

Response codes

• Normal response code: 204 (No Content)
• Error Response Codes: Bad Request (400), Unauthorized (401), Not Found (404), Forbidden (403)

Example response

Status Code: 204 No Content
Connection: keep-alive
Content-Type: application/json; charset=UTF-8
X-Compute-Request-Id: req-a40f8c97-3d4f-449f-add7-d77a546fd337

Return a list of storage connectivity groups that are compatible with an image

Returns a list of objects, where each set contains the storage connectivity group ID and a name for a group that is available and compatible for deployment of the specified image. The operation does not take a REST body and returns a priority ordered list of storage connectivity groups that are available to use for deployment of the image. For a storage connectivity group to be available, the group must have at least one VIOS that is storage-ready with connectivity to the backing volume of the image.

Request

Table 5. Parameters in the request for storage connectivity groups that are compatible with an image

Name	Style	Type	Description
image_id	URI	UUID	The image ID to return compatible storage connectivity groups.
host_name	query	string	Optional. Filter storage connectivity groups to only those that contain the specified hypervisor host name of the compute host.
details	query	string	Optional. Return detailed properties of each storage connectivity group instead of just the display name and ID.

Example request

GET
/v2.1/{tenant_id}/images/{image_id}/storage-connectivity-groups
Content-Type: application/json
Accept: application/json
X-Auth-Token : 16ac964aae06430aa4c8e1588c3740b3

Response

Table 6. Parameters in the response for storage connectivity groups that are compatible with an image

Name	Style	Type	Description
display_name	body	string	Display name of the storage connectivity group.
id	body	UUID	The ID of the storage connectivity group.

Note: More options are displayed in the response if details option is provided.

Response codes

• Normal response code: 200 (OK)
• Error Response Codes: Bad Request (400), Unauthorized (401), Not Found (404), Forbidden (403)

Example response

Status Code: 200 OK
Connection: keep-alive
Content-Type: application/json; charset=UTF-8
X-Compute-Request-Id: req-6b15eb26-53b0-4c80-891c-c9fd54dad8ea

{
  "storage_connectivity_groups":
    [
      {
        "display_name": "Production-FC",
        "id": "7fb98472-e526-42f4-b378-a5e51a3e7303"
      },
      {
        "display_name": "Development-SSP",
        "id": "7fb98472-e526-42f4-b378-a5e51a3e7301"
      }
   ]
}

Return compute hosts that are viable for storage connectivity

Returns the list of compute hosts, which are hypervisor names, that can be deployed to by using the supplied query parameters as constraints. This API is a target filtering API for storage. Generally, this API is used in conjunction with other compute and network filtering APIs to generate a intersected list of viable host targets for a deployment (unhosted instance) or a migrate operation (existing hosted instance). If the instance is associated with an image, or volume type is specified, then the storage provider is looked up based on the image and volume type or either of them. The operation does not take a request body. The hosts that are returned are identified by the PowerVC hypervisor host name.

Request

Table 7. Parameters in the request for getting compute hosts that are viable for storage connectivity

Name	Style	Type	Description
instance_uuid	query	UUID	Optional. The instance UUID that will be used to get the storage requirements of an instance. When the option is provided, virtual machine instance if looked up in the database. If a storage connectivity group is associated with the instance, then that group is used to determine viable (candidate) hosts that can host the instance. If the storage connectivity group is not associated with the instance, then the flavor that is associated with the instance is checked for a specified storage connectivity group in its extra_specs. If this is not possible either, then a default storage connectivity group is chosen for the instance. You can provide the instance_uuid option or the server_id option but not both the options.
server_id	query	string	Optional. Similar to the instance_uuid option except that the virtual machine instance is looked up through the compute API. You can provide the server_id option or the instance_uuid option but not both the options.
flavorRef	query	string	Optional. However, this option is required if an imageRef is provided. A custom flavor ID might be provided that specifies a storage connectivity group in its extra_specs. If the option is provided, this flavor would override any associated flavor with the instance that is provided.
imageRef	query	string	Optional. If the option is provided, it is the ID of the image that would override any image that is associated with a specified instance. The API tries to look up the volume type from the image to exclude hosts from being viable if the storage provider of the volume type is in error state. Hosts are also excluded if the storage provider location does not have enough room for the deployment of the image.
volume_typeRef	query	string	Optional. This option overrides any volume type on either the passed image or instance. The string value can either be a single volume type ID or it can be a string representation of a dictionary mapping of volume IDs to volume type IDs, where the request is for viable hosts in a multi-volume deployment situation. If any volume type specifies a storage provider that is in error state, then no hosts will be returned as viable.

Example request

GET 
/v2.1/{tenant_id}/storage-viable-hosts/instance_uuid=d1827db2-96b2-4f34-8bbc-20ed82be43e2
X-Auth-Token: 9e3c904d236040ab9d0f0f20867b0246
Content-Type: application/json
Accept: application/json

Response

Table 8. Parameters in the response for getting compute hosts that are viable for storage connectivity

Name	Style	Type	Description
host_name	body	object	The information that is returned in the body is indexed by the hypervisor host name of the compute host. host_name is also referred to as the machine-type-model-serial name of PowerVM® hosts.
host	body	string	The hypervisor host name of the viable host element. This is the same value as the key listed in host_name. It is also currently the only property returned for the host, but the object format allows for future expansion of properties.

Response codes

• Normal response code: 200 (OK)
• Error Response Codes: Bad Request (400), Unauthorized (401), Not Found (404), Forbidden (403)

Example response

Status Code: 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Type: application/json; charset=UTF-8

{
 "789522X_067A34B": {
  "host": "789522X_067A34B"
 },
 "789522X_067A35B": {
  "host": "789522X_067A35B"
 }
}

Get accessible storage providers by virtual machine instance

Request

Table 9. Parameters in the request for accessible storage providers by instance

Name	Style	Type	Description
server_id	URI	UUID	The ID of the managed server instance.

Example request

GET
/v2.1/{tenant_id}/servers/{server_id}/storage-hosts
Content-Type: application/json
Accept: application/json
X-Auth-Token : 16ac964aae06430aa4c8e1588c3740b3

Response

Table 10. Parameters in the response for accessible storage providers by instance

Name	Style	Type	Description
storage_hosts	body	list of objects	Each object represents a storage provider that is an accessible candidate for storage. Accessible candidates are those from which the virtual machine might attach disk volumes, per the storage connectivity group that is associated with the virtual machine. It is not a guarantee that the storage is accessible.
host	value in objects	string	The storage provider backend name. This is the storage_hostname that is returned by the Cinder storage-providers REST API.
is_boot	value in objects	boolean	True if the storage provider is a candidate for attaching boot volumes. False otherwise.
is_data	value in objects	boolean	True if the storage provider is a candidate for attaching data volumes. False otherwise.

Response codes

• Normal response code: 200 (OK)
• Error Response Codes: Bad Request (400), Unauthorized (401), Not Found (404), Forbidden (403)

Example response

Status Code: 200 OK
Connection: keep-alive
Content-Type: application/json; charset=UTF-8
X-Compute-Request-Id: req-6b15eb26-53b0-4c80-891c-c9fd54dad8ea

{
	"storage-hosts": [
		{
                    "is_boot": false,   
                     "is_data": true,
			"host": "ip_x_xx_xx_v7000"
		}
	]
}