Base storage connectivity group APIs

Edit online

The lifecycle management APIs cover different operations for storage connectivity groups. Use the APIs to get the list of storage connectivity groups, view details of a storage connectivity group, and add, edit, delete the storage connectivity groups through POST, PUT, and DELETE operations.

Note: PowerVC uses the term storage template instead of volume type.

Lifecycle management API options
Create a storage connectivity group
Return a list of storage connectivity groups
Return detailed properties for a list of storage connectivity groups
Return details of a storage connectivity group
Update a storage connectivity group
Delete a storage connectivity group
Get candidate images by storage connectivity group
Return virtual machine references that are associated with a specific storage connectivity group
Return a list of storage templates for accessible storage providers
Return the list of volumes to which a storage connectivity group can provide connectivity

Lifecycle management API options

Table 1. Lifecycle management API options to manage storage connectivity groups
Method	URI	Description
POST	`/v2.1/{tenant_id}/storage-connectivity-groups`	Creates a storage connectivity group. Alternatively, use `priority_external` or `priority_cluster` in POST body to create the priority order for the storage connectivity group.
GET	`/v2.1/{tenant_id}/storage-connectivity-groups`	Returns a list of storage connectivity groups.
GET	`/v2.1/{tenant_id}/storage-connectivity-groups/detail`	Returns details on a list of storage connectivity groups.
GET	`/v2.1/{tenant_id}/storage-connectivity-groups/{scg_id}`	Returns the detailed information for the storage connectivity group that is specified by ID {scg_id}.
PUT	`/v2.1/{tenant_id}/storage-connectivity-groups/{scg_id}`	Updates the storage connectivity group with the specified scg_id.
DELETE	`/v2.1/{tenant_id}/storage-connectivity-groups/{scg_id}`	Deletes the specified storage connectivity group.
GET	`/v2.1/{tenant_id}/storage-connectivity-groups/{scg_id}/images`	Returns a list of candidate images for the storage connectivity group that is specified by `{scg_id}`.
GET	`/v2.1/{tenant_id}/storage-connectivity-groups/{scg_id}/serverlist`	Returns a list of virtual machines that are associated with the storage connectivity group that is specified by `{scg_id}`.
GET	`/v2.1/{tenant_id}/storage-connectivity-groups/{scg_id}/volume-types`	Returns a list of volume types that are supported by storage providers and that are accessible by the storage connectivity group that is specified by `{scg_id}`.
GET	`/v2.1/{tenant_id}/storage-connectivity-groups/{scg_id}/volumes`	Returns a list of volumes that are applicable to the storage connectivity group that are specified by `{scg_id}`.

Create a storage connectivity group

The request body takes a nested JSON object structure with the properties that must be set for the new storage connectivity group. display_name, fc_storage_access, and vios_ids are required properties. The releases starting from PowerVC 1.2.1 support the cluster_provider_name property to specify that the storage connectivity group allows connectivity to the shared storage pool for the provider.

The response header Location contains the URL to access the new storage connectivity group resource. An error is returned for the following conditions:

No properties are specified in the request body objects.
An object is not given in the request body.
One or more of the following keys that are required are missing in the request
- display_name
- fc_storage_access
- vios_ids
.
A non user-editable property is specified in the request body. The user-editable properties are: display_name, enabled, fc_storage_access, auto_add_vios, cluster_provider_name, port_tag, include_untagged, boot_connectivity, data_connectivity, vios_redundancy, exact_redundancy, vios_ids, init_pg_data, and boot_ipgs.
A badly formatted request structure as determined by the web server.
Property values that have an improper type. For example, an integer is given when a string type is expected.
A display_name is given that is a duplicate for another storage connectivity group (409 Conflict). They must be unique.
Other conflict situations. For example, npiv and pv-vscsi cannot both be specified in the same boot_connectivity or data_connectivity list.

Request

Table 2. Parameters in the request for creating a storage connectivity group
Name	In	Type	Description
`storage_connectivity_group`	body	object	Contains the storage connectivity group properties that are to be set. The properties are given in the subsequent table rows.
`display_name`	body	string	The display name for the new storage connectivity group to create.
`boot_connectivity`	storage_connectivity_groups	list of strings	Optional. List of allowed connectivity types for the ephemeral boot volume of a virtual machine. The supported connectivity types are: `npiv`, `pv-vscsi`, and `ibm-ssp`. You cannot specify both `npiv` and `pv-vscsi`. If `cluster_provider_name` is specified, the default is `[npiv, ibm-ssp]`. Otherwise, the default is `[npiv]`. npiv Fibre Channel connectivity with N_Port ID Virtualization, where virtual machines have virtual adapters that are used to connect to the hosted virtual NPIV ports. Additionally, the virtual machines are zoned independently on the Fibre Channel switches during volume attachment. pv-vscsi Physical volume virtual SCSI connectivity over Fibre Channel. Virtual machines have vSCSI adapters to Virtual I/O Server -hosted physical volumes and they are not independently zoned at volume attach time. ibm-ssp Shared storage pool connectivity. Virtual machines have vSCSI adapters to a shared storage pool hosted by a Virtual I/O Server cluster.
`data_connectivity`	storage_connectivity_groups	list of strings	Optional. List of allowed connectivity types for the ephemeral boot volume of a virtual machine. The supported connectivity types are: `npiv`, `pv-vscsi`, and `ibm-ssp`. You cannot specify both `npiv` and `pv-vscsi`. See `boot_connectivity` for details about each type. If `cluster_provider_name` is specified, the default is `[npiv, ibm-ssp]`. Otherwise, the default is `[npiv]`.
`vios_redundancy`	storage_connectivity_groups	integer	Optional. The minimum number of Virtual I/O Servers to be used for storage volume connectivity on a host. This can be considered VIOS multiplicity. Valid values are positive integers. A value of 1 means only a single Virtual I/O Server is required, for example, for certain development workloads. A value of 2 means dual-VIOS and is appropriate for production workloads. The default value is 1, but this default can be overriden with the nova configuration file property `ibmpowervm_default_vios_redundancy`.
`exact_redundancy`	storage_connectivity_groups	boolean	Optional. Whether the value given by `vios_redundancy` is the exact value or the minimum. If this value is `true`, the number of Virtual I/O Servers that will be used for volume attachment to a virtual machine will be exactly the amount specified for `vios_redundancy`. If `false` is specified, the number of Virtual I/O Servers that will be used for volume attachment will be at least the number specified for `vios_redundancy`, but more could be used. The default is `false`, but this default can be overriden with the nova configuration file property `ibmpowervm_default_exact_redundancy`. In either case, attachments will fail if connectivity is not achieved through the minimum number of Virtual I/O Servers specified by `vios_redundancy`.
`fc_storage_access`	body	boolean	Whether the new storage connectivity group allows NPIV connectivity to registered SAN storage providers. If `boot_connectivity` or `data_connectivity` are also specified and either of those lists contains `npiv`, the value of this parameter must be `true`.
`vios_ids`	body	list of strings	A list of Virtual I/O Server IDs that are to be included as members of the new storage connectivity group. These IDs are returned by the host-storage-topologies REST API in the `vios_list` entries.
`cluster_provider_name`	body	string	Optional. The `storage_hostname` of the shared storage pool provider as returned by the Cinder storage-providers REST API. If `ibm-ssp` is specified in either `boot_connectivity` or `data_connectivity`, this parameter must also be specified. If `boot_connectivity` and `data_connectivity` are not specified but `fc_storage_access` is specified as `false`, this parameter must also be specified.
`auto_add_vios`	body	boolean	Optional. Whether the new storage connectivity group automatically adds applicable Virtual I/O Servers as members when they are discovered from the registered hosts.
`port_tag`	body	string	Optional. The port tag string to set on the new storage connectivity group. Only Fibre Channel ports with a matching `port_tag` are allowed to provide connectivity. The `port_tag` value only applies to `npiv` and `pv-vscsi` for a storage connectivity group.
`include_untagged`	body	boolean	Specifies whether to include untagged ports as eligible for attachment. Use `true` to include untagged ports and `false` if you do not want them included. The default is `false`.
`init_pg_data`	body	object	Optional. Used to create initiator port groups (IPG). Format: `{‘ipg-name-1‘ : “<FC-Port-1>, <FC-Port-2>“}, {‘ipg-name‘ : “<FC-Port-2>, <FC-Port-4>“}`. Each valid and unique-named initiator port group should be a subset of the existing selected VIOSs. Each IPG should satisfy storage connectivity group’s constraints.
`boot_ipgs`	body	string	Optional. Used to tag IPGs as ‘boot-only‘. Format: `{‘boot_ipgs‘ : “ipg-1, ipg-2“}`. Each specified IPG in the field should be a subset of the specified initiator port groups (`init_pg_data`).

The following is an example of a POST operation to create a storage connectivity group called myScg. The vios_ids list element contains IDs that come from the response to a GET host-storage-topologies API request. For information, see Additional storage connectivity groups APIs and extensions.

Example

POST	
/v2.1/{tenant_id}/storage-connectivity-groups
Content-Type: application/json
Accept: application/json
X-Auth-Token : 16ac964aae06430aa4c8e1588c3740b3
{
 "storage_connectivity_group": {
  "auto_add_vios": false,
  "fc_storage_access": true,
  "boot_connectivity": ["ibm-ssp"],
  "data_connectivity": ["npiv"],
  "vios_ids": [
   "8246L2D_10085AA##2",
   "8246L2D_100857A##1"
  ],
  "enabled": true,
  "display_name": "myScg"
  "cluster_provider_name": "222075b42cb50d11e3830b6cae8b027c55"
  "vios_redundancy": 2,
  "exact_redundancy": true,
  
 }
}

Response

Table 3. Parameters in the response for creating a storage connectivity group
Name	In	Type	Description
`created_id`	body	UUID	The ID string of the newly created storage connectivity group.
`location`	header	URI	The REST URL to return details of the new storage connectivity group that was created.

Response codes

Normal response code: Created (201)
Error Response Codes: Bad Request (400®), Unauthorized (401), Forbidden (403), Not Found (404), Conflict (409)

Example response

Status Code: 201 Created
Connection: keep-alive
Content-Type: application/json; charset=UTF-8
Location: /v2.1/{tenant_id}/storage-connectivity-groups/17c0f3e5-af60-440b-b46a-1024d43b6dca
6dca
X-Compute-Request-Id: req-276d39b4-7159-4b13-994d-0736775a8d7b

{
   "created_id": "17c0f3e5-af60-440b-b46a-1024d43b6dca"
}

Return a list of storage connectivity groups

This operation does not take a REST body and returns a JSON data structure. The JSON data structure is an object that contains the key storage_connectivity_groups with a value that is a list of storage connectivity group objects. The contents of the nested objects contain the display name and ID. The detail API variation gives a much more detailed set of properties.

Request

Table 4. Parameters in the request for returning a list of storage connectivity groups
Name	In	Type	Description
`sort_type`	query	string	Optional. Valid values are `external` or `cluster`. The list is returned in priority order. A storage connectivity group can have either a cluster priority or an external priority or both. If a sort type is specified, only the storage connectivity groups that have a priority set that matches the sort type are returned. If `cluster` is specified and the `cluster_provider` option is given, then the priority order of only those groups that are applicable to the particular shared storage pool cluster provider are returned. If `external` is specified, then the `boot_connectivity` or `data_connectivity` list property must contain either npiv or pv-vscsi, for external SAN connectivity.
`enabled_only`	query	string	Optional. Valid values are `true` or `false`. Default value is `false`. If the value is `true`, then only the storage connectivity groups that are enabled for deployment are returned. Else all storage connectivity groups are returned.
`cluster_provider`	query	string	Optional. The storage provider host name of the shared storage pool cluster to be used. This option is valid only if the `sort_type` query parameter is given with `cluster` value. The `cluster_provider` is the same name as the `storage_hostname` property that is returned by the Cinder storage-providers REST API.
`deploy_ready_only`	query	string	Optional. Valid values are `true` or `false`. Default value is `false`. If the value is `true`, then the storage connectivity groups that are returned are the ones that have one or more Virtual I/O Server members and that have `storage_ready=true` defined and there is at least one applicable storage provider not in error state that can be used for boot or data volume storage.

The following is an example of a GET request and response for listing the defined storage connectivity groups that are deploy-ready.

Example

GET	
/v2.1/{tenant_id}/storage-connectivity-groups?deploy_ready_only=true
Content-Type: application/json
Accept: application/json
X-Auth-Token : b35c9574458e40e49d32d092895e1c2d

Response

Table 5. Parameters in the response for returning a list of storage connectivity groups
Name	In	Type	Description
`display_name`	body	string	Display name of the storage connectivity group.
`id`	body	UUID	The ID of the storage connectivity group.

Response codes

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

Example response

Status Code: 200 OK
Connection: keep-alive
Content-Type: application/json; charset=UTF-8
X-Compute-Request-Id: req-3fc28fef-bace-48b4-a141-8480e67dcbb8

{
 "storage_connectivity_groups": [
  {
   "display_name": "Any host, all VIOS",
   "id": "350d9550-ce2d-4384-9dae-06ff0bad6f7f"
  },
  {
   "display_name": "Any host in p730-cluster",
   "id": "b4f344e5-ad60-447c-936c-91b33901e6cc"
  },
  {
   "display_name": "Production",
   "id": "d205945b-c21f-4b88-b3a9-6c2e197fe981"
  },
  {
   "display_name": "Development",
   "id": "547f0ab6-88d6-42af-8bb4-333cbe1619bf"
  }
 ]
}

Return detailed properties for a list of storage connectivity groups

This operation does not take a REST body and returns a JSON data structure. Returns a list of storage connectivity groups. Each storage connectivity group in the list contains a set of objects with detailed properties. By default, some computed and nested properties are excluded. To view all properties, provide the include_ports query option. The list of retuned groups is filtered and sorted based on the options that are provided.

Request

Table 6. Parameters in the request for returning details of storage connectivity groups
Name	In	Type	Description
`sort_type`	query	string	Optional. Valid values are `external` or `cluster`. The list is returned in priority order. A storage connectivity group can have either a cluster priority or an external priority or both. If a sort type is specified, only the storage connectivity groups that have a priority set that matches the sort type are returned. If `cluster` is specified and the `cluster_provider` option is given, then the priority order of only those groups that are applicable to the particular shared storage pool cluster provider are returned. If `external` is specified, then the `boot_connectivity` or `data_connectivity` list property must contain either npiv or pv-vscsi, for external SAN connectivity.
`enabled_only`	query	string	Optional. Valid values are `true` or `false`. Default value is `false`. If the value is `true`, then only the storage connectivity groups that are enabled for deployment are returned. Else all storage connectivity groups are returned.
`cluster_provider`	query	string	Optional. The storage provider host name of the shared storage pool cluster to be used. This option is valid only if the `sort_type` query parameter is given with `cluster` value. The `cluster_provider` is the same name as the `storage_hostname` property that is returned by the Cinder storage-providers REST API.
`deploy_ready_only`	query	string	Optional. Valid values are `true` or `false`. The default value is `false`. If the value is `true`, then the storage connectivity groups that are returned meet all of these requirements: They have at least as many Virtual I/O Server members as the number specified for `vios_redundancy`. They have the value `storage_ready=true`, which is returned with the include_ports option. There is one or more applicable storage providers not in error state that can be used for boot or data volume storage.
`include_ports`	query	string	Optional. Valid values are `true` or `false`. The default value is `false`. If the value is `true`, additional details are returned, including these: The Fibre Channel port information in the `host_list` hierarchy of VIOS member resources for the storage connectivity group. Computed connectivity information, such as `storage_ready`, `connectivity_types`, and `port_ready_count`. Health status information, such as `health_value`, `value_reasons`, and `port_health`.

The following is an example of a GET request and response for the detailed listing of all the defined storage connectivity groups that are deploy-ready.

Example

GET	
/v2.1/{tenant_id}/storage-connectivity-groups/detail
Content-Type: application/json
Accept: application/json
X-Auth-Token : b35c9574458e40e49d32d092895e1c2d

Response

Table 7. Parameters in the response for returning details of storage connectivity groups
Name	Body Parent	Type	Description
`storage_connectivity_groups`	body	list of objects	Root body parameter that contains a list of storage connectivity groups.
`display_name`	storage_connectivity_groups	string	Display name of the storage connectivity group.
`id`	storage_connectivity_groups	UUID	The ID of the storage connectivity group.
`auto_add_vios`	storage_connectivity_groups	boolean	Whether to add VIOS automatically to the storage connectivity group. The values are `true` or `false`.
`boot_connectivity`	storage_connectivity_groups	list of strings	Required for GET operations, optional for POST and PUT operations. List of allowed connectivity types for the ephemeral boot volume of a virtual machine. The supported connectivity types are: `npiv`, `pv-vscsi`, and `ibm-ssp`.
`data_connectivity`	storage_connectivity_groups	list of strings	Required for GET operations, optional for POST and PUT operations. List of allowed connectivity types for attached data volumes of a virtual machine. The supported connectivity types are: `npiv`, `pv-vscsi`, and `ibm-ssp`.
`vios_redundancy`	storage_connectivity_groups	integer	Required for GET operations, optional for POST and PUT operations. The minimum number of Virtual I/O Servers to be used for storage volume connectivity on a host. This can be considered VIOS multiplicity. Valid values are positive integers.
`exact_redundancy`	storage_connectivity_groups	boolean	Required for GET operations, optional for POST and PUT operations. Specifies whether the value given by `vios_redundancy` is the exact value or the minimum. If this value is `true`, the number of Virtual I/O Servers that will be used for volume attachment to a virtual machine will be exactly the amount specified for `vios_redundancy`. If `false` is specified, the number of Virtual I/O Servers that will be used for volume attachment will be at least the number specified for `vios_redundancy`, but more could be used. With either value, attachments will fail if connectivity is not achieved through the minimum number of Virtual I/O Servers specified by `vios_redundancy`.
`fc_storage_access`	storage_connectivity_groups	boolean	Whether the storage connectivity group provides access to registered Fibre Channel SAN storage devices. Valid values are `true` or `false`.
`enabled`	storage_connectivity_groups	boolean	Whether the storage connectivity group is enabled for new virtual machine deployments. The values are `true` or `false`. This setting does not affect the use of the storage connectivity group by existing virtual machine deployments.
`auto_defined`	storage_connectivity_groups	boolean	Whether the storage connectivity group was automatically defined. The value is `true` for default groups and `false` for custom storage connectivity groups.
`priority_external`	storage_connectivity_group, storage_connectivity_groups	integer	Optional. The field is used to sort the storage connectivity groups that have `fc_storage_access` set to `true`. Certain APIs return the storage connectivity groups in priority order. The `priority_external` field is not set directly. Instead, it is set by using a POST with `priority_lists` information in the body.
`priority_cluster`	storage_connectivity_groups	integer	Optional. Use the field to sort the storage connectivity groups that have an association with a shared storage pool provider. This association is given in the `vios_cluster` property of a storage connectivity group, if the property exists. Certain APIs return the storage connectivity groups in priority order. The `priority_cluster` field is not set directly. Instead, it is set by using a POST with `priority_lists` information in the body.
`created_at`	storage_connectivity_groups	date-time	The date and time when the storage connectivity group was registered in PowerVC
`updated_at`	storage_connectivity_groups	date-time	Optional. The date and time when the storage connectivity group was updated in PowerVC. If the field is not returned, then it implies that the storage connectivity group was not updated since it was created.
`port_ready_count`	storage_connectivity_groups	object	The number of ports that are considered `storage_ready` for each connectivity type that is configured in the storage connectivity group. The key can be `pv_vscsi`, `npiv`, or `ibm_ssp`. This is returned only when `include_ports=true` option is passed.
`vios_ready_count`	storage_connectivity_groups	integer	The value is the number of Virtual I/O Servers that are `storage_ready` across the whole storage connectivity group. Returned only when `include_ports=true` option is passed.
`applicable_providers`	storage_connectivity_groups	list of strings	List of storage provider host names that the storage connectivity group can provide access to. The storage provider host names are not display names. The list of storage providers is a computed value. If `fc_storage_access` is `true`, then all registered SAN storage providers that are not in error state are included. If there is an associated `vios_cluster`, then the shared storage pool provider is included if it is not in error state.
`port_tag`	storage_connectivity_groups	string	The port tag string of the storage connectivity group. This property is only returned when a port tag is set. Only the Fibre Channel ports with a matching `port_tag` are allowed to provide connectivity through this connectivity group.
`include_untagged`	storage_connectivity_group	boolean	Specifies whether to include untagged ports as eligible for attachment. This property is only returned when a port tag is set. A value of `true` means that the ports are included, and `false` means that they will not be included.
`vios_cluster`	storage_connectivity_groups	object	One or more shared storage pool provider properties. Returned only when the storage connectivity group is associated with a shared storage pool provider.
`provider_name`	vios_cluster	string	The name of the shared storage pool provider that is associated with the storage connectivity group. It is the same name as the `storage_hostname` property that is returned by the Cinder storage-providers REST API.
`provider_display_name`	vios_cluster	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.
`backend_state`	vios_cluster	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.
`host_list`	storage_connectivity_groups	list of objects	Contains a set of objects for each compute host with one or more Virtual I/O Servers that are members of this storage connectivity group.
`name`	body	string	The hypervisor host name of the compute host. This value is also referred to as the machine-type-model-serial name of PowerVM® hosts.
`vios_ready_count`	body	integer	The value is the number of Virtual I/O Servers that are `storage_ready` for this compute host. Returned only when `include_ports=true` option is passed.
`vios_list`	body	list of objects	Contains a set of objects for each Virtual I/O Server member of the storage connectivity group that is also a partition on the compute host.
`name`	body	string	The name of the Virtual I/O Server.
`lpar_id`	body	integer	The ID of the Virtual I/O Server logical partition. The ID is typically a positive integer.
`id`	body	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 VIOS entries.
`state`	body	string	The state of the Virtual I/O Server logical partition. For the VIOS 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`	body	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. Possible values include `active`, `inactive`, `none`, `unknown`, and `busy`.
`total_fcport_count`	body	integer	The total number of Fibre Channel ports that are owned by this VIOS entry. Returned only when `include_ports=true` option is passed.
`port_ready_counts`	body	integer	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`. Returned only when `include_ports=true` is passed.
`connectivity_types`	body	list of strings	Optional. The set of connectivity types currently allowed by the Virtual I/O Server entry. This might be different than the combined values specified for `boot_connectivity` and `data_connectivity`. This is returned only when `include_ports=true` is specified.
`fcport_list`	body	list of objects	The Fibre Channel port properties that are returned are a subset of the port properties that are given by the host-storage-topologies REST API. Returned only when `include_ports=true` option is passed. Contains an object for each owned Fibre Channel port that is computed to be `ready`. See the `port_ready_count` description for details.
`name`	body	string	The name of the Fibre Channel port. For example, `fcs0`.
`id`	body	string	The ID of the Fibre Channel port. This ID is used to refer to the port by other APIs.
`wwpn`	body	string	The worldwide port name.
`status`	body	string	Optional. The port's status value.
`adapter_id`	body	string	The parent Fibre Channel adapter ID.
`fabric`	body	string	The managed fabric identifier 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.
`available_connections`	body	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 up connections.
`health_status`	body	object	Optional. Health status information for the storage connectivity group. This is only returned if the `include_ports` query option is specified on the API request.
`boot_health`	body	string	Optional. Reflects the current connectivity health status for the storage connectivity group to be used for boot volume deployment. `OK`, `Inactive`, `SCG_Disabled`, or `No_Providers`. If the status is `OK`, then the storage connectivity group can be used for deployment. If not, the reasons for this status are given in the `value_reasons` property.
`data_health`	body	string	Optional. Reflects the current connectivity health status for the storage connectivity group to be used for data volume deployment. `OK`, `Inactive`, `SCG_Disabled`, or `No_Providers`. If the status is `OK`, then the storage connectivity group can be used for deployment. If not, the reasons for this status are given in the `value_reasons` property.
`value_reasons`	body	list of strings	Optional. The list of issues found when evaluating the `health_value` for the storage connectivity group. These are high-level reasons; detailed explanations can be found for each host in the reasons field of the `member_status` property.
`effective_connectivity`	body	list of strings	Optional. The list of the effective connectivity types when the API was called. If `health_value` is OK, this list should be the combination of the `data_connectivity` and `boot_connectivity` values specified for the storage connectivity group. If environmental information gathered shows that one or more connectivity types are not available, this is a subset of the specified values. If any host member allows a connectivity type, it is listed.
`member_status`	body	object	Optional. Lists health status information for each host. The key should be the name of the host that was specified in the `host_list` property.
`connectivity`	body	string	Optional. A comparison between the collection of effective `connectivity_types` of all Virtual I/O Server partitions at a point in time and the connectivity types defined in the storage connectivity group in the `boot_connectivity` and `data_connectivity` lists. Possible values are `full`, `partial`, or `none`. A value of `full` means that there are sufficient Virtual I/O Servers currently supporting the full set of connectivity types defined in `boot_connectivity` and `data_connectivity`. This value applies to a specific host. Within the host there is a set of Virtual I/O Server partitions; each has an effective connectivity list. The connectivity types listed for each partition depends on its topology and what the environmental conditions allow. The Virtual I/O Server connectivity types a partition allows can be found in the following property: host_list > vios_list > connectivity_types.
`reasons`	body	list of strings	Optional. A list of warning messages that give details about why a host might have partial or no connectivity.
`effective_fabrics`	body	list of strings	Optional. The names of the switch fabrics that the host has connectivity with. This property is only present if the storage connectivity group is configured for a connectivity type that can use the fabrics. For example, `npiv`.
`port_health`	body	list of strings	Optional. A list of messages that explain why one or more ports are not available for use by one or more connectivity types.

Response codes

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

Example response

Status Code: 200 OK
Connection: keep-alive
Content-Type: application/json; charset=UTF-8
X-Compute-Request-Id: req-06d6a1b8-7670-4d7c-bbb8-0ff3890befca
{
 "storage_connectivity_groups": [
  {
   "auto_add_vios": true,
   "fc_storage_access": true,
   "display_name": "Any host, all VIOS",
   "boot_connectivity": [
    "npiv"
   ],   
   "enabled": true,
   "created_at": "2014-03-31T18:21:52.963174",
   "host_list": [
    {
     "name": "8231E2D_109EFDT",
     "vios_list": [
      {
       "lpar_id": 2,
       "state": "running",
       "id": "8231E2D_109EFDT##2",
       "rmc_state": "active",
       "name": "vios2230_2"
      },
      {
       "lpar_id": 1,
       "state": "running",
       "id": "8231E2D_109EFDT##1",
       "rmc_state": "active",
       "name": "vios2230_1"
      }
     ]
    }
   ],
   "priority_external": 1,
   "vios_redundancy": 1,
   "data_connectivity": [
    "npiv"
   ],   
   "auto_defined": true,
   "applicable_providers": [],
   "id": "350d9550-ce2d-4384-9dae-06ff0bad6f7f"
     
  },
  {
   "auto_add_vios": false,
   "fc_storage_access": true,
   "display_name": "Development",
   "boot_connectivity": [
    "ibm_ssp"
   ],
   "enabled": true,
   "created_at": "2014-04-02T21:33:45.474298",
   "host_list": [
    {
     "name": "8231E2D_109EFDT",
     "vios_list": [
      {
       "lpar_id": 2,
       "state": "running",
       "id": "8231E2D_109EFDT##2",
       "rmc_state": "active",
       "name": "vios2230_2"
      }
     ]
    }
   ],
   "updated_at": "2014-04-03T17:40:04.332026",
   "priority_cluster": 2,
   "port_tag": "porttag",
   "include_untagged": false,
   "exact_redundancy": false,
     "data_connectivity": [
    "ibm_ssp",
    "npiv"
   ],
   "vios_redundancy": 1,
   "auto_defined": false,
   "applicable_providers": [
    "222075b42cb50d11e3830b6cae8b027c55"
   ],
   "id": "547f0ab6-88d6-42af-8bb4-333cbe1619bf",
   "vios_cluster": {
    "provider_name": "222075b42cb50d11e3830b6cae8b027c55",
    "provider_display_name": "p730-cluster",
    "backend_state": "running"
   }
  }
 ]
}

Return details of a storage connectivity group

This operation does not take a REST body and returns a JSON data structure. The JSON data structure has data that contains properties of the storage connectivity group.

Request

Table 8. Parameters in the request for returning details of a specific storage connectivity group
Name	In	Type	Description
`scg_id`	URI	UUID	The ID for the storage connectivity group.
`include_ports`	query	string	Optional. Valid values are `true` or `false`. The default value is `false`. If the value is `true`, additional details are returned, including these: The Fibre Channel port information in the `host_list` hierarchy of VIOS member resources for the storage connectivity group. Computed connectivity information, such as `storage_ready`, `connectivity_types`, and `port_ready_count`. Health status information, such as `health_value`, `value_reasons`, and `port_health`.

The following is an example of a GET request and response to return the details of the auto-defined storage connectivity group for a cluster shared storage pool ID.

Example

GET	
/v2.1/{tenant_id}/storage-connectivity-groups/{scg_id}?include_ports=true
Content-Type: application/json
Accept: application/json
X-Auth-Token : 5cc0c563d6114b3b8a3fcc8b7a3842c5

Response

Table 9. Parameters in the response for returning details of a specific storage connectivity group
Name	Body Parent	Type	Description
`storage_connectivity_group`	body	list of objects	Root body parameter that contains a list of storage connectivity groups.
`display_name`	storage_connectivity_group	string	Display name of the storage connectivity group.
`boot_connectivity`	storage_connectivity_groups	list of strings	Required for GET operations, optional for POST and PUT operations. List of allowed connectivity types for the ephemeral boot volume of a virtual machine. The supported connectivity types are: `npiv`, `pv-vscsi`, and `ibm-ssp`.
`data_connectivity`	storage_connectivity_groups	list of strings	Required for GET operations, optional for POST and PUT operations. List of allowed connectivity types for attached data volumes of a virtual machine. The supported connectivity types are: `npiv`, `pv-vscsi`, and `ibm-ssp`.
`vios_redundancy`	storage_connectivity_groups	integer	Required for GET operations, optional for POST and PUT operations. The minimum number of Virtual I/O Servers to be used for storage volume connectivity on a host. This can be considered VIOS multiplicity. Valid values are positive integers.
`exact_redundancy`	storage_connectivity_groups	boolean	Required for GET operations, optional for POST and PUT operations. Specifies whether the value given by `vios_redundancy` is the exact value or the minimum. If this value is `true`, the number of Virtual I/O Servers that will be used for volume attachment to a virtual machine will be exactly the amount specified for `vios_redundancy`. If `false` is specified, the number of Virtual I/O Servers that will be used for volume attachment will be at least the number specified for `vios_redundancy`, but more could be used. With either value, attachments will fail if connectivity is not achieved through the minimum number of Virtual I/O Servers specified by `vios_redundancy`.
`id`	storage_connectivity_group	UUID	The ID of the storage connectivity group.
`auto_add_vios`	storage_connectivity_group	boolean	Whether to add VIOS automatically to the storage connectivity group. The values are `true` or `false`.
`fc_storage_access`	storage_connectivity_group	boolean	Whether the storage connectivity group provides access to registered Fibre Channel SAN storage devices. Valid values are `true` or `false`.
`enabled`	storage_connectivity_group	boolean	Whether the storage connectivity group is enabled for new virtual machine deployments. The values are `true` or `false`. This setting does not affect the use of the storage connectivity group by existing virtual machine deployments.
`auto_defined`	storage_connectivity_group	boolean	Whether the storage connectivity group was automatically defined. The value is `true` for default groups and `false` for custom storage connectivity groups.
`priority_external`	storage_connectivity_group	integer	Optional. The field is used to sort the storage connectivity groups that have `fc_storage_access` set to `true`. Certain APIs return the storage connectivity groups in priority order. The `priority_external` field is not set directly. Instead, it is set by using a POST with `priority_lists` information in the body.
`priority_cluster`	storage_connectivity_group	integer	Optional. Use the field to sort the storage connectivity groups that have an association with a shared storage pool provider. This association is given in the `vios_cluster` property of a storage connectivity group, if the property exists. Certain APIs return the storage connectivity groups in priority order. The `priority_cluster` field is not set directly. Instead, it is set by using a POST with `priority_lists` information in the body.
`created_at`	storage_connectivity_group	date-time	The date and time when the storage connectivity group was registered in PowerVC
`updated_at`	storage_connectivity_group	date-time	Optional. The date and time when the storage connectivity group was updated in PowerVC. If the field is not returned, then it implies that the storage connectivity group was not updated since it was created.
`port_ready_count`	storage_connectivity_group	integer	The number of ports that are considered `storage_ready` for each connectivity type that is configured in the storage connectivity group. The key can be `pv_vscsi`, `npiv`, or `ibm_ssp`.
`vios_ready_count`	storage_connectivity_group	integer	The value is the number of Virtual I/O Servers that are `storage_ready` across the whole storage connectivity group. Returned only when `include_ports=true` option is passed.
`applicable_providers`	storage_connectivity_group	list of strings	List of storage provider host names that the storage connectivity group can provide access to. The storage provider host names are not display names. The list of storage providers is a computed value. If `fc_storage_access` is `true`, then all registered SAN storage providers that are not in error state are included. If there is an associated `vios_cluster`, then the shared storage pool provider is included if it is not in error state.
`port_tag`	storage_connectivity_group	string	The port tag string of the storage connectivity group. This property is only returned when a port tag is set. Only the Fibre Channel ports with a matching `port_tag` are allowed to provide connectivity through this connectivity group.
`include_untagged`	storage_connectivity_group	boolean	Specifies whether to include untagged ports as eligible for attachment. This property is only returned when a port tag is set. A value of `true` means that the ports are included, and `false` means that they will not be included.
`vios_cluster`	storage_connectivity_group	objects	One or more shared storage pool provider properties. Returned only when the storage connectivity group is associated with a shared storage pool provider.
`provider_name`	vios_cluster	string	The name of the shared storage pool provider that is associated with the storage connectivity group. It is the same name as the `storage_hostname` property that is returned by the Cinder storage-providers REST API.
`provider_display_name`	vios_cluster	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.
`backend_state`	vios_cluster	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.
`host_list`	storage_connectivity_group	list of objects	Contains an object for each compute host with one or more Virtual I/O Servers that are members of this storage connectivity group.
`name`	body	string	The hypervisor host name of the compute host. This value is also referred to as the machine-type-model-serial name of PowerVM hosts.
`port_ready_count`	body	object	The number of ports that are considered `storage_ready` for each connectivity type that is configured for the host. The key can be `pv_vscsi`, `npiv`, or `ibm_ssp`. This is returned only when `include_ports=true` option is passed.
`vios_list`	body	list of objects	Contains an object for each VIOS member of the storage connectivity group that is also a partition on the compute host.
`name`	body	string	The name of the Virtual I/O Server.
`lpar_id`	body	integer	The ID of the Virtual I/O Server logical partition. The ID is typically a positive integer.
`id`	body	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 VIOS entries.
`state`	body	string	The state of the Virtual I/O Server logical partition. For the VIOS 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`	body	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. Possible values include `active`, `inactive`, `none`, `unknown`, and `busy`.
`total_fcport_count`	body	integer	The total number of Fibre Channel ports that are owned by this VIOS entry. Returned only when `include_ports=true` option is passed.
`port_ready_counts`	body	integer	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`. Returned only when `include_ports=true` is passed.
`connectivity_types`	body	list of strings	Optional. The set of connectivity types currently allowed by the Virtual I/O Server entry. This might be different than the combined values specified for `boot_connectivity` and `data_connectivity`. This is returned only when `include_ports=true` is specified.
`fcport_list`	body	list of objects	The Fibre Channel port properties that are returned are a subset of the port properties that are given by the host-storage-topologies REST API. Returned only when `include_ports=true` option is passed. Contains an object for each owned Fibre Channel port that is computed to be `ready`. See the `port_ready_count` description for details.
`name`	body	string	The name of the Fibre Channel port. For example, `fcs0`.
`id`	body	string	The ID of the Fibre Channel port. This ID is used to refer to the port by other APIs.
`wwpn`	body	string	The worldwide port name.
`status`	body	string	The port's status value.
`adapter_id`	body	string	The parent Fibre Channel adapter ID.
`fabric`	body	string	The managed fabric identifier 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.
`available_connections`	body	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 up connections.
`connectivity`	body	list of strings	Lists the types of connectivity that are configured for this port in the specified storage connectivity group.
`health_status`	body	object	Optional. Health status information for the storage connectivity group. This is only returned if the `include_ports` query option is specified on the API request.
`health_value`	body	string	Optional. Reflects the current connectivity health status for the storage connectivity group to be used for boot volume deployment. `OK`, `Inactive`, `SCG_Disabled`, or `No_Providers`. If the status is `OK`, then the storage connectivity group can be used for deployment. If not, the reasons for this status are given in the `value_reasons` property.
`value_reasons`	body	list of strings	Optional. The list of issues found when evaluating the `health_value` for the storage connectivity group. These are high-level reasons; detailed explanations can be found for each host in the reasons field of the `member_status` property.
`effective_connectivity`	body	list of strings	Optional. The list of the effective connectivity types when the API was called. If `health_value` is OK, this list should be the combination of the `data_connectivity` and `boot_connectivity` values specified for the storage connectivity group. If environmental information gathered shows that one or more connectivity types are not available, this is a subset of the specified values. If any host member allows a connectivity type, it is listed.
`member_status`	body	object	Optional. Lists health status information for each host. The key should be the name of the host that was specified in the `host_list` property.
`connectivity`	body	string	Optional. A comparison between the collection of effective `connectivity_types` of all Virtual I/O Server partitions at a point in time and the connectivity types defined in the storage connectivity group in the `boot_connectivity` and `data_connectivity` lists. Possible values are `full`, `partial`, or `none`. A value of `full` means that there are sufficient Virtual I/O Servers currently supporting the full set of connectivity types defined in `boot_connectivity` and `data_connectivity`. This value applies to a specific host. Within the host there is a set of Virtual I/O Server partitions; each has an effective connectivity list. The connectivity types listed for each partition depends on its topology and what the environmental conditions allow. The Virtual I/O Server connectivity types a partition allows can be found in the following property: host_list > vios_list > connectivity_types.
`reasons`	body	list of strings	Optional. A list of warning messages that give details about why a host might have partial or no connectivity.
`effective_fabrics`	body	list of strings	Optional. The names of the switch fabrics that the host has connectivity with. This property is only present if the storage connectivity group is configured for a connectivity type that can use the fabrics. For example, `npiv`.
`port_health`	body	list of strings	Optional. A list of messages that explain why one or more ports are not available for use by one or more connectivity types.
`init_pg_data`	body	object	Optional. Used to create initiator port groups (IPG). Format: `{‘ipg-name-1‘ : “<FC-Port-1>, <FC-Port-2>“}, {‘ipg-name‘ : “<FC-Port-2>, <FC-Port-4>“}`. Each valid and unique-named initiator port group should be a subset of the existing selected VIOSs. Each IPG should satisfy storage connectivity group’s constraints.
`boot_ipgs`	body	string	Optional. Used to tag IPGs as ‘boot-only‘. Format: `{ ‘boot_ipgs‘ : “ipg-1, ipg-2“}`. Each specified IPG in the field should be a subset of the specified initiator port groups (`init_pg_data`).

Response codes

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

Example response

Status Code: 200 OK
Connection: keep-alive
Content-Type: application/json; charset=UTF-8
X-Compute-Request-Id: req-06d6a1b8-7670-4d7c-bbb8-0ff3890befca
{
 "storage_connectivity_group": {
  "auto_add_vios": true,
  "fc_storage_access": true,
  "display_name": "Any host in powervc_demo_cluster",
  "boot_connectivity": [
   "ibm_ssp"
  ],
  "host_list": [
   {
    "vios_list": [
     {
      "name": "vios2230_2",
      "storage_ready": true,
      "lpar_id": 2,
      "total_fcport_count": 4,
      "rmc_state": "active",
      "port_ready_counts": {
       "pv_vscsi": 4,
       "npiv": 2,
      "state": "running",
      "connectivity_types": [
       "ibm_ssp",
       "npiv"
      ],
      "backend_uuid": "7C534C3C-9CED-4F4F-A113-A9FA79CACC5A",
      "fcport_list": [
       {
        "status": "OK",
        "fabric": "B",
        "available_connections": 64,
        "adapter_id": "U78AB.001.WZSJMPJ-P1-C5",
        "wwpn": "10000090FA2A5344",
        "id": "1aU78AB.001.WZSJMPJ-P1-C5-T1",
        "name": "fcs2"
       },
       {
        "status": "OK",
        "fabric": "A",
        "available_connections": 64,
        "adapter_id": "U78AB.001.WZSJMPJ-P1-C5",
        "wwpn": "10000090FA2A5345",
        "id": "1aU78AB.001.WZSJMPJ-P1-C5-T2",
        "name": "fcs3"
       },
       {
        "status": "OK",
        "fabric": "A",
        "available_connections": 64,
        "adapter_id": "U78AB.001.WZSJMPJ-P1-C4",
        "wwpn": "10000090FA2A2377",
        "id": "1aU78AB.001.WZSJMPJ-P1-C4-T2",
        "name": "fcs1"
       },
       {
        "status": "OK",
        "fabric": "B",
        "available_connections": 64,
        "adapter_id": "U78AB.001.WZSJMPJ-P1-C4",
        "wwpn": "10000090FA2A2376",
        "id": "1aU78AB.001.WZSJMPJ-P1-C4-T1",
        "name": "fcs0"
       }
      ],
      "id": "8231E2D_109EFBT##2"
     },
     {
      "name": "vios2230_1",
      "storage_ready": true,
      "lpar_id": 1,
      "total_fcport_count": 4,
      "rmc_state": "active",
      "port_ready_count": {
       "pv_vscsi": 4,
       "npiv": 2,
      "state": "running",
      "connectivity_types": [
       "ibm_ssp",
       "npiv"
      ],
      "backend_uuid": "6C581835-04E3-4A2E-AB64-10976D7F141F",
      "fcport_list": [
       {
        "status": "OK",
        "fabric": "B",
        "available_connections": 64,
        "adapter_id": "U78AB.001.WZSJMPJ-P1-C2",
        "wwpn": "10000090FA2A4F06",
        "id": "1aU78AB.001.WZSJMPJ-P1-C2-T1",
        "name": "fcs0"
       },
       {
        "status": "OK",
        "fabric": "A",
        "available_connections": 64,
        "adapter_id": "U78AB.001.WZSJMPJ-P1-C2",
        "wwpn": "10000090FA2A4F07",
        "id": "1aU78AB.001.WZSJMPJ-P1-C2-T2",
        "name": "fcs1"
       },
       {
        "status": "OK",
        "fabric": "A",
        "available_connections": 64,
        "adapter_id": "U78AB.001.WZSJMPJ-P1-C3",
        "wwpn": "10000090FA2A89CF",
        "id": "1aU78AB.001.WZSJMPJ-P1-C3-T2",
        "name": "fcs3"
       },
       {
        "status": "OK",
        "fabric": "B",
        "available_connections": 64,
        "adapter_id": "U78AB.001.WZSJMPJ-P1-C3",
        "wwpn": "10000090FA2A89CE",
        "id": "1aU78AB.001.WZSJMPJ-P1-C3-T1",
        "name": "fcs2"
       }
      ],
      "id": "8231E2D_109EFBT##1"
     }
    ],
    "name": "8231E2D_109EFBT",
    "vios_ready_count": 2
   },
   {
    "vios_list": [
     {
      "name": "vios2230_2",
      "storage_ready": true,
      "lpar_id": 2,
      "total_fcport_count": 4,
      "rmc_state": "active",
      "state": "running",
      "connectivity_types": [
       "ibm_ssp",
       "npiv"
      ],
      "backend_uuid": "3F8EA7C6-FAD9-428D-B6F5-D7CDB3688782",
      "fcport_list": [
       {
        "status": "OK",
        "fabric": "B",
        "available_connections": 64,
        "adapter_id": "U78AB.001.WZSJMPT-P1-C4",
        "wwpn": "10000090FA2A54EA",
        "id": "1aU78AB.001.WZSJMPT-P1-C4-T1",
        "name": "fcs0"
       },
       {
        "status": "OK",
        "fabric": "A",
        "available_connections": 64,
        "adapter_id": "U78AB.001.WZSJMPT-P1-C4",
        "wwpn": "10000090FA2A54EB",
        "id": "1aU78AB.001.WZSJMPT-P1-C4-T2",
        "name": "fcs1"
       },
       {
        "status": "OK",
        "fabric": "A",
        "available_connections": 63,
        "adapter_id": "U78AB.001.WZSJMPT-P1-C5",
        "wwpn": "10000090FA2A8A27",
        "id": "1aU78AB.001.WZSJMPT-P1-C5-T2",
        "name": "fcs3"
       },
       {
        "status": "OK",
        "fabric": "B",
        "available_connections": 63,
        "adapter_id": "U78AB.001.WZSJMPT-P1-C5",
        "wwpn": "10000090FA2A8A26",
        "id": "1aU78AB.001.WZSJMPT-P1-C5-T1",
        "name": "fcs2"
       }
      ],
      "id": "8231E2D_109EFCT##2"
     },
     {
      "name": "vios2230_1",
      "storage_ready": true,
      "lpar_id": 1,
      "total_fcport_count": 4,
      "rmc_state": "active",
      "state": "running",
      "connectivity_types": [
       "ibm_ssp",
       "npiv"
      ],
      "backend_uuid": "17D1EED0-B0CE-4216-82B8-FDDF33721E5B",
      "fcport_list": [
       {
        "status": "OK",
        "fabric": "A",
        "available_connections": 64,
        "adapter_id": "U78AB.001.WZSJMPT-P1-C3",
        "wwpn": "10000090FA2A5867",
        "id": "1aU78AB.001.WZSJMPT-P1-C3-T2",
        "name": "fcs3"
       },
       {
        "status": "OK",
        "fabric": "B",
        "available_connections": 64,
        "adapter_id": "U78AB.001.WZSJMPT-P1-C3",
        "wwpn": "10000090FA2A5866",
        "id": "1aU78AB.001.WZSJMPT-P1-C3-T1",
        "name": "fcs2"
       },
       {
        "status": "OK",
        "fabric": "A",
        "available_connections": 63,
        "adapter_id": "U78AB.001.WZSJMPT-P1-C2",
        "wwpn": "10000090FA2A8923",
        "id": "1aU78AB.001.WZSJMPT-P1-C2-T2",
        "name": "fcs1"
       },
       {
        "status": "OK",
        "fabric": "B",
        "available_connections": 63,
        "adapter_id": "U78AB.001.WZSJMPT-P1-C2",
        "wwpn": "10000090FA2A8922",
        "id": "1aU78AB.001.WZSJMPT-P1-C2-T1",
        "name": "fcs0"
       }
      ],
      "id": "8231E2D_109EFCT##1"
     }
    ],
    "name": "8231E2D_109EFCT",
    "vios_ready_count": 2
   }
  ],
  "created_at": "2014-07-24T20:53:02.741369",
  "enabled": true,
  "exact_redundancy": false,
    "health_status": {
   "value_reasons": [],
   "effective_connectivity": [
    "ibm_ssp",
    "npiv"
   ],
   "health_value": "OK",
   "member_status": {
    "8231E2D_109EFBT": {
     "reasons": [],
     "connectivity": "full",
     "effective_fabrics": [
      "A",
      "B"
     ],
     "port_health": []
    },
    "8231E2D_109EFCT": {
     "reasons": [],
     "connectivity": "full",
     "effective_fabrics": [
      "A",
      "B"
     ],
     "port_health": []
    }
   }
  },
  "vios_ready_count": 4,
  "data_connectivity": [
   "ibm_ssp",
   "npiv"
  ],
  "vios_redundancy": 1,
  "auto_defined": true,
  "applicable_providers": [
   "ip9_114_181_186",
   "22608580b2086711e4a00d00006cae8b02"
  ],
  "id": "c3a27056-1465-444c-bae1-3525e9e8334a",
  "vios_cluster": {
   "provider_name": "22608580b2086711e4a00d00006cae8b02",
   "provider_display_name": "powervc_demo_cluster",
   "backend_state": "running"
  }
 }
}

Update a storage connectivity group

The request body takes a nested set of objects with the storage connectivity group fields that must be updated. There are no required fields in the request body. The vios_ids list replaces the existing set of Virtual I/O Servers and is used instead of the entire host_list structure that is returned for a storage connectivity group GET APIs since only the IDs are required. A failure is returned when unsupported keys are provided.

A Bad Request (400) is returned for the following conditions:

No properties are specified in the request body objects.
An object is not given in the request body.
A non user-editable property is specified in the request body.
When any key other than enabled is specified when storage connectivity group is auto-defined. Auto-defined (default) storage connectivity groups have very limited properties that can be updated. In general, you can only enable or disable them for deployment.
A badly formatted request structure as determined by the web server.
The display_name that is given is a duplicate of another storage connectivity group, resulting in Conflict (409).

A Conflict (409) error is also returned when the storage connectivity group is already associated with one or more virtual machines and one of the following property updates is attempted. The conflict error can be overriden by using the force option.

Removing Virtual I/O Servers.
Setting fc_storage_access to false from true when the storage connectivity group is already associated with one or more virtual machines.
Changing the value of cluster_provider_name.
Removing a value from boot_connectivity.
Removing a value from data_connectivity.
Reducing the value of vios_redundancy.

Request

Table 10. Parameters in the request for updating a storage connectivity group
Name	In	Type	Description
`scg_id`	URI	string	The ID for the storage connectivity group.
`force`	body	boolean	Will not check if the storage connectivity group is auto-defined or if it is associated with one or more virtual machines and yet allows the update to go through. However, the update operation will not fail if `force` is set to `true`. Avoid using this option because it can result in a storage connectivity group with a definition that is inconsistent with virtual machines associated with it.
`storage_connectivity_group`	body	object	Contains the storage connectivity group properties that are to be updated. You must provide at least one property.
`display_name`	body	string	Optional. The display name for the new storage connectivity group to create.
`fc_storage_access`	body	boolean	Whether the new storage connectivity group allows NPIV connectivity to registered SAN storage providers. If `boot_connectivity` or `data_connectivity` are also specified and either of those lists contains `npiv`, the value of this parameter must be `true`.
`vios_ids`	body	list of strings	Optional. A list of Virtual I/O Server IDs that are to be included as members of the new storage connectivity group. These IDs are returned by the host-storage-topologies REST API in the `vios_list` entries. This list replaces the existing list of VIOS IDs.It does not add to the existing list.
`cluster_provider_name`	body	list of strings	Optional. The `storage_hostname` of the shared storage pool provider as returned by the Cinder storage-providers REST API. It is only valid to update this property if `ibm-ssp` is a connectivity type defined in `boot_connectivity` or `data_connectivity` properties.
`auto_add_vios`	body	boolean	Optional. Whether the new storage connectivity group automatically adds applicable Virtual I/O Servers in the future when they are discovered from registered hosts.
`ports_per_fabric_npiv`	body	integer	For each VIOS, specifies the number of ports to connect per fabric.
`fabric_set_req`	body	list of strings	NPIV Fabric access requirement: This includes following cases. At least one fabric per VIOS - minimum one fabric can be used per VIOS. Exactly one fabric per VIOS - exactly one fabric can be used per VIOS. Every fabric per VIOS - each fabric can be used for a VIOS. In this case, you can have dual VIOS where 2 VIOSes will be used for 2 fabrics. Every fabric per host -- every fabric connected on each host can be used.
`fabric_set_npiv`	body	list of strings	The managed fabric identifier that the Fibre Channel port is logged into. Valid values are A, B, C, and so on.
`port_tag`	body	string	Optional. The port tag string to set on the new storage connectivity group. Only Fibre Channel ports with a matching `port_tag` are allowed to provide connectivity. The `port_tag` value only applies to `npiv` and `pv-vscsi` for a storage connectivity group.
`include_untagged`	body	boolean	Specifies whether to include untagged ports as eligible for attachment. Use `true` to include untagged ports and `false` if you do not want them included. The default is `false`.
`boot_connectivity`	body	list of strings	Optional. List of allowed connectivity types for the ephemeral boot volume of a virtual machine. The supported connectivity types are: `npiv`, `pv-vscsi`, and `ibm-ssp`. You cannot specify both `npiv` and `pv-vscsi`. npiv Fibre Channel connectivity with N_Port ID Virtualization, where virtual machines have virtual adapters that are used to connect to the hosted virtual NPIV ports. Additionally, the virtual machines are zoned independently on the Fibre Channel switches during volume attachment. pv-vscsi Physical volume virtual SCSI connectivity over Fibre Channel. Virtual machines have vSCSI adapters to Virtual I/O Server -hosted physical volumes and they are not independently zoned at volume attach time. ibm-ssp Shared storage pool connectivity. Virtual machines have vSCSI adapters to a shared storage pool hosted by a Virtual I/O Server cluster.
`data_connectivity`	body	list of strings	Optional. List of allowed connectivity types for the ephemeral boot volume of a virtual machine. The supported connectivity types are: `npiv`, `pv-vscsi`, and `ibm-ssp`. You cannot specify both `npiv` and `pv-vscsi`. See `boot_connectivity` for details about each type.
`vios_redundancy`	body	integer	Optional. The minimum number of Virtual I/O Servers to be used for storage volume connectivity on a host. This can be considered VIOS multiplicity. Valid values are positive integers. A value of 1 means only a single Virtual I/O Server is required, for example, for certain development workloads. A value of 2 means dual-VIOS and is appropriate for production workloads.
`exact_redundancy`	storage_connectivity_groups	boolean	Required for GET operations, optional for POST and PUT operations. Specifies whether the value given by `vios_redundancy` is the exact value or the minimum. If this value is `true`, the number of Virtual I/O Servers that will be used for volume attachment to a virtual machine will be exactly the amount specified for `vios_redundancy`. If `false` is specified, the number of Virtual I/O Servers that will be used for volume attachment will be at least the number specified for `vios_redundancy`, but more could be used. With either value, attachments will fail if connectivity is not achieved through the minimum number of Virtual I/O Servers specified by `vios_redundancy`.
`init_pg_data`	body	object	Optional. Used to create initiator port groups (IPG). Format: `{‘ipg-name-1‘ : “<FC-Port-1>, <FC-Port-2>“}, {‘ipg-name‘ : “<FC-Port-2>, <FC-Port-4>“}`. Each valid and unique-named initiator port group should be a subset of the existing selected VIOSs. Each IPG should satisfy storage connectivity group’s constraints.
`boot_ipgs`	body	string	Optional. Used to tag IPGs as ‘boot-only‘. Format: `{ ‘boot_ipgs‘ : “ipg-1, ipg-2“}`. Each specified IPG in the field should be a subset of the specified initiator port groups (`init_pg_data`).

Example

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

{
    "storage_connectivity_group": {
        "display_name": "scg12",
        "include_untagged": false,
        "enabled": true,
        "exact_redundancy": true,
        "vios_redundancy": 1,
        "vios_ids": ["79C78967-F2A3-483F-A3E5-BF7EDB76057B"],
        "boot_connectivity": ["npiv"],
        "data_connectivity": ["npiv"],
        "fc_storage_access": true,
        "ports_per_fabric_npiv": 1,
        "fabric_set_req": "per_vios",
       "fabric_set_npiv": ["A", "B"]
    }
}

Response codes

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

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

Delete a storage connectivity group

This operation does not take a REST body. If data in the body is given, a Bad Request (400) error is returned. The response does not contain any body unless an error is returned. When you try to delete a storage connectivity group that is associated with a deployed virtual machine, then Conflict (409) code is returned. You must first remove the virtual machine from being managed. The storage connectivity group remains associated with a virtual machine after deployment. When you try to delete an auto_defined storage connectivity group, then Bad Request (400) code is returned.

Note: You can disable auto_defined storage connectivity groups, but cannot delete them.

Request

Table 11. Parameters in the request for updating a storage connectivity group
Name	In	Type	Description
`scg_id`	query	string	The ID of the storage connectivity group to be deleted.
`force`	query	string	Optional. Removes a storage connectivity group, even when it is in use by a virtual machine. Valid values are `true` or `false`. Also allows default groups to be removed, but the default groups get recreated when a provider is found to exist without a connectivity group or when PowerVC started again.

Example

DELETE	
/v2.1/{tenant_id}/storage-connectivity-groups/{scg_id}
Content-Type: application/json
Accept: application/json
X-Auth-Token : ea5d2a8c444c4658a5232523ae8f8dae

Response codes

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

Example response

Status Code: 204 No Content
Connection: keep-alive
Content-Type: application/json; charset=UTF-8
X-Compute-Request-Id: req-72bc92aa-561f-4806-a561-b8250f2850b5

Get candidate images by storage connectivity group

Returns a list of objects representing the candidate images for a specified storage connectivity group. These are images backed by volumes on storage providers that the storage connectivity group currently would allow connectivity to. This operation does not take a request body. For details, see these sections:

Request
Response
Response codes

Request

Table 12. Parameters in the request for candidate images by storage connectivity group
Name	In	Type	Description
`scg_id`	URI	UUID	The ID of the storage connectivity group.

Example request

GET 
/v2.1/{tenant_id}/storage-connectivity-groups/{scg_id}/images
X-Auth-Token: 5142946e4d9e43229ecde328df70bff5
Content-Type: application/json
Accept: application/json
User-Agent: powervc-httpclient

Response

Table 13. Parameters in the request for candidate images by storage connectivity group
Name	In	Type	Description
`images`	body	list of objects	Root body element where the value is a list of sets of objects. Each set represents an image that the storage connectivity group currently allows access to.
`id`	body	string	The ID of the image.
`name`	body	string	The name of the image.

Response codes

Normal response code: 200 (OK)
Error Response Codes: Bad Request (400, 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-bcb13eba-527c-4881-8760-9b22f24ad2fe

{
 "images": [
  {
   "id": "ef254c0a-d76c-444a-8ebc-5ce8c74d660e",
   "name": "aix7_image"
  }
 ]
}

Return virtual machine references that are associated with a specific storage connectivity group

Returns a list representing the virtual machines that are associated with the specified storage connectivity group. Virtual machines become associated with a storage connectivity group if they were deployed using the group or if a managed virtual machine was migrated or had new storage attached to it. The migration or attachment causes a default storage connectivity group to be chosen and assigned to the virtual machine if an association does not yet exist. This operation does not take a request body.

For details, see these sections:

Request
Response
Response codes

Request

Table 14. Parameters in the request for viewing virtual machines references that are associated with a specific storage connectivity group
Name	In	Type	Description
`scg_id`	URI	UUID	The ID of the storage connectivity group.

Example request

GET 
/v2.1/{tenant_id}/storage-connectivity-groups/{scg_id}/serverlist
X-Auth-Token: cc421236edca4c68853641ed496845a4
Content-Type: application/json
Accept: application/json
User-Agent: powervc-httpclient

Response

Table 15. Parameters in the response for viewing virtual machines references that are associated with a specific storage connectivity group
Name	In	Type	Description
`servers`	body	objects	Each object represents a server virtual machine that is associated with the storage connectivity group. The virtual machine is the one that is specified in the request URI.
`display_name`	body	string	Display name of the server.
`id`	body	UUID	The ID of the server.
`messages`	body	list of strings	Informational or warning messages that are accumulated during API processing.

Response codes

Normal response code: 200 (OK)
Error Response Codes: Bad Request (400), 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-bcb13eba-527c-4881-8760-9b22f24ad2fe
{
 "messages": [
  "NV-F294B3B Server 27090034-ce00-449b-b12d-e2558a38f9a2 has no storage connectivity group reference information in database.",
  "NV-F294B3B Server 81deac47-4c37-449f-a7a4-1a6a7b30aa7c has no storage connectivity group reference information in database."
 ],
 "servers": [
  {
   "display_name": "rhel_vm-7e59582f-00000011",
   "id": "d1827db2-96b2-4f34-8bbc-20ed82be43e2"
  },
  {
   "display_name": "Rajni_Test_ca-b2805be6-00000003",
   "id": "4a26e8cd-cdbc-44ca-851e-8b0377392a1f"
  }
 ]
}

Return a list of storage templates for accessible storage providers

Returns a list of objects, where each object represents a storage template (or volume type) defined for a storage provider. The associated storage providers are reported as attachable candidates for volume connectivity for the storage connectivity group. However, the provider might not actually be attachable due to other settings in the environment. This operation does not take a request body.

See these sections for details:

Example request
Response
Response codes

Example request

GET 
/v2.1/{tenant_id}/storage-connectivity-groups/{scg_id}/volume-types
X-Auth-Token: 5142946e4d9e43229ecde328df70bff5
Content-Type: application/json
Accept: application/json
User-Agent: powervc-httpclient

Response

Table 16. Parameters in the response for listing storage templates that are applicable for a storage connectivity group
Name	In	Type	Description
`volume=types`	body	list of objects	Each set represents one volume type.
`name`	body	string	Name of the volume type.
`id`	body	UUID	The ID of the volume type.
`provider`	body	string	The storage provider backend name. This is the `storage_hostname` that is returned by the Cinder storage-providers REST API.
`messages`	body	list of string	Informational or warning messages that are accumulated during API processing.
`is_boot`	body	boolean	True if the volume type is applicable for boot connectivity within the storage connectivity group. False otherwise.
`is_data`	body	boolean	True if the volume type is applicable for data connectivity within the storage connectivity group. False otherwise.

Response codes

Normal response code: 200 (OK)
Error Response Codes: Bad Request (400), 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-bcb13eba-527c-4881-8760-9b22f24ad2fe
{
 "volume-types": [
  {
   "id": "29f3dde6-2d35-495e-bc7d-83a48da3bae5",
   "name": "SVC-186 default",
   "provider": "ip_x_xx_xx_v7000",
   "is_boot": true,   
   "is_data": true
  },
  {
   "id": "cf33003d-906f-456a-837f-04409635ef16",
   "name": "new-svc type",
   "provider": "ip_x_xx_xx_v7000",
   "is_boot": true,   
   "is_data": false
  },
  {
   "id": "99c1162f-3bc6-497e-93af-ff57a20a7db9",
   "name": "power_ssp_cluster default",
   "provider": "22fa3d06ee994a11e397a100006cae8b02",
   "is_boot": false,   
   "is_data": true
  }
 ]
}

Return the list of volumes to which a storage connectivity group can provide connectivity

Returns a list of volumes that can be accessed by the storage connectivity group specified. These are the PowerVC managed volumes that the storage connectivity group currently has connectivity to. For example, if a storage provider is in error state, then its volumes are not returned by this API. This operation does not take a request body. The operation supports several query parameters to filter the returned list so that only volumes available for attachment to a particular virtual machine can be requested, based on the virtual machines associated storage connectivity group.

For details, see these sections:

Request
Response
Response codes

Request

Table 17. Parameters in the request for returning volumes that can be attached using a specific storage connectivity group
Name	In	Type	Description
`scg_id`	URI	UUID	The storage connectivity group ID to which the list of accessible volumes are to be returned.
`include_boot`	query	string	Optional. Whether boot volumes (ephemeral disks) should be included in the list of volumes that are returned. Valid values are `true` or “`false`. The default value is `true`.
`include_unavailable`	query	string	Optional. Whether volumes that do not have `available` status are returned. Valid values are `true` or `false`. The default value is `true`. When the option is `true`, all managed volumes, whether they are attached, attaching, deleting, or some other state are returned. If not, only available volumes are returned.
`details`	query	string	Optional. Whether detailed volume properties should be returned. Valid values are `true` or `false`. The default value is `false`. When the option is `false` only those properties that are in the response table are returned. If the option is `true`, other properties from Cinder that are mapped by the PowerVC Cinder client, are also returned. The set of these properties are not defined in this API.

Example request

GET 
/v2.1/{tenant_id}/storage-connectivity-groups/{scg_id}/volumes
X-Auth-Token: 5142946e4d9e43229ecde328df70bff5
Content-Type: application/json
Accept: application/json
User-Agent: powervc-httpclient

Response

Table 18. Parameters in the response for returning volumes that can be attached using a specific storage connectivity group
Name	In	Type	Description
`volumes`	body	list of objects	Contains one set for each volume that the storage connectivity group applies to.
`display_name`	body	string	Display name of the volume.
`id`	body	UUID	The ID of the volume.
`provider`	body	string	The storage provider backend name. The storage provider backend name. This is the `storage_hostname` that is returned by the Cinder storage-providers REST API.
`status`	body	string	The status of the volume.
`messages`	body	list of strings	Informational or warning messages that are accumulated during API processing.

Response codes

Normal response code: 200 (OK)
Error Response Codes: Bad Request (400), 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-bcb13eba-527c-4881-8760-9b22f24ad2fe
{
 "volumes": [
  {
   "status": "in-use",
   "display_name": "boot-8246L2D_10085BA-April6th_Capt-a7d70a28-00000020",
   "id": "12c229d9-78a0-4d25-91ae-4ca087dc1e57",
   "volume_type": " SVC-186 default ",
   "provider": "ip_x_xx_xx_v7000"
  },
  {
   "status": "available",
   "display_name": "Image April6th_Capture_3_VM2Capture_attempt1",
   "id": "a566dfa9-7e08-44d6-a518-c124b3c1d5b3",
   "volume_type": "power_ssp_cluster default",
   "provider": "22fa3d06ee994a11e397a100006cae8b02"
  },
  {
   "status": "in-use",
   "display_name": "Apr6_attach_vol_ssp_1",
   "id": "8bcc49d9-73d0-4cbc-86c4-4dc62861a89b",
   "volume_type": "power_ssp_cluster default",
   "provider": "22fa3d06ee994a11e397a100006cae8b02"
  },
  {
   "status": "available",
   "display_name": "Image Apr6_Capture_2_VM1_Attempt1",
   "id": "ac4b08c2-9eca-4c3f-adda-4cee15fef3b8",
   "volume_type": "new-svc type",
   "provider": "ip_x_xx_xx_v7000"
  }
 ]
}