awsprov_templates.json reference

The awsprov_templates.json host template file for Amazon Web Services (AWS) lists all the templates that host factory can use to provision AWS hosts. This file must be configured with the correct values from your AWS environment. Configure the template file to provision On-Demand instances, Spot instances, or a mix of On-Demand and Spot instances.

Each host template represents a class of instances that share some attributes, such as hardware configuration, installed software stack, operating system, and security settings.

Location

The awsprov_templates.json file is located at $EGO_ESRVDIR/hostfactory/conf/providers/aws/conf/.

Parameters

Important:

Pay attention especially to the attributes of the instance specified in JSON key-value pairs (attributes{types,ncores,ncpus,nram}). The HostFactory service uses these definitions in its calculations to map resource demand from your cluster to the corresponding cloud provider instances. Any inaccuracies in these values might result in inaccurate calculations, leading to overprovisioning or underprovisioning of cloud hosts.
Hosts are selected for provisioning in the order listed in the templates files. In other words, compute hosts of the second template are selected only when hosts of the first template are not available.
If you want Spot templates to be given preference over On-Demand templates for requests based on resource units, ensure that Spot templates are listed before On-Demand templates.

Note: If you enter double values for parameter fields that expect integers, the double value is rounded down to the nearest integer.

priceType

Required. Pricing type of EC2 instances to be requested. Valid values are ondemand for On-Demand instances, spot for Spot instances, and heterogeneous for a mix of On-Demand and Spot instances.

For the heterogeneous option, a Spot Fleet request is submitted to provision Spot instances for the requested capacity. If the Spot Fleet request partially fulfills the requested capacity, the Spot Fleet request is canceled near the expiration time and a new request is submitted to provision On-Demand instances for the remaining capacity. The number of On-Demand instances can vary depending on the number Spot Instances provisioned by the first request.

Default is ondemand.

Note: For successful EC2 instance provisioning, the IAM user whose credentials are used to provision instances must be assigned the appropriate permissions. See Minimal permissions for AWS provisioning for a minimal list of required permissions.

For Spot instance provisioning (priceType set to spot or heterogeneous), an IAM role for Spot Fleet must be created and permissions must be granted to the IAM user. For more information, see Spot Fleet prerequisites in AWS documentation.

templateId

Required. Unique name for the template. Valid value is a string of up to 64 characters, which can contain the following characters: 0-9, A-Z, a-z, -, and _.

Tip: Include a keyword such as Spot or OnDemand in the template ID to easily identify instances of different EC2 pricing on the cluster management console.

maxNumber

Required. Maximum number of instances of this template that can be provisioned. Valid value is an integer in the range -1 - 10000. Use -1 to indicate an unlimited number of instances, up to a maximum of 10,000, and 0 to indicate that no instances of this template must be provisioned.

When the priceType parameter is set to spot or heterogeneous, maxNumber indicates the maximum number of units that can be provisioned. In this case, instances with a larger weight account for more units compared to instances with a smaller weight.

Note: AWS Spot Fleets can overprovision resources, because of which the maxNumber can be exceeded for templates with priceType set to spot or heterogeneous.

attributes

Required. Hardware attributes of the hosts:

type: Type of the VM (string). Only type X86_64 (representing an x86_64 Linux® host) is supported.
ncores: Number of cores per CPU (numeric). Valid value is a positive integer higher than 0.
ncpus: Number of CPUs per host (numeric). Valid value is a positive integer higher than 0. For EC2 instance types with hyperthreading enabled, define the ncpus to be half of the vCPU value (IBM® Spectrum Conductor does not consider hyperthreads). For example, when r4.8xlarge provides 32 vCPUs, define ncpus as 16.
nram: Available RAM (MB).

Obtain attribute values for different instance types from the Amazon EC2 Instance Types reference. The following examples show the mapping from vCPU to attributes ncpus and ncores:

Model	vCPU	Mem (GiB)	attributes
t2.micro	1	1	`type: X86_64 ncores: 1 ncpus: 1 nram: 1024 MB`
m4.4xlarge	16	64	16 vCPUs map to 8 ncpus, with 2 hyperthreads (IBM Spectrum Conductor does not consider hyperthreads) `type: X86_64 ncores: 2 ncpus: 8 nram: 64000 MB`

imageId

Required. Amazon Machine Image (AMI) ID that is used to launch EC2 instances. This AMI ID can be an image of an AWS instance with IBM Spectrum Conductor preinstalled (see Creating a custom image in AWS). Alternatively, it can be a base OS image that is provided by AWS; you would then use a post-provisioning script to install IBM Spectrum Conductor on the instance after it is provisioned. For information on provisioning options, see Image options for cloud compute hosts.

Note: For Spot instances, only a subset of base images or custom images based on those base images are allowed. To check which base images are available for use, go to EC2 > Spot Instances > Create a Spot Fleet on the AWS console.

subnetId

Required. ID of the subnet (in the desired VPC) into which the instances are launched.

When priceType is set to ondemand, valid value is a single string ID. If you specify multiple subnets, only the first subnet ID in the list is used.
When priceType is set to spot or heterogeneous, valid value is a single string ID or a comma-separated array of strings.

All compute hosts that connect to your IBM Spectrum Conductor cluster must use private subnets. Ensure that your cluster is configured to access these private subnets.

vmType or vmTypes

Required. EC2 instance type to be provisioned.

When priceType is set to ondemand, use vmType to specify a single string ID of the EC2 instance type to be provisioned.
When priceType is set to spot or heterogeneous, use vmTypes to specify a list of comma-separated key-value pairs. In each key:value pair, key is a string that represents the instance type and value is an integer that represents the weighted capacity of the number of units provided by the specified instance type. The weighted value must be an integer greater than 1, and cannot be a decimal value.
For Spot or heterogeneous templates, the attributes represent a unit. Provisioned instances with a larger weight account for more units compared to instances with a smaller weight. For more information on instance weighting, see Spot fleet instance weighting.

rootDeviceVolumeSize

For Elastic Block Store (EBS)-backed AMIs, size (in GiB) of the EBS root device volume for EC2 On-Demand and Spot instances launched from the template. Valid value is an integer in the range 1 – 16384 (16 TiB). Default is the root device volume size of the AMI used for provisioning instances. If the volume size specified is lower than the root device volume size of the AMI, this parameter does not take effect. If the volume size specified is larger than 16TiB, the maximum allowed size of 16 TiB is used instead.

instanceTags

Optional. Tags that must be added to provisioned instances (On-Demand, Spot, or both) to more easily organize and identify them (for example, by purpose, owner, or environment). Valid value is a string of one or more tags, where each tag is a key-value pair in the format key=value. Multiple tags are separated by a semicolon (;). For more information on tag restrictions, see User-defined tag restrictions.

keyName

Optional. Name of the Amazon EC2 key pair that can be used to connect to the launched EC2 instance. You can use the key pair to log in using SSH; Linux instances do not have a password. If you do not specify this parameter, you cannot use SSH to connect to this instance.

securityGroupIds

Optional. A list of strings for AWS security groups that are applied to the instances. If you do not specify this parameter, AWS uses the default security group associated with the VPC.

fleetRole

Required when priceType is set to spot or heterogeneous. The role that grants permissions to launch and terminate Spot Fleet instances on behalf of the designated IAM user.

maxSpotPrice

Optional. When priceType is set to spot or heterogeneous, maximum price that you are willing to pay for this Spot unit. If this parameter is not defined, the price of On-Demand instances is used as the default maximum Spot price.

The maximum Spot price relates to the instance type’s weight (defined in the vmTypes parameter). If an instance type’s weight is set to 2, the maximum Spot price for that instance type is considered to be two times the actual maxSpotPrice specified.

spotFleetRequestExpiry

Optional. When priceType is set to spot or heterogeneous, time (in minutes) after which an unfulfilled Spot Fleet request is canceled. Valid value is an integer in the range specified by AWS. Default is 30 minutes.

When priceType is set to spot, Spot instances are provisioned until this period expires.
When priceType is set to heterogeneous, Spot instances are provisioned until this period expires, then On-Demand instances are provisioned for any unfulfilled demand.

allocationStrategy

Optional. Allocation strategy for Spot instances. Valid values are lowestPrice to indicate that Spot instances must come from pools with the lowest price, diversified to indicate that Spot instances can be distributed across all pools, or capacityOptimized to indicate that Spot instances must come from the pool with optimal capacity for the number of instances that are launching. Default is lowestPrice. For more information, see Allocation strategy for Spot instances.

poolsCount

Optional. When priceType is set to spot or heterogeneous and allocationStrategy is set to lowestPrice, specify the number of Spot instance pools to use. Valid value is an integer higher than 0.

instanceProfile

Optional. An IAM instance profile to assign to the provisioned instance, enabling jobs on that instance to use instance-profile credentials to access other AWS resources. An instance profile is essentially the same as an IAM role. Valid value is either a short name of the IAM user or the Amazon Resource Name (ARN). The IAM user role designated for provisioning must be assigned the IAM:PassRole in order to pass the instance profile to the provisioned instances. For more information, see ARNs and AWS service namespaces.

userDataScript

Optional. Full path to a post-provisioning script, which is included in the instance and is run during instance startup. For information on using sample scripts, see Configuring the sample post-provisioning script for AWS.

Example awsprov_templates.json file

Sample template for On-Demand instances

{
  "templates": [
    {
      "templateId": "Template-VM-Consmall",
      "maxNumber": 20,
      "attributes": 
        {
          "type": ["String", "X86_64"],
          "ncores": ["Numeric", "1"],
          "ncpus": ["Numeric", "1"],
          "nram": ["Numeric", "1024"]
        },
      "imageId": "ami-f09fbde7",
      "rootDeviceVolumeSize": 100,
      "subnetId": "subnet-20069069",
      "vmType": "t2.micro",
      "keyName": "Con-Key",
      "securityGroupIds": ["sg-541fdc29"],
      "userDataScript": "/opt/ibm/spectrumcomputing/3.8/hostfactory/providers/aws/scripts/postprovision/fresh_install.sh"
    },
    {
      "templateId": "Template-VM-Conlarge",
      "maxNumber": 4,
      "attributes":
        {
          "type": ["String", "X86_64"],
          "ncores": ["String", "2"],
          "ncpus": ["String", "8"],
          "nram": ["Numeric", "16384"]
        },
      "imageId": "ami-f09fbde7",
      "subnetId": "subnet-20069069",
      "vmType": "m4.4xlarge",
      "keyName": "Con-Key",
      "securityGroupIds": ["sg-541fdc29"],
      "userDataScript": ""
    }
  ]
}

Sample template for Spot instances

Table 1. Configuration options for Spot templates
Goal	Parameters to be configured in awsprov_templates.json
Use Spot instances to only reduce AWS costs (minimal configuration)	Set priceType to either spot or heterogeneous, and Specify fleetRole to the IAM role that grants permissions to launch and terminate Spot Fleet instances.
Increase chances of getting Spot instances	Specify multiple instance types in vmTypes to allow AWS a better chance of fulfilling provisioning requests.
Totally fulfill demand even when AWS does not have enough available Spot capacity	Set priceType to heterogeneous, Specify fleetRole, and Define spotFleetRequestExpiry to a short 1 or 2 minutes, so that the remainder of your demand is requested as a fleet of On-Demand instances when the Spot Fleet request expires.
Fulfill all your demand using instance types at the lowest price	Set allocationStrategy to lowestPrice, and Define poolsCount. Use a low or high number of Spot pools across which to allocate your Spot instances. Increasing the pool count increases the chances of a specific request being fully provisioned, but also increases the time required for provisioning.
Increase high availability by provisioning instances across multiple pools (instead of trying to fulfill all your demand using instance types at the lowest price)	Set allocationStrategy to diversified, and Define all required instance types in vmTypes.
Ensure that requested instances do not exceed a price limit per hour	Set priceType to spot, Specify the fleetRole, and Set the maxSpotPrice. Note: For typical scenarios, do not define maxSpotPrice because it might limit your results or result in a failed request if the value is too low. To ensure that demanded machines do not exceed a specific price limit per hour, check the Spot instance pricing history and the current price of instance types from the AWS console, then set this value.
Give Spot templates preference over On-Demand templates for requests based on resource units	Change the order of templates in the awsprov_templates.json file. Resources are provisioned from templates in the order listed in the host template; Spot instances (which are cheaper than On-Demand instances) can be listed before On-Demand templates.

{
    "templates": [
        {
            "templateId": "SpotTemplate-VM-SYM",
            "maxNumber": 230,
            "attributes": {
                "type": ["String", "X86_64"],
                "ncores": ["Numeric", "1"],
                "ncpus": ["Numeric", "16"],
                "nram": ["Numeric", "249856"]
            },
            "imageId": "ami-01e24be29428c15b2",
            "rootDeviceVolumeSize": 100,
            "instanceTags": "company=abc;project=awscloudspot;team=xyz",
            "subnetId":["subnet-12a34b56","subnet-123ab456789cdef01"],
            "vmTypes": {"r4.8xlarge":1, "r4.16xlarge":2},
            "keyName": "Con-Key",
            "priceType": "spot",
            "allocationStrategy": "lowestPrice",
            "instanceProfile": "arn:aws:iam::123456789012:instance-profile/myRole",
            "spotFleetRequestExpiry": 40,
            "poolsCount": 1,
            "fleetRole":"arn:aws:iam::123456789012:role/aws-ec2-spot-fleet-tagging-role",
            "securityGroupIds": ["sg-e0d4b999"],
            "userDataScript": "/opt/ibm/spectrumcomputing/3.8/hostfactory/providers/aws/postprovision/fresh_install.sh"
    },