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.
- Return host storage topologies
- Set topology Fibre Channel port metadata
- Return a list of storage connectivity groups that are compatible with an image
- Return compute hosts that are viable for storage connectivity
- Get accessible storage providers by virtual machine instance
API variations for additional storage connectivity group functions and related extensions.
Method | URI | Description |
---|---|---|
GET |
|
Returns a set of storage topology information that is needed for the configuration of storage connectivity groups and Fibre Channel port metadata. |
POST |
|
Updates PowerVC database information that contains metadata for VIOS owned Fibre Channel ports. |
GET |
|
Returns a list of storage connectivity groups that are applicable for deployment of the image. |
GET |
|
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 |
|
Returns a list of storage hosts, which are providers, for which
the virtual machine that is specified by |
Return host storage topologies
- 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.
Name | Style | Type | Description |
---|---|---|---|
|
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. |
|
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. |
|
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:
|
GET
/v2.1/{tenant_id}/host-storage-topologies
Content-Type: application/json
Accept: application/json
X-Auth-Token : 16ac964aae06430aa4c8e1588c3740b3
Name | Body Parameter | Type | Description |
---|---|---|---|
|
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_list entry |
string |
The host name of the compute host. This is the same value that is returned from the os-hosts command. |
|
host_list entry |
string |
The UUID of the HMC that is used to get the host topology information. |
|
host_list_entry |
integer |
The value is the number of Virtual I/O Servers that are |
|
host_list_entry |
list of objects |
Contains an entry for each defined Virtual I/O Server partition under the parent compute host. |
|
vios_list_entry |
string |
The name of the Virtual I/O Server. |
|
vios_list entry |
integer |
The ID of the Virtual I/O Server logical partition. The ID is typically a positive integer. |
|
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. |
|
vios_list entry |
string |
The state of the Virtual I/O Server logical partition. For the Virtual I/O Server to be |
|
vios_list entry |
string |
The state of the Resource Monitoring and Control component of
the Virtual I/O Server. For the VIOS to be |
|
vios_list entry |
boolean |
Whether the VIOS can be used for storage connectivity. The
VIOS state and |
|
vios_list entry |
integer |
The total number of Fibre Channel ports that are owned by this VIOS entry. |
|
vios_list entry |
object |
The number of ports that are
considered |
|
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
|
|
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
|
|
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. |
|
vios_list entry |
list of objects |
Contains an entry for each Fibre Channel port that is owned
by the VIOS. See the VIOS |
|
fcport_list entry |
string |
The name of the Fibre Channel port. For example,
|
|
fcport_list entry |
string |
The ID of the Fibre Channel port. This ID is used to refer to the port by other APIs. |
|
fcport_list entry |
string |
The worldwide port name. Generally a unique hexadecimal string. |
|
fcport_list entry |
string |
The parent Fibre Channel adapter ID. |
|
fcport_list entry |
string |
The fabric identifier, which is managed by PowerVC, that the Fibre Channel port is logged in to. Valid
values are |
|
fcport_list entry |
boolean |
|
|
fcport_list entry |
string |
Optional. This is only valid when
|
|
fcport_list entry |
string |
Optional. |
|
fcport_list entry |
string |
The status of the Fibre Channel port. These are the possible
values:
|
|
fcport_list entry |
string |
The NPIV status of the Fibre Channel port. These are the
possible values:
|
|
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. |
- Normal response code: 200 (OK)
- Error Response Codes: Bad Request (400®), Unauthorized (401), Not Found (404), Forbidden (403)
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
fabric
, enabled
, and
port_tag
. For details, see these sections:
Name | Style | Type | Description |
---|---|---|---|
|
body |
list of objects |
Each element contains Fibre Channel port metadata for each port to update. |
|
body |
string |
The ID of the Fibre Channel port to update the metadata for. |
|
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 |
|
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 |
|
body |
string |
Optional. This is only valid when
|
|
body |
string |
Optional. The fabric identifier, which is managed by PowerVC, that the Fibre Channel port is logged in to. Valid
values are |
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"
}
]
}
- Normal response code: 204 (No Content)
- Error Response Codes: Bad Request (400), Unauthorized (401), Not Found (404), Forbidden (403)
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.
Name | Style | Type | Description |
---|---|---|---|
|
URI |
UUID |
The image ID to return compatible storage connectivity groups. |
|
query |
string |
Optional. Filter storage connectivity groups to only those that contain the specified hypervisor host name of the compute host. |
|
query |
string |
Optional. Return detailed properties of each storage connectivity group instead of just the display name and ID. |
GET
/v2.1/{tenant_id}/images/{image_id}/storage-connectivity-groups
Content-Type: application/json
Accept: application/json
X-Auth-Token : 16ac964aae06430aa4c8e1588c3740b3
Name | Style | Type | Description |
---|---|---|---|
|
body |
string |
Display name of the storage connectivity group. |
|
body |
UUID |
The ID of the storage connectivity group. |
details
option is provided.- Normal response code: 200 (OK)
- Error Response Codes: Bad Request (400), Unauthorized (401), Not Found (404), Forbidden (403)
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 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
.
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.
- The Fibre Channel port status is
- 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.
Name | Style | Type | Description |
---|---|---|---|
|
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
|
|
query |
string |
Optional. Similar to the |
|
query |
string |
Optional. However, this option is required if an
|
|
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. |
|
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. |
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
Name | Style | Type | Description |
---|---|---|---|
|
body |
object |
The information that is returned in the body is indexed by
the hypervisor host name of the compute host.
|
|
body |
string |
The hypervisor host name of the viable host element. This is
the same value as the key listed in
|
- Normal response code: 200 (OK)
- Error Response Codes: Bad Request (400), Unauthorized (401), Not Found (404), Forbidden (403)
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
Name | Style | Type | Description |
---|---|---|---|
|
URI |
UUID |
The ID of the managed server instance. |
GET
/v2.1/{tenant_id}/servers/{server_id}/storage-hosts
Content-Type: application/json
Accept: application/json
X-Auth-Token : 16ac964aae06430aa4c8e1588c3740b3
Name | Style | Type | Description |
---|---|---|---|
|
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. |
|
value in objects |
string |
The storage provider backend name. This is the
|
|
value in objects |
boolean |
True if the storage provider is a candidate for attaching boot volumes. False otherwise. |
|
value in objects |
boolean |
True if the storage provider is a candidate for attaching data volumes. False otherwise. |
- Normal response code: 200 (OK)
- Error Response Codes: Bad Request (400), Unauthorized (401), Not Found (404), Forbidden (403)
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"
}
]
}