Submit request for cloud hosts as a requestor

POST method to submit demand for cloud resources through the host factory requestor plug-in.

Method URL Description
POST https://host_name:port/platform/rest/hostfactory/requestor/$requestor_name/request Creates a request for cloud resources.

Prerequisites

  • You must be the cluster administrator or your user account must be assigned the HF_ALL_REQUESTOR_MANAGE permission.
  • The specified requestor must be configured for REST mode in the hostRequestors.json file, enabling you to demand cloud hosts through the RESTful API.
    To enable the built-in cws requestor in REST mode:
    1. Edit the hostRequestors.json file at $EGO_ESRVDIR/hostfactory/conf/requestors/.
    2. For the cws requestor, set the requestMode parameter to REST.
    3. Save your changes.

Request

POST https://host_name:port/platform/rest/hostfactory/requestor/$requestor_name/request?parameter

where requestor_name identifies the REST-enabled requestor in the hostRequestors.json file. The built-in requestor is cws.

Table 1. Request parameter
Parameter Type Required/Optional Description
hfcsrftoken string Optional CSRF token that is obtained with successful login.

This command takes a JSON request string to request resources that use one of the following formats:

1: Request hosts of a specific template
To request hosts that use a specific template, the JSON request string must follow this template:
{
  "request_name": (optional)(string) "Name for demand request",
  "request_comments": (optional)(string) "Comments",
  "demand_hosts": [
    {
      "prov_name": (mandatory)(string) "A provider in hostProviders.json",                  
      "template_name": (mandatory)(string) "Preconfigured template prov_name_template.json",
      "ninstances": (mandatory)(numeric) "Number of instances of this template"
    }
   ]
}
JSON property Type Required Description
request_name String Optional Unique identifier (for example, LoB1_AppA) to more easily group requests. Valid value is a string of up to 128 characters, which can contain numbers, uppercase and lowercase letters, hyphens (-), and underscores (_).
request_comments String Optional Comments about the request. Valid value is a string of up to 256 characters.
prov_name String Required Name of a cloud provider that is defined in the hostProviders.json file (for example, aws).
template_name String Required Name of a preconfigured host provisioning template (for example, Template-VM-Consmall defined as the templateID in the awsprov_template.json file).
ninstances Number Required Number of instances of the specified host template (for example, Template-VM-Consmall).
If you use curl, the command might look like the following example, which requests 2 EC2 instances from AWS that use the Template-VM-Consmall template: 
curl --header -b /tmp/cookie --cacert /opt/ibm/spectrumcomputing/wlp/usr/shared/resources/security/cacert.pem --tlsv1.2 -X POST https://myprimaryhost.example.com:9443/platform/rest/hostfactory/requestor/cws/request?hfcsrftoken=915ee7644f431e630dac68b9ab3e40bc -d '{ "request_name": "LoB1_AppA", "request_comments": "Application A in LoB1", "demand_hosts": [ { "prov_name": "aws", "template_name": "Template-VM-Consmall", "ninstances": 2 } ] }'
2: Request resources with a minimum requirement
To request cloud resources that must meet a minimum requirement in terms of cores and memory, the JSON request string must follow this template:
{
  "request_name": (optional)(string) "Name for demand request",
  "request_comments": (optional)(string) "Comments",
  "demand_resource": [
    {
      "nunits" : (mandatory)(numeric) "Total units required",
      "unit_minimum" : (mandatory)
       {
            "ncores" : (mandatory) (numeric) "Minimum cores per unit"
            "nram"   : (optional)(numeric) "Minimum RAM per unit; default 1MB"
       }
    }
   ]
}
JSON property Type Required Description
request_name String Optional Unique identifier (for example, LoB1_AppC) to more easily group requests. Valid value is a string of up to 64 characters, which can contain numbers, uppercase and lowercase letters, hyphens (-), and underscores (_).
request_comments String Optional Comments about the request.
unit_minimum > ncores Number Required Minimum number of cores required per unit.
unit_minimum > nram Number Optional Minimum amount of memory (in MB) required per unit.
The following example requests a total of 100 cores, with a minimum requirement of 1 core and 2 GB per compute unit:
curl --header -b /tmp/cookie --cacert /opt/ibm/spectrumcomputing/wlp/usr/shared/resources/security/cacert.pem --tlsv1.2 -X POST https://myprimaryhost.example.com:9443/platform/rest/hostfactory/requestor/cws/request?hfcsrftoken=915ee7644f431e630dac68b9ab3e40bc -d '{ "request_name": "LoB1_AppC", "request_comments": "Application C in LoB1", "demand_resource": [ { "nunits" : 100, "unit_minimum" : { "ncores" : 1, "nram"   : 2048 } } ] }'
The following example requests a total of 32 cores, with a minimum requirement of 32 cores and 512 GB per compute unit:
curl --header -b /tmp/cookie --cacert /opt/ibm/spectrumcomputing/wlp/usr/shared/resources/security/cacert.pem --tlsv1.2 -X POST https://myprimaryhost.example.com:9443/platform/rest/hostfactory/requestor/cws/request?hfcsrftoken=915ee7644f431e630dac68b9ab3e40bc -d '{ "request_name": "LoB1_AppD", "request_comments": "Application D in LoB1", "demand_resource": [ { "nunits" : 1, "unit_minimum" : { "ncores" : 32, "nram"   : 524288 } } ] }'

Response

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