Additional storage connectivity group APIs and extensions

Use these additional APIs to get topology information for creating storage connectivity groups, configure Fibre Channel port information, get lists of resources that have connectivity through a storage connectivity group, or retrieve lists of storage connectivity groups that are applicable to various resources.

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

Table 1. API variations for additional storage connectivity group functions and related extensions.
Method URI Description

GET

/v2.1/{tenant_id}/host-storage-topologies

Returns a set of storage topology information that is needed for the configuration of storage connectivity groups and Fibre Channel port metadata.

POST

/v2.1/{tenant_id}/host-storage-topologies

Updates PowerVC database information that contains metadata for VIOS owned Fibre Channel ports.

GET

/v2.1/{tenant_id}/images/{image_id}/storage-connectivity-groups

Returns a list of storage connectivity groups that are applicable for deployment of the image.

GET

/v2.1/{tenant_id}/storage-viable-hosts

Returns a set of objects that contain host IDs, which are hypervisor names, that can be deployed to or migrated to. The list is filtered by one or more of the storage parameter options that are provided.

GET

/v2.1/{tenant_id}/servers/{server_id}/storage-hosts

Returns a list of storage hosts, which are providers, for which the virtual machine that is specified by {server_id} has connectivity through its associated storage connectivity group.

Return host storage topologies

Returns a JSON data structure with a set of topology information that is useful for management of host storage resources and is needed for the configuration of storage connectivity groups and Fibre Channel port metadata. This operation does not take a REST body and returns an object with a host_list top-level element. The topology information includes the following for all hosts:
  • The ID of each VIOS on the host that is required to specify VIOS members for a storage connectivity group.
  • The ID of the Fibre Channel port that is required to set Fibre Channel port metadata information to be used by PowerVC.
See these sections for details:
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

Updates PowerVC database information that contains metadata for VIOS owned Fibre Channel ports. This operation takes in Fibre Channel port list and returns no data. The Fibre Channel port ID and information can be obtained from the host-storage-topologies GET API. Only three properties on a port are allowed to be set or changed. They are fabric, enabled, and port_tag. For details, see these sections:
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.

For details, see these sections:
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.

The general sequence is that first resources, including the target storage provider, are looked up if they are available or are specified in query parameters. If any of the following checks are satisfied, then the API returns no viable hosts:
  • The target provider is in error state.
  • The target provider free capacity is less than the image size.
  • The provider of the backing volume of the image does not match the provider of the target volume_type. This is a current PowerVC limitation.
  • The storage connectivity group in the flavor or instance does not provide access to the provider of the target volume_type.
If the above checks are OK, then the storage connectivity group is determined. Hosts in the storage connectivity group that have one or more Virtual I/O Servers that are considered to be storage-ready are returned by this API. The storage-ready state of a VIOS is returned in the detailed listing of the storage connectivity group when the include_ports query option is provided. At least the following conditions must be satisfied for a VIOS to be storage ready:
  • The Virtual I/O Server state is running.
  • The VIOS Resource Monitoring and Control (RMC) state is active or busy. Many Virtual I/O Server functions depend on this service.
  • One or more physical Fibre Channel ports that are owned by VIOS are ready.
    • The Fibre Channel port status is OK.
    • The port must be enabled for attachment.
    • If specified, the port tag must match the tag that is set on the storage connectivity group.
  • There are one or more applicable storage providers that are not in Error state. An applicable storage provider is supported by the Virtual I/O Server and is allowed by the storage connectivity group. A storage connectivity group can be configured to allow access only to the registered SAN providers, only to one shared storage pool provider, or a combination of both.
For details, see these sections:
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

In the body response, returns the key storage-hosts, where the value is a list of objects representing the storage provider names for which the virtual machine instance has connectivity. Connectivity is determined by the associated storage connectivity group of the virtual machine. This operation does not take a request body. For details, see these sections:
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"
		}
	]
}