Get cloud hosts

GET method to view the list of cloud hosts.

Method URL Description
GET https://host_name:port/platform/rest/hostfactory/hosts Gets a list of hosts provisioned from the cloud to the cluster and returned to the cloud.

Prerequisite

You must be the cluster administrator, a read-only cluster administrator, or your user account must be assigned the HF_ALL_REQUESTOR_VIEW permission.

Request

GET https://host_name:port/platform/rest/hostfactory/hosts?parameters
Parameter Type Required/Optional Description
requestId String Optional ID of the scale-out request. To view hosts provisioned for multiple request IDs, specify a comma-separated list of request IDs (for example, &requestId=1114,1115).
requestName String Optional Name of the scale-out request. To view hosts provisioned with specific request names, specify a comma-separated list of request names (for example, &requestName=LoB1_AppA,LoB1_AppB).
reqName String Optional Name of the requestor. To view hosts provisioned for multiple requestors, specify a comma-separated list of requestor names (for example, &reqName=symA,symB).
provName String Optional Name of the cloud provider (for example, &provName=ibmcloud).
state String Optional State of the host provisioned from the cloud. Valid host states are:
  • Provisioned: The host is successfully allocated from the cloud to the cluster.
  • Releasing: The cloud host is being returned to the cloud.
  • Released: The cloud host is successfully returned to the cloud.
To view hosts in multiple states, specify a comma-separated list of states (for example, &state=Released,Provisioned).
launchTime String Optional The date/time at which the host was launched, represented as a number of seconds since epoch (January 1 1970 00:00:00).
  • To view hosts provisioned within a specific duration, specify the start time and end time of the interval, separated by a comma (for example, &launchTime=10000,20000).
  • To view hosts provisioned at a specific time, specify the start time and end time, separated by a comma, to be the same value (for example, &launchTime=10000,10000).
hfcsrftoken string Optional CSRF token that is obtained with successful login.
sortBy String Optional Field name by which data must be sorted, which could be: allocatedTime, hostname, lastFailureInfo, lastFailureTime, launchTime, ncores, ncpus, nram, provName, releaseTime, reqName, returnCount, state, or templateName. While you can sort by all fields, you can specify only one field at a time. For example, to sort by host name, add &sortBy=hostname to the URL. Include the sortOrder parameter to specify the sort order, either ascending or descending.
sortOrder Boolean Optional Order in which to sort data, either ascending (asc) or descending (desc), for the field name specified in the sortBy parameter. For example, to sort host name in ascending order, add &sortBy=hostname&sortOrder=asc.
pageSize Number Optional Maximum number of query results per page. You can control this number by configuring the HF_REST_RESULT_DEFAULT_PAGESIZE and HF_REST_RESULT_MAX_PAGESIZE parameters in the hostfactoryconf.json file.
  • If you do not specify pageSize, the number of results defined in HF_REST_RESULT_DEFAULT_PAGESIZE is returned (default 2000).
  • If you specify pageSize, the specified number of results is returned. For example, if &pageSize=3000, 3000 results are returned. Ensure that you specify pageSize to be lower than or equal to HF_REST_RESULT_MAX_PAGESIZE; otherwise, an error is returned.
startIndex Number Optional Start index of paginated query results. Valid value is 0 (default) or an integer multiple of the pageSize parameter. For example, when pageSize is 25, startIndex must be 0, 25, 50, or so on.
The startIndex and pageSize work together to return query results. For example:
  • If startIndex=0 and pageSize=100, the first 100 query results are returned.
  • If startIndex=300 and pageSize=100, the first 100 query results starting from index 300 are returned.

If you use curl, the command might look like the following example:

curl --header -b /tmp/cookie --cacert /opt/ibm/spectrumcomputing/wlp/usr/shared/resources/security/cacert.pem --tlsv1.2 -X GET https://myprimaryhost.example.com:9443/platform/rest/hostfactory/hosts?hfcsrftoken=915ee7644f431e630dac68b9ab3e40bc&requestId=1114,1115&requestName=LoB1_AppA,LoB1_AppB&reqName=symA,symB&provName=ibmcloud&state=Released,Provisioned&launchTime=10000,20000&sortBy=hostname&sortOrder=asc&startIndex=0&pageSize=100

Response

This command returns a JSON object that follows this template:
{"page":${current page number},"records":${total number of records},"rows":[hosts array],"total":${total page number when pagination}}
For example:
{"page":1,"records":3,"rows":[
{"allocatedTime":69570,"hostname":"host1","lastFailureInfo":"cannot get cpu","lastFailureTime":1234,"launchTime":1507700000,"ncores":4,"ncpus":2,"nram":8192,
  "provName":"ibmcloud", "releaseTime":1507769570,"reqName":"symA","returnCount":5,"state":"Released","templateName":"template1"},
{"allocatedTime":1507769570,"hostname":"host2","lastFailureInfo":"cannot get mem","lastFailureTime":1234,"launchTime":4321,"ncores":4,"ncpus":2,"nram":8192,
  "provName":"ibmcloud", "releaseTime":1234,"reqName":"symB","returnCount":5,"state":"Provisioned","templateName":"template1"},
{"allocatedTime":3332,"hostname":"host3","lastFailureInfo":"cannot get disk","lastFailureTime":1234,"launchTime":1507700000,"ncores":4,"ncpus":2,"nram":8192,
  "provName":"ibmcloud", "releaseTime":0,"reqName":"symB","returnCount":5,"state":"Released","templateName":"template3"}],
"total":1}

The output appears on a single line; it is split here for clarity.

Status code Description
200 OK
400 Bad request
500 Internal server error. Check the log files and look for hints in the API response body.