KumoScale Provisioner API

3.1 Inventory Management

The inventory management APIs provide the means for maintaining the pool of KumoScale appliances, available for volume allocation.

This includes creating and modifying the pool, monitoring its health, maintaining its coherency and persistency, and extracting the pool’s information.

3.1.1 Add Backend

Add a KumoScale Backend to the backend pool.

Method

URI

POST

/backends

Linux Curl Command Example

curl -k --cert ./ssdtoolbox.pem -i -X POST -H 'Content-Type: application/json' -d '{"mgmtIPs": [ "172.28.129.10" ], "rack": "Rack2", "region": "Region2", "zone": "Zone2"}' https://10.93.66.121:8090/backends

Normal response codes: 200

3.1.1.1 Request

No URI parameters.

Example 1: Add Backend: JSON request

{

"mgmtIPs": [ "172.28.10.13" ],

"rack": "Dev",

"region": "ISR",

"zone": "Lab"

}

Parameter Name

Type

Is Mandatory

Description

mgmtIPs

List<String>

Mandatory

KS Management IP or DNS name

rack

String

Optional

KS location Rack ID

zone

String

Optional

Accessible Zone ID (e.g., shared switch)

region

String

Optional

Accessible Group ID (e.g., shared cage)

3.1.1.2 Response

Example 2: Add Backend: JSON response

{

"description":"Success",

"status":"Success"

}

Parameter Name

Type

Description

description

String

Result description.

status

String

Result code.

Success - Success

AlreadyExists - Backend already exists with mgmtIPs

NoGroups - Backend has no configured groups

InvalidLocationValue - Rack/Zone/Region has more than 255 chars

NotAvailable - Backend is incompatible, or the persistent ID was not provided.

KS Set Provisioner API result codes.

3.1.2 Update Backend

Update properties of an existing KumoScale Backend in the pool.

Method

URI

PUT

/backends/{id}

Linux Curl Command Example

curl -k --cert ./ssdtoolbox.pem -i -X PUT -H 'Content-Type: application/json' -d '{"rack": "Rack2", "region": "Region2", "zone": "Zone2"}' https://10.93.66.121:8090/backends/apCMak3chDoyCPJf

Normal response codes: 200

3.1.2.1 Request

URI parameters:

Parameter Name

Type

Is Mandatory

Description

id

String

Mandatory

KS persistent ID (~ MAC address).

Example 1: Update Backend: JSON request

{

"inUse": true,

"rack": "Dev",

"region": "ISR",

"zone": "Lab"

}

Parameter Name

Type

Is Mandatory

Description

rack

String

Optional

KS location Rack ID

zone

String

Optional

Accessible Zone ID (e.g., shared switch)

region

String

Optional

Accessible Group ID (e.g., shared cage)

inUse

boolean

Optional

Is it used for volume management

3.1.2.2 Response

Example 2: Update Backend: JSON response

{

"description":"Success",

"status":"Success"

}

Parameter Name

Type

Description

description

String

Result description.

status

String

Result code.

Success - Success

NotExists – A Backend with the required id does not exist.

InvalidLocationValue - Rack/Zone/Region has more than 255 chars.

KS Set Provisioner API result codes.

3.1.3 Remove Backend

Remove a KumoScale Backend from the pool.

Method

URI

DELETE

/backends/{id}

Linux Curl Command Example

curl -k --cert ./ssdtoolbox.pem -i -X DELETE --header "Content-Type: application/json" https://10.93.66.121:8090/backends/apCMak3chDoyCPJf

Normal response codes: 200

3.1.3.1 Request

URI parameters:

Parameter Name

Type

Is Mandatory

Description

id

String

Mandatory

KS persistent ID (~ MAC address).

3.1.3.2 Response

Example 2: Remove Backend: JSON response

{

"description":"Success",

"status":"Success"

}

Parameter Name

Type

Description

description

String

Result description.

status

String

Result code.

Success - Success

NotExists - A Backend with the required id does not exist.

BackendHasVolumes - There are configured volumes on the backend.

KS Delete Provisioner API result codes.

3.1.4 List Backends

Lists all of the KumoScale backends, currently in the Provisioner’s pool, and their state.

Method

URI

GET

/backends

Linux Curl Command Example

curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/backends

Normal response codes: 200

3.1.4.1 Request

No URI parameters.

3.1.4.2 Response

Example 109: List Backends: JSON response 

[

{

   "persistentID": "0c:c4:7a:66:96:83",

       "mgmtIPs": [

           "172.28.116.13"

       ],

       "rack": "Rack1",

       "zone": "Zone2",

       "region": "Region2",

       "inUse": true,

       "state": "Available",

       "totalCapacity": 8001574060032,

       "availableCapacity": 8001431797760,

       "lastProbTime": 1576066112110,

       "probeInterval": 60,

       "totalBW": 0,

       "availableBW": 0,

       "totalIOPS": 0,

       "availableIOPS": 0,

       "portals":[{

             "ip":"10.10.10.1",

             "port":4420,

             "transport":"RoCEv2"

           }]

   }

]

Parameter Name

Type

Description

persistentID

String

KS persistent ID (~ MAC address)

mgmtIPs

List<String>

KS Management IP or DNS name

rack

String

KS location Rack ID

zone

String

Accessible Zone ID (e.g., shared switch)

region

String

Accessible Group ID (e.g., shared cage)

inUse

boolean

Is it used for volume management

state

enum

Available / Unavailable

totalCapacity

long

KS current total capacity - The sum of all SSDs capacity

availableCapacity

long

KS sum of all available space

lastProbTime

long

Last probe time

probeInterval

int

Probe interval in secs

totalBW

long

KS total potential bandwidth in B/s

availableBW

long

KS available bandwidth in B/s (unused out of potential value)

totalIOPS

long

KS total potential IOPS

availableIOPS

long

KS available IOPS (unused out of potential value)

portals

List

A list of portals. Each entry includes the following parameters:

ip – the ip address of the portal

port – the port of the portal

transport – the transport type of the portal

3.1.5 Get Backend by ID

Retrieve a KumoScale backend and its details from the Provisioner’s pool according to its ID.

Method

URI

GET

/backends

Linux Curl Command Example

curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/backends/0c:c4:7a:66:96:83

Normal response codes: 200

3.1.5.1 Request

URI parameters:

Parameter Name

Type

Is Mandatory

Description

id

String

Mandatory

The persistent ID of the backend

3.1.5.2 Response

Example 110: Get Backend by Id: JSON response 

[

{

   "persistentID": "0c:c4:7a:66:96:83",

       "mgmtIPs": [

           "172.28.116.13"

       ],

       "rack": "Rack1",

       "zone": "Zone2",

       "region": "Region2",

       "inUse": true,

       "state": "Available",

       "totalCapacity": 8001574060032,

        "availableCapacity": 8001431797760,

       "lastProbTime": 1576066112110,

       "probeInterval": 60,

       "totalBW": 0,

       "availableBW": 0,

       "totalIOPS": 0,

       "availableIOPS": 0,

       "portals":[{

             "ip":"10.10.10.1",

             "port":4420,

             "transport":"RoCEv2"

           }]

   }

]

Parameter Name

Type

Description

persistentID

String

The persistent ID of the backend

mgmtIPs

List<String>

A list of KS Management IPs or DNS names

rack

String

KS location Rack ID

zone

String

Accessible Zone ID (e.g., shared switch)

region

String

Accessible Group ID (e.g., shared cage)

inUse

boolean

Is it currently in use by the Provisioner

state

enum

Is the backend Available / Unavailable

totalCapacity

long

KS total capacity - The sum of all SSDs capacity

availableCapacity

long

KS sum of all available space

lastProbTime

long

Last probe time

probeInterval

int

Probe interval in secs

totalBW

long

KS total potential bandwidth in B/s

availableBW

long

KS available bandwidth in B/s (unused out of potential value)

totalIOPS

long

KS total potential IOPS

availableIOPS

long

KS available IOPS (unused out of potential value)

portals

List

ip – the portal ip address

port – the portal port

transport – the portal transport type

3.1.6 Get Info

Returns the total of the free capacities on all the KumoScales in the Provisioner’s pool.

Method

URI

GET

/info

Linux Curl Command Example

curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/info

Normal response codes: 200

3.1.6.1 Request

No URI parameters.

3.1.6.2 Response

Example 111: Get Info: JSON response 

{

"totalFreeSpace": 1920315949046,

"version": "1.1",

"syslogsBackend":"0c:c4:7a:88:09:ee"

}

Parameter Name

Type

Description

totalFreeSpace

long

The total free space in bytes (on all KumoScale appliances)

version

String

Provisioner software version

syslogsBackend

String

The persistentID of the backend the syslog config was learned from

3.2 Multi-Tenancy Management

3.2.1 Create Tenant

Create a tenant with capacity and performance budgets for a multi-tenancy environment.

Method

URI

POST

/tenants

Linux Curl Command Example

curl -k --cert ./ssdtoolbox.pem -i -X POST -H 'Content-Type: application/json' -d '{"tenantId": "163988d3-e871-4e0d-913d-12a7f3f0187e","name":"TEST_TENANT","capacity":1000,"totalIOPS":1000000,"totalBW":1000000}' https://10.93.66.121:8090/tenants/

Normal response codes: 200

3.2.1.1 Request

No URI parameters.

Example 1: Create Tenant: JSON request

{

   "name":"TEST_TENANT",

   "capacity":1000,

   "totalIOPS":1000000,

   "totalBW":1000000

}

Parameter Name

Type

Is Mandatory

Description

name

String

Mandatory

The tenant name

capacity

long

Mandatory

The tenant capacity budget in GB.

totalIOPS

long

Mandatory

The tenant IOPS budget.

totalBW

long

Mandatory

The tenant bandwidth budget in B/s.

tenantId

String

Optional

The tenant ID

3.2.1.2 Response

Example 2: Create Tenant: JSON response

{

"description":"Success",

"status":"Success",

"tenantId":"163988d3-e871-4e0d-913d-12a7f3f0187e"

}

Parameter Name

Type

Description

description

String

Result description.

status

String

Result code.

Success - Success

InvalidInput – An input parameter is invalid.

TenantAlreadyExists – A tenant with input name already exists.

NoBackends – No backends are configured.

KS Set Provisioner API result codes.

tenantId

String

The tenant ID

3.2.2 Get Tenants

Lists all the configured tenants, their configuration and information.

Method

URI

GET

/tenants

Linux Curl Command Example

curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/tenants

Normal response codes: 200

3.2.2.1 Request

No URI parameters.

3.2.2.2 Response

Example 2: Get Tenants: JSON response

[

   {

     "tenantId":"0",

     "name":"default",

     "capacity":1024,

     "totalIOPS":0,

       "totalBW":4,

       "consumedCapacity":0,

       "consumedIOPS":0,

       "consumedBW":0

   },

{

       "tenantId":"8e601fd1-e3b7-41ad-8f54-bbd621c07f21",

       "name":"TEST_TENANT",

      "capacity":1000,

       "totalIOPS":1000000,

       "totalBW":1000000,

       "consumedCapacity":0,

       "consumedIOPS":0,

       "consumedBW":0

   }

]

Parameter Name

Type

Description

tenantId

String

The tenant ID

name

String

The tenant name

capacity

number

The tenant capacity budget in GB

totalIOPS

number

The tenant IOPS budget.

totalBW

number

The tenant bandwidth budget in B/s.

consumedCapacity

number

The tenant used capacity in GB.

consumedIOPS

number

The amount of consumed IOPS.

consumedBW

number

The amount of consumed bandwidth in B/s.

3.2.3 Modify Tenant

Update the tenant’s budget.

Method

URI

PUT

/tenants/{tenantId}

Linux Curl Command Example

curl -k --cert ./ssdtoolbox.pem -i -X PUT -H 'Content-Type: application/json' -d '{"tenantId":"b803fdba-eac9-4340-ae99-4febe131e92b","capacity":1000,"totalIOPS":1000000,"totalBW":1000000}' https://10.93.66.121:8090/tenants/{tenantId}

Normal response codes: 200

Request

No URI parameters

Example 1: Modify Tenant: JSON request

{

     "tenantId":"b803fdba-eac9-4340-ae99-4febe131e92b",

     "capacity":2000,

     "totalIOPS":2000000,

     "totalBW":2000000

}

Parameter Name

Type

Is Mandatory

Description

tenantId

String

Mandatory

The tenant ID

capacity

number

Mandatory

The updated tenant’s capacity budget in GB.

totalIOPS

number

Mandatory

The updated tenant’s IOPS budget.

totalBW

number

Mandatory

The updated tenant’s bandwidth budget in B/s.

Response

Example 2: Modify Tenant: JSON response

{

"description":"Success",

"status":"Success"

}

Parameter Name

Type

Description

description

String

Result description.

status

String

Result code.

Success - Success

InvalidInput – An input parameter is invalid.

TenantNotFound – The Tenant ID does not exist.

NoBackends – No backends are configured.

KS Set Provisioner API result codes.

3.2.4 Delete Tenant

Delete a configured tenant.

Method

URI

DELETE

/tenants/{tenantId}

Linux Curl Command Example

curl -k --cert ./ssdtoolbox.pem -i -X DELETE -H 'Content-Type: application/json' https://10.93.66.121:8090/tenants/11115ca6-5c7a-421a-303b-cfc145ba2b68

Normal response codes: 200

Request

  • URI parameters:

Parameter Name

Type

Is Mandatory

Description

tenantId

String

Mandatory

The tenant ID

Response

Example 2: Delete Tenant: JSON response

{

"description":"Success",

"status":"Success"

}

Parameter Name

Type

Description

description

String

Result description.

status

String

Result code.

Success – Success

InvalidInput – An input parameter is invalid.

TenantNotFound – The Tenant ID does not exist.

NoBackends – No backends are configured.

TenantHasVolumes – There are volumes configured over the tenant.

KS Set Provisioner API result codes.

3.3 Volume Management

Allocate volumes for the user.

    3.3.1 Create Volume

    Create a volume in the pool.

    Method

    URI

    POST

    /{tenantId}/volumes

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X POST -H 'Content-Type: application/json' -d '{"capacity": 20,

      “provisioningType”: “THIN”,

    “reservedSpacePercentage”: 10,

      "storageClass": {

       "sameRackAllowed": true,

       "numReplicas": 1,

        "racks": [ "Dev" ],

       "regions": [ "ISR" ],

       "zones": [ "Lab" ] ,

       "maxIOPSPerGB": 1,

       "desiredIOPSPerGB": 1,

       "maxBWPerGB": 1,

       "desiredBWPerGB": 1,

       "blockSize": 1

      },

      "uuid": "163988d3-e871-4e0d-913d-12a7f3f0187e",

      "alias": "Vol1"}' https://10.93.66.121:8090/{tenantId}/volumes

    Normal response codes: 200

    3.3.1.1 Request

    No URI parameters.

    Example 1: Create Volume: JSON request

    {

    "capacity": 20,

    “provisioningType”: “THIN”,

    “reservedSpacePercentage”: 10,

    "storageClass": {

        "sameRackAllowd": true,

        "numReplicas": 1,

        "racks": [ "Dev" ],

        "regions": [ "ISR" ],

        "zones": [ "Lab" ] ,

        "maxIOPSPerGB": 1,

        "desiredIOPSPerGB": 1,

        "maxBWPerGB": 1,

        "desiredBWPerGB": 1,

        "blockSize": 512

     },

    "uuid": "163988d3-e871-4e0d-913d-12a7f3f0187e",

    "alias": "Vol1"

    }

    Parameter Name

    Type

    Is Mandatory

    Description

    capacity

    long

    Mandatory

    Requested capacity in GiB granularity.

    alias

    String

    Mandatory

     

    uuid

    String

    Optional

     

    provisioningType

    Enum (THICK ,THIN)

    Optional

    The volume provisioning type: thin-provisioned or thick provisioned. The default is thick.

    reservedSpacePercentage

    int

    Optional

    For thin volumes:

    The initial allocated capacity in percentage.

    Default is max(10% of volume capacity, 20GB).

    Minimal value is max(2% of volume capacity, 20GB).

    Maximum value is the volume capacity.

    storageClass

    StorageClass

    Optional

     

    sameRackAllowed (storageClass)

    boolean

    Optional

    for replicated volumes:

    Can more than one replica be allocated on the same rack.

    Default – false.

    numReplicas (storageClass)

    int

    Optional

    Default – 1 (a non-resilient volume).

    racks (storageClass)

    List<String>

    Optional

    A list of racks which the volume(s) may reside on.

    zones (storageClass)

    List<String>

    Optional

    Lists of zones the volume(s) should be accessible from.

    regions (storageClass)

    List<String>

    Optional

    Lists of regions the volumes should be accessible from.

    maxIOPSPerGB (storageClass)

    int

    Optional

    Upper limit for IOPS/GB.

    desiredIOPSPerGB (storageClass)

    int

    Optional

    Desired IOPS/GB.

    maxBWPerGB (storageClass)

    int

    Optional

    Upper limit for bandwidth in B/s per GB.

    desiredBWPerGB (storageClass)

    int

    Optional

    Desired bandwidth in B/s per GB.

    blockSize

    (storageClass)

    enum

    Optional

    Volume block size in bytes – 512 or 4096 (Default).

    tenantId

    String

    Optional

    The tenant ID of the tenant the volume is created for.

    3.3.1.2 Response

    Example 2: Create Volume: JSON response

    {

    "description":"Success",

    "status":"Success"

    }

    Parameter Name

    Type

    Description

    description

    String

    Result description.

    status

    String

    Result code.

    Success - Success

    AlreadyExists - A volume with requested UUID already exists.

    InvalidInput - No alias was provided.

    AlreadyExists - A volume with the requested alias already exists.

    InvalidReplicas - Invalid number of replicas.

    NoMatchingBackend - Could not find a compatible backend to allocate the at least one of the replicas on.

    NotEnoughMatchingBackends - Could not create all replicas.

    TenantNotFound – The Tenant ID does not exist.

    TenantCapacityExceeded – The tenant has reached its capacity budget.

    KS Create Volume API result codes.

    3.3.2 Delete Volume

    Delete a volume from the KumoScale appliance.

    Method

    URI

    DELETE

    /{tenantId}/volumes/{id}

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X DELETE --header "Content-Type: application/json" https://10.93.66.121:8090/{tenantId}/volumes/163988d3-e871-4e0d-913d-12a7f3f0187e

    Normal response codes: 200

    3.3.2.1 Request

    URI parameters:

    Parameter Name

    Type

    Is Mandatory

    Description

    id

    String

    Mandatory

    Volume UUID.

    tenantId

    String

    Optional

    The Tenant ID which the volume belongs to

    3.3.2.2 Response

    Example 2: Delete Volume: JSON response

    {

    "description":"Success",

    "status":"Success"

    }

    Parameter Name

    Type

    Description

    description

    String

    Result description.

    status

    String

    Result code.

    Success - Success

    NotExists - A Backend with the required id does not exist.

    TenantNotFound – The Tenant ID does not exist.

    KS Delete Volume API result codes.

    3.3.3 Get Volumes

    Retrieve the location of the KumoScale which the Volume(s) was configured on.

    Method

    URI

    GET

    /{tenantId}/volumes/{id}

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/volumes

    Example with the use of limit and offset parameters

    curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/{tenantId}/volumes?limit=5&offset=0

    Example with the use of limit and marker parameters

    curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/{tenantId}/volumes?limit=5&marker= 5836c3cc-1c7e-4f2e-9698-e39175a41bd7

    Normal response codes: 200

    3.3.3.1 Request

    URI parameters:

    Parameter Name

    Type

    Is Mandatory

    Description

    id

    String

    Mandatory (for single query)

    Volume UUID.

    limit

    int

    optional

    Requests a page size of items. Returns a number of items up to a limit value.

    Offset

     

    int

    optional

    Used in conjunction with Limit to return a selection of items. Offset determines the starting point of the list. The engine will retrieve Volumes starting from the offset.

    marker

    String

    optional

    The engine will select Volumes starting from this UUID and greater than this value.

    tenantId

    String

    Optional

    The Tenant ID which the volume belongs to.

    3.3.3.2 Response

    Example 112: Get Volumes: JSON response 

    [ {

       "alias": "pvc-6a7086af-236c-48c5-b2c1-161734892bd6",

       "uuid": "e3c666d5-9933-43b8-9d70-2765f5fb9b3c",

       "capacity": 1099511627776,

       "provisioningType": "THIN",

       "reservedSpace": 1073741824

       "numReplicas": 1,

       "maxIOPS": 10240000,

       "desiredIOPS": 0,

       "maxBW": 0,

       "desiredBW": 0,

       "blockSize": "4KB",

       "maxReplicaDownTime": 0,

       "tenantId": "e3c666d5-1111-43b8-9d70-9665f5fb9b3c",

       "location": [

         {

           "uuid": "e3c666d5-9933-43b8-9d70-2765f5fb9b3c",

           "backend": {

             "persistentID": "00:0c:29:d1:5a:4c"

           },

           "replicaState": "Available",

           "currentStateTime": 10704

         }

       ],

       "snapshotID": "01d7571c-5eb3-4afd-a609-9ea9ac23eaec",

       "writable": true,

       "reservedSpace": 164282499072]

    Parameter Name

    Type

    Description

    uuid

    String

    Volume UUID.

    alias

    String

    Volume alias.

    capacity

    long

    Volume capacity in bytes.

    provisioningType

    Enum (THICK ,THIN, OTHER)

    The type of the volume: THIN/THICK/OTHER.

    OTHER is used for a snapshot volume

    reservedSpace

    int

    For thin volumes:

    The actual initially allocated capacity in bytes.

    numReplicas

    int

    Number of volume replicas.

    maxIOPS

    long

    Upper limit for IOPS

    desiredIOPS

    long

    Desired IOPS

    maxBW

    long

    Upper limit for BW

    desiredBW

    long

    Desired BW

    blockSize

    enum

    Volume block size – 512B or 4KB

    snapshotID

    String

    For snapshot volumes only – the source snapshot UUID.

    writable

    boolean

    For snapshot volumes only – true if the volume is writable.

    reservedSpace

    long

    For snapshot volumes only – reserved space in bytes

    location

    List<VolumeLocation>

     

    uuid (location)

    String

    Volume replica UUID.

    backend (location)

    Backend

    The persistent ID of the backend the replica resides in.

    replicaState (location)

    ReplicaState

    Volume replica state - Available, Terminating, Missing or Synchronizing.

    currentStateTime (location)

    long

    For replicated volumes: The duration of the current state of the replica, in ms.

    tenantId

    String

    The Tenant ID which the volume belongs to.

    3.3.4 Get Volume by Alias

    Retrieve the location of the KS which the Volume(s) was configured on by the volume alias.

    Method

    URI

    GET

    /{tenantId}/volumes_by_alias/{alias}

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/{tenantId}/volumes_by_alias/vol1

    Normal response codes: 200

    3.3.4.1 Request

    URI parameters:

    Parameter Name

    Type

    Is Mandatory

    Description

    alias

    String

    Mandatory

    Volume alias.

    tenantId

    String

    Optional

    The Tenant ID which the volume belongs to.

    3.3.4.2 Response

    See ‎3.3.3.2.

    3.3.5 Expand Volume

    Expand exists volume on all its KS replicas.

    Method

    URI

    PATCH

    /{tenantId}/volumes/{id}

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X PATCH --header "Content-Type: application/json" –d "{"newCapacity": 0}" https://10.93.66.121:8090/{tenantId}/volumes/163988d3-e871-4e0d-913d-12a7f3f0187e

    Normal response codes: 200

    3.3.5.1 Request

    URI parameters:

    Parameter Name

    Type

    Is Mandatory

    Description

    id

    String

    Mandatory

    Volume UUID.

    newCapacity

    int

    Mandatory

    New Volume capacity in GB.

    tenantId

    String

    Optional

    The Tenant ID which the volume belongs to.

    Example 1: Create Volume: JSON request

    {

    "newCapacity": 20

    }

    3.3.5.2  Response

    Example 2: Expand Volume: JSON response

    {

    "description":"Success",

    "status":"Success"

    }

    Parameter Name

    Type

    Description

    description

    String

    Result description.

    status

    String

    Result code.

    Success - Success

    NotExists - A Backend with the required id does not exist.

    InvalidSize – Current capacity is greater than or equal to newCapacity

    NoFreeSpace – There is not enough free space on at least one of the volume’s backend.

    TenantNotFound – The Tenant ID does not exist.

    TenantCapacityExceeded – The tenant has reached its capacity budget.

    KS Modify Volume API result codes.

    3.3.6 Add Replica

    Add another replica to a replicated volume.

    Method

    URI

    POST

    /{tenantId}/replica/{id}

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X POST -H 'Content-Type: application/json' -d '{"sameRackAllowed": true,

       "racks": [ "Dev" ],

       "regions": [ "ISR" ],

        "zones": [ "Lab" ]

    }' https://10.93.66.121:8090/{tenantId}/replica/163988d3-e871-4e0d-913d-12a7f3f0187e

    Normal response codes: 200

    3.3.6.1 Request

    No URI parameters.

    Example 1: Add Replica: JSON request

    {

       "sameRackAllowed": true,

       "racks": [ "Dev" ],

       "regions": [ "ISR" ],

       "zones": [ "Lab" ]

    }

    Parameter Name

    Type

    Is Mandatory

    Description

    uuid

    String

    Mandatory

    The volume’s UUID.

    sameRackAllowed

    boolean

    Optional

    Can the replica’s be allocated on the same rack.

    Default – false.

    racks

    List<String>

    Optional

    A list of racks the volume(s) should reside on.

    zones

    List<String>

    Optional

    Lists of zones the volume(s) should be accessible from.

    regions

    List<String>

    Optional

    Lists of regions the volumes should be accessible from.

    tenantId

    String

    Optional

    The Tenant ID which the volume belongs to.

    3.3.6.2 Response

    Example 2: Add Replica: JSON response

    {

    "description":"Success",

    "status":"Success"

    }

    Parameter Name

    Type

    Description

    description

    String

    Result description.

    status

    String

    Result code.

    Success - Success

    NotExists - A Backend with the required id does not exist.

    NotReplicated – The volume is not replicated.

    NoMatchingBackend - Could not find a compatible backend to allocate the replica on.

    InvalidReplicas - Invalid number of replicas.

    ReplicaTerminating – The replica is terminating.

    NoFreeSpace - There is not enough free space.

    TopologyConstraints – Cannot add a replica due to topology constraints.

    NotInUse - Some of the backends are not in use.

    SameRackNotAllowed - Could not find matching backends on different racks for replication.

    NotAvailable - The backend is not available.

    NotEnoughMatchingBackends - There were not enough backends which matched the storage class criteria.

    TenantNotFound – The Tenant ID does not exist.

    TenantCapacityExceeded – The tenant has reached its capacity budget.

    KS Create Volume API result codes.

    3.3.7 Delete Replica

    Mark a replica to be removed from a Replicated volume.

    Method

    URI

    PATCH

    /{tenantId}/replica/{id}/{replicaID}

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X PATCH --header "Content-Type: application/json" https://10.93.66.121:8090/{tenantId}/replica/163988d3-e871-4e0d-913d-12a7f3f0187e/48f27797-ff72-42dc-8121-069699f97b7e

    Normal response codes: 200

    3.3.7.1 Request

    URI parameters:

    Parameter Name

    Type

    Is Mandatory

    Description

    id

    String

    Mandatory

    Volume UUID.

    replicaID

    String

    Mandatory

    The volume ID of the replica (physical volume).

    tenantId

    String

    Optional

    The Tenant ID which the volume belongs to.

    3.3.7.2 Response

    Example 2: Delete Replica: JSON response

    {

    "description":"Success",

    "status":"Success"

    }

    Parameter Name

    Type

    Description

    description

    String

    Result description.

    status

    String

    Result code.

    Success - Success

    NotExists - A Backend with the required id does not exist.

    NotReplicated – The volume is not replicated.

    AllReplicasDown – All replicas are down.

    ReplicaTerminating – One of the replicas is "Terminating".

    TenantNotFound – The Tenant ID does not exist.

    3.3.8 Delete Replica Confirm

    Remove a replica (delete volume) from a Replicated volume.

    Method

    URI

    DELETE

    /{tenantId}/replica/{volumeID}/{replicaID}

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X DELETE --header "Content-Type: application/json" https://10.93.66.121:8090/{tenantId}/replica/163988d3-e871-4e0d-913d-12a7f3f0187e/48f27797-ff72-42dc-8121-069699f97b7e

    Normal response codes: 200

    3.3.8.1 Request

    URI parameters:

    Parameter Name

    Type

    Is Mandatory

    Description

    volumeID

    String

    Mandatory

    Volume UUID.

    replicaID

    String

    Mandatory

    The volume ID of the replica (physical volume).

    tenantId

    String

    Optional

    The Tenant ID which the volume belongs to.

    3.3.8.2 Response

    Example 2: Delete Replica Confirm: JSON response

    {

    "description":"Success",

    "status":"Success"

    }

    Parameter Name

    Type

    Description

    description

    String

    Result description.

    status

    String

    Result code.

    Success - Success

    NotExists - A Backend with the required id does not exist.

    NoTerminating – None of the replicas is "Terminating".

    TenantNotFound – The Tenant ID does not exist.

    KS Delete Volume API result codes.

    3.3.9 Set Replica State

    Sets a volume replica state to either Available or Missing.

    Method

    URI

    PATCH

    /{tenantId}/replica/{id}/{replicaID}/{replicaState}

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X PATCH --header "Content-Type: application/json" https://10.93.66.121:8090/{tenantId}/replica/163988d3-e871-4e0d-913d-12a7f3f0187e/48f27797-ff72-42dc-8121-069699f97b7e/Available

    Normal response codes: 200

    3.3.9.1 Request

    URI parameters:

    Parameter Name

    Type

    Is Mandatory

    Description

    id

    String

    Mandatory

    Volume UUID.

    replicaID

    String

    Mandatory

    The volume ID of the replica (physical volume).

    replicaState

    String

    Mandatory

    The replica state: Available, Missing or Synchronizing.

    tenantId

    String

    Optional

    The Tenant ID which the volume belongs to.

    3.3.9.2 Response

    Example 1: Set Replica State: JSON response

    {

    "description":"Success",

    "status":"Success"

    }

    Parameter Name

    Type

    Description

    description

    String

    Result description.

    status

    String

    Result code.

    Success – Success

    InvalidInput - Invalid replica state

    NotExists – A replica with this ID not found.

    NotReplicated – The volume is not replicated.

    ReplicaTerminating – The replica is terminating.

    TenantNotFound – The Tenant ID does not exist.

    3.3.10 Create Snapshot

    Create a snapshot over a volume.

    Method

    URI

    POST

    /{tenantId}/snapshots

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X POST -H 'Content-Type: application/json' -d '{"alias":"TestSnap3",

    "volumeID":"a039bf3b-35c1-43d3-a831-31e2f5bce37a",

    "snapshotID":"668965ad-84f8-4081-891d-989790e1e310",

    "reservedSpacePercentage":10}' https://10.93.66.121:8090/{tenantId}/snapshots

    Normal response codes: 200

    3.3.10.1 Request

    No URI parameters.

    Example 1: Create Snapshot: JSON request

    {

    "alias":"TestSnap3",

    "volumeID":"a039bf3b-35c1-43d3-a831-31e2f5bce37a",

    "snapshotID":"668965ad-84f8-4081-891d-989790e1e310",

    "reservedSpacePercentage":10

    }

    Parameter Name

    Type

    Is Mandatory

    Description

    alias

    String

    Mandatory

    Snapshot alias (same rules like volume alias)

    volumeID

    String

    Mandatory

    Volume UUID of the parent volume for snapshot.

    snapshotID

    String

    Optional

    The snapshot UUID.

    reservedSpacePercentage

    int

    Optional

    Percentage of the parent volume for used for log

    Default is max(10% of volume capacity, 20GB).

    Minimal value is max(2% of volume capacity, 20GB).

    Maximum value is the volume capacity.

    tenantId

    String

    Optional

    The Tenant ID which the volume belongs to.

    3.3.10.2 Response

    Example 2: Create Snapshot: JSON response

    {

    "description":"Success",

    "status":"Success",

    "persistentId":"41a81c17-ffa8-480c-b26c-1fb514f5dca2"

    }

    Parameter Name

    Type

    Description

    description

    String

    Result description.

    status

    String

    Result code.

    Success - Success

    NotExists - Volume is not exists with id

    Replicated - Volume is replicated

    TenantNotFound - The Tenant ID does not exist.

    TenantCapacityExceeded - The tenant has reached its capacity budget.

    KS Create Snapshot API result codes.

    persistentId

    String

    The snapshot UUID.

    3.3.11 Delete Snapshot

    Delete a snapshot.

    Method

    URI

    DELETE

    /{tenantId}/snapshots/{id}

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X DELETE --header "Content-Type: application/json" https://10.93.66.121:8090/{tenantId}/snapshots/163988d3-e871-4e0d-913d-12a7f3f0187e

    Normal response codes: 200

    3.3.11.1 Request

    URI parameters:

    Parameter Name

    Type

    Is Mandatory

    Description

    id

    String

    Mandatory

    Snapshot UUID.

    tenantId

    String

    Optional

    The Tenant ID which the volume belongs to.

    3.3.11.2 Response

    Example 2: Delete Snapshot: JSON response

    {

    "description":"Success",

    "status":"Success"

    }

    Parameter Name

    Type

    Description

    description

    String

    Result description.

    status

    String

    Result code.

    Success - Success

    NotExists – A snapshot with this ID does not exist

    Assigned – a snapshot volume is still assigned for this snapshot

    TenantNotFound - The Tenant ID does not exist.

    KS Delete Snapshot API result codes.

    3.3.12 Get Snapshots

    Retrieve a list of all of the snapshots if the limit parameter is not specified.

    Otherwise, retrieve a list with size <=limit snapshots (a page).

    Method

    URI

    GET

    /{tenantId}/snapshots/{id}

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/{tenantId}/snapshots

    Example with the use of limit and offset parameters

    curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/{tenantId}/snapshots?limit=5&offset=0

    Example with the use of limit and marker parameters

    curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/{tenantId}/snapshots?limit=5&marker=5836c3cc-1c7e-4f2e-9698-e39175a41bd7

    Normal response codes: 200

    3.3.12.1 Request

    URI parameters:

    Parameter Name

    Type

    Is Mandatory

    Description

    id

    String

    Mandatory (when retrieving a specific snapshot)

    Snapshot UUID.

    limit

    int

    optional

    Requests a page size of items. Returns a number of items up to the limit.

    Offset

     

    int

    optional

    Used in conjunction with Limit to return a selection of items. Offset determines the starting point of the list. The engine will retrieve Volumes starting from the offset.

    marker

    String

    optional

    The engine will select Snapshots starting from this UUID and greater than this value.

    tenantId

    String

    Optional

    The Tenant ID which the volume and snapshot belong to.

    3.3.12.2 Response

    Example 113: Get Snapshots: JSON response 

    [

    {

       "alias": "TestSnap3",

       "volumeID": "8e27042d-c923-4537-ade2-42356bd4a132",

       "snapshotID": "668965ad-84f8-4081-891d-989790e1e310",

       "replicaID": "8e27042d-c923-4537-ade2-42356bd4a132",

       "reservedSpacePercentage": 10,

       "reservedSpace": 10737418240,

       "capacity": 10737418240,

       "timestamp": 1586166064958,

       "tenantId": "0"

    }

    ]

    Parameter Name

    Type

    Description

    volumeID

    String

    The volume UUID.

    alias

    String

    The snapshot alias.

    ReplicaID

    String

    The UUID of the volume’s replica which the snapshot was taken from.

    capacity

    long

    The snapshot capacity in bytes.

    snapshotID

    String

    The snapshot UUID.

    reservedSpace

    long

    The allocated space in bytes

    reservedSpacePercentage

    integer

    The allocated space in percentage

    timestamp

    long

    The timestamp from when the snapshot was taken.

    tenantId

    String

    The ID of the tenant the snapshot belongs to.


    3.3.13 Get Snapshots by Volume

    Get Snapshots according to a Volume UUID.

    Method

    URI

    GET

    /{tenantId}/snapshots_by_vol/{volID}

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/{tenantId}/snapshots _by_vol/41a81c17-ffa8-480c-b26c-1fb514f5dca2

    Normal response codes: 200

    3.3.13.1 Request

    URI parameters:

    Parameter Name

    Type

    Is Mandatory

    Description

    volID

    String

    Mandatory

    The volume UUID.

    tenantId

    String

    Optional

    The Tenant ID which the volume belongs to.

    3.3.13.2 Response

    See Response

    3.3.14 Get Snapshots by Alias

    Get a snapshot by its alias

    Method

    URI

    GET

    /{tenantId}/snapshots_by_alias/{alias}

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -X GET https://10.93.66.121:30100/{tenantId}/snapshots_by_alias/sns1

    Normal response codes: 200

    3.3.14.1 Request

    URI parameters:

    Parameter Name

    Type

    Is Mandatory

    Description

    alias

    String

    Mandatory

    The snapshot alias.

    tenantId

    String

    Optional

    The Tenant ID which the snapshot belongs to.

    3.3.14.2 Response

    See Response

    3.3.15 Create Snapshot Volume

    Create a snapshot volume over a snapshot.

    Method

    URI

    POST

    /{tenantId}/snapshots

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X POST -H 'Content-Type: application/json' -d '{"alias":"TestSnap3",

    "volumeID":"a039bf3b-35c1-43d3-a831-31e2f5bce37a",

    "snapshotID":"668965ad-84f8-4081-891d-989790e1e310",

    "reservedSpacePercentage":10,

    "writable":true,

    "maxIOPSPerGB":100,

    "maxBWPerGB":2000}' https://10.93.66.121:8090/{tenantId}/snapshot_volumes

    Normal response codes: 200

    3.3.15.1 Request

    No URI parameters.

    Example 1: Create Snapshot Volume: JSON request

    {

    "alias":"TestSnap3",

    "volumeID":"a039bf3b-35c1-43d3-a831-31e2f5bce37a",

    "snapshotID":"668965ad-84f8-4081-891d-989790e1e310",

    "reservedSpacePercentage":10,

    "writable":true,

    "maxIOPSPerGB":100,

    "maxBWPerGB":2000

    }

    Parameter Name

    Type

    Is Mandatory

    Description

    alias

    String

    Mandatory

    The volume alias

    volumeID

    String

    Optional

    The volume UUID.

    snapshotID

    String

    Mandatory

    The snapshot UUID.

    reservedSpacePercentage

    int

    Optional

    For writable snapshot volumes only: The percentage of the parent volume to reserve for the snapshot volume use.

    Default is max(10% of volume capacity, 20GB).

    Minimal value is max(2% of volume capacity, 20GB).

    Maximum value is the volume capacity.

    writable

    boolean

    Optional

    Indicates if the snapshot volume is RO or RW.

    (The default is false).

    maxIOPSPerGB

    int

    Optional

    The upper limit for IOPS/GB (QoS).

    maxBWPerGB

    int

    Optional

    The upper limit for bandwidth in B/s per GB (QoS).

    tenantId

    String

    Optional

    The Tenant ID which the volume belongs to.

    3.3.15.2 Response

    Example 2: Create Snapshot Volume: JSON response

    {

    "description":"Success",

    "status":"Success",

    "persistentId":"41a81c17-ffa8-480c-b26c-1fb514f5dca2",

    }

    Parameter Name

    Type

    Description

    description

    String

    Result description.

    status

    String

    Result code.

    Success - Success

    NotExists – A snapshot with this id does not exist

    AlreadyExists - A volume with requested UUID already exists or volumes already assigned for this snapshot.

    TenantNotFound - The Tenant ID does not exist.

    TenantCapacityExceeded - The tenant has reached its capacity budget.

    KS Create Snapshot Volume API result codes.

    persistentId

    String

    The Snapshot Volume UUID.

    3.3.16 Migrate Volume

    Migrate a replica of a volume from one backend to another according to the volume’s storage class constraints. This command may be used for online replicated volumes only.

    Method

    URI

    POST

    /{tenantId}/migrate_volume

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X POST -H 'Content-Type: application/json' -d '{"repId":"48f27797-ff72-42dc-8121-069699f97b7e", "volId":"a039bf3b-35c1-43d3-a831-31e2f5bce37a"}' https://10.93.66.121:8090/{tenantId}/migrate_volume

    Normal response codes: 200

    3.3.16.1 Request

    No URI parameters.

    Example 1: Migrate Volume: JSON request

    {

    "repId":"48f27797-ff72-42dc-8121-069699f97b7e",

    "volId":"a039bf3b-35c1-43d3-a831-31e2f5bce37a"

    }

    Parameter Name

    Type

    Is Mandatory

    Description

    repId

    String

    Mandatory

    The ID of the replica you want to migrate

    volId

    String

    Mandatory

    The volume UUID th replica belongs to.

    tenantId

    String

    Optional

    The Tenant ID which the volume belongs to.

    3.3.16.2 Response

    Example 2: Migrate Volume: JSON response

    {

    "description":"Success",

    "status":"Success",

    }

    Parameter Name

    Type

    Description

    description

    String

    Result description.

    status

    String

    Result code.

    Success – Success

    ReplicaNotFound - a replica with the repId doesn’t exist.

    VolumeNoFoundthe volume is not found.

    TaskNotFound – the task not found.

    NotReplicated – the volume is not replicated.

    NotEnoughReplicas – The volumes does not have enough available replicas (the number it was created with)

    VolumeNotPublished – The volume is not published (is not online)

    ReplicaTerminating – The replica is in ‘Terminating’ state

    HostNotFound – The host was not found.

    TaskAlreadyRunning – There is an active remote migration task running on this volume.

    NoBackendToMigrateReplica - No matching backend to migrate the replica to.

    TenantNotFound - The Tenant ID does not exist.

     

    3.4 Logging to an External Syslog Server

    3.4.1 Forward Log

    Forward a command or event to the syslogs.

    Method

    URI

    POST

    /forward_log

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X POST --header "Content-Type: application/json" –d -d '{"loggingType":"COMMAND",

       "level":"ERROR",

        "host":"TestHost",

        "appName":"TestApp",  

        "message":"TestMessage-forwardLogTest",

        "parametersList":{

           "Test":"TestValue"

       }

    }' https://10.93.66.121:8090/forward_log

    Normal response codes: 200

    3.4.1.1 Request

    URI parameters:

    Parameter Name

    Type

    Is Mandatory

    Description

    loggingType

    enum

    Mandatory

    An enum with following possible values {EVENT, COMMAND}

    level

    enum

    Mandatory

    The level to record the event in the syslog, values: {FATAL, ERROR, WARN, INFO}.

    host

    String

    Mandatory

    The host name

    appName

    String

    Mandatory

    The name of the application which generated the event

    message

    String

    Mandatory

    The message to write to the syslog

    parametersList

    List<String, String>

    Optional

    The parameters list of the event/command

    3.4.1.2 Response

    Example 2: Forward Log: JSON response

    {

    "description":"Success",

    "status":"Success"

    }

    Parameter Name

    Type

    Description

    description

    String

    Result description.

    status

    String

    Result code.

    Success - Success

    SyslogNotAvailable - when the provisioner doesn’t have a working syslog configuration.

    3.4.2 Get Syslogs

    Get the provisioner syslogs.

    Method

    URI

    GET

    /syslogs

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/syslogs

    Normal response codes: 200

    3.4.2.1 Request

    No URI parameters.

    3.4.2.2 Response

    Example 2: Get Syslogs: JSON response

    [

         {

             "id":3889,

             "name":"TestSyslog",

             "url":"tcp://172.28.10.1:6514",

             "state":true,

             "useTls":true,

             "certFileName":"syslog_cert.crt"

         }

    ]

    Parameter Name

    Type

    Description

    syslogs

    List

    The syslog parameters returned:

    id - The syslog entity ID.

    name - The syslog server name.

    url - The syslog server URL.

    state -  The syslog connection state.

    useTls - If true - use TLS for the communicating with the syslog server. certFileName - The filename of the file containing the syslog certificate in KS(Which was uploaded using Certificate Upload API)


    3.5 License Management

    3.5.1 Set License

    Set the License.

    The <license string> should be replaced with the license contents received from KIOXIA. It is advised to run this command via KumoScale Provisioner CLI.

    Method

    URI

    POST

    /license

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X POST --header "Content-Type: application/json" –d '{"license":"<license string>"}' https://10.93.66.121:8090/license

    Normal response codes: 200

    3.5.1.1 Request

    Parameter Name

    Type

    Is Mandatory

    Description

    license

    String

    Mandatory

    The license key

    3.5.1.2 Response

    Example 2: Set License: JSON response

    {

         "description":"Success",

           "status":"Success"

    }

    Parameter Name

    Type

    Description

    description

    String

    Result description.

    status

    String

    Result code.

    Success - Success

    LicenseError – Not enough backends succeeded to set the license.

    InvalidLicense – The license could not be decrypted.

    KS Set License API result codes. 


    3.5.2 Get License

    Get the License.

    Method

    URI

    GET

    /license

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/license

    Normal response codes: 200

    3.5.2.1 Request

    No URI parameters.

    3.5.2.2 Response

    Example 2: Get License: JSON response

    {

         "type":"POC",

           "expirationDate": "2020-02-26T00:00:00.350+0000",

           "maxBackends":4

    }

    Parameter Name

    Type

    Description

    type

    enum

    {POC, PRODUCTION}

    expirationDate

    Date

    The expiration date (or null - no expiration date)

    maxBackends

    int

    The number backends the license permits or null if unlimited

     

    3.6 Inventory Management

    3.6.1 Reset Inventory

    Reset the inventory.

    Method

    URI

    DELETE

    /reset_inventory

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X DELETE --header "Content-Type: application/json" https://10.93.66.121:8090/reset_inventory

    Normal response codes: 200

    3.6.1.1 Request

    No request data

    3.6.1.2 Response

    Example 2: Reset Inventory: JSON response

    {

         "description":"Success",

         "status":"Success"

    }

    Parameter Name

    Type

    Description

    description

    String

    Result description.

    status

    String

    Result code.

    Success - Success

    CommunicationError –KumoScale could not be reached.

    KS Reset Inventory API result codes

    3.6.2 Get Inventory

    Get the inventory.

    Method

    URI

    GET

    /inventory

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/inventory

    Normal response codes: 200

    3.6.2.1 Request

    No URI parameters.

    3.6.2.2 Response

    Example 2: Get Inventory: JSON response

    {

       "inventorySamples":[

         {

             "timestamp":1576066112110,

             "backends":[

               {

                   "hardwareId":"00:0c:29:b9:6b:1d",

                   "version":"3.7",

                   "state":"AVAILABLE",

                   "numSSDs":2

               },

                {

                   "hardwareId":"0c:c4:7a:88:09:ee",

                   "version":"3.7",

                   "state":"AVAILABLE",

                   "numSSDs":7

               }

             ]

         },

         {

             "timestamp":1576066112110,

             "backends":[

               {

                   "hardwareId":"00:0c:29:b9:6b:1d",

                   "version":"3.7",

                   "state":"AVAILABLE",

                   "numSSDs":2

               },

               {

                   "hardwareId":"0c:c4:7a:88:09:ee",

                   "version":"3.7",

                   "state":"AVAILABLE",

                   "numSSDs":7

               }

             ]

         }

       ]

    }

    Parameter Name

    Type

    Description

    inventoryRecords

    List

    A list of inventory records.

    timestamp

    long

    The timestamp when the inventory snapshot was taken.

    inventorySamples

    List

    A list of inventory sample records.

    backends

    List

    A list of the backends.

    hardwareId

    String

    The backend persistence ID

    version

    String

    The backend KumoScale software version

    state

    Enum

    The backend state (Available, Unavailable)

    numSSDs

    Int

    The number of SSDs in the backend

    3.7 Host Management

    3.7.1 List Hosts

    Lists all the application hosts configured in the Provisioner and their details.

    Method

    URI

    GET

    /hosts

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/hosts

    Example with the use of limit and offset parameters

    curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/hosts?limit=5&offset=0

    Example with the use of limit and marker parameters

    curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/hosts?limit=5&marker= 5836c3cc-1c7e-4f2e-9698-e39175a41bd7&hostName=”myHost”

    Normal response codes: 200

    3.7.1.1 Request

    URI parameters:

    Parameter Name

    Type

    Is Mandatory

    Description

    limit

    int

    optional

    Requests a page size of items. Returns a number of items up to a limit value.

    offset

     

    int

    optional

    Used in conjunction with Limit to return a selection of items. Offset determines the starting point of the list. The Provisioner will retrieve Hosts starting from the offset.

    marker

    String

    optional

    The Provisioner will select Hosts starting from this ID and greater than this value.

    hostName

    String

    optional

    The host name.

    3.7.1.2 Response

    Example 114: List Hosts: JSON response 

    [

       {

         "uuid":"a262a4e9-00a4-4c1a-8857-b4f68518cb1e",

         "name":"testHostName1",

         "nqn":"testNqn1",

         "clientType":"Agent",

         "state":"Available",

         "version":"1.3",

         "lastProbTime":1579181067908,

         "duration":180

       }

    ]

    Parameter Name

    Type

    Description

    nqn

    String

    The host NQN

    uuid

    String

    The host UUID

    clientType

    Enum

    {Kubernetes, Agent}

    version

    String

    SW version

    state

    Enum

    The host state {available, unavailable}

    lastProbTime

    Timestamp

    The last time the host was available (for an unavailable host)

    duration

    Int

    Probe duration length (seconds)

    name

    String

    The host name

    3.7.2 Host Probe

    A Host makes this call to notify the Provisioner about itself and update its properties.

    Method

    URI

    POST

    /host_probe

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X POST -H 'Content-Type: application/json' -d '{"hostId":"6d4a8383-c09f-4f91-836d-5ed192ca6f64",

      "hostNqn":"nqn.2014-08.org.nvmexpress:NVMf:uuid:73e93bce-0318-4927-8491-a824d04e8e7e",

        "name":"testhostname",

        "clientType":"Agent",

        "version":"1.3",

       "duration":30}' https://10.93.66.121:8090/host_probe

    Normal response codes: 200

    3.7.2.1 Request

    Example 1: Host Probe: JSON request

    {

       "hostId":"6d4a8383-c09f-4f91-836d-5ed192ca6f64",

       "hostNqn":"nqn.2014-08.org.nvmexpress:NVMf:uuid:73e93bce-0318-4927-8491-a824d04e8e7e",

       "name":"testhostname",

       "clientType":"Agent",

       "version":"1.3",

       "duration":30

    }

    Parameter Name

    Type

    Is Mandatory

    Description

    hostNqn

    String

    Mandatory

    The host NQN

    hostId

    String

    Mandatory

    The host UUID

    clientType

    Enum

    Mandatory

    {Kubernetes, Agent}

    name

    String

    Mandatory

    The host name

    duration

    int

    Mandatory

    Probe duration in seconds

    version

    String

    Mandatory

    SW version

    3.7.2.2 Response

    Example 2: Host Probe: JSON response

    {

         "description":"Success",

           "status":"Success"

    }

    Parameter Name

    Type

    Description

    description

    String

    Result description.

    status

    String

    Result code.

    Success - Success

    3.7.3 Delete Host

    Delete a host from the pool.

    Method

    URI

    DELETE

    /hosts/{uuid}

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X DELETE --header "Content-Type: application/json" https://10.93.66.121:8090/hosts/9491a177-2c02-46f2-a60f-fee19ed7aae3

    Normal response codes: 200

    3.7.3.1 Request

    URI parameters:

    Parameter Name

    Type

    Is Mandatory

    Description

    UUID

    String

    Mandatory

    The host UUID

    3.7.3.2 Response

    Example 2: Delete Host: JSON response

    {

    "description":"Success",

    "status":"Success"

    }

    Parameter Name

    Type

    Description

    description

    String

    Result description.

    status

    String

    Result code.

    Success - Success

    NotExists - A Host with the required uuid does not exist.

    3.8 Connectivity

    3.8.1 Get Targets

    Lists all of the targets configured in the Provisioner and their details, according to the connected host ID or a volume ID that was added to it as a namespace (only one of the parameters should be provided).

    Method

    URI

    GET

    /targets

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/targets?hostId= abb6673a-086d-402c-b3d4-fc04c4114a14

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/targets?volId=16815ca6-8c0a-421a-902b-cfc145ba2b68

    Normal response codes: 200

    3.8.1.1 Request

    Example 1: Get Targets: JSON request

    URI parameters:

    Parameter Name

    Type

    Is Mandatory

    Description

    hostId

    String

    optional

    The host UUID connected to the target.

    volId

    String

    optional

    The volume UUID of a volume which was added to the target as a namespace.

    • Only one of the input parameters may be provided.

    3.8.1.2 Response

    Example 2: Get Targets: JSON response

    [

    {"targetName":"nqn.2019-10.com.kioxia:testhostname-000c29b96b1d","backend":{ "persistentID":"0c:c4:7a:88:09:ee"}},

    {"targetName":"nqn.2019-10.com.kioxia:testhostname-000c29e18bfb"," backend ":{ "persistentID":"0c:c4:6a:11:56:ee"}}

    ]

    Parameter Name

    Type

    Description

    targetName

    String

    The target name

    backend

    String

    persistentID – the backend ID

    3.8.2 Publish

    Publish a volume to a specific host.

    Method

    URI

    POST

    /{tenantId}/publish

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X POST --header "Content-Type: application/json" -d '{"hostId":"6150e5cd-c88b-464e-924c-6099ea2d9a96","volId":"91ef6e29-d662-49bf-bc7e-ffd81a3e85ce"}' https://10.93.66.121:8090/{tenantId}/publish

    Normal response codes: 200

    3.8.2.1 Request

    Example 1: Publish: JSON request

    {

         "hostId":"6150e5cd-c88b-464e-924c-6099ea2d9a96",

         "volId":"91ef6e29-d662-49bf-bc7e-ffd81a3e85ce"

    }

    URI parameters:

    Parameter Name

    Type

    Is Mandatory

    Description

    hostId

    String

    Mandatory

    The host UUID

    volId

    String

    Mandatory

    The volume UUID

    tenantId

    String

    Optional

    The Tenant ID which the volume belongs to.

    3.8.2.2 Response

    Example 2: Publish: JSON response

    {

    "description":"Success",

    "status":"Success"

    }

    Parameter Name

    Type

    Description

    description

    String

    Result description.

    status

    String

    Result code.

    Success - Success

    HostNotFoundThe host does not exist.

    VolumeNotFoundThe volume does not exist.

    PublishFailed – The operation failed.

    AlreadyPublished – All replicas already published to the host.

    TenantNotFound - The Tenant ID does not exist.

    KS Create Target API, Create Namespace API, Connect Host API result codes.

    3.8.3 Unpublish

    Unpublish a volume from a specific host and stop migration tasks for this volume.

    Method

    URI

    POST

    /{tenantId}/unpublish

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X POST --header "Content-Type: application/json" -d '{"hostId":"6150e5cd-c88b-464e-924c-6099ea2d9a96","volId":"91ef6e29-d662-49bf-bc7e-ffd81a3e85ce"}' https://10.93.66.121:8090/{tenantId}/unpublish

    Normal response codes: 200

    3.8.3.1 Request

    Example 1: Unpublish: JSON request

    {

         "hostId":"6150e5cd-c88b-464e-924c-6099ea2d9a96",

         "volId":"91ef6e29-d662-49bf-bc7e-ffd81a3e85ce"

    }

    URI parameters:

    Parameter Name

    Type

    Is Mandatory

    Description

    hostId

    String

    Mandatory

    The host UUID

    volId

    String

    Mandatory

    The volume UUID

    tenantId

    String

    Optional

    The Tenant ID which the volume belongs to.

    3.8.3.2 Response

    Example 2: Unpublish: JSON response

    {

    "description":"Success",

    "status":"Success"

    }

    Parameter Name

    Type

    Description

    description

    String

    Result description.

    status

    String

    Result code.

    Success - Success

    HostNotFoundThe host does not exist.

    VolumeNotFoundThe volume does not exist.

    UnpublishFailed – The operation failed.

    NotAvailable – Unpublishing a target which is not found in KS

    TenantNotFound - The Tenant ID does not exist.

    KS Remove Target API, Remove Namespace API, Disconnect Host API result codes.

    3.9 Task Management

    3.9.1 Get Tasks

    Lists all of the tasks in the Provisioner and their details, according to the task ID or host ID it relates to, or all the tasks. Only one of the parameters may be provided.

    Note: Parameters that are null are not retuned in the JSON

    Method

    URI

    GET

    /tasks

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/tasks?taskId=11115ca6-5c7a-421a-303b-cfc145ba2b68

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/tasks?hostId=16815ca6-8c0a-421a-902b-cfc145ba2b68

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem https://10.93.66.121:8090/tasks

    Normal response codes: 200

    3.9.1.1 Request

    Example 1: Get Tasks: JSON request

    URI parameters:

    Parameter Name

    Type

    Is Mandatory

    Description

    taskId

    String

    optional

    The task ID.

    hostId

    String

    optional

    The host UUID.

    • Only one of the input parameters may be provided.

    3.9.1.2 Response

    Example 2: Get Tasks: JSON response

    [

       {

         "state":"FINISHED",

         "startDate":"2020-02-19T09:48:01.037",

         "endDate":"2020-02-19T09:49:05.011",

         "progress":100,

         "type":"RemoteMigration",

         "statusDescription":"Success",

         "stoppable":false,

         "taskId":"0fb7e7c1-9405-42dc-b288-2b138ba617d0",

         "taskConfiguration":[

             {

               "name":"volId",

               "value":"a9d5de10-54a8-41e0-ada0-4eaa22211e91"

             }

         ],

         "hostId":"a8d5de10-84a8-41e0-ada0-4eaa56206e96",

         "taskStatus":"Success"

       }

    ]

    Parameter Name

    Type

    Description

    taskId

    String

    The task ID.

    state

    Enum

    {IDLE,RUNNING,FINISHED,FAILED,ABORTED}.

    taskConfiguration

    tags

    List of <Tag> the task was configured with.

    type

    Enum

    {Remote Migration, Install License, Update Inventory, Fetch Inventory, Reset Inventory}.

    hostId

    String

    The host UUID of the host related to the task.

    progress

    number

    Progress in percentage.

    taskStatus

    String

    The error code string.

    statusDescription

    String

    The error code description.

    startDate

    Date

    The task starting time in yyyy-MM-dd'T'HH:mm:ss.SSS format.

    endDate

    Date

    The task end time in yyyy-MM-dd'T'HH:mm:ss.SSS format.

    stoppable

    boolean

    Is the task stoppable.

    3.9.2 Update Task

    Update properties of a task according to its task ID or its host ID.

    Method

    URI

    PUT

    /tasks

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X PUT -H 'Content-Type: application/json' -d ' {

        "state":"FINISHED",

        "progress":100,

        "statusDescription":"Success",

        "taskId":"b803fdba-eac9-4340-ae99-4febe131e92b",

        "hostId":"d74d186c-27c8-4932-93cc-61817b86fdf9",

        "taskStatus":"Success",

    }' https://10.93.66.121:8090/tasks

    Normal response codes: 200

    3.9.2.1 Request

    No URI parameters

    Example 1: Update Task: JSON request

    {

       "state":"FINISHED",

       "progress":100,

       "statusDescription":"Success",

       "taskId":"b803fdba-eac9-4340-ae99-4febe131e92b",

       "hostId":"d74d186c-27c8-4932-93cc-61817b86fdf9",

       "taskStatus":"Success",

    }

    Parameter Name

    Type

    Is Mandatory

    Description

    taskId

    String

    Mandatory

    The task ID.

    state

    String

    Optional

    The task state.

    progress

    Number

    Optional

    The progress in percentage.

    taskStatus

    String

    Optional

    The error code string.

    statusDescription

    String

    Optional

    The error code description.

    type

    Enum

    Optional

    The task type.

    taskConfiguration

    List<Tag>

    Optional

    The task configuration.

    hostId

    String

    Mandatory

    The host UUID.

    3.9.2.2 Response

    Example 2: Update Task: JSON response

    {

    "description":"Success",

    "status":"Success"

    }

    Parameter Name

    Type

    Description

    description

    String

    Result description.

    status

    String

    Result code.

    Success - Success

    TaskNotFound –The task was not found

    UpdateTaskFailed – Failed to update the task

    TaskEndedThe task already ended

    3.9.3 Remove Task

    Remove a task in the pool by task id and host id if given.

    Method

    URI

    DELETE

    /tasks

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X DELETE -H 'Content-Type: application/json'https://10.93.66.121:8090/tasks?taskId=11115ca6-5c7a-421a-303b-cfc145ba2b68

    Linux Curl Command Example

    curl -k --cert ./ssdtoolbox.pem -i -X DELETE -H 'Content-Type: application/json' https://10.93.66.121:8090/tasks? taskId=11115ca6-5c7a-421a-303b-cfc145ba2b68&hostId=16815ca6-8c0a-421a-902b-cfc145ba2b68

    Normal response codes: 200

    3.9.3.1 Request

    • URI parameters:

    Parameter Name

    Type

    Is Mandatory

    Description

    taskId

    String

    Mandatory

    Task ID

    hostId

    String

    optional

    The host UUID.

    3.9.3.2 Response

    Example 2: Remove Task: JSON response

    {

    "description":"Success",

    "status":"Success"

    }

    Parameter Name

    Type

    Description

    description

    String

    Result description.

    status

    String

    Result code.

    Success - Success

    NoTask – Task with task ID does not exist

    OngoingTask – Cannot remove ongoing tasks

    TaskBelongsToOtherHost – The task belongs to another host