StoragePools

This chapter describes the storagepools resource, properties and operations.

Overview

One or more disks(DASD or FCP) can be grouped logically as a single resource called as 'storagepools'. The 'storagepools' size can be dynamically changed by adding or removing disks to the same. So this resource represents a collection of 'storage-devices' or 'fcp-disks'. A 'storage-devices' (which represents a 'dasd') or 'fcp-disks' (represents a SCSI LUN) can be added or removed to/from a Storagepools.

Resource Properties

A storagepools instance is represented by the following fields.

Type values are described in Data types.

Name	Type	Description
self	String/URI	The URI of this instance.
name	String	Storage Pool's human readable name .
id	String	Storage pool unique Identifier.
status	String Enum	Storage pool's status, refer status Enum values for valid values.
size	Float	Pool total capacity in Giga bytes(GB). The size will be '--' when the `status` attribute is `beingedited`.
used	Float	Pool total capacity utilised in Giga bytes(GB). The used value will be '--' when the `status` attribute is `beingedited`.
disks	Array of 'storage-devices' and/or 'fcp-disks'	Assigned disks to the pool.
fs	String	File system type. Supported values are 'ext4', 'btrfs', 'xfs', 'swap'. This property will be part of an instance only if 'isFilesystemExist' is set to 'True'.
isFilesystemExist	Boolean	Indicates if file system is installed or not. Supported values are 'True', 'False'. A value of 'True' indicates that 'fs' property would be part of an instance with one of the valid value. If the value is 'False', then 'fs' would not be part of 'storagepools' instance.

status Enum values

active - Storage Pool is ready to accept new request for disk addition or removal.
beingedited - Storage Pool is busy in either processing disk addition or removal. Any new disk addition request will be denied except the retrieve functionality when a Storage Pool is in this state.

Retrieve all storage pools

Use this operation to retrieve the list of defined storagepools.

Authentication/Authorization

The caller must provide an API token, refer to Invoking API operations.

The user represented by the API token must have the following role:

administrator

Network

This operation is available from the following network(s):

management

HTTP Method and URI

GET /api/com.ibm.zaci.system/storagepools

Query Parameters

None

Request headers

For the list of required headers, refer to the Invoking API operations section.

The following sections describe the acceptable values for certain headers.

Accept media types

application/vnd.ibm.zaci.payload+json media type

Request message body

None

Response

An HTTP status code of 200 indicates a successful operation. The response message body contains data formatted as requested in the Accept header, with kind=collection. The instances array contains zero or more objects, as described under the Resource Properties topic.

Two types of Disk/s could exist in the pool -

The Disk/s successfully added to the pool and the status shown as in 'used' state.
The Disk/s which failed to be added to the pool and the progress indicates at which stage it failed. And these Disk/s are ready to be added to the pool and in 'free' status.

Any other HTTP status code indicates a failed operation. The response message body contains error information, refer to the Error responses topic for more details.

Example 1: GET all defined Storage pools.

Request

GET /api/com.ibm.zaci.system/storagepools HTTP/1.1
Host: 9.9.9.9:443
Authorization: Bearer qwert.asdfg.zxcvb
zACI-API: com.ibm.zaci.system/1.0
Accept: application/vnd.ibm.zaci.payload+json;version=1.0

Response

HTTP/1.1 200 OK
Date: Tue, 15 May 2015 08:12:31 GMT
zACI-API: com.ibm.zaci.system/1.0
Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0
Content-Length: 332

{
"kind": "collection",
"self": "/api/com.ibm.zaci.system/storagepools",
"resource-version": "1.0",
"resource-name": "storagepools",
"instances": [
    {
    "self": "/api/com.ibm.zaci.system/storagepools/root_pool"
    "name": "Appliance Operation",
    "id": root_pool,
    "size": 21.99,
    "status": 'active',
    "used": 2.45,
    "fs": 'btrfs',
    "isFilesystemExist": True,
    "disks": [{'capacity': 21.99,
               'id': '0.0.af88',
               'progress': '',
               'self': '/api/com.ibm.zaci.system/storage-devices/0.0.af88',
               'status': 'used',
               'type': '3390/0c'}]},
    {
    'self': '/api/com.ibm.zaci.system/storagepools/data_pool',
    'name': 'Analytics Data pool',
    'id': 'data_pool',
    'size': 0.0,
    'status': 'active',
    'used': 0.0,
    'fs': 'ext4',
    'isFilesystemExist': True,
    'disks': [] }]
}

Example 2: GET all Storage Pool, when DASD addition is being processed by one of the pool: data_pool

Request

GET /api/com.ibm.zaci.system/storagepools HTTP/1.1
Host: 9.9.9.9:443
Authorization: Bearer qwert.asdfg.zxcvb
zACI-API: com.ibm.zaci.system/1.0
Accept: application/vnd.ibm.zaci.payload+json;version=1.0

Response

HTTP/1.1 200 OK
Date: Tue, 09 Aug 2016 11:10:29 GMT
zACI-API: com.ibm.zaci.system/1.0
Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0
Content-Length: 1211

{
"kind": "collection",
"self": "/api/com.ibm.zaci.system/storagepools",
"resource-version": "1.0",
"resource-name": "storagepools",
"instances": [
    {
    "self": "/api/com.ibm.zaci.system/storagepools/root_pool"
    "name": "Appliance Operation",
    "id": root_pool,
    "size": 21.99,
    "used": 2.45,
    "status": "active",
    "fs": 'btrfs',
    "isFilesystemExist": True,
    "disks": [{'capacity': 21.99,
               'id': '0.0.af88',
               'progress': '',
               'status': 'used',
               'self': '/api/com.ibm.zaci.system/storage-devices/0.0.af88',
               'type': '3390/0c'}]
    },
    {
    "self": "/api/com.ibm.zaci.system/storagepools/data_pool"
    "name": "Analytics Data pool",
    "id": "data_pool",
    "size": "--",
    "used": "--",
    "status": "beingedited",
    "fs": 'ext4',
    "isFilesystemExist": True,
    "disks": [{'capacity': '44.98',
               'id': '0.0.a29d',
               'progress': '',
               'status': 'used',
               'self': '/api/com.ibm.zaci.system/storage-devices/0.0.a29d',
               'type': '3390/0c'},
                {'capacity': '',
               'id': '0.0.a29e',
               'progress': {'ADD2POOL': 'PENDING',
                            'FORMAT':  'INPROGRESS',
                            'ONLINE':  'DONE',
                            'PARTITION': 'PENDING'},
               'status': 'beingadded',
               'self': '/api/com.ibm.zaci.system/storage-devices/0.0.a29e',
               'type': '3390/0c'}]
    }]
}

Retrieve a storage pool

Use this operation to retrieve a Storage pool.

Authentication/Authorization

The caller must provide an API token, refer to Invoking API operations.

The user represented by the API token must have the following role:

administrator

Network

This operation is available from the following network(s):

management

HTTP Method and URI

GET /api/com.ibm.zaci.system/storagepools/{id}

In this request, the URI variable {id} is the Pool unique id. The URI is obtained via the * Retrieve all storage pools operation.

Query Parameters

None

Request headers

For the list of required headers, refer to the Invoking API operations section.

The following sections describe the acceptable values for certain headers.

Accept media types

application/vnd.ibm.zaci.payload+json media type

Request message body

None

Response

An HTTP status code of 200 indicates a successful operation. The response message body contains data formatted as requested in the Accept header, with kind=instance. The properties is described under the Resource Properties topic.

Two types of Disk/s could exist in the pool -

The Disk/s successfully added to the pool and the status shown as in 'used' state.
The Disk/s which failed to be added to the pool and the progress indicates at which stage it failed. And these Disk/s are ready to be added to the pool and in 'free' status.

Any other HTTP status code indicates a failed operation. The response message body contains error information, refer to the Error responses topic for more details.

The response message body contains a application/vnd.ibm.zaci.payload+json media type object, with kind=error. The failure object contains additional details, as described under the Error responses topic.

Example 1: GET valid Storage pool.

Request

GET /api/com.ibm.zaci.system/storagepools/data_pool
Host: 9.9.9.9:443
Authorization: Bearer qwert.asdfg.zxcvb
zACI-API: com.ibm.zaci.system/1.0
Accept: application/vnd.ibm.zaci.payload+json;version=1.0

Response

HTTP/1.1 200 OK
Date: Tue, 18 Oct 2016 11:03:58 GMT
zACI-API: com.ibm.zaci.system/1.0
Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0
Content-Length: 358
{
"kind": "instance",
"parameters": {
    "self": "/api/com.ibm.zaci.system/storagepools/data_pool"
    "name": "Analytics Data pool",
    "id": data_pool,
    "size": 44.98,
    "status": 'active',
    "used": 3.15,
    "fs": 'ext4',
    "isFilesystemExist": True,
    "disks": [{'capacity': 44.98,
               'id': '0.0.a29d',
               'progress': '',
               'self': '/api/com.ibm.zaci.system/storage-devices/0.0.a29d',
               'status': 'used',
               'type': '3390/0c'}]
     }
}

Example 2: GET invalid Storage pool.

Request

GET /api/com.ibm.zaci.system/storagepools/temppool
Host: 9.9.9.9:443
Authorization: Bearer qwert.asdfg.zxcvb
zACI-API: com.ibm.zaci.system/1.0
Accept: application/vnd.ibm.zaci.payload+json;version=1.0

Response

HTTP/1.1 200 OK
Date: Tue, 18 Oct 2016 11:13:58 GMT
zACI-API: com.ibm.zaci.system/1.0
Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0
Content-Length: 38
{
"kind": "instance",
"parameters": {}
}

Example 3: GET Storage pool when DASD is being added.

Request

GET /api/com.ibm.zaci.system/storagepools/data_pool
Host: 9.9.9.9:443
Authorization: Bearer qwert.asdfg.zxcvb
zACI-API: com.ibm.zaci.system/1.0
Accept: application/vnd.ibm.zaci.payload+json;version=1.0

Response

HTTP/1.1 200 OK
Date: Tue, 18 Oct 2016 12:03:58 GMT
zACI-API: com.ibm.zaci.system/1.0
Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0
Content-Length: 452
{
"kind": "instance",
"parameters": {
    "self": "/api/com.ibm.zaci.system/storagepools/data_pool"
    "name": "Analytics Data pool",
    "id": data_pool,
    "size": --,
    "status": 'beingedited',
    "used": --,
    "fs": 'ext4',
    "isFilesystemExist": True,
    "disks": [{'capacity': "",
               'id': '0.0.a29d',
               'progress': {'ADD2POOL': 'PENDING',
                            'FORMAT': 'INPROGRESS',
                            'ONLINE': 'DONE',
                            'PARTITION': 'PENDING'},
               'self': '/api/com.ibm.zaci.system/storage-devices/0.0.a29d',
               'status': 'beingadded',
               'type': '3390/0c'}]
     }
}

Example 3: GET Storage pool when fcp disk is being added.

Request

GET /api/com.ibm.zaci.system/storagepools/data_pool
Host: 9.9.9.9:443
Authorization: Bearer qwert.asdfg.zxcvb
zACI-API: com.ibm.zaci.system/1.0
Accept: application/vnd.ibm.zaci.payload+json;version=1.0

Response

HTTP/1.1 200 OK
Date: Tue, 18 Oct 2016 12:03:58 GMT
zACI-API: com.ibm.zaci.system/1.0
Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0
Content-Length: 452
{
"kind": "instance",
"parameters": {
    "self": "/api/com.ibm.zaci.system/storagepools/data_pool"
    "name": "Analytics Data pool",
    "id": data_pool,
    "size": --,
    "status": 'beingedited',
    "used": --,
    "fs": 'ext4',
    "isFilesystemExist": True,
    "disks": [{'capacity': '20',
               'id': '36005076307ffc6a60000000000001f25',
               'progress': {'ADD2POOL': 'PENDING',
                            'PARTITION': 'INPROGRESS'},
               'self': '/api/com.ibm.zaci.system/fcp-disks/36005076307ffc6a60000000000001f25',
               'status': 'beingadded',
               'type': 'FCP'}]
     }
}

Add one or more disks to a storage pool

Use this operation to add one more disks to a Storage pool.

Authentication/Authorization

The caller must provide a API token, refer to Invoking API operations.

The user represented by the API token must have the following role:

administrator

Network

This operation is available from the following network(s):

management

HTTP Method and URI

POST /api/com.ibm.zaci.system/storagepools/{pool-id}/{subresource}

The URI variable {pool-id} is the Storage pool identifier and it can obtained via Retrieve all storage pools operation. This URI can be used to add either DASDs or fcp-disks to a pool and {subresource} can be used to identify the resource type to be added to the pool. {subresource} can be either storage-devices (to represent a DASD) or fcp-disks(to represent a SCSI disk/LUN).

Query Parameters

None

Request headers

For the list of required headers, refer to the Invoking API operations section.

The following sections describe the acceptable values for certain headers.

Accept media types

application/vnd.ibm.zaci.payload+json media type

Content-type media types

application/vnd.ibm.zaci.payload+json media type

Request message body

The request message body must contain data formatted as specified in the Content-type header, with kind=request. The format of the parameters object is described in the following table.

Name	Type	Rqd/Opt	Description
addDisks	List	Rqd	List of disks to be added. If `subresource` in URI is `storage-devices`, then list should contain DASDs device number and if `subresource` is `fcp-disks`, then list should contain SCSI disk unique identifiers.

Response

An HTTP status code of 202 indicates that the request has been accepted. HTTP status code of 409.2 indicates that the disks requested to add is already part of the same or different pool.

And in order to know the status and progress of storage devices which were added to the pool, the client can poll in regular interval the functionality - Retrieve a storage device until the Storage devices status becomes used from beingadded which indicates a successful addition. If the device addition fails, then the status attribute of storage devices will become free and progress property of Storage device indicates the Stage which Failed. Once the device become used or free, the client can stop polling and show the updates accordingly. Refer Resource Properties to know more about Storage devices properties.

Before adding disk/s to the pool, the disk/s will be formatted. So all the existing data on the disk/s added to the pool will be lost.

Any other HTTP status code indicates a failed operation. Refer to Common request validation reason codes for a list of common HTTP status codes and associated IBM Secure Service Container for IBM Cloud Private System API reason codes. The response message body contains a application/vnd.ibm.zaci.payload+json media type object, with kind=error. The failure object contains additional details, as described under the Error responses topic.

Example 1: Add DASDs to a Storage pool

Request

POST /api/com.ibm.zaci.system/storagepools/data_pool/storage-devices HTTP/1.1
Host: 9.9.9.9:443
Authorization: Bearer qwert.asdfg.zxcvb
zACI-API: com.ibm.zaci.system/1.0
Accept: application/vnd.ibm.zaci.payload+json;version=1.0
Content-type: application/vnd.ibm.zaci.payload+json;version=1.0
Content-length:200
{
"kind": "request",
"parameters": {
    "addDisks": ["0.0.a29d", "0.0.a29e"]
    }
}

Response

HTTP/1.1 202 Accepted
Date: Tue, 09 Aug 2016 08:12:31 GMT
zACI-API: com.ibm.zaci.system/1.0
Content-Length: 95
Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0
Server: z Software Test Appliance/1.1
{
"kind": "response",
"parameters": {
    "self": "/api/com.ibm.zaci.system/storagepools/data_pool"}
}

Example 2: Add fcp disks to a Storage pool

Request

POST /api/com.ibm.zaci.system/storagepools/data_pool/fcp-disks HTTP/1.1
Host: 9.9.9.9:443
Authorization: Bearer qwert.asdfg.zxcvb
zACI-API: com.ibm.zaci.system/1.0
Accept: application/vnd.ibm.zaci.payload+json;version=1.0
Content-type: application/vnd.ibm.zaci.payload+json;version=1.0
Content-length:200
{
"kind": "request",
"parameters": {
    "addDisks": [ '36005076307ffc6a60000000000001f25',
                  '36005076307ffc6a60000000000001f26']
    }
}

Response

HTTP/1.1 202 Accepted
Date: Mon, 28 Oct 2016 08:12:31 GMT
zACI-API: com.ibm.zaci.system/1.0
Content-Length: 95
Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0
Server: z Software Test Appliance/1.1
{
"kind": "response",
"parameters": {
    "self": "/api/com.ibm.zaci.system/storagepools/data_pool"}
}