Skip to main content

We've Moved!

Product Documentation has moved to docs.hitachivantara.com
Hitachi Vantara Knowledge

Managing resources by using virtual storage machines

You can manage resources on virtual storage machines by using the REST API.

Overview of managing resources by using virtual storage machines

A "virtual storage machine" is a virtual storage system created on a storage system by using the global storage virtualization function. You can set virtual information, such as models and serial numbers, for virtual storage machines.

A virtual storage machine can be used as a global-active device or for nondisruptive migration. By registering resources in virtual storage machines, you can collectively manage resources of multiple physical storage systems on a single virtual storage machine, or divide resources of a single physical storage system into multiple virtual storage machines and manage the resources separately.

Examples of virtual storage machine configurations

The following figure shows examples of virtual storage machine configurations:

GUID-F9DE9EA1-5848-452C-947E-D38D44AB104A-low.gif

In this figure, a virtual storage machine of the virtual model VSP G1000 (virtual serial number: 11223) and a virtual storage machine of the virtual model Virtual Storage Platform (virtual serial number: 12345) are created in a VSP 5500 storage system (serial number: 10111), and the resources registered in the virtual storage machines are allocated to the hosts. When the configuration is set up like this, from the virtual point of view it seems as if host A is accessing VSP G1000 (virtual serial number: 11223), and host B is accessing Virtual Storage Platform (virtual serial number: 12345).

For details on how to manage resources by using virtual storage machines, see the Provisioning Guide for Open Systems, or the Provisioning Guide.

Workflow for managing resources by using virtual storage machines

The following explains how to manage resources on virtual storage machines by using the REST API.
Workflow for creating a virtual storage machine and registering resources

Create a virtual storage machine, and then register the required resources. Allocate the registered resources to the hosts in the same way as allocating resources of a physical storage system, or use the registered resources in the volumes of a global-active device pair.

GUID-20DFF447-BDAC-493E-8F3B-19BD12217C3B-low.gif
  • Create a virtual storage machine

    Create a virtual storage machine, and then specify the model name and serial number. A resource group to be used on the virtual storage machine is also created at the same time.

  • Get a list of the virtual storage machines

    Get information such as the storage device IDs of the created virtual storage machines, and the IDs of resource groups on the virtual storage machines.

  • Add resource groups on a virtual storage machine (optional)

    If necessary, add resource groups to the virtual storage machine. Perform this operation by executing the API request for creating resource groups.

  • Add resources to the virtual storage machines

    In the resource groups of the virtual storage machine, add resources such as host numbers, host group numbers, and LDEV numbers. Perform this operation by executing the API request for adding a resource to a resource group.

    • To add an LDEV number, first delete the set virtual LDEV number, and then add the LDEV number. After adding the LDEV number in the virtual storage machine, set the virtual LDEV number.
    • To add a host group number or iSCSI target number, add an undefined host group or iSCSI target.
Workflow for deleting an unnecessary virtual storage machine

Delete the resources on a virtual storage machine before you delete the virtual storage machine.

GUID-9E95BE44-5A4D-4DA5-AC3A-BEFC51EE1F25-low.gif

  • Delete the virtual LDEV number

    Delete the virtual LDEV number that was set for the virtual LDEV on the virtual storage machine.

  • Remove the resources in the virtual storage machine

    Delete the LDEVs, parity groups, host numbers, and all other resources that are added in the resource group in the virtual storage machine. Perform this operation by executing the API request for removing resources from resource groups.

  • Delete the virtual storage machine

    Delete the virtual storage machine. Note that when all of the resource groups are deleted from the virtual storage machine, the virtual storage machine is automatically deleted.

Getting a list of virtual storage machines

The following request obtains a list of virtual storage machines. You can get information such as serial numbers, model names, and resource group IDs.
Execution permission

Storage Administrator (View Only)

Request line
GET base-URL/v1/objects/virtual-storages
Request message
  • Object ID

    None.

  • Query parameters

    None.

  • Body

    None.

Response message
  • Body

    {
      "data" : [
        {
          "virtualStorageDeviceId" : "800000002015",
          "virtualSerialNumber" : "2015",
          "virtualModel" : "VSP G1000/G1500 and VSP F1500",
          "resourceGroupIds" : [ 
            1,
            3
          ],
          "virtualStorageTypeId" : "R8"
        },
        {
          "virtualStorageDeviceId" : "882000400002",
          "virtualSerialNumber" : "400002",
          "virtualModel" : "VSP G350",
          "resourceGroupIds" : [ 
            0, 
            2, 
            4
          ],
          "virtualStorageTypeId" : "M850S1"
        }
      ]
    }

    Attribute

    Type

    Description

    virtualStorageDeviceId

    string

    Storage device ID of the virtual storage machine

    virtualSerialNumber

    string

    Serial number of the virtual storage machine

    virtualModel

    string

    Model name of the virtual storage machine

    resourceGroupIds

    int[]

    Resource group ID

    virtualStorageTypeId

    string

    Storage system type ID of the virtual storage machine

    If storage system is not be determined, Unknown is output.

Status codes

For details on the status codes for the request that performs this operation, see the description of HTTP status codes.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/virtual-storages

Getting information about a specific virtual storage machine

The following request gets information about the specified virtual storage machine. You can get information such as serial numbers, model names, and resource group IDs.
Execution permission

Storage Administrator (View Only)

Request line
GET base-URL/v1/objects/virtual-storages/object-ID
Request message
  • Object ID

    Specify the virtualStorageDeviceId value obtained by getting information about the virtual storage machine.

    Attribute

    Type

    Description

    virtualStorageDeviceId

    string

    (Required) Storage device ID of the virtual storage machine

  • Query parameters

    None.

  • Body

    None.

Response message
  • Body

    {
      "virtualStorageDeviceId" : "882000400002",
      "virtualSerialNumber" : "400002",
      "virtualModel" : "VSP G350",
      "resourceGroupIds" : [
        0, 
        2, 
        4
      ],
      "virtualStorageTypeId" : "M850S1"
    }

    Attribute

    Type

    Description

    virtualStorageDeviceId

    string

    Storage device ID of the virtual storage machine

    virtualSerialNumber

    string

    Serial number of the virtual storage machine

    virtualModel

    string

    Model name of the virtual storage machine

    resourceGroupIds

    int[]

    Resource group ID

    virtualStorageTypeId

    string

    Storage system type ID of the virtual storage machine

    If storage system is not be determined, Unknown is output.

Status codes

For details on the status codes for the request that performs this operation, see the description of HTTP status codes.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/virtual-storages/882000400002

Creating a virtual storage machine

The following request creates a virtual storage machine. A resource group is also created at the same time.
Note

If you locked any resources of the target storage system by using the REST API, you will not be able to use this API function. In such cases, unlock the resources before running the API function.

Execution permission

Security Administrator (View & Modify)

Request line
POST base-URL/v1/objects/virtual-storages
Request message
  • Object ID

    None.

  • Query parameters

    None.

  • Body

    {
      "virtualSerialNumber": "422222",
      "virtualModel": "VSP G700",
      "resourceGroupName": "DevGroup"
    }

    Attribute

    Type

    Description

    virtualSerialNumber

    string

    (Required) Serial number of the virtual storage machine

    virtualModel

    string

    (Required) Model name of the virtual storage machine

    Specifiable values are as follows:

    • VSP E990

    • VSP E790

    • VSP E590

    • VSP F900

    • VSP F700

    • VSP F370

    • VSP F350

    • VSP G900

    • VSP G700

    • VSP G370

    • VSP G350

    • VSP G130

    • VSP G800 and VSP F800#

    • VSP G400/G600 and VSP F400/F600#

    • VSP G200

    • HUS VM

    • VSP 5000 series AFA

    • VSP 5000 series hybrid

    • VSP G1000/G1500 and VSP F1500

    • VSP

    resourceGroupName

    string

    (Required) Name of the resource group to be created when the virtual storage machine is created

    Specify a name consisting of 1 to 32 characters.

    #: If the storage system model is VSP N400 or VSP N600, specify VSP G400/G600 and VSP F400/F600. If the storage system model is VSP N800, specify VSP G800 and VSP F800.

Response message
  • Body

    A job object is returned. For details on attributes other than affectedResources, see the description of job objects.

    Attribute

    Description

    affectedResources

    URL of the created virtual storage machine

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X POST --data-binary @./InputParameters.json https://192.0.2.100/ConfigurationManager/v1/objects/virtual-storages/

Deleting a virtual storage machine

The following request deletes a virtual storage machine. Remove all of the resources included in the virtual storage machine before running this request.
Note

If you locked any resources of the target storage system by using the REST API, you will not be able to use this API function. In such cases, unlock the resources before running the API function.

Execution permission

Security Administrator (View & Modify)

Request line

DELETE base-URL/v1/objects/virtual-storages/object-ID
Request message
  • Object ID

    Specify the virtualStorageDeviceId value obtained by getting information about the virtual storage machine.

    Attribute

    Type

    Description

    virtualStorageDeviceId

    string

    (Required) Storage device ID of the virtual storage machine

  • Query parameters

    None.

  • Body

    None.

Response message
  • Body

    A job object is returned. For details on attributes other than affectedResources, see the description of job objects.

    Attribute

    Description

    affectedResources

    URL of the deleted virtual storage machine

Status codes

For details on the status codes of the request for this operation, see the description on HTTP status codes.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X DELETE https://192.0.2.100/ConfigurationManager/v1/objects/virtual-storages/409900010000

Getting information about virtual LDEVs

The following request gets information about the virtual LDEVs (LDEVs to which virtual LDEV numbers have been assigned) on a virtual storage machine. If no virtual LDEVs exist in the specified range, an empty list will be returned. To get information about virtual LDEVs, use multiple query parameters so that virtual LDEVs are included.
Execution permission

Storage Administrator (View Only)

Request line
GET base-URL/v1/objects/ldevs
Request message
  • Object ID

    None.

  • Query parameters

    You can filter the execution result by specifying conditions, or request additional detailed information about virtual LDEVs. To get information about virtual LDEVs, specify the target virtual storage machine by using the virtualSerialNumber parameter.

    • When filtering the execution result

      By default, information about a maximum of 100 virtual LDEVs is obtained. You can get information about a maximum of 16,384 virtual LDEVs by specifying the count parameter. When the ldevOption parameter or the poolId parameter is specified, if the number of virtual LDEVs for which information is to be obtained exceeds 16,384, use the headVirtualLdevId parameter and specify a value so that the virtual LDEV numbers whose information is to be obtained are included in the range. The information that can be obtained is only about the number of virtual LDEVs that are included in the range specified by the combination of the headVirtualLdevId parameter and the count parameter.

      Tip

      Of the resources displayed by the filter, you can obtain information only about the resources for which you have been granted access permissions.

      For example, if you specify 10 for the count parameter and you have permission to access all virtual LDEVs, information about 10 virtual LDEVs will be obtained. If you have permission to access specific virtual LDEVs only, information will be obtained only about virtual LDEVs for which you have been granted access permissions.

      Important

      For a VSP E series, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900 storage system, pay attention to the number of concurrent executions of this API request. For details, see "Implementing retry processing".

      For query parameters that can be specified at the same time, see the following table that lists the combinations of query parameters that can be specified.

      Parameter

      Type

      Filter Condition

      virtualSerialNumber

      string

      (Required) Specify the serial number of a virtual storage machine.

      Information about virtual LDEVs on the virtual storage machine is obtained in the ascending order of virtual LDEV numbers.

      headVirtualLdevId

      int

      (Optional) Specify the virtual LDEV number (a decimal) from which the processing to get information is to start.

      Information about the LDEVs is obtained in the ascending order of virtual LDEV numbers, starting with the specified virtual LDEV number.

      If this parameter is omitted, 0 is assumed.

      When specifying this parameter, be sure to also specify the virtualSerialNumber parameter.

      count

      int

      (Optional) Specify the number of virtual LDEVs about which you want to obtain information. Specify a value in the range from 1 to 16384.

      If this parameter is omitted, 100 is assumed.

      ldevOption

      string

      (Optional) Virtual LDEV conditions for getting information

      You can specify the following conditions:

      • defined

        Get information about virtual LDEVs that have been implemented.

      • undefined

        Get information about virtual LDEVs that are not implemented.

      • dpVolume

        Obtaining DP volume information

      • luMapped

        Get information about virtual LDEVs for which LU paths are defined.

      • luUnmapped

        Get information about virtual LDEVs for which LU paths have not been defined.

      • externalVolume

        Get information about external volumes.

      If this is omitted, information about all types of virtual LDEVs will be obtained.

      poolId

      int

      (Optional) Pool number

      Get information about the virtual LDEVs that are associated with the specified pool.

      By using the ldevOption parameter when specifying conditions, the following information can be obtained:

      • If dpVolume is specified for the ldevOption parameter:

        Gets information about the DP volumes that are associated with the specified pool.

      • If luMapped is specified for the ldevOption parameter:

        Gets information about virtual LDEVs for which LU paths associated with the specified pool are defined.

      • If luUnmapped is specified for the ldevOption parameter:

        Gets information about virtual LDEVs for which LU paths associated with the specified pool have not been defined.

      If you specify this parameter without specifying the ldevOption parameter, the API gets information about the volumes that make up the pool (pool volumes).

      resourceGroupId

      int

      (Optional) ID of the resource group to which virtual LDEVs for which information is to be obtained belong

      journalId

      int

      (Optional) ID of the journal to which virtual LDEVs for which information is to be obtained belong

      parityGroupId

      string

      (Optional) Number of the parity group to which LDEVs for which information is to be obtained belong

      Specify concatenated parity groups in the same way as the above.

      If the concatenated parity groups are 1-3-1, 1-3-2, or 1-3-3, specify as follows:

      parityGroupId=1-3

      The following table shows the combinations of query parameters that can be specified.

      Parameter

      virtual​Serial​Number

      head​Virtual​Ldev​Id

      count

      ldev​Option

      poolId

      resource​Group​Id

      journal​Id

      parity​Group​Id

      virtual​Serial​Number

      --

      Y

      Y

      Y

      Y

      Y

      Y

      Y

      head​Virtual​Ldev​Id

      Y

      --

      Y

      Y

      N

      N

      N

      N

      count

      Y

      Y

      --

      Y

      Y

      Y

      Y

      Y

      ldevOption

      Y

      Y

      Y

      --

      Y#

      Y

      N

      N

      poolId

      Y

      N

      Y

      Y#

      --

      Y

      N

      N

      resourceGroupId

      Y

      N

      Y

      Y

      Y

      --

      Y

      Y

      journalId

      Y

      N

      Y

      N

      N

      Y

      --

      N

      parityGroupId

      Y

      N

      Y

      N

      N

      Y

      N

      --

      #: If defined, undefined, or externalVolume is specified as the value of the ldevOption parameter, you cannot specify this combination of parameters.

    • When requesting additional detailed information

      Parameter

      Type

      Description

      detailInfoType

      string

      (Optional) Type of detailed information to be obtained

      You can use this parameter together with parameters that filter the execution results.

      The following values can be specified. To specify multiple values, separate the values by using commas.

      • FMC

        Adds detailed information about accelerated compression for the virtual LDEVs that belong to parity groups with drive type SSD(FMC).

      • virtualSerialNumber

        Adds detailed information about virtual storage machines.

      • class

        Adds additional information from the storage system's cache.

        You can specify this item for VSP 5000 series.

        To get up-to-date information, you must run the API request that refreshes the storage system's cache before running this request. For details, see "Updating the cache of storage system configuration information".

        Immediately after you create an LDEV, if you specify class and at the same time specify defined in the query parameter ldevOption and then run the command, the volume status might be output as unimplemented. In such a case, wait a while and then run this request again. Alternatively, run the API request that updates the cache of storage system configuration information, and then run this request again.

      • qos

        Adds information about QoS settings.

        You can specify this item for VSP 5000 series, VSP G350, G370, G700, G900, VSP F350, F370, F700, F900.

  • Body

    None.

Response message
  • Body

    {
      "data": [
        {
          "ldevId": 0,
          "virtualLdevId": 0,
          "virtualSerialNumber": "410012",
          "clprId": 0,
          "emulationType": "OPEN-V-CVS",
          "byteFormatCapacity": "1.00 G",
          "blockCapacity": 2097152,
          "numOfPorts": 1,
          "ports": [
            {
              "portId": "CL3-B",
              "hostGroupNumber": 25,
              "hostGroupName": "bs10300-7",
              "lun": 19
            }
          ],
          "attributes": [
            "CVS",
            "HDP",
            "GAD"
          ],
          "status": "NML",
          "mpBladeId": 2,
          "ssid": "0004",
          "poolId": 4,
          "numOfUsedBlock": 0,
          "isFullAllocationEnabled": false,
          "resourceGroupId": 6,
          "dataReductionStatus": "DISABLED",
          "dataReductionMode": "disabled",
          "isAluaEnabled": false
        },
        {
          "ldevId": 1,
          "virtualLdevId": 1,
          "virtualSerialNumber": "410012",
          "clprId": 0,
          "emulationType": "OPEN-V-CVS",
          "byteFormatCapacity": "1.00 G",
          "blockCapacity": 2097152,
          "numOfPorts": 1,
          "ports": [
            {
              "portId": "CL3-B",
              "hostGroupNumber": 25,
              "hostGroupName": "bs10300-7",
              "lun": 21
            }
          ],
          "attributes": [
            "CVS",
            "HDP",
            "GAD"
          ],
          "label": "ldev_label_1",
          "status": "NML",
          "mpBladeId": 0,
          "ssid": "0004",
          "poolId": 10,
          "numOfUsedBlock": 0,
          "isFullAllocationEnabled": false,
          "resourceGroupId": 6,
          "dataReductionStatus": "DISABLED",
          "dataReductionMode": "disabled",
          "isAluaEnabled": false
        }
      ]
    }

    The following table describes the attributes to be obtained in the body of the response message. For details on attributes to be obtained, see the description of the API function for getting volume information.

    Attribute

    Type

    Description

    ldevId

    int

    LDEV number

    virtualLdevId

    int

    Virtual LDEV number

    virtualSerialNumber

    string

    Serial number of the virtual storage machine

    If you execute the request with virtualSerialNumber specified for the detailInfoType query parameter, the request also obtains detailed information about the virtual storage machines.

    Attribute

    Type

    Description

    virtualModel

    string

    Model name of the virtual storage machine

    If you run this request with class specified for detailInfoType in the query parameters, additional information from the storage system's cache is also obtained.

    Attribute

    Type

    Description

    virtualEmulationType

    string

    Virtual emulation type of the virtual LDEV

    virtualSsId

    int

    Virtual SSID of the virtual LDEV

    isVirtualCvs

    boolean

    Whether a virtual CVS is set for the virtual LDEV

    • true: Set
    • false: Not set
Status codes

For details on the status codes of the request for this operation, see the section explaining HTTP status codes.

Coding example
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X GET "https://192.0.2.100/ConfigurationManager/v1/objects/ldevs?count=2&virtualSerialNumber=410012"

Setting a virtual LDEV number

The following request sets a virtual LDEV number for an LDEV.
Execution permission

Storage Administrator (Provisioning)

Request line
POST base-URL/v1/objects/ldevs/object-ID/actions/assign-virtual-ldevid/invoke
Request message
  • Object ID

    Specify the ldevId value obtained by getting information about volumes.

    Attribute

    Type

    Description

    ldevId

    int

    (Required) Specify the LDEV number with a decimal (base 10) number.

  • Query parameters

    None.

  • Body

    The following coding example sets the virtual LDEV number 405 for a LDEV:

    {
      "parameters": {
        "virtualLdevId": 405
      }
    }

    Attribute

    Type

    Description

    virtualLdevId

    int

    (Required) Specify the virtual LDEV number with a decimal (base 10) number.

    If you specify 65535, the reserved attribute of global-active device will be set.

Response message
  • Body

    A job object is returned. For details on attributes other than affectedResources, see the section explaining job objects.

    Attribute

    Description

    affectedResources

    URL of the LDEV for which the virtual LDEV number is set

Action template
GET base-URL/v1/objects/ldevs/object-ID/actions/assign-virtual-ldevid
Status codes

The following table describes the meaning of the status code of the request for this operation. For details on other status codes, see the description on HTTP status codes.

Status code

Message

Description

412

Precondition Failed

The virtual LDEV number is already set for the target LDEV.

Coding example

To get an action template:

curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/ldevs/1/actions/assign-virtual-ldevid

To run the request after getting an action template:

curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X POST --data-binary @./InputParameters.json https://192.0.2.100/ConfigurationManager/v1/objects/ldevs/1/actions/assign-virtual-ldevid/invoke

Deleting a virtual LDEV number

The following request deletes the virtual LDEV number set for an LDEV.
Execution permission

Storage Administrator (Provisioning)

Request line
POST base-URL/v1/objects/ldevs/object-ID/actions/unassign-virtual-ldevid/invoke
Request message
  • Object ID

    Specify the ldevId value obtained by getting information about the virtual LDEV number.

    Attribute

    Type

    Description

    ldevId

    int

    (Required) Specify the LDEV number with a decimal (base 10) number.

  • Query parameters

    None.

  • Body

    The following coding example deletes virtual LDEV number 405:

    {
      "parameters": {
        "virtualLdevId": 405
      }
    }

    Attribute

    Type

    Description

    virtualLdevId

    int

    (Required) Specify the virtual LDEV number with a decimal (base 10) number.

    If you specify 65535, the reserved attribute of global-active device is canceled.

Response message
  • Body

    A job object is returned. For details on attributes other than affectedResources, see the section explaining job objects.

    Attribute

    Description

    affectedResources

    URL of the LDEV for which the virtual LDEV number is deleted

Action template
GET base-URL/v1/objects/ldevs/object-ID/actions/unassign-virtual-ldevid
Status codes

The following table describes the meaning of the status code of the request for this operation. For details on other status codes, see the description on HTTP status codes.

Status code

Message

Description

412

Precondition Failed

The virtual LDEV number is not set for the target LDEV.

Coding example

To get an action template:

curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/ldevs/1/actions/unassign-virtual-ldevid

To run the request after getting an action template:

curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X POST --data-binary @./InputParameters.json https://192.0.2.100/ConfigurationManager/v1/objects/ldevs/1/actions/unassign-virtual-ldevid/invoke