FCP Disks

This chapter describes the fcp-disks resource, properties and operations.

Overview

An FCP disk represents a Logical Unit Number(LUN)/SCSI volume presented to the host from a storage target.

Resource Properties

An fcp-disks instance is represented by the following fields.

Name	Type	Description
self	String/URI	The URI of this instance
id	String	Unique Device Identifier of the LUN.
type	String	`FCP` - The disk type.
status	String	FCP Disk's status. Refer to status Enum values for supported values.
capacity	Long	Size of the disk in GB.
paths	List	Path refers to a channel to reach an fcp disk/LUN from the host. Path consists of initiator (FCP device), Target port(WWPN), LUN. One FCP device can be configured to see multiple LUNs through multiple target WWPNs. Refer FCP Path for various path attributes.
progress	Map of Stages/State	Progress of fcp disk when added to a Storage Pool. Refer Progress Stages Enum values for different Progress - Stages and Progress State Enum values for valid `State` of a Progress `Stage`.

FCP Path

Name	Type	Description
fcp-device	String	The initiator device.
target	String	The World Wide Port Name (WWPN) of the target controller.
lun	String	The Logical Unit Number in hexadecimal format.
status	String	The Path status.Valid values are active, faulty.

status Enum values

used - Disks which were already assigned to a Storage pool and in use.
free - Disks which are free and yet to be assigned to any storage pool.
beingadded - Disks which are in the process of adding to a Storage pool.
unknown - Disks status which could not be determined.

Progress Stages Enum values

PARTITION - A fcp disk being partitioned. It is the 1st stage of disk addition to pool.
ADD2POOL - A fcp disk being added to the Storage pool. It is the final/2nd Stage of disk addition to pool.

Progress State Enum values

Represents the State of a Stage. For example: If Stage 'PARTITION' has a State DONE, it indicates that the fcp disk has been successfully partitioned.

DONE - a successfully completed Progress Stage.
INPROGRESS- On going Stage
PENDING - Stage still to be executed.
FAILED - failed Stage.

Resource Operations

Retrieve a FCP disk

Use this operation to get a FCP disk instance. An instance can only be obtained after at least one successful FCP disks discovery operation, refer Retrieve list of fcp disks to know about FCP disks discovery based on FCP devices.

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/fcp-disks/{id}

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. HTTP status code of 404 indicates that the fcp disk corresponding to the given id is not found or LUN discovery API(refer Retrieve list of fcp disks) is not invoked before executing this api. The response message body contains data formatted as requested in the Accept header, with kind=instance. Refer Resource Properties for the FCP disk properties.

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 Secure Service Container 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

Request

GET /api/com.ibm.zaci.system/fcp-disks/36005076307ffc6a60000000000001f25 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: 563

{
"kind": "instance",
"properties":
    "self": "/api/com.ibm.zaci.system/fcp-disks/36005076307ffc6a60000000000001f25"
    "id": '36005076307ffc6a60000000000001f25',
    "type": 'FCP',
    "capacity": 30,
    "status": "free",
    "paths": [{'fcp-device': '0.0.1200',
               'target': '50050763070386a6',
               'lun': '401f402000000000',
               'status': 'active'},
              {'fcp-device': '0.0.1200',
               'target': '50050763070386a7',
               'lun': '401f402000000000',
               'status': 'active'
              }],
    "progress": {}
}

Retrieve a FCP disk for a path

Use this operation to get a FCP disk instance for a path.

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/fcp-disks?fcp-device={fcp device id}&target={target wwpn}&lun={lun identifier}

Query Parameters

Name	Type	Minimum values	Maximum values	Description
fcp-device	String	1	none	The FCP device bus id. Refer to the Retrieve a list of storage devices for list of fcp device bus ids.
target	String	1	none	The Target Controller's World Wide Port Name (WWPN).
lun	String	1	none	The Logical Unit Number in hexadecimal format.

To retrieve a FCP disk for a given path, then all the three query parameters fcp-device, target and lun has to be passed.

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, HTTP code 403 indicates that the fcp device is non-NPIV and HTTP code code 404 indicates that path is not valid. The response message body contains data formatted as requested in the Accept header, with kind=instance. Refer Resource Properties for the FCP disk properties.

Example

Request

GET /api/com.ibm.zaci.system/fcp-disks?fcp-device='0.0.1200'&target='50050763070386a6'&lun='401f402000000000' 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: 563

{
"kind": "instance",
"properties":
    "self": "/api/com.ibm.zaci.system/fcp-disks/36005076307ffc6a60000000000001f25"
    "id": '36005076307ffc6a60000000000001f25',
    "type": 'FCP',
    "capacity": 30,
    "status": "free",
    "paths": [{'fcp-device': '0.0.1200',
               'target': '50050763070386a6',
               'lun': '401f402000000000',
               'status': 'active'},
              {'fcp-device': '0.0.1200',
               'target': '50050763070386a7',
               'lun': '401f402000000000',
               'status': 'active'
              }],
    "progress": {}
}

Retrieve list of fcp disks

Use this operation to get all available fcp disks. Refer Resource Properties for FCP disk properties.

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

GET /api/com.ibm.zaci.system/fcp-disks

Query Parameters

Name	Type	Minimum values	Maximum values	Description
fcp-device	String	0	none	The FCP device bus id. Refer to the Retrieve a list of storage devices for list of fcp device bus ids. If query passed, then API will fetch LUNs discovered only through the requested fcp devices and if not passed, then all LUNs from all available FCP devices will be returned.
status	String	0	none	Refers to the resource property status. Return fcp-disks instances based on the status type. Returns all fcp-disks instances if this query parameter is not provided.

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

None

Response

An HTTP status code of 200 indicates that the request has been processed successfully. 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.

Example 1: Get list of fcp disks for initiator fcp device 0.0.1200

Request

GET /api/com.ibm.zaci.system/fcp-disks?fcp-device='0.0.1200' 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

Response

HTTP/1.1 200 Ok
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": "collection",
"self": "/api/com.ibm.zaci.system/fcp-disks",
"resource-version": "1.0",
"resource-name": "fcp-disks",
"instances": [
    {
    "self": "/api/com.ibm.zaci.system/fcp-disks/36005076307ffc6a60000000000001f25"
    "id": '36005076307ffc6a60000000000001f25',
    "type": 'FCP',
    "capacity": 30,
    "status": "free",
    "paths": [{'fcp-device': '0.0.1200',
               'target': '50050763070386a6',
               'lun': '401f402000000000',
               'status': 'active'},
              {'fcp-device': '0.0.1200',
               'target': '50050763070386a7',
               'lun': '401f402000000000',
               'status': 'active'
              }],
     "progress": {}
    },
    {
    "self": "/api/com.ibm.zaci.system/fcp-disks/36005076307ffc6a60000000000001f26"
    "id": '36005076307ffc6a60000000000001f26',
    "type": 'FCP',
    "capacity": 40,
    "status": "used",
    "paths": [{'fcp-device': '0.0.1200',
               'target': '50050763070386a6',
               'lun': '401f402000000001',
               'status': 'active'},
              {'fcp-device': '0.0.1200',
               'target': '50050763070386a7',
               'lun': '401f402000000001',
               'status': 'active'
              }],
    "progress": {}
    }]
}

Example 2: Get fcp disks for all fcp devices

Request

GET /api/com.ibm.zaci.system/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

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0
Content-Length: 1050
Connection: keep-alive
Zaci-Api: com.ibm.zaci.system/1.0
Server: Secure Service Container Installer/1.0

{
"kind": "collection",
"self": "/api/com.ibm.zaci.system/fcp-disks",
"resource-version": "1.0",
"resource-name": "fcp-disks",
"instances": [
    {
    "self": "/api/com.ibm.zaci.system/fcp-disks/36005076307ffc6a60000000000001500"
    "id": '36005076307ffc6a60000000000001500',
    "type": 'FCP',
    "capacity": 30,
    "status": "free",
    "paths": [{'fcp-device': '0.0.1200',
               'target': '50050763070386a6',
               'lun': '401f402000000000',
               'status': 'active'}],
    "progress": {}
    },
    {
    "self": "/api/com.ibm.zaci.system/fcp-disks/36005076307ffc6a60000000000001f26"
    "id": '36005076307ffc6a60000000000001f26',
    "type": 'FCP',
    "capacity": 40,
    "status": "used",
    "paths": [{'fcp-device': '0.0.1200',
               'target': '50050763070386a6',
               'lun': '401f402000000001',
               'status': 'active'}],
    "progress": {}
    }]
}

Example 3: Get fcp disks for a fcp device with 'free' status.

Request

GET /api/com.ibm.zaci.system/fcp-disks?fcp-device='0.0.1200'&status=free 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

Response

    HTTP/1.1 200 OK
    Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0
    Content-Length: 1050
    Connection: keep-alive
    Zaci-Api: com.ibm.zaci.system/1.0
    Server: Secure Service Container Installer/1.0

{
"kind": "collection",
"self": "/api/com.ibm.zaci.system/fcp-disks",
"resource-version": "1.0",
"resource-name": "fcp-disks",
"instances": [
    {
    "self": "/api/com.ibm.zaci.system/fcp-disks/36005076307ffc6a60000000000001500"
    "id": '36005076307ffc6a60000000000001500',
    "type": 'FCP',
    "capacity": 30,
    "status": "free",
    "paths": [{'fcp-device': '0.0.1200',
               'target': '50050763070386a6',
               'lun': '401f402000000000',
               'status': 'active'}],
    "progress": {}
    }]
}