KumoScale Provisioner REST API Command Reference

The KumoScale™ Provisioner REST API is the primary public interface to KumoScale software. It allows users to manage the pool of KumoScale storage nodes, and to allocate, connect, monitor, and manage storage volumes.

Inventory Management

The inventory management APIs provide the means for maintaining the pool of KumoScale storage nodes (also known as backends), available for volume allocation.

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

Creating and modifying the pool is done via operators.

Add Backend

Add a KumoScale storage node (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": [ "###.##.###.###" ], "rack": "Rack2", "region": "Region2", "zone": "Zone2", "hostId":"#######-########-#######-########", " mgmtPort ": 443}' https://##.##.###.###:8090/backends

Normal response codes: 200

Request

No URI parameters.

Example: Add Backend: JSON resquest

{

"mgmtIPs": [ "###.##.###.###" ],

"rack": "Dev",

"region": "ISR",

"zone": "Lab",

"hostId": "#######-########-#######-########",
"mgmtPort": 443,


}

Parameter Name

Type

Is Mandatory

Description

mgmtIPs

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)

hostId

String

Optional

If backend (storage node) is running within a host (initiator), the hostId, otherwise should not be given

mgmtPort

Int

optional

The backend (storage node) port which will be used to access the backend. Default: 443.

Response

Example: 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
  • BackendWithHostIdAlreadyExists – This host id is used by another backend.
  • KS Set Provisioner API result codes

Update Backend

Update properties of an existing KumoScale storage node (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", "hostId":"#######-#######-######-#####"," mgmtPort ": 444 }' https://##.##.###.####:8090/backends/apCMak3chDoyCPJf

Normal response codes: 200

Request

URI parameters:

Parameter Name

Type

Is Mandatory

Description

Id

String

Mandatory

KS persistent ID (~ MAC address).

Example: Update Backend: JSON request

{

"inUse": true,

"rack": "Dev",

"region": "ISR",

"zone": "Lab"

"hostId": "#######-#######-######-#####",

   " mgmtPort ": 444

}

Parameter Name

Type

Is Mandatory

Description

rack

String

Optional

KS location Rack ID , default is null

Zone

String

Optional

Accessible Zone ID (e.g., shared switch) , default is null

region

String

Optional

Accessible Group ID (e.g., shared cage) , default is null

inUse

Boolean

Optional

Is it used for volume management

hostId

String

Optional

If backen, the hostId, otherwise should not be given

mgmtPort

Int

optional

The storage node port which will be used to access the storage node.

Response

Example: Update Backend: JSON response

{

"description":"Success",

"status":"Success"

}

Parameter Name

Type

Description

description

String

Result description

Status

String

Result code.

  • Success - Success
  • NotExists – A storage node (backend) with the required id does not exist.
  • InvalidLocationValue - Rack/Zone/Region has more than 255 chars
  • BackendWithHostIdAlreadyExists – This host id is used by another storage node (backend).
  • KS Set Provisioner API result codes

Remove Backend

Remove a KumoScale storage node (backend) from the pool

Method

URI

DELETE

/backends/{id}?force=false

Linux Curl Command Example

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

Normal response codes: 200

Request

URI parameters:

Parameter Name

Type

Is Mandatory

Description

Id

String

Mandatory

KS persistent ID (~ MAC address).

force

String – Boolean true or false

Optional, default false

If true, force the deletion of the backend even if it has volumes on it and its in Unavailable state

Response

Example: Remove Backend: JSON response

{

"description":"Success",

"status":"Success"

}

Parameter Name

Type

Description

description

String

Result description

Status

String

Result code.

  • Success - Success
  • NotExists – A storage node (backend) with the required id does not exist.
  • BackendHasVolumes - There are configured volumes on the backend.
  • KS Set Provisioner API result codes

List Backends

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

Method

URI

GET

/backends

Linux Curl Command Example

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

Normal response codes: 200

Request

No URI parameters.

Response

Example 1: List Backends: JSON response

{

   "persistentID": "82:7b:62:b4:12:c4",

   "mgmtIPs": [

     "172.28.10.51",

     "fe80::c696:5290:b65:c0a5"

   ],

   "mgmtPort": 443,

   "rack": "Dev1",

   "zone": "Israel",

   "region": "Dev1",

   "inUse": true,

   "state": "Available",

   "totalCapacity": 1099511627776,

   "availableCapacity": 0,

   "numVolumes": 0,

   "lastProbTime": 1633005301913,

   "probeInterval": 60,

   "totalBW": 4525654016,

   "availableBW": 4525654016,

   "totalIOPS": 348600,

   "availableIOPS": 348600,

   "version": "3.20.1b-14705",

   "numberOfSSDs": 2,

   "certified": true,

   "portals": [

     {

       "ip": "172.28.10.51",

       "port": 4420,

       "transport": "TCP_IP"

     }

   ],

   "name": "KS1",

   "authenticationMode": "OPEN_IDC"

}

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. (not reported in case not configured)

zone

String

Accessible Zone ID (e.g., shared switch). (not reported in case not configured)

region

String

Accessible Group ID (e.g., shared cage). (not reported in case not configured)

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. (not reported in case probe was not received yet for this node)

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.

hostId

String

The host id. (not reported in case no csi driver exist on the storagenode)

mgmtPort

int

The backend port which will be used to access the backend.

targetDriverVersion

String

The version of the target driver at this backend

numVolumes

Int

Total number of volumes.

certified

boolean

true if the backend is certified. The backend is considered certified if all its SSDs are certified.

version

String

The backend’s version.

numberOfSSDs

int

Number of ssds.

name

string

The backend’s name

authenticationMode

Enum

Current backend configured authentication mode (LOCAL , LDAP, OpenIDC)

Get Backend by ID

Retrieve a KumoScale storage node (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://##.##.##.###:8090/backends/0c:c4:7a:66:96:83

Normal response codes: 200

Request

URI parameters:

Parameter Name

Type

Is Mandatory

Description

id

String

Mandatory

The persistent ID of the backend.

Response

Example 2: Get Backend by Id: JSON response

{

   "persistentID": "82:7b:62:b4:12:c4",

   "mgmtIPs": [

     "###.##.##.#",

     "fe80::c696:5290:b65:c0a5"

   ],

   "mgmtPort": 443,

   "rack": "Dev1",

   "zone": "Israel",

   "region": "Dev1",

   "inUse": true,

   "state": "Available",

   "totalCapacity": 1099511627776,

   "availableCapacity": 0,

   "numVolumes": 0,

   "lastProbTime": 1633005781901,

   "probeInterval": 60,

   "totalBW": 4525654016,

   "availableBW": 4525654016,

   "totalIOPS": 348600,

   "availableIOPS": 348600,

   "version": "3.20.1b-14705",

   "numberOfSSDs": 2,

   "certified": true,

   "portals": [

     {

       "ip": "192.20.10.1",

       "port": 4420,

       "transport": "TCP_IP"

     }

   ],

   "name": "KS1"

}

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. (not reported in case not configured)

zone

String

Accessible Zone ID (e.g., shared switch). (not reported in case not configured)

region

String

Accessible Group ID (e.g., shared cage). (not reported in case not configured)

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. (not reported in case probe was not received yet for this node)

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

hostId

String

The host id. (not reported in case no csi driver exist on the storagenode)

mgmtPort

int

The backend port which will be used to access the backend.

numVolumes

Int

Total number of volumes.

certified

boolean

true if the backend is certified. The backend is considered certified if all its SSDs are certified.

version

String

The backend’s version.

numberOfSSDs

int

Number of ssds.

name

string

The backend’s name

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://##.##.##.###:8090/info

Normal response codes: 200

Request

No URI parameters.

Response

Example 3: Get Info: JSON response

{

"totalFreeSpace": 1920315949046,

"version": "1.1",

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

"authenticationMode": "OPEN_IDC"

}

Parameter Name

Type

Description

totalFreeSpace

long

The total free space in bytes (on all KumoScale storage nodes).

version

String

Provisioner software version.

syslogsBackend

String

The persistentID of the backend the syslog config was based on.

authenticationMode

Enum

Current Provisioner configured authentication mode (JWT/OpenIDC)

Probe

KumoScale makes this call to notify the Provisioner that it is up and running and to update it with its properties.

Method

URI

POST

/probe

Linux Curl Command Example

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

"usedBW": 1034998978304,

" totalBW ": 1920315949046,

"usedIOPS": 120903849098,

" totalIOPS ": 1920315949046,

  "mgmtIPs": [ "172.28.10.13" ],

  "provisioner": {

    "inUse": true,

    "pushInterval": 60,       “url”: <protocol>://<ip/host>:<port>.

       "tags": [ { "name": "rack",   "value": "Dev"   } ],

"authorizationServerPublicKey":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkSX9EtwPkUaF1TdOGpMGA5IjhX+Y4Pm0wpzQZjtEbVl6OX3Zuz7kaj30NJCy9/YhPFMJuRPj/7POjpQ31Wk+Z9wip+wk088dl8lO8PjxwD7P5+E5jQQYKpWDoxLrohyJToPK8Emtb65TU+C33gaE8VhEAs/lVF1wQ2NQYO1dkFZW3gP8vKF9ojN0KjdrHvK7HCd0l1alYyPTNo2vfNM33j4yKftvp6P1N6G3XoiverMBTvDUXRNmDS496QVujwtmaB/oK1lmSJdRtakjl7oy22nidrKETSTT6gH8Nre33Ju3q2Umg+FH8WJhpiWFM/VuRKpFgmMOt5G4aVbCbxCqHwIDAQAB",

"authorizationServerTokenURL":"http://172.28.90.1:8080/auth/realms/Dev/protocol/openid-connect/token",

"backendsClientID":"liorf-backend",

"backendsResourceID":"liorf-backend",

"backendsClientSecret":"dfd6774e-fc1d-40c5-a12d-02ee4b5ed100"

  },

  " mgmtPort ": 443,

  “persistentID:” “"ce:10:66:d3:a2:dd",

  "targetDriverVersion": "3.20.1b-2188",

  "totalCapacity": 4000315949046,

"version": “3.17.13465,

"numberOfSSDs": 2,

" Certified ": true,

“changes”: 0,

  "authenticationMode": "OPEN_IDC"}' https://10.93.66.121:8090/probe

Normal response codes: 200

Request

No URI parameters.

Example 1: Probe: JSON request

{

"availableCapacity": 1920315949046,

"usedBW": 100000000000,

"totalBW": 1920315949046,

"usedIOPS": 129039487386,

"totalIOPS": 1920315949046,

"mgmtIPs": [ "172.28.10.13" ],

"provisioner": {

   "inUse": true,

   "url": "https://172.28.60.11:30100",

   "pushInterval": 60,

   "tags": [ { "name": "rack", "value": "Dev" },

                   { "name": "storageClassName", "value": "sc1" },

                   { "name": "shareSSDBetweenVolumes", "value": "true" }   ],

"authorizationServerPublicKey":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkSX9EtwPkUaF1TdOGpMGA5IjhX+Y4Pm0wpzQZjtEbVl6OX3Zuz7kaj30NJCy9/YhPFMJuRPj/7POjpQ31Wk+Z9wip+wk088dl8lO8PjxwD7P5+E5jQQYKpWDoxLrohyJToPK8Emtb65TU+C33gaE8VhEAs/lVF1wQ2NQYO1dkFZW3gP8vKF9ojN0KjdrHvK7HCd0l1alYyPTNo2vfNM33j4yKftvp6P1N6G3XoiverMBTvDUXRNmDS496QVujwtmaB/oK1lmSJdRtakjl7oy22nidrKETSTT6gH8Nre33Ju3q2Umg+FH8WJhpiWFM/VuRKpFgmMOt5G4aVbCbxCqHwIDAQAB",       "authorizationServerTokenURL":"http://172.28.90.1:8080/auth/realms/Dev/protocol/openid-connect/token",

"backendsClientID":"liorf-backend",

"backendsResourceID":"liorf-backend",

"backendsClientSecret":"dfd6774e-fc1d-40c5-a12d-02ee4b5ed100"

},

"totalCapacity": 4000315949046,
"version": “3.17.13465,

" numberOfSSDs ": 2,

" Certified ": true,

" mgmtPort ": 443,

"targetDriverVersion": "3.20.1b-2188",

“persistentID:” “"ce:10:66:d3:a2:dd",

“changes”: 0,

"authenticationMode": "OPEN_IDC"}

Parameter Name

Type

Is Mandatory

Description

availableCapacity

long

Mandatory

The sum of the available space in the appliance.

usedBW

long

Mandatory

The sum of the used bandwidth in the appliance in B/s.

totalBW

long

Mandatory

KS total bandwidth in B/s.

usedIOPS

long

Mandatory

The sum of used IOPS in the appliance.

totalIOPS

long

Mandatory

The total potential IOPS.

mgmtIPs

List<String>

Mandatory

KS Management IPs or DNS name.

totalCapacity

long

Mandatory

KS total capacity - the sum of all SSDs capacity.

persistentID

String

Mandatory

A persistent ID string of this engine.

provisioner

Provisioner

Mandatory

 

inUse (provisioner)

boolean

Mandatory

Is it used for volume management.

pushInterval (provisioner)

int

Mandatory

Interval between consequence probe calls in seconds. Range [60 - 86400].

url (provisioner)

String

Mandatory

Provisioner url in the format:     <protocol>://<ip/host>:<port>.ing

authorizationServerPublicKey (provisioner)

String

Mandatory

public key used to decrypt tokens

authorizationServerTokenURL (provisioner)

String

Mandatory

authorization server url for generating tokens

backendsResourceID (provisioner)

String

Mandatory

ID of backends resource –

the client name as defined in the authorization

server of client which reflects backends.

backendsClientID (provisioner)

String

Mandatory

ID of a backend client, which has a service account role

ADMIN at backends resource

backendsClientSecret (provisioner)

String

Mandatory

The backends client secret

tags (provisioner)

List<Tag>

Mandatory

KS location Rack, Zone and Group ID’s, Host ID, storageClassName, shareSSDBetweenVolumes.

name (tag)

String

Mandatory

 

value (tag)

String

Mandatory

 

version

String

Mandatory

 

numberOfSSDs

int

Mandatory

 

mgmtPort

int

Mandatory

The backend management port number.

Certified

Boolean

Mandatory

True if the appliance is certified. The appliance is considered certified if all its SSDs are certified and the hyper threading is disabled in it.

targetDriverVersion

String

Mandatory

The target driver version on the probing backend

changes

int

Mandatory

A bitmask, which tells provisioner if it needs to refresh more data.

Current bits:

  PORTALS_CHANGED=1

SYSLOG_CHANGED=2

authenticationMode

Enum

Mandatory

Current backend configured authentication mode (LOCAL , LDAP, OpenIDC)

Response

Example 2: Probe: JSON response

{

"description":"Success",

"status":"Success"

}

Parameter Name

Type

Description

description

String

Result description.

status

String

Result code.

Success - Success

Reset Inventory

Reset the inventory, an internal task is created to track the operation progress, it has an expiration period of halt an hour, which means when the task is finished it will be removed after the expiration period has passed.

Method

URI

DELETE

/reset_inventory

Linux Curl Command Example

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

Normal response codes: 200

Request

No request data

Response

Example 2: Reset Inventory: JSON response

{

"description":"Success.",

"status":"Success",

"id":1727

}

Parameter Name

Type

Description

description

String

Result description.

id

int

Command ID (internal usage).

status

String

Result code:

  • Success – Success.

  • CommunicationError – KumoScale could not be reached.

  • KS Reset Inventory API result codes.

Get Inventory

Get the inventory, an internal task is created to track the operation progress, has an expiration period of half an hour. This means when the task is finished it will be removed after the expiration period has passed.

Method

URI

GET

/inventory

Linux Curl Command Example

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

Normal response codes: 200

Request

No URI parameters.

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

timeStamp

Date

The inventory sampling date

changes

List<InventoryChange>

The list of changes in a specific inventory sampling date

Change (InventoryChange)

Enum

{NONE,NEW,REMOVED,MODIFIED} – The change type

Tags (InventoryChange)

List of pairs {name , value}

 

name can be alpha numeric string

value can be any string with the following supported keys:

  • id – string ,max length 256, not empty
  • version - string ,max length 256,not empty
  • state – string , max length 16,not empty
  • numSSDs – int >=0 current number of SSDs

Multi-Tenancy Management

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://##.##.##.###:8090/tenants/

Normal response codes: 200

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.

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 current input name already exists.
  • NoBackends – No backends (storage nodes) are configured.
  • KS Set Provisioner API result codes.

tenantId

String

The tenant ID

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://##.##.##.###:8090/tenants

Normal response codes: 200

Request

No URI parameters.

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.

Modify Tenant

Updates 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://##.##.##.###: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.

Delete Tenant

Deletes 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://##.##.##.###: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.

Volume Management

Allocates volumes for the user.

Create Volume

Creates 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",

"protocol": "NVMeoF",

"reservedSpacePercentage": 10,

"storageClass": {

    "sameRackAllowed": true,

    "numReplicas": 1,

    "racks": [ "Dev" ],

    "regions": [ "ISR" ],

    "zones": [ "Lab" ] ,

    "maxIOPSPerGB": 1,

    "desiredIOPSPerGB": 1,

    "maxBWPerGB": 1,

    "desiredBWPerGB": 1,

    "blockSize": 1,

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

   "allowSpan": true

    "name": "sc1",

    "shareSSDBetweenVolumes": true

},

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

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

Normal response codes: 200

Request

No URI parameters.

Example 1: Create Volume: JSON request

{

"capacity": 20,

   “provisioningType”: “THIN”,

      "protocol": "NVMeoF",

   “reservedSpacePercentage”: 10,

   "storageClass": {

     "sameRackAllowd": true,

     "numReplicas": 1,

     "racks": [ "Dev" ],

     "regions": [ "ISR" ],

     "zones": [ "Lab" ] ,

     "maxIOPSPerGB": 1,

     "desiredIOPSPerGB": 1,

     "maxBWPerGB": 1,

     "desiredBWPerGB": 1,

     "blockSize": 512,

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

     "allowSpan": true,

     "name": "sc1",

     "shareSSDBetweenVolumes": true

   },

   "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.

Protocol

Enum

Optional

{NVMeoF,Local} default is NVMeoF

storageClass

StorageClass

Optional

Description from Storage Class CR.

sameRackAllowed (storageClass)

boolean

Optional

For replicated volumes:

Whether or not more than one replica can 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

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

regions (storageClass)

List<String>

Optional

A list 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).

name

(storageClass)

String

Optional

The name of the storage class.

Mandatory if shareSSDBetweenVolumes is false.

shareSSDBetweenVolumes

(storageClass)

boolean

Optional

Whether or not the volume is allowed to be placed on an SSD that already has a volume with the same storageClassName.

hostId

(storageClass)

String

Optional

The host id.

allowSpan

(storageClass)

Boolean

Optional

Allow span.

tenantId

String

Optional

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

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 at least one of the replicas on.

  • NotEnoughMatchingBackends - Could not create all replicas.

  • NoBackendWithHostIdExists – No backend with the requested host Id exists.

  • TenantNotFound – The Tenant ID does not exist.

  • TenantCapacityExceeded – The tenant has reached its capacity budget.

  • KS Create Volume API result codes.

Delete Volume

Delete a volume from the KumoScale implementation.

Method

URI

DELETE

/{tenantId}/volumes/{id}

Linux Curl Command Example

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

Normal response codes: 200

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.

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 doesn’t exist.
  • VolumeIsInUse - Volume is in use by a snapshot.
  • KS Delete Volume API result codes.

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://##.##.##.###:8090/volumes

Example with the use of limit and offset parameters

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

Example with the use of limit and marker parameters

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

Example with the use of hostID parameter

curl -k --cert ./ssdtoolbox.pem https://##.##.##.###:8090/{tenantId}/volumes?hostID= 408e3ab3-2894-4240-ac2b-c5b7912bc014

Normal response codes: 200

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 volume tenantId

backendId

String

Optional

If given, the API will return only volumes which has at least one replica on this backend.

hostID

String

Optional

If given, the API will return only volumes which are connected to the host with this hostID.

Response

Example 4: Get Volumes: JSON response

[ 

{

   "alias": "sanity-node-get-volume-stats-4EC0D022-CB5B17BB",

   "uuid": "e2b69cf4-e49c-485e-ac0e-d5b07bf61d53",

   "capacity": 10737418240,

   "provisioningType": "THICK",

   "numReplicas": 2,

   "maxIOPS": 0,

   "desiredIOPS": 0,

   "maxBW": 0,

   "desiredBW": 0,

   "blockSize": "4KB",

   "maxReplicaDownTime": 0,

   "location": [

     {

       "uuid": "cb9958c2-8aec-40ce-b906-f646010d6add",

       "backend": {

         "persistentID": "00:0c:29:8c:71:5f"

       },

       "replicaState": "Unknown",

       "currentStateTime": 0,

       "inUse": true

     },

     {

       "uuid": "ca576348-4f2c-4c92-a4a9-3bd1d513ec93",

       "backend": {

         "persistentID": "00:0c:29:bf:e1:a3"

       },

       "replicaState": "Unknown",

       "currentStateTime": 0,

       "inUse": false

     }

   ],

   "tenantId": "0",

   "protocol": "NVMeoF",

   "allowSpan": false,

   "storageClassName": "default",

   "shareSSDBetweenVolumes": true,

   "inUse": false

},

{

   "alias": "pvc-7a2a9dd4-4f32-4dd2-bd66-eb82cc3c4db1",

   "uuid": "f9fda535-39d9-4bfd-b7d8-09fb1f6de46d",

   "capacity": 42949672960,

   "provisioningType": "THIN",

   "numReplicas": 1,

   "maxIOPS": 0,

   "desiredIOPS": 0,

   "maxBW": 0,

   "desiredBW": 0,

   "blockSize": "4KB",

   "maxReplicaDownTime": 0,

   "location": [

     {

       "uuid": "f9fda535-39d9-4bfd-b7d8-09fb1f6de46d",

       "backend": {

         "persistentID": "00:0c:29:bf:e1:a3"

       },

       "replicaState": "Unknown",

       "currentStateTime": 0,

       "inUse": false

     }

   ],

   "tenantId": "0",

   "protocol": "Local",

   "allowSpan": true,

   "storageClassName": "default",

   "shareSSDBetweenVolumes": true,

   "inUse": false,

   "reservedSpace": 21474836480

}

]

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

inUse

Boolean

Specifies if the volume is in use

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 – Unknown, Available, Terminating, Missing, or Synchronizing.

currentStateTime (location)

long

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

inUse(location)

Boolean

Specifies if the location(replica) is in use

tenantId

String

The Tenant ID which the volume belongs to.

protocol

Enum

The volume’s protocol: {NVMeoF,Local}.

allowSpan

boolean

Whether or not span allowed.

storageClassName

String

The name of the storage class. (not reported in case not configured)

shareSSDBetweenVolumes

boolean

Whether or not the volume can be placed on an SSD that already has a volume with the same storageClassName.

Get Volume by Alias

Retrieves 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://##.##.##.###:8090/{tenantId}/volumes_by_alias/vol1

Normal response codes: 200

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.

Response

See Get Volumes.

Get Volume Extended

Retrieves extended volume information on a specific volume.

Method

URI

GET

/{tenantId}/volume_extended/{uuid}

Linux Curl Command Example

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

Normal response codes: 200

Request

URI parameters:

Parameter Name

Type

Is Mandatory

Description

uuid

String

Mandatory

Volume uuid.

tenantId

String

Optional

The volume tenantId

Response

Example: Get Volumes Extended: JSON response 

[

   {

     "alias":"TestVol1",

     "uuid":"7d10d980-1d28-4fc3-9110-e79b9b87ac02",

     "capacity":10737418240,

     "provisioningType":"THICK",

     "numReplicas":1,

     "maxIOPS":0,

     "desiredIOPS":0,

     "maxBW":0,

     "desiredBW":0,

     "blockSize":"4KB",

     "maxReplicaDownTime":0,

     "location":[

         {

           "uuid":"7d10d980-1d28-4fc3-9110-e79b9b87ac02",

           "backend":{

               "persistentID":"00:0c:29:79:04:8c"

           },

           "replicaState":"Unknown",

           "currentStateTime":0,

           "subVolumes":[

               {

                 "capacity":10737418240,

                 "ssdID":"VMWare NVME-0000",

                 "ssdName":SSD1

               }

           ],

           "sessions":[

               {

                 "hostID":"7b52b22e-d054-4635-baf3-9666ffe85264"

               }

           ]

         }

     ],

     "tenantId":"0",

     "protocol":"NVMeoF",

     "allowSpan":true,

     "shareSSDBetweenVolumes":true

   }

]

All parameters from 2.2.3 section (Get volumes) and additionally, for each replica:

Parameter Name

Type

Description

Sub-Volumes

List

List of sub-volume, each part includes: capacity, ssdId and name.

Capacity

Int

The capacity of the sub-volume (in bytes)

ssdID

String

Persistent ID of the SSD

ssdName

String

Name of the SSD

Session

List

 

host ID

String

Host UUID (reported only in case there is initiator that connected to the volume)

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://##.##.##.###:8090/{tenantId}/volumes/163988d3-e871-4e0d-913d-12a7f3f0187e

Normal response codes: 200

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 to which the volume belongs.

Example 1: Create Volume: JSON request

{

"newCapacity": 20

}

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.

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://##.##.##.###:8090/{tenantId}/replica/163988d3-e871-4e0d-913d-12a7f3f0187e

Normal response codes: 200

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 replicas 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

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

regions

List<String>

Optional

A list of regions the volumes should be accessible from.

tenantId

String

Optional

The Tenant ID which the volume belongs to.


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.

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://##.##.##.###:8090/{tenantId}/replica/163988d3-e871-4e0d-913d-12a7f3f0187e/48f27797-ff72-42dc-8121-069699f97b7e

Normal response codes: 200

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.

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.

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://##.##.##.###:8090/{tenantId}/replica/163988d3-e871-4e0d-913d-12a7f3f0187e/48f27797-ff72-42dc-8121-069699f97b7e

Normal response codes: 200

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 to which the volume belongs.

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.

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://##.##.##.###:8090/{tenantId}/replica/163988d3-e871-4e0d-913d-12a7f3f0187e/48f27797-ff72-42dc-8121-069699f97b7e/Available

Normal response codes: 200

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 to which the volume belongs.

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.

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://##.##.##.###:8090/{tenantId}/snapshots

Normal response codes: 200

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 as 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 used for a 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.

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.

Delete Snapshot

Delete a snapshot from the KumoScale implementation.

Method

URI

DELETE

/{tenantId}/snapshots/{id}

Linux Curl Command Example

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

Normal response codes: 200

Request

URI parameters:

Parameter Name

Type

Is Mandatory

Description

id

String

Mandatory

Snapshot UUID.

tenantId

String

Optional

The Tenant ID to which the volume belongs.

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.
  • TenantNotFound - The Tenant ID does not exist.
  • VolumeIsInUse - Volume is in use by a snapshot
  • KS Delete Snapshot API result codes.

Get Snapshots

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

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

Method

URI

GET

/{tenantId}/snapshots/{id}

Linux Curl Command Example

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

Example with the use of limit and offset parameters

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

Example with the use of limit and marker parameters

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

Normal response codes: 200

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 to which the volume and snapshot belong.

Response

Example 5: 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 by percentage.

timestamp

long

The timestamp from when the snapshot was taken.

tenantId

String

The ID of the tenant to which the snapshot belongs.

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://##.##.##.###:8090/{tenantId}/snapshots _by_vol/41a81c17-ffa8-480c-b26c-1fb514f5dca2

Normal response codes: 200

Request

URI parameters:

Parameter Name

Type

Is Mandatory

Description

volID

String

Mandatory

The volume UUID.

tenantId

String

Optional

The Tenant ID to which the volume belongs.

Response

See Get Snapshots.


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://##.##.##.###:30100/{tenantId}/snapshots_by_alias/sns1

Normal response codes: 200

Request

URI parameters:

Parameter Name

Type

Is Mandatory

Description

alias

String

Mandatory

The snapshot alias.

tenantId

String

Optional

The Tenant ID to which the snapshot belongs.

Response

See Get Snapshots.

Create Snapshot Volume

Create a snapshot volume in the pool.

Method

URI

POST

/{tenantId}/snapshot_volume

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,

"protocol":"Local",

"allowSpan":true,

"storageClassName":"sc1"}' https://192.0.2.0:8090/{tenantId}/snapshot_volumes

Normal response codes: 200

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,

"protocol":"Local",

"allowSpan":true,

"storageClassName":"sc1"

}

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 reserved for the log.

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

Reserved Space minimal value is max (2% of volume capacity, 20GB), as in Thin Volume.

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.

maxBWPerGB

int

Optional

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

tenantId

String

Optional

The Tenant ID to which the volume belongs.

Protocol

Enum

Optional

The volume’s required protocol: {NVMeoF,Local} default is NVMeoF.

allowSpan

boolean

Optional

Allow span (Default – true).

storageClassName

String

Optional

The name of the storage class.

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.

Migrate Volume

Migrates 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://192.0.2.0:8090/{tenantId}/migrate_volume

Normal response codes: 200

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 the replica belongs to.

tenantId

String

Optional

The Tenant ID to which the volume belongs.

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 repd provided doesn’t exist.

  • VolumeNoFoundthe volume is not found.

  • TaskNotFound – the task not found.

  • NotReplicated – the volume is not replicated.

  • NotEnoughReplicas – The volumes do 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.

  • VolumePublishedToMultipleHosts – The volume is published to more than one host.

Clone Volume

Clone a Volume in the pool.

Method

URI

POST

/{tenantId}/clone_volume

Linux Curl Command Example

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

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

"alias":"cloneVolAlias",

"capacity":20,

"reservedSpacePercentage":10,

"volumeId":"778988ad-84f8-3381-771d-989790e1e355"

}' https://192.0.2.0:8090/{tenantId}/clone_volume

Normal response codes: 200

Request

No URI parameters.

Example 1: Clone Volume: JSON request

{

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

"alias":"cloneVolAlias",

"volumeId":"778988ad-84f8-3381-771d-989790e1e355",

"reservedSpacePercentage":10,

"capacity":20

}

Parameter Name

Type

Is Mandatory

Description

sourceVolumeId

String

Mandatory

The source volume UUID.

volumeId

String

Optional

The clone UUID.

alias

String

Mandatory

The clone alias.

reservedSpacePercentage

int

Optional

Percentage of the parent volume for used for log

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

Reserved Space minimal value is max(2% of volume capacity, 20GB) as in thin volume

* In any case – reserved space will not be more than volume capacity.

capacity

int

Optional

The capacity of the target volume, possible values are the source volume capacity or bigger.

* The parameter units are GB

tenantId

String

Optional

The clone volume tenantId

Response

Example 2: Clone 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 – Source volume doesn’t exists with id

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

  • TenantNotFound – The tenant doesn’t exist.

  • TenantCapacityExceeded – tenant doesn’t have enough capacity for cloned volume.

  • KS Clone Volume API result codes.

  • KS Modify Volume API result codes.

persistentId

String

The new Cloned Volume UUID.

Logging to an External Syslog Server

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://##.##.##.###:8090/forward_log

Normal response codes: 200

Request

URI parameters:

Parameter Name

Type

Is Mandatory

Description

loggingType

enum

Mandatory

An enum with the 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.

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 - The provisioner does not have a working syslog configuration.

Get Syslogs

Get the provisioner syslogs.

Method

URI

GET

/syslog

Linux Curl Command Example

curl -k --cert ./ssdtoolbox.pem https://##.##.##.###:8090/syslog

Normal response codes: 200

Request

No URI parameters.

Response

Example 2: Get Syslogs: JSON response

[

     {

         "id":3889,

         "name":"TestSyslog",

         "url":"tcp://192.0.2.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 (uploaded using Certificate Upload API)

License Management

Set License

Set the License. An internal task is created to track the operation progress. It has an expiration period of half an hour, which means when the task is finished it will be removed after the expiration period has passed.

Method

URI

POST

/LICENSE

Linux Curl Command Example

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

Normal response codes: 200

Request

Parameter Name

Type

Description

license

String

The license key

Response

Example 144: Set License: JSON response

{

"description":"Success.",

"status":"Success",

}

Parameter Name

Type

Description

description

String

Result description.

status

String

Result code:

  • Success –successful.

  • LicenseError – If not enough backends succeeded to set the license.

  • InvalidLicense – if the license could not be decrypted.

  • KS Set License API result codes.

Get License

Get the license information.

Method

URI

GET

/license

Linux Curl Command Example

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

Normal response codes: 200

Request

No URI parameters.

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 of backends the license permits or null if unlimited.

Host Management

List Hosts

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

Method

URI

GET

/hosts

Linux Curl Command Example

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

Example with the use of limit and offset parameters

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

Example with the use of limit and marker parameters

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

Normal response codes: 200

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.


Response

Example 6: List Hosts: JSON response

[

   {

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

     "name":"testHostName1",

     "nqn":"testNqn1",

     "clientType":"Agent",

     "state":"Available",

     "version":"1.4",

     "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.

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.4",

   "duration":30}' https://##.##.##.###:8090/host_probe

Normal response codes: 200

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.4",

   "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.


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.

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://##.##.##.###:8090/hosts/9491a177-2c02-46f2-a60f-fee19ed7aae3

Normal response codes: 200

Request

URI parameters:

Parameter Name

Type

Is Mandatory

Description

UUID

String

Mandatory

The host UUID.

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.
  • HostAvailable The host is available and cannot be deleted.

Connectivity

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://##.##.##.###:8090/targets?hostId= abb6673a-086d-402c-b3d4-fc04c4114a14

Linux Curl Command Example

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

Normal response codes: 200

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.

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.

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://##.##.##.###:8090/{tenantId}/publish

Normal response codes: 200

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 to which the volume belongs.

Response

Example 2: Publish: JSON response

{

"description":"Success",

"status":"Success"

}

Parameter Name

Type

Description

description

String

Result description.

status

String

Result code.

  • Success – Success.
  • HostNotFound – The host does not exist.
  • VolumeNotFound – The volume does not exist.
  • PublishFailed – The operation failed.
  • AlreadyPublished – All replicas already published to the host.
  • TenantNotFound - The Tenant ID does not exist.
  • VolumeNotInHost - The volume is not in the host.
  • KS Create Target API, Create Namespace API, Connect Host API result codes.

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://##.##.##.###:8090/{tenantId}/unpublish

Normal response codes: 200

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 to which the volume belongs.

Response

Example 2: Unpublish: JSON response

{

"description":"Success",

"status":"Success"

}

Parameter Name

Type

Description

description

String

Result description.

status

String

Result code.

  • Success – Success.
  • HostNotFound – The host does not exist.
  • VolumeNotFound – The 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.
  • VolumeNotInHost - The volume is not in the host.
  • KS Remove Target API, Remove Namespace API, Disconnect Host API result codes.

Task Management

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 tasks. Only one of the parameters may be provided.

Notes: Parameters that are null are not returned in the JSON.

Method

URI

GET

/tasks

Linux Curl Command Example

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

Linux Curl Command Example

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

Linux Curl Command Example

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

Normal response codes: 200

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.

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

A 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 by 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.

Update Task

Updates 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://##.##.##.###:8090/tasks

Normal response codes: 200

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 by 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.

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.

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://##.##.##.###: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://##.##.##.###:8090/tasks? taskId=11115ca6-5c7a-421a-303b-cfc145ba2b68&hostId=16815ca6-8c0a-421a-902b-cfc145ba2b68

Normal response codes: 200

Request

URI parameters:

Parameter Name

Type

Is Mandatory

Description

taskId

String

Mandatory

Task ID.

hostId

String

optional

The host UUID.

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.

Telemetry API’s

Get Metrics

Shows all Prometheus metrics that was collected from the provisioner.

Method

URI

GET

/metrics

Linux Curl Command Example

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

Normal response codes: 200

Request

No URI parameters.

Response

Example: Get Metrics response:

# HELP ks_node_state ks node state per Storage Node

# TYPE ks_node_state gauge

ks_node_state{node="00:0c:29:4b:b3:b7",name="ks-node7-000c294bb3b7",rack="null",zone="null",region="null",} 0.0

ks_node_state{node="00:0c:29:b8:b0:05",name="ks-node8-000c29b8b005",rack="null",zone="null",region="null",} 0.0

ks_node_state{node="00:0c:29:cd:26:f2",name="ks-node1-000c29cd26f2",rack="null",zone="null",region="null",} 0.0

ks_node_state{node="00:0c:29:08:b9:fc",name="ks-node4-000c2908b9fc",rack="null",zone="null",region="null",} 0.0

ks_node_state{node="00:0c:29:9e:2b:4d",name="ks-node2-000c299e2b4d",rack="null",zone="null",region="null",} 0.0

ks_node_state{node="00:0c:29:0f:60:62",name="ks-node6-000c290f6062",rack="null",zone="null",region="null",} 0.0

ks_node_state{node="00:0c:29:07:44:f1",name="ks-node5-000c290744f1",rack="null",zone="null",region="null",} 0.0

ks_node_state{node="00:0c:29:27:86:09",name="ks-node3-000c29278609",rack="null",zone="null",region="null",} 0.0

# HELP ks_vol_capacity_bytes ks vol capacity bytes per volume

# TYPE ks_vol_capacity_bytes gauge

ks_vol_capacity_bytes{uuid="71fd3724-431f-49fc-83b6-b625f47f5a3b",alias="pvc-7f07b3c8-be9c-4dbf-b1a6-1f2d72a9fe4b",numReplicas="1",tenantID="0",storageClassName="default",provisioningType="THIN",protocol="Local",repUUID1="",nodeID1="00:0c:29:27:86:09",nodeName1="ks-node3-000c29278609",repUUID2="",nodeID2="",nodeName2="",repUUID3="",nodeID3="",nodeName3="",} 1.073741824E11

ks_vol_capacity_bytes{uuid="a94d1640-328e-4107-be89-1e2017d79f08",alias="pvc-6304471d-5f39-4c02-a1f8-7b5cac6b7b10",numReplicas="1",tenantID="0",storageClassName="default",provisioningType="THIN",protocol="Local",repUUID1="",nodeID1="00:0c:29:9e:2b:4d",nodeName1="ks-node2-000c299e2b4d",repUUID2="",nodeID2="",nodeName2="",repUUID3="",nodeID3="",nodeName3="",} 4.294967296E10

ks_vol_capacity_bytes{uuid="e95734cd-adba-4272-81f0-e04da27692c3",alias="pvc-7562688a-fa9d-4d77-9678-d39f41203e19",numReplicas="1",tenantID="0",storageClassName="default",provisioningType="THIN",protocol="Local",repUUID1="",nodeID1="00:0c:29:cd:26:f2",nodeName1="ks-node1-000c29cd26f2",repUUID2="",nodeID2="",nodeName2="",repUUID3="",nodeID3="",nodeName3="",} 4.294967296E10

ks_vol_capacity_bytes{uuid="2fe5b895-77fb-4490-b544-76964991041f",alias="pvc-b5f77a21-604d-4380-80cf-843b761a8bc2",numReplicas="1",tenantID="0",storageClassName="default",provisioningType="THICK",protocol="Local",repUUID1="",nodeID1="00:0c:29:9e:2b:4d",nodeName1="ks-node2-000c299e2b4d",repUUID2="",nodeID2="",nodeName2="",repUUID3="",nodeID3="",nodeName3="",} 1.073741824E9

ks_vol_capacity_bytes{uuid="7fcd76bd-f6ff-461c-bf13-da963494644d",alias="pvc-09a7bbe0-dcde-413a-b048-ef8c790882a4",numReplicas="1",tenantID="0",storageClassName="default",provisioningType="THIN",protocol="Local",repUUID1="",nodeID1="00:0c:29:9e:2b:4d",nodeName1="ks-node2-000c299e2b4d",repUUID2="",nodeID2="",nodeName2="",repUUID3="",nodeID3="",nodeName3="",} 4.294967296E10

ks_vol_capacity_bytes{uuid="7dfdc865-c9a9-4594-abea-310a5e506cbb",alias="pvc-bbe1e338-20cd-4320-8a6d-6acfa4623b16",numReplicas="1",tenantID="0",storageClassName="default",provisioningType="THIN",protocol="Local",repUUID1="",nodeID1="00:0c:29:27:86:09",nodeName1="ks-node3-000c29278609",repUUID2="",nodeID2="",nodeName2="",repUUID3="",nodeID3="",nodeName3="",} 4.294967296E10

# HELP ks_node_used_capacity_bytes ks node used capacity bytes per Storage Node

# TYPE ks_node_used_capacity_bytes gauge

ks_node_used_capacity_bytes{node="00:0c:29:0f:60:62",name="ks-node6-000c290f6062",} 2.01326592E8

ks_node_used_capacity_bytes{node="00:0c:29:27:86:09",name="ks-node3-000c29278609",} 6.4726499328E10

ks_node_used_capacity_bytes{node="00:0c:29:b8:b0:05",name="ks-node8-000c29b8b005",} 1.34217728E8

ks_node_used_capacity_bytes{node="00:0c:29:08:b9:fc",name="ks-node4-000c2908b9fc",} 1.34217728E8

ks_node_used_capacity_bytes{node="00:0c:29:4b:b3:b7",name="ks-node7-000c294bb3b7",} 1.34217728E8

ks_node_used_capacity_bytes{node="00:0c:29:9e:2b:4d",name="ks-node2-000c299e2b4d",} 6.5800241152E10

ks_node_used_capacity_bytes{node="00:0c:29:cd:26:f2",name="ks-node1-000c29cd26f2",} 4.3167776768E10

ks_node_used_capacity_bytes{node="00:0c:29:07:44:f1",name="ks-node5-000c290744f1",} 2.01326592E8

# HELP ks_node_used_iops ks node used iops per Storage Node

# TYPE ks_node_used_iops gauge

ks_node_used_iops{node="00:0c:29:0f:60:62",name="ks-node6-000c290f6062",} 0.0

ks_node_used_iops{node="00:0c:29:27:86:09",name="ks-node3-000c29278609",} 13670.0

ks_node_used_iops{node="00:0c:29:b8:b0:05",name="ks-node8-000c29b8b005",} 0.0

ks_node_used_iops{node="00:0c:29:08:b9:fc",name="ks-node4-000c2908b9fc",} 0.0

ks_node_used_iops{node="00:0c:29:4b:b3:b7",name="ks-node7-000c294bb3b7",} 0.0

ks_node_used_iops{node="00:0c:29:9e:2b:4d",name="ks-node2-000c299e2b4d",} 14010.0

ks_node_used_iops{node="00:0c:29:cd:26:f2",name="ks-node1-000c29cd26f2",} 6835.0

ks_node_used_iops{node="00:0c:29:07:44:f1",name="ks-node5-000c290744f1",} 0.0

# HELP ks_node_used_bw_bytes_per_sec ks node used bw bytes per sec per Storage Node

# TYPE ks_node_used_bw_bytes_per_sec gauge

ks_node_used_bw_bytes_per_sec{node="00:0c:29:0f:60:62",name="ks-node6-000c290f6062",} 0.0

ks_node_used_bw_bytes_per_sec{node="00:0c:29:27:86:09",name="ks-node3-000c29278609",} 1.7747392E8

ks_node_used_bw_bytes_per_sec{node="00:0c:29:b8:b0:05",name="ks-node8-000c29b8b005",} 0.0

ks_node_used_bw_bytes_per_sec{node="00:0c:29:08:b9:fc",name="ks-node4-000c2908b9fc",} 0.0

ks_node_used_bw_bytes_per_sec{node="00:0c:29:4b:b3:b7",name="ks-node7-000c294bb3b7",} 0.0

ks_node_used_bw_bytes_per_sec{node="00:0c:29:9e:2b:4d",name="ks-node2-000c299e2b4d",} 1.81893504E8

ks_node_used_bw_bytes_per_sec{node="00:0c:29:cd:26:f2",name="ks-node1-000c29cd26f2",} 8.873696E7

ks_node_used_bw_bytes_per_sec{node="00:0c:29:07:44:f1",name="ks-node5-000c290744f1",} 0.0

# HELP ks_node_free_iops ks node free iops per Storage Node

# TYPE ks_node_free_iops gauge

ks_node_free_iops{node="00:0c:29:0f:60:62",name="ks-node6-000c290f6062",} 522900.0

ks_node_free_iops{node="00:0c:29:27:86:09",name="ks-node3-000c29278609",} 334930.0

ks_node_free_iops{node="00:0c:29:b8:b0:05",name="ks-node8-000c29b8b005",} 348600.0

ks_node_free_iops{node="00:0c:29:08:b9:fc",name="ks-node4-000c2908b9fc",} 348600.0

ks_node_free_iops{node="00:0c:29:4b:b3:b7",name="ks-node7-000c294bb3b7",} 348600.0

ks_node_free_iops{node="00:0c:29:9e:2b:4d",name="ks-node2-000c299e2b4d",} 334590.0

ks_node_free_iops{node="00:0c:29:cd:26:f2",name="ks-node1-000c29cd26f2",} 341765.0

ks_node_free_iops{node="00:0c:29:07:44:f1",name="ks-node5-000c290744f1",} 522900.0

# HELP ks_node_free_bw_bytes_per_sec ks node free bw bytes per sec per Storage Node

# TYPE ks_node_free_bw_bytes_per_sec gauge

ks_node_free_bw_bytes_per_sec{node="00:0c:29:0f:60:62",name="ks-node6-000c290f6062",} 6.788481024E9

ks_node_free_bw_bytes_per_sec{node="00:0c:29:27:86:09",name="ks-node3-000c29278609",} 4.348180096E9

ks_node_free_bw_bytes_per_sec{node="00:0c:29:b8:b0:05",name="ks-node8-000c29b8b005",} 4.525654016E9

ks_node_free_bw_bytes_per_sec{node="00:0c:29:08:b9:fc",name="ks-node4-000c2908b9fc",} 4.525654016E9

ks_node_free_bw_bytes_per_sec{node="00:0c:29:4b:b3:b7",name="ks-node7-000c294bb3b7",} 4.525654016E9

ks_node_free_bw_bytes_per_sec{node="00:0c:29:9e:2b:4d",name="ks-node2-000c299e2b4d",} 4.343760512E9

ks_node_free_bw_bytes_per_sec{node="00:0c:29:cd:26:f2",name="ks-node1-000c29cd26f2",} 4.436917056E9

ks_node_free_bw_bytes_per_sec{node="00:0c:29:07:44:f1",name="ks-node5-000c290744f1",} 6.788481024E9

# HELP ks_node_free_capacity_bytes ks node free capacity bytes per Storage Node

# TYPE ks_node_free_capacity_bytes gauge

ks_node_free_capacity_bytes{node="00:0c:29:0f:60:62",name="ks-node6-000c290f6062",} 2.19882192896E12

ks_node_free_capacity_bytes{node="00:0c:29:27:86:09",name="ks-node3-000c29278609",} 1.034785128448E12

ks_node_free_capacity_bytes{node="00:0c:29:b8:b0:05",name="ks-node8-000c29b8b005",} 1.099377410048E12

ks_node_free_capacity_bytes{node="00:0c:29:08:b9:fc",name="ks-node4-000c2908b9fc",} 1.099377410048E12

ks_node_free_capacity_bytes{node="00:0c:29:4b:b3:b7",name="ks-node7-000c294bb3b7",} 2.74743689216E11

ks_node_free_capacity_bytes{node="00:0c:29:9e:2b:4d",name="ks-node2-000c299e2b4d",} 1.033711386624E12

ks_node_free_capacity_bytes{node="00:0c:29:cd:26:f2",name="ks-node1-000c29cd26f2",} 7.81465944064E11

ks_node_free_capacity_bytes{node="00:0c:29:07:44:f1",name="ks-node5-000c290744f1",} 1.649066115072E12

Volume Parameters:

 

Metric Name

Type

Sampled value

Source

ks_vol_capacity_bytes

Gauge

Capacity (in bytes)

Get Volumes

Labels:

  • uuid - UUID of the parent volume in case of replicated Volume or volume in case of simple volume.
  • alias - Volume's alias
  • numReplicas - Number of replicas
  • tenantID - tenant ID (0 for default tenant)
  • storageClassName - Storage Class name or "unknown" if not provided
  • provisioningType - Thin, thick, "Snapshot/Clone"
  • protocol - NVMeoF or Local
  • repUUIDX - For replicated volume – UUID of the X replica (blank for simple)
  • nodeIDX - For replicated volume – node ID (Persistent ID) of the X replica. For simple volume, Node ID of the volume

nodeNameX - - For replicated volume – the node name of the X replica. For simple volume, Node name of the volume.

ks_connected_volumes_state

explanation:

The state considered “Available” if at least one replica has “Available” ReplicaState.


* Only reported for nvmeof volumes which are published

Gauge

State:

0= Available

1= UnAvailable

Get Volumes

Labels:

  • uuid - UUID of the parent volume in case of replicated Volume or volume in case of simple volume.
  • alias - Volume's alias.
  • hostId - Connected host UUID.
  • hostname – the host name.
  • nqn - Nqn of connected host.

version - Software version of the host's agent.

ks_connected_replica_state

* Only reported for nvmeof volumes which are published

Gauge

State:

0=Available

1=Terminating

2=Missing
3=Unknown

4=Synchronizing

Get Volumes

Labels:

  • uuid - UUID of the parent volume.
  • alias- Alias of the parent volume.
  • repUUID- UUID of the replica.
  • hostId-Connected host UUID.
  • hostname – the host name.

Nqn- Nqn of connected host.

Storage Node Parameters:

 

Metric Name

Type

Sampled value

Source

ks_node_free_capacity_bytes

 

Gauge

Free Capacity

(Bytes)

List Backends

Labels:

  • node- KS persistence ID.
  • name - KS name.

ks_node_used_capacity_bytes

 

Gauge

Used Capacity

(bytes)

List Backends

Labels:

  • node- KS persistence ID.
  • name - KS name.

ks_node_free_iops

 

Gauge

Free IOps

(IO per second)

List Backends

Labels:

  • node- KS persistence ID.
  • name - KS name.

ks_node_used_iops

 

Gauge

Used IOps

(IO per sec)

List Backends

Labels:

  • node- KS persistence ID.
  • name - KS name.

ks_node_free_bw_bytes_per_sec

 

Gauge

Free bandwidth

(bytes per sec)

List Backends

Labels:

  • node- KS persistence ID.
  • name - KS name.

ks_node_used_bw_bytes_per_sec

 

Gauge

Used bandwidth

(bytes per sec)

List Backends

Labels:

  • node- KS persistence ID.
  • name - KS name.

ks_node_state

 

Gauge

State:

1=Available

2=Unavailable

List Backends

Labels:

  • node - KS persistence ID.
  • name - KS name.
  • rack- KS location Rack ID.  
  • zone- KS location zone ID.  
  • region- KS location region ID.

Authorization Server Config API’s

Set Authorization Server

Enable to configure authorization server for OpenIDC authentication mode.

Method

URI

POST

/auth_server

Linux Curl Command Example

curl -k --cert ./ssdtoolbox.pem -X POST -H 'Content-Type: application/json' -d '{"authorizationServerPublicKey":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkSX9EtwPkUaF1TdOGpMGA5IjhX+Y4Pm0wpzQZjtEbVl6OX3Zuz7kaj30NJCy9/YhPFMJuRPj/7POjpQ31Wk+Z9wip+wk088dl8lO8PjxwD7P5+E5jQQYKpWDoxLrohyJToPK8Emtb65TU+C33gaE8VhEAs/lVF1wQ2NQYO1dkFZW3gP8vKF9ojN0KjdrHvK7HCd0l1alYyPTNo2vfNM33j4yKftvp6P1N6G3XoiverMBTvDUXRNmDS496QVujwtmaB/oK1lmSJdRtakjl7oy22nidrKETSTT6gH8Nre33Ju3q2Umg+FH8WJhpiWFM/VuRKpFgmMOt5G4aVbCbxCqHwIDAQAB", "authorizationServerTokenURL":"http://182.29.94.3:8080/auth/realms/Dev/protocol/openid-connect/token", "backendsClientID":"liorf-backend", "backendsResourceID":"liorf-backend", "backendsClientSecret":"dfd6774e-fc1d-40c5-a12d-02ee4b5ed100", "provisionerClientID":"liorf-prov", "provisionerResourceID":"liorf-prov", "provisionerClientSecret":"e7ba4360-b5c9-41fc-9386-ea69c243f7a2"}' https://5.96.67.194:8090/auth_server

Normal response codes: 200

Request

No URI parameters.

Example 1: Set Authorization Server: JSON request

{

"authorizationServerPublicKey":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkSX9EtwPkUaF1TdOGpMGA5IjhX+Y4Pm0wpzQZjtEbVl6OX3Zuz7kaj30NJCy9/YhPFMJuRPj/7POjpQ31Wk+Z9wip+wk088dl8lO8PjxwD7P5+E5jQQYKpWDoxLrohyJToPK8Emtb65TU+C33gaE8VhEAs/lVF1wQ2NQYO1dkFZW3gP8vKF9ojN0KjdrHvK7HCd0l1alYyPTNo2vfNM33j4yKftvp6P1N6G3XoiverMBTvDUXRNmDS496QVujwtmaB/oK1lmSJdRtakjl7oy22nidrKETSTT6gH8Nre33Ju3q2Umg+FH8WJhpiWFM/VuRKpFgmMOt5G4aVbCbxCqHwIDAQAB",      "authorizationServerTokenURL":"http://172.28.90.1:8080/auth/realms/Dev/protocol/openid-connect/token",

"backendsClientID":"liorf-backend",

"backendsResourceID":"liorf-backend",

"backendsClientSecret":"dfd6774e-fc1d-40c5-a12d-02ee4b5ed100",

"provisionerClientID":"liorf-prov",

"provisionerResourceID":"liorf-prov",

"provisionerClientSecret":"e7ba4360-b5c9-41fc-9386-ea69c243f7a2"

}

Parameter Name

Type

Is Mandatory

Description

provisionerResourceID

String

Mandatory

ID of the provisioner resource –

the client name as defined in the authorization

server of client which reflects provisioner

ProvisionerClientID

String

Mandatory

ID of the provisioner client, which has a service account role

ADMIN at provisioner resource

provisionerClientSecret

String

Mandatory

The provisioner client secret

authorizationServerPublicKey

String

Mandatory

public key used to decrypt tokens

authorizationServerTokenURL

String

Mandatory

authorization server url for generating tokens

backendsResourceID

String

Mandatory

ID of backends resource –

the client name as defined in the authorization

server of client which reflects backends.

backendsClientID

String

Mandatory

ID of a backend client, which has a service account role

ADMIN at backends resource

backendsClientSecret

String

Mandatory

The backends client secret

Response

Example 2: Set Authorization Server: JSON response

{

"description":"Success",

"status":"Success",

}

Parameter Name

Type

Description

description

String

Result description.

status

String

Result code.

  • Success - Success
  • CreateProvisionerClientTokenFailed – Could not create a provisioner client token
  • CreateBackendsClientTokenFailed - Could not create a backends client token
  • DecryptProvisionerClientTokenFailed – Could not decrypt the provisioner client token
  • DecryptBackendsClientTokenFailed - Could not decrypt the backends client token
  • ProvisionerClientUnauthorized – The provisioner client token has no ADMIN role
  • BackendsClientUnauthorized – The backends client token has no ADMIN role
  • NotAvailable - Not all backends are available
  • NoChange – No configuration change

Delete Authorization Server

Enable to configure authorization server back to JWT authentication mode.

Method

URI

DELETE

/auth_server

Linux Curl Command Example

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

Normal response codes: 200

Request

No URI parameters.

Response

Example 2: Delete Authorization Server: JSON response

{

"description":"Success",

"status":"Success",

}

Parameter Name

Type

Description

description

String

Result description.

status

String

Result code.

  • Success - Success
  • InvalidAuthMode – The current authentication mode is not OpenIDC
  • NotAvailable - Not all backends are available

Get Authorization Server

Get the authorization server configuration.

Method

URI

GET

/auth_server

Linux Curl Command Example

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

Normal response codes: 200

Request

No URI parameters.

Response

Example 2: Get Authorization Server: JSON response

{

"authorizationServerPublicKey":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkSX9EtwPkUaF1TdOGpMGA5IjhX+Y4Pm0wpzQZjtEbVl6OX3Zuz7kaj30NJCy9/YhPFMJuRPj/7POjpQ31Wk+Z9wip+wk088dl8lO8PjxwD7P5+E5jQQYKpWDoxLrohyJToPK8Emtb65TU+C33gaE8VhEAs/lVF1wQ2NQYO1dkFZW3gP8vKF9ojN0KjdrHvK7HCd0l1alYyPTNo2vfNM33j4yKftvp6P1N6G3XoiverMBTvDUXRNmDS496QVujwtmaB/oK1lmSJdRtakjl7oy22nidrKETSTT6gH8Nre33Ju3q2Umg+FH8WJhpiWFM/VuRKpFgmMOt5G4aVbCbxCqHwIDAQAB",      "authorizationServerTokenURL":"http://172.28.90.1:8080/auth/realms/Dev/protocol/openid-connect/token",

"backendsClientID":"liorf-backend",

"backendsResourceID":"liorf-backend",

"backendsClientSecret":"dfd6774e-fc1d-40c5-a12d-02ee4b5ed100",

"provisionerClientID":"liorf-prov",

"provisionerResourceID":"liorf-prov",

"provisionerClientSecret":"e7ba4360-b5c9-41fc-9386-ea69c243f7a2"

}

Parameter Name

Type

Description

provisionerResourceID

String

ID of the provisioner resource –

the client name as defined in the authorization

server of client which reflects provisioner

ProvisionerClientID

String

ID of the provisioner client, which has a service account role

ADMIN at provisioner resource

provisionerClientSecret

String

The provisioner client secret

authorizationServerPublicKey

String

public key used to decrypt tokens

authorizationServerTokenURL

String

authorization server url for generating tokens

backendsResourceID

String

ID of backends resource –

the client name as defined in the authorization

server of client which reflects backends.

backendsClientID

String

ID of a backend client, which has a service account rolehttps://kumoscale.kioxia.com/en/documents/rest-api-command-reference-320

ADMIN at backends resource

backendsClientSecret

String

The backends client secret

Next: REST API Client