The State of The Amazon EC2 Spot Market is now available! Download The White Paper

Spotinst API Documentation

Welcome to Spotinst API Documentation!

Welcome to the heart and soul of Spotinst: our API, which allows you to manage and operate your Spotinst account using conventional RESTful API. Whatever you can do via our portal, you can also do via our API.

Except for content explicitly made available to the general public, access and use of this site and all content herein is restricted to users authorized by Spotinst and may be subject to confidentiality restrictions. Please also note that the information contained herein is for informational purposes only and to the extent it conflicts with the terms of your contractual agreements with Spotinst, the terms of those contracts will govern.

Next 


API Semantic

This page explains the semantics of our REST API. It includes information on:

  • How to ask a service about itself: what fields it supports, which fields are filterable

  • How to get only the information you want by filtering and sorting

  • The structure of our JSON responses in different scenarios

HTTP Protocol

The Spotinst API supports HTTP Protocol version 1.1 or later. While some calls may work with the deprecated 1.0 version, this is not guaranteed. Please ensure that your client communicates using at least version 1.1.

API Endpoint

Spotinst API URL:

https://api.spotinst.io

Please note - We enforce using the secure endpoint (https) for our production API to ensure the privacy of your data.

REST Semantic

Our API services are RESTful. REST (Representational State Transfer) is a type of software architecture in which requests model the communication from a web browser to a web server. Below are the central REST methods used in our API services, and their uses:

REST Method Use
POST Create
GET Read
PUT Update
DELETE Delete

cURL

In our documentation we use curl to make HTTP requests. Curl is a command-line tool for transferring files with URL syntax, supporting FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, LDAP, LDAPS, and more. Example scripts have been provided on each API wiki page to illustrate the structure of the curl commands you will need to run Spotinst API services. In addition, an example of how to a make a genericPOST request is shown below.

$ curl -X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer <TOKEN>"
-d @some.jsonfile 'http://api.spotinst.com/'
Request Parameter Description
-H "Content-Type: " Indicates which type of data you pass, could be "application/json" or "application/x-www-form-urlencoded"
-H "Authorization: Bearer " Retrieves your authentication token
-X The type of the request. in this case "POST"
-d Indicates that you are going to upload a file or a encoded payload
"https://api.spotinst.io/aws/ec2/group" End point URL and path for your request

Use Single Quotes Around Your Request URL Some requests require single quotes around your request URL, as in the above curl request. If you get an error message from your UNIX shell, make sure your request URL has single quotes before troubleshooting further. For more information on how UNIX shell quotes and escaping work, see this documentation on quotes and escaping in shells.

JSON Fields Types

POST and PUT requests require JSON data. For PUT requests, only the JSON fields included in a request will be updated. All other fields will be unchanged. Different fields require different types of values. The table of types below extends those defined in the JSON standard.

Type Description Example
Boolean True or false true
String(100) A string of 100 characters or less “Spotinst Cloud”
Int An integer 87
Decimal A generic decimal number 3.0
Float A floating-point number with 32-bit precision 3.14…
Double A floating-point number with 64-bit precision 3.14…
Enum One of a number of predetermined values “male” or “female”
Money A floating-point numeric value used to represent money 19.23
Timestamp A date and time string in the form YYYY-MM-DD HH:MM:SS “2009-01-14 05:41:04”
Date A date and time string in the form YYYY-MM-DD HH:MM:SS “2009-01-14 05:41:04”
Multi-Object A wrapper for any sub-fields under the current field “countries_and_brands”: [ { “country”: “FR”, “brand”: { “id”: 466, “name”: “PKR” } } ]
Array A list containing one or more values [87, 45, 99.12, 101.71]

JSON fields and values use underscores, e.g., audit_type_direct.

Organization and Accounts

Each Spotinst account is assigned to an Organization and a set of environment Accounts. Each account should be linked to either a Cloud provider account or a Multai Load Balancer Account.

Each Account will have an Account ID that needs to be used while performing an API call to resources in the account.

To locate the Account Id, please navigate to the account settings and locate the Account ID value.

act-123de678

Organizations with a single Account

Each API call you make can be used with or without the account ID.

Organizations with multiple Accounts

Each API call you make should be appended with the account ID. For example:

GET https://api.spotinst.io/aws/ec2/group?accountId=act-123de678

This call will return the list of Elastigroups for the specific Account used.

Please note - If no account ID is provided, the default account for the Organization will be used

Next  Previous


Authentication

In every API call you make to spotinst API, you must include Authentication token to authenticate yourself. There are two kind of tokens you can use:

  • Personal Access Token

  • Temporary Access Token

WARNING: Do not share your personal access token or your application secret with anyone outside your organization. Please contact our support if you’re concerned your token has been compromised.

Permanent Access Token

Personal Access Tokens are a useful mechanism for accessing the API. You can create many, but not unlimited, personal access tokens (It is recommended to add description to each token)

You can create personal token from Spotinst Spotinst Console.

Temporary Access Token

The temporary access token is valid for 2 hours (7200 seconds).

You can create personal token using the below command:

$ curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'username=<USERNAME>&password=<PASSWORD>&grant_type=password&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>' https://oauth.spotinst.io/token

The request will return the accessToken - Use this token when making calls to Spotinst API

Remember to keep your tokens secret, treat them just like passwords! They act on your behalf when interacting with the API. Don’t hardcode them into your programs; instead, opt to use them as environment variables.

Next  Previous


Spotinst Whitelabel IPs

Spotinst whitelabel IPs are required for integrations to work as expected. The IP need to be whitelabeled on the Master nodes of Rancher, HCS, Kubernetes and Chef. Make sure your whitelabel IPs are always up-to-date with the latest list

34.226.61.134/32
13.90.255.25/32 
13.90.103.164/32 
13.90.101.230/32 
13.90.100.43/32
Next  Previous


Spotinst Policy

AWS

Spotinst Latest Policy for AWS. Make sure your policy is always up-to-date with the latest json

You can find and modify your Spotinst Policy in the AWS IAM Console.

For additional information and guide please see: Updating the Spotinst Policy

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "GeneralSpotInstancesAccess",
            "Action": [
                "ec2:RequestSpotInstances",
                "ec2:CancelSpotInstanceRequests",
                "ec2:CreateSpotDatafeedSubscription",
                "ec2:Describe*",
                "ec2:AssociateAddress",
                "ec2:AttachVolume",
                "ec2:ConfirmProductInstance",
                "ec2:CopyImage",
                "ec2:CopySnapshot",
                "ec2:CreateImage",
                "ec2:CreateSnapshot",
                "ec2:CreateTags",
                "ec2:CreateVolume",
                "ec2:DeleteTags",
                "ec2:DisassociateAddress",
                "ec2:ModifyImageAttribute",
                "ec2:ModifyInstanceAttribute",
                "ec2:MonitorInstances",
                "ec2:RebootInstances",
                "ec2:RegisterImage",
                "ec2:RunInstances",
                "ec2:StartInstances",
                "ec2:StopInstances",
                "ec2:TerminateInstances",
                "ec2:UnassignPrivateIpAddresses",
                "ec2:DeregisterImage",
                "ec2:DeleteSnapshot",
                "ec2:DeleteVolume",
                "ec2:ModifyReservedInstances",
                "ec2:CreateReservedInstancesListing",
                "ec2:PurchaseReservedInstancesOffering",
                "ec2:CancelReservedInstancesListing",
                "ec2:ModifyNetworkInterfaceAttribute"
            ],
            "Effect": "Allow",
            "Resource": [
                "*"
            ]
        },
        {
            "Sid": "AccessELB",
            "Action": [
                "elasticloadbalancing:Describe*",
                "elasticloadbalancing:Deregister*",
                "elasticloadbalancing:Register*",
                "elasticloadbalancing:RemoveTags",
                "elasticloadbalancing:RegisterTargets"
            ],
            "Effect": "Allow",
            "Resource": [
                "*"
            ]
        },
        {
            "Sid": "AccessCloudWatch",
            "Action": [
                "cloudwatch:DescribeAlarmHistory",
                "cloudwatch:DescribeAlarms",
                "cloudwatch:DescribeAlarmsForMetric",
                "cloudwatch:GetMetricStatistics",
                "cloudwatch:ListMetrics",
                "cloudwatch:PutMetricData"
            ],
            "Effect": "Allow",
            "Resource": [
                "*"
            ]
        },
        {
            "Sid": "AccessSNS",
            "Action": [
                "sns:Publish",
                "sns:ListTopics",
                "sns:CreateTopic",
                "sns:GetTopicAttributes",
                "sns:ListSubscriptionsByTopic",
                "sns:Subscribe"
            ],
            "Effect": "Allow",
            "Resource": [
                "*"
            ]
        },
        {
            "Sid": "AccessIAM",
            "Action": [
                "iam:AddRoleToInstanceProfile",
                "iam:ListInstanceProfiles",
                "iam:ListInstanceProfilesForRole",
                "iam:PassRole",
                "iam:ListRoles",
                "iam:ListAccountAliases",
                "iam:GetPolicyVersion",
                "iam:ListPolicies",
                "organizations:ListAccounts",
                "iam:GetPolicy",
                "iam:ListAttachedRolePolicies"
            ],
            "Effect": "Allow",
            "Resource": [
                "*"
            ]
        },
        {
            "Sid": "GeneralAccessElaticBeanstalk",
            "Action": [
                "elasticbeanstalk:Describe*",
                "elasticbeanstalk:RequestEnvironmentInfo",
                "elasticbeanstalk:RetrieveEnvironmentInfo",
                "elasticbeanstalk:ValidateConfigurationSettings",
                "elasticbeanstalk:UpdateEnvironment",
                "cloudformation:GetTemplate",
                "cloudformation:DescribeStackResources",
                "cloudformation:DescribeStackResource",
                "cloudformation:DescribeStacks",
                "cloudformation:ListStackResources",
                "cloudformation:UpdateStack",
                "cloudformation:DescribeStackEvent",
                "cloudformation:DescribeStackEvents",
                "logs:PutRetentionPolicy",
                "logs:createLogGroup"
            ],
            "Effect": "Allow",
            "Resource": [
                "*"
            ]
        },
        {
            "Sid": "AccessAutoScalingGroups",
            "Action": [
                "autoscaling:*"
            ],
            "Effect": "Allow",
            "Resource": [
                "*"
            ]
        },
        {
            "Sid": "AccessEMR",
            "Action": [
                "elasticmapreduce:*",
                "s3:GetObject"
            ],
            "Effect": "Allow",
            "Resource": [
                "*"
            ]
        },
        {
            "Sid": "AccessECS",
            "Action": [
                "ecs:List*",
                "ecs:Describe*",
                "ecs:DeregisterContainerInstance",
                "ecs:UpdateContainerInstancesState"
            ],
            "Effect": "Allow",
            "Resource": [
                "*"
            ]
        },
        {
            "Sid": "AccessCodeDeploy",
            "Action": [
                "codedeploy:*"
            ],
            "Effect": "Allow",
            "Resource": [
                "*"
            ]
        },
        {
            "Sid": "AccessGeneralS3",
            "Action": [
                "s3:GetObject",
                "s3:List*",
                "s3:GetBucketLocation"
            ],
            "Effect": "Allow",
            "Resource": [
                "*"
            ]
        },
        {
            "Sid": "AccessOpsWorks",
            "Action": [
                "opsworks:DeregisterInstance",
                "opsworks:DescribeInstances",
                "opsworks:DescribeStacks",
                "opsworks:DescribeLayers"
            ],
            "Effect": "Allow",
            "Resource": [
                "*"
            ]
        },
        {
            "Sid": "AccesS3forElasticBeanstalk",
            "Effect": "Allow",
            "Action": [
                "s3:*"
            ],
            "Resource": [
                "arn:aws:s3:::elasticbeanstalk*"
            ]
        }
    ]
}
Next  Previous


Spotinst Account

You can create an Account via the following API calls - as well as set the conection with your Cloud provider.

Account

Create Account
POST/setup/account

Create a Spotinst account.

account.name - (string) - (required) Provide a name for your account. The account name must contain at least one character that is a-z or A-Z


Example URI

POST https://api.spotinst.io/setup/account

Request  Create Account
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "account": {
    "name": "AccountName"
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "64181193-f129-4981-835a-6fcdb1e5e01f",
    "url": "/setup/account",
    "method": "POST",
    "timestamp": "2017-10-17T10:43:42.538Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:setup:account",
    "items": [
      {
        "id": "act-123456",
        "name": "AccountName",
        "organizationId": "606012341234"
      }
    ],
    "count": 1
  }
}

Get Accounts
GET/setup/account

Get a list of Spotinst accounts in your organization.


Example URI

GET https://api.spotinst.io/setup/account

Request  Get Account
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "e2923755-80ec-4751-be1a-3b4b4400d1d1",
    "url": "/setup/account",
    "method": "GET",
    "timestamp": "2017-11-15T08:03:54.322Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:setup:account",
    "items": [
      {
        "accountId": "act-0b18f123",
        "organizationId": "606079861123",
        "name": "test",
        "createdAt": "2017-06-04T16:32:58.000Z"
      },
      {
        "accountId": "act-57765123",
        "organizationId": "606079861123",
        "name": "prod",
        "createdAt": "2017-04-16T09:58:24.000Z"
      }
    ],
    "count": 2
  }
}

AWS credentials

Set Cloud credentials
POST/setup/credentials/aws?accountId={ACCOUNT_ID}

Link a Spotinst account to an AWS account.

credentials.iamRole - (string) - (required) Provide the iamRole ARN with the latest spotinst Policy

credentials.externalId - (string) - (required) Provide the External ID used while setting up the IAM Role. This should be a random string of your choosing, for example: “jkn78sv05v4mk1”.


Example URI

POST https://api.spotinst.io/setup/credentials/aws?accountId=act-12345

Parameters

  • ACCOUNT_ID
    string (required) Example: act-12345

    The Account id you want to update


Request  Set Credentials
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "credentials": {
    "iamRole": "arn:aws:iam::1234567890:role/Spotinst_Iam_Role",
    "externalId": "1a2b3c4d5e6f7g8h9i0g"
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "8a8a3f88-7620-4783-bf00-953e0b8892fe",
    "url": "/setup/credentials/aws?accountId=act-123456",
    "method": "POST",
    "timestamp": "2017-10-17T10:43:54.421Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    }
  }
}
Next  Previous


Amazon Web Services

Elastigroups

List All
GET/aws/ec2/group?name={groupNAME}

Describe all the Elastigroups and their full JSONs


Example URI

GET https://api.spotinst.io/aws/ec2/group?name=GroupName

Parameters

  • groupNAME
    string (required) Example: GroupName

    (optional) The Elastigroup name you want to list


Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  items: []
}

Create
POST/aws/ec2/group

Create a new Elastigroup cluster

Available Body parameters

  • name - string - (required) Elastigroup name

  • description - string - (optional) Describe your Elastigroup

Capacity

  • capacity.target - int - (Required) The number of instances to launch

  • capacity.minimum - int - (Required) The lower limit number of instances that you can scale down to

  • capacity.maximum - int - (Required) The upper limit number of instances that you can scale up to

  • capacity.unit - string - (Required) The capacity unit to launch instances by. Valid Values: instance (default), weight

Strategy

  • strategy.risk - int - (Required if onDemandCount is not specified) The percentage of Spot instances to launch (range: 0 - 100).

  • strategy.onDemandCount - int - (Required if risk is not specified) Number of on demand instances to launch in the group. All other instances will be spot instances. When this parameter is set the “risk” parameter is being ignored.

  • strategy.availabilityVsCost - string - (Required) The strategy orientation. Valid Values: costOriented , availabilityOriented , balanced, equalAzDistribution (please read this artice before using equalAzDistribution orientation: Equal AZ Instance Distribution)

  • strategy.fallbackToOd - boolean - (Optional) In case of no spots available, Elastigroup will launch an On-demand instance instead

  • strategy.utilizeReservedInstances - boolean - (Optional) In case of any available Reserved Instances, Elastigroup will utilize them before purchasing Spot instances

  • strategy.drainingTimeout - int - (Optional) The time in seconds to allow the instance be drained from incoming TCP connections and detached from ELB before terminating it, during a scale down operation

  • strategy.signals - Array - (Optional) The signals defined for this group

  • strategy.signals.name - `string` - (Optional)

The name of the signal defined for the group.Valid Values: INSTANCE_READY, INSTANCE_READY_TO_SHUTDOWN

  • strategy.signals.timeout - int - (Optional) The timeout in seconds to hold the instance until a signal is sent. If no signal is sent the instance will be replaced (INSTANCE_READY) or we will terminate the instance (INSTANCE_READY_TO_SHUTDOWN) after the timeout. The default value is 30 minutes (1800 seconds, minimal value is 60 seconds)

  • strategy.persistence - Object - (Optional) You can register persistence (Stateful) recovery arguments

  • strategy.persistence.shouldPersistPrivateIp - boolean - (Optional) Should the instance maintain its private IP

  • strategy.persistence.shouldPersistRootDevice - boolean - (Optional) Should the instance maintain its root device volumes

  • strategy.persistence.shouldPersistBlockDevices - boolean - (Optional) Should the instance maintain its Data volumes

  • strategy.persistence.blockDevicesMode - string - (Optional) determine the way we attach the data volumes to the data devices, possible values: ‘reattach’ and ‘onLaunch’ (default is onLaunch)

Compute

  • compute.product - string - (Required) Operation system type. Possible values: Linux/UNIX SUSE Linux Windows Linux/UNIX (Amazon VPC) SUSE Linux (Amazon VPC) Windows (Amazon VPC)

  • compute.elasticIps - Array<String> - (Optional) Optional - List of ElasticIps Allocation Ids to associate to the group instances.(e.g. “eipalloc-9d4e16f8”).

Instance Types

  • compute.instanceTypes.ondemand - string - (Required) Available Instance types

  • compute.instanceTypes.spot - Array - (Required) The following instance types are not supported for Spot: T2 I2 HS1

  • compute.instanceTypes.weights - Array<Object> - (Optional) Custom weight for each instance type (only valid in weight capacity unit)

  • compute.instanceTypes.weights.instanceType - String - (Optional) The instance type to customize its weight

  • compute.instanceTypes.weights.weightedCapacity - Integer - (Optional) The weight

Availability Zones

  • compute.availabilityZones - Array<Object> - (Required) Information about one or more availability Zones for the group.

  • compute.availabilityZones.name - string - (Required) The Availability Zone name (e.g: us-east-1a \ us-east-1b)

  • compute.availabilityZones.subnetId - string - (Optional) specify EC2 or VPC subnet id. if not specified , the instances will be launched in the default subnet for the AZ

  • compute.availabilityZones.placementGroupName - string - (Optional) specify a Placement Group name, the instances will be launched in the Placement Group for the AZ.

Launch Specification

  • compute.launchSpecification.loadBalancerNames - Array<String> - Deprecated - use loadBalancersConfig instead(Optional) The elastic load balancer names.

  • compute.launchSpecification.loadBalancersConfig - Object - (Optional) Elastic Load Balancers configurations

  • compute.launchSpecification.loadBalancersConfig.loadBalancers - Array<Object> - (Optional) List of classic load balancers and/or application load balancer target groups and/or Mulati load balancer target sets

  • compute.launchSpecification.loadBalancersConfig.loadBalancers.name - String - (Optional) The AWS resource name

  • compute.launchSpecification.loadBalancersConfig.loadBalancers.arn - String - (Optional) The AWS resource ARN (required only for ALB target groups)

  • compute.launchSpecification.loadBalancersConfig.loadBalancers.type - string - (Optional) The resource type. Valid Values: CLASSIC TARGET_GROUP MULTAI_TARGET_SET

  • compute.launchSpecification.loadBalancersConfig.loadBalancers.balancerId - String - (Optional) The Multai load balncer ID (lb-xxxxxx)

  • compute.launchSpecification.loadBalancersConfig.loadBalancers.targetSetId - String - (Optional) The Multai load target set ID (ts-xxxxxx)

  • compute.launchSpecification.loadBalancersConfig.loadBalancers.azAwareness - boolean - (Optional) “AZ Awareness” will ensure that instances within the same AZ are using the corresponding MLB runtime instance in the same AZ. This feature reduces multi-zone data transfer fees

  • compute.launchSpecification.loadBalancersConfig.loadBalancers.autoWeight - boolean - (Optional) “Auto Weight” will automatically provide a higher weight for instances that are larger as appropriate. For example, if you have configured your Elastigroup with m4.large and m4.xlarge instances the m4.large will have half the weight of an m4.xlarge. This ensures that larger instances receive a higher number of MLB requests

  • compute.launchSpecification.healthCheckType - String - (Optional) The service to use for the health check. Valid Values: ELB HCS TARGET_GROUP MLB EC2 MULTAI_TARGET_SET

  • compute.launchSpecification.healthCheckGracePeriod - Integer - (Optional) The amount of time, in seconds, after the instance has launched to starts and check its health. Default: 300 seconds

  • compute.launchSpecification.healthCheckUnhealthyDurationBeforeReplacement - Integer - (Optional) The amount of time, in seconds, an existing instance should remain active after becoming unhealthy. After the set time out the instance will be replaced

  • compute.launchSpecification.securityGroupIds - Array<string> - (Required) One or more security group IDs. In case of update it will override the existing Security Group with the new given array

  • compute.launchSpecification.monitoring - boolean - (Required) Describes whether instance Enhanced Monitoring is enabled

  • compute.launchSpecification.ebsOptimized - boolean - (Optional) Enable EBS optimization for supported instances which are not enabled by default. Note - additional charges will be applied.

  • compute.launchSpecification.imageId - string - (Required) The ID of the image used to launch the instance. The following instance types are supported by HVM image: M3, M4, C3, C4, D2, G2, R3, CC2, CC1, CG1, CR1. The following instance types are supported by PV image:M1, M2, M3, C1, C3. In case of conflict between Instance type to image type, an error message will be returned

  • compute.launchSpecification.keyPair - string - (Required) Specify a Key Pair to attach to the instances

  • compute.launchSpecification.blockDeviceMappings - Array<Object> - (Optional) Array list of block devices that are exposed to the instance, You can specify virtual devices and EBS volumes

  • compute.launchSpecification.networkInterfaces - Array<Object> - (Optional) List of network interfaces in an EC2 instance for AWS CloudFormation. If you define network interface, please pay attention to omit these properties from other sections in this Json and set it here: securityGroups - compute.launchSpecification and subnetId - compute.availabilityZones

  • compute.launchSpecification.iamRole - Object - (Optional) The instance profile iamRole

  • compute.launchSpecification.iamRole.name - string - (Optional) The iamRole name

  • compute.launchSpecification.userData - Base64 - (Optional) The Base64-encoded MIME user data to make available to the instances

  • compute.launchSpecification.shutdownScript - Base64 - (Optional) The Base64-encoded shutdown script that executet prior to instnace termination, for more information please see: shutdown script

  • compute.launchSpecification.tags.tagKey - string - (Optional) The tag’s key

  • compute.launchSpecification.tags.tagValue - string - (Optional) The tag’s value

Scaling

  • scaling.up.policyName - string - (Optional) The policy name

  • scaling.up.metricName - string - (Optional) The name of the metric. Default value is CPUUtilization

  • scaling.up.statistic - string - (Optional) The metric statistics to return. Valid Values: average , sum , sampleCount , maximum , minimum , precentile

  • scaling.up.extendedStatistic - string - (Optional) Percentile statistic. Valid values: p0.1 - p100

  • scaling.up.unit - string - (Optional) The unit for the alarm’s associated metric. Valid Values: seconds , microseconds , milliseconds , bytes , kilobytes , megabytes , gigabytes , terabytes , bits , kilobits , megabits , gigabits , terabits , percent , count , bytes/second , kilobytes/second , megabytes/second , gigabytes/second , terabytes/second , bits/second , kilobits/second , megabits/second , gigabits/second , terabits/second , count/second , none

  • scaling.up.threshold - double - (Optional) The value against which the specified statistic is compared

  • scaling.up.action - object - (Optional) The action to take when scale up is needed

  • scaling.up.action.type - string - (Optional) The type of the action to take when scale up is needed. Valid Values: adjustment , updateCapacity setMinTarget , percentageAdjustment

  • scaling.up.action.adjustment - int - (Optional) The number / percentage associated with the specified adjustment type. Required if using “adjustment” or “percentageAdjustment” as action type

  • scaling.up.action.minTargetCapacity - int - (Optional) The number with the target capacity needed. Required if using “setMinTarget” as action type

  • scaling.up.action.target - int - (Optional) The desired number of instances. Required if using “updateCapacity” as action type and neither “minimum” nor “maximum” are not defined.

  • scaling.up.action.minimum - int - (Optional) The lower limit number of instances that you can scale down to. Optional, required if using “updateCapacity” as action type and neither “target” nor “maximum” are not defined

  • scaling.up.action.maximum - int - (Optional) The upper limit number of instances that you can scale up to. Optional, required if using “updateCapacity” as action type and neither “target” nor “minimum” are not defined

  • scaling.up.namespace - string - (Optional) The namespace for the alarm’s associated metric. Default value is AWS/EC2.

  • scaling.up.dimensions - Array<Object> - (Optional) The dimensions for the alarm’s associated metric. If the user mentioned name as instanceId, there is NO value

  • scaling.up.period - int - (Optional) The period in seconds over which the statistic is applied.

  • scaling.up.evaluationPeriods - int - (Optional) The number of periods over which data is compared to the specified threshold.

  • scaling.up.cooldown - int - (Optional) The amount of time, in seconds, after a scaling activity completes before any further trigger-related scaling activities can start.

  • scaling.up.operator - string - (Optional) The operator to use in order to determine if the scaling policy is applicable. Valid values: gt gte lt lte

  • scaling.down.policyName - string - (Optional) The policy name

  • scaling.down.metricName - string - (Optional) The name of the metric. Default value is CPUUtilization

  • scaling.down.statistic - String - (Optional) The metric statistics to return. Valid Values: average sum sampleCount maximum minimum

  • scaling.down.extendedStatistic - string - (Optional) Percentile statistic. Valid values: p0.1 - p100

  • scaling.down.unit - string - (Optional) The unit for the alarm’s associated metric. Valid Values: seconds microseconds milliseconds bytes kilobytes megabytes gigabytes terabytes bits kilobits megabits gigabits terabits percent count bytes/second kilobytes/second megabytes/second gigabytes/second terabytes/second bits/second kilobits/second megabits/second gigabits/second terabits/second count/second none

  • scaling.down.adjustment - /scaling.down.maxTargetCapacity - Deprecated, use "scaling.down.action" instead.(Optional) int

  • scaling.down.action - object - (Optional) The action to take when scale down is needed.

  • scaling.down.action.type - string - (Optional) The type of the action to take when scale down is needed. Valid Values: adjustment updateCapacity setMaxTarget percentageAdjustment

  • scaling.down.action.adjustment - int - (Optional) The number / percentage associated with the specified adjustment type. Required if using “adjustment” or “percentageAdjustment” as action type.

  • scaling.down.action.maxTargetCapacity - int - (Optional) The number with the target capacity needed. Required if using “setMaxTarget” as action type.

  • scaling.down.action.target - int - (Optional) The desired number of instances. Optional, required if using “updateCapacity” as action type and neither “minimum” nor “maximum” are not defined.

  • scaling.down.action.minimum - int - (Optional) The lower limit number of instances that you can scale down to. Optional, required if using “updateCapacity” as action type and neither “target” nor “maximum” are not defined.

  • scaling.down.action.maximum - int - (Optional) The upper limit number of instances that you can scale up to. Optional, required if using “updateCapacity” as action type and neither “target” nor “minimum” are not defined.

  • scaling.down.threshold - double - (Optional) The value against which the specified statistic is compared.

  • scaling.down.namespace - string - (Optional) The namespace for the alarm’s associated metric. Default value is AWS/EC2

  • scaling.down.dimensions - Array<Object> - (Optional) The dimensions for the alarm’s associated metric. If the user mentioned name as instanceId, there is NO value

  • scaling.down.period - int - (Optional) The period in seconds over which the statistic is applied

  • scaling.down.evaluationPeriods - int - (Optional) The number of periods over which data is compared to the specified threshold

  • scaling.down.cooldown - int - (Optional) The amount of time, in seconds, after a scaling activity completes before any further trigger-related scaling activities can start

  • scaling.down.operator - string - (Optional) The operator to use in order to determine if the scaling policy is applicable. Valid values: gt gte lt lte

  • scaling.target.source - string - (Optional) The source of the metric supported values: “cloudWatch”, “spectrum”

  • scaling.target.policyName - string - (Optional) The policy name

  • scaling.target.metricName - string - (Optional) The name of the metric. Default value is CPUUtilization

  • scaling.target.statistic - String - (Optional) The metric statistics to return. Valid Values: average sum sampleCount maximum minimum

  • scaling.target.unit - string - (Optional) The unit for the alarm’s associated metric. Valid Values: seconds microseconds milliseconds bytes kilobytes megabytes gigabytes terabytes bits kilobits megabits gigabits terabits percent count bytes/second kilobytes/second megabytes/second gigabytes/second terabytes/second bits/second kilobits/second megabits/second gigabits/second terabits/second count/second none

  • scaling.target.namespace - string - (Optional) The namespace for the alarm’s associated metric. Default value is AWS/EC2

  • scaling.target.target - int - (Optional) The target value for the group

  • scaling.target.cooldown - int - (Optional) The amount of time, in seconds, after a scaling activity completes before any further trigger-related scaling activities can start

Scheduling

  • scheduling - object - (Optional) All definitions for using scheduling

  • scheduling.tasks - Array - (Optional) All scheduled tasks for this group

  • scheduling.tasks.isEnabled - boolean - (Optional) Describes whether the task is enabled. When true the task should run when false it should not run.

  • scheduling.tasks.frequency - string - (Optional) The recurrence frequency to run this task. Valid Values: hourly daily weekly. Only one of ‘frequency’ or ‘cronExpression’ should be used at a time

  • scheduling.tasks.cronExpression - String - (Optional) A valid cron expression. For example : " * * * * * ".The cron is running in UTC time zone and is in Unix cron format (http://www.unix.com/man-page/linux/5/crontab/). Only one of ‘frequency’ or ‘cronExpression’ should be used at a time.

  • scheduling.tasks.taskType - string - (Optional) The task type to run. Valid Values: backup_ami, scale, roll, statefulUpdateCapacity.

  • scheduling.tasks.scaleTargetCapacity - Integer - (Optional) The target capacity of the group. Should be used when choosing ‘taskType’ of ‘scale’.

  • scheduling.tasks.scaleMinCapacity - Integer - (Optional) The min capacity of the group. Should be used when choosing ‘taskType’ of ‘scale’.

  • scheduling.tasks.scaleMaxCapacity - Integer - (Optional) The max capacity of the group. Should be used when choosing ‘taskType’ of ‘scale’.

  • scheduling.tasks.TargetCapacity - Integer - (Optional) The target capacity of the group. Should be used when choosing ‘taskType’ of ‘statefulUpdateCapacity’.

  • scheduling.tasks.MinCapacity - Integer - (Optional) The min capacity of the group. Should be used when choosing ‘taskType’ of ‘statefulUpdateCapacity’.

  • scheduling.tasks.MaxCapacity - Integer - (Optional) The max capacity of the group. Should be used when choosing ‘taskType’ of ‘statefulUpdateCapacity’.

  • scheduling.tasks.batchSizePercentage - Integer - (Optional) The percentage size of each batch in the roll. Should be used when choosing ‘taskType’ of ‘roll’.

Third Parties Integration

  • thirdPartiesIntegration - object - (Optional) All definitions for using 3rd-party Integrations

  • thirdPartiesIntegration.rancher - object - (Optional) All definitions for using Rancher Labs integration

  • thirdPartiesIntegration.rancher.masterHost - string - (Optional) Rancher master url. for example: http://myRancher.com:8080/v1

  • thirdPartiesIntegration.rancher.accessKey - string - (Optional) Rancher API Access Key

  • thirdPartiesIntegration.rancher.secretKey - string - (Optional) Rancher API Secret Key

  • thirdPartiesIntegration.elasticBeanstalk - object - (Optional) All definitions for using Elastic Beanstalk integration

  • thirdPartiesIntegration.elasticBeanstalk.environmentId - string - (Optional) Elastic Beanstalk Environment ID.

  • thirdPartiesIntegration.elasticBeanstalk.deploymentPreferences - object - (Optional) All deployment preferences when deploying a Elastic Beanstalk version.

  • thirdPartiesIntegration.elasticBeanstalk.deploymentPreferences.automaticRoll - boolean - (Optional) Describes whether new instances will automatically replace old instances upon new Elastic Beanstalk version upload.

  • thirdPartiesIntegration.elasticBeanstalk.deploymentPreferences.batchSizePercentage - Integer - (Optional) Indicates in percentage the amount of instances should be replaced in each batch. If set to null it will be a system default.

  • thirdPartiesIntegration.elasticBeanstalk.deploymentPreferences.gracePeriod - Integer - (Optional) The amount of time, in seconds, after the instance has launched to starts and check its health. If set to null it will be a system default.

  • thirdPartiesIntegration.ecs - object - (Optional) All definitions for using Amazon EC2 Container Service integration

  • thirdPartiesIntegration.ecs.clusterName - string - (Optional) ECS cluster name

  • thirdPartiesIntegration.ecs.autoScale - object - (Optional) Settings for ECS auto-scaling

  • thirdPartiesIntegration.ecs.autoScale.isEnabled - boolean - (Optional) State of Autoscaling feature - default is false

  • thirdPartiesIntegration.ecs.autoScale.cooldown - integer - (Optional) Cooldown period in Seconds before another scaling action is triggered - default is 300

  • thirdPartiesIntegration.ecs.autoScale.down - object - (Optional) Settings for automated Scale down

  • thirdPartiesIntegration.ecs.autoScale.down.evaluationPeriods - integer - (Optional) What is the evaluation period in minutes for the automated scale down action

  • thirdPartiesIntegration.ecs.autoScale.headroom - object - (Optional) Settings for headroom spare capacity settings

  • thirdPartiesIntegration.ecs.autoScale.headroom.cpuPerUnit - integer - (Optional) CPU units spare capacity settings

  • thirdPartiesIntegration.ecs.autoScale.headroom.memoryPerUnit - integer - (Optional) Memory units spare capacity settings

  • thirdPartiesIntegration.ecs.autoScale.headroom.numOfUnits - integer - (Optional) How many units should of the configured CPU and Memory should be in the spare capacity

  • thirdPartiesIntegration.kubernetes - object - (Optional) All definitions for using Kubernetes integration

  • thirdPartiesIntegration.kubernetes.apiServer - string - (Optional) URL for Kubernetes API Server - protocol://host:port

  • thirdPartiesIntegration.kubernetes.token - string - (Optional) Kubernetes Token

  • thirdPartiesIntegration.rightScale - object - (Optional) All definitions for using RightScale integration

  • thirdPartiesIntegration.rightScale.accountId - string - (Optional) Right Scale account id

  • thirdPartiesIntegration.rightScale.refreshToken - string - (Optional) Right Scale refresh token

  • thirdPartiesIntegration.chef - object - (Optional) All definitions for using Chef integration

  • thirdPartiesIntegration.chef.chefServer - string - (Optional) Chef Server IP address or Host

  • thirdPartiesIntegration.chef.organization - string - (Optional) Chef organization name

  • thirdPartiesIntegration.chef.user - string - (Optional) Chef user name

  • thirdPartiesIntegration.chef.pemKey - string - (Optional) Chef Validator Pem Key (https://docs.chef.io/chef_private_keys.html#chef-validator)

  • thirdPartiesIntegration.chef.chefVersion - string - (Optional) Chef version

  • thirdPartiesIntegration.opsWorks - object - (Optional) All definitions for using opsWorks integration

  • thirdPartiesIntegration.opsWorks.layerId - string - (Optional) Layer ID in OpsWorks

  • thirdPartiesIntegration.opsWorks.stackType - string - (Optional) The possible values for stackType are: REGIONAL / CLASSIC. There is no default and it is a required variable for Opswork integration

  • thirdPartiesIntegration.mesosphere - object - (Optional) All definitions for using mesosphere integration

  • thirdPartiesIntegration.mesosphere.apiServer - string - (Optional) API server in mesosphere

  • thirdPartiesIntegration.mlbRuntime - object - (Optional) All definitions for using Multai Load Balancer integration

  • thirdPartiesIntegration.mlbRuntime.deploymentId - string - (Optional) The relevant Deployment ID (dp-XXXX)

  • thirdPartiesIntegration.nomad - object - (Optional) All definitions for using nomad integration

  • thirdPartiesIntegration.nomad.masterHost - string - (Optional) The Nomad master IP address ( for example “504.404.304.204”)

  • thirdPartiesIntegration.nomad.masterPort - string - (Optional) The Nomad master configured port ( for example “4455”)


Example URI

POST https://api.spotinst.io/aws/ec2/group

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "group": {
    "name": "spotinst-group",
    "description": "Development",
    "capacity": {
      "target": 2,
      "minimum": 2,
      "maximum": 10
    },
    "strategy": {
      "risk": 100,
      "availabilityVsCost": "balanced"
    },
    "scaling": {
      "up": [
        {
          "metricName": "CPUUtilization",
          "statistic": "average",
          "unit": "percent",
          "threshold": 90,
          "namespace": "AWS/EC2",
          "dimensions": [
            {
              "name": "InstanceId"
            }
          ],
          "period": 300,
          "evaluationPeriods": 1,
          "cooldown": 300,
          "action": {
            "type": "percentageAdjustment",
            "adjustment": 20
          },
          "operator": "gte"
        }
      ],
      "down": [
        {
          "metricName": "CPUUtilization",
          "statistic": "average",
          "unit": "percent",
          "threshold": 10,
          "namespace": "AWS/EC2",
          "dimensions": [
            {
              "name": "InstanceId"
            }
          ],
          "period": 300,
          "evaluationPeriods": 1,
          "cooldown": 300,
          "action": {
            "type": "updateCapacity",
            "target": 10,
            "minimum": 5,
            "maximum": 20
          },
          "operator": "lte"
        },
        {
          "metricName": "overhead",
          "statistic": "average",
          "unit": "milliseconds",
          "threshold": 0.8,
          "namespace": "Monitoring",
          "dimensions": [
            {
              "name": "Cluster",
              "value": "M2M"
            },
            {
              "name": "Environment",
              "value": "ia-staging"
            }
          ],
          "period": 300,
          "evaluationPeriods": 1,
          "cooldown": 300,
          "action": {
            "type": "adjustment",
            "adjustment": 1
          },
          "operator": "lt"
        }
      ],
      "target": [
        {
          "policyName": "target_policy_1",
          "metricName": "CPUUtilization",
          "statistic": "average",
          "source": "cloudWatch",
          "unit": "percent",
          "target": 50,
          "namespace": "AWS/EC2",
          "cooldown": 300
        }
      ]
    },
    "scheduling": {
      "tasks": [
        {
          "frequency": "hourly",
          "taskType": "backup_ami"
        },
        {
          "taskType": "roll",
          "cronExpression": "00 17 * * 3",
          "batchSizePercentage": 30
        },
        {
          "taskType": "scale",
          "cronExpression": "00 22 * * 3",
          "scaleTargetCapcity": 0,
          "scaleMinCapcity": 0,
          "scaleMaxCapcity": 3
        }
      ]
    },
    "compute": {
      "instanceTypes": {
        "ondemand": "m3.medium",
        "spot": [
          "c3.large",
          "c4.large",
          "m3.large",
          "r3.large"
        ]
      },
      "availabilityZones": [
        {
          "name": "us-east-1a",
          "subnetId": "subnet-4c1d1538"
        },
        {
          "name": "us-east-1b",
          "subnetId": "subnet-2791bb61"
        },
        {
          "name": "us-east-1d",
          "subnetId": "subnet-703a6f58"
        },
        {
          "name": "us-east-1e",
          "subnetId": "subnet-c62846fc"
        }
      ],
      "product": "Linux/UNIX",
      "elasticIps": [
        "eipalloc-9d4e16f8"
      ],
      "launchSpecification": {
        "loadBalancersConfig": {
          "loadBalancers": [
            {
              "name": "MyTargetGroup",
              "arn": "arn:aws:elasticloadbalancing:us-west-2:922761411349:targetgroup/MyTargetGroup/1fe63217f8ffcc05",
              "type": "TARGET_GROUP"
            },
            {
              "name": "MyClassicLB",
              "type": "CLASSIC"
            }
          ]
        },
        "healthCheckType": "ELB",
        "healthCheckGracePeriod": 300,
        "securityGroupIds": [
          "sg-af18c4ca"
        ],
        "monitoring": false,
        "ebsOptimized": true,
        "imageId": "ami-1ecae776",
        "keyPair": "spotinst",
        "blockDeviceMappings": [
          {
            "deviceName": "/dev/sdm",
            "ebs": {
              "deleteOnTermination": "true",
              "volumeSize": "80",
              "volumeType": "gp2"
            }
          },
          {
            "deviceName": "/dev/sda1",
            "ebs": {
              "deleteOnTermination": "true",
              "volumeSize": "24",
              "volumeType": "gp2"
            }
          }
        ],
        "userData": "IyEvYmluL2Jhc2gNCnRvdWNoIHRlc3QuZmlsZQ==",
        "tags": [
          {
            "tagKey": "allow",
            "tagValue": "allow-ssh"
          }
        ]
      }
    }
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "id": "sig-12345"
}

Update
PUT/aws/ec2/group/{GROUP_ID}

Update one or more parameters in your Elastigroup Use the Elastigroup Json in the body to update the Elastigroup. Only the specified fields will apply.


Example URI

PUT https://api.spotinst.io/aws/ec2/group/sig-12345

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup id you want to update


Request  Update capacity
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "group": {
    "capacity": {
      "target": 0,
      "minimum": 0,
      "maximum": 0
    }
  }
}

Request  Update AMI
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "group": {
    "compute": {
      "launchSpecification": {
        "imageId": "ami-1ecae776"
      }
    }
  }
}

Request  Update Security Group
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "group": {
    "compute": {
      "launchSpecification": {
        "securityGroupIds": [
          "sg-c6e031a3"
        ]
      }
    }
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

List Group
GET/aws/ec2/group/{GROUP_ID}

Describe a specific Elastigroup JSON


Example URI

GET https://api.spotinst.io/aws/ec2/group/sig-98765

Parameters

  • GROUP_ID
    string (required) Example: sig-98765

    The group ID you want to query


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "items": []
}

Delete
DELETE/aws/ec2/group/{GROUP_ID}

Delete an existing Elastigroup


Example URI

DELETE https://api.spotinst.io/aws/ec2/group/sig-98765

Parameters

  • GROUP_ID
    string (required) Example: sig-98765

    The group ID you want to delete


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Body
{
  "request": {
    "id": "4a0d5084-0b41-4255-82e5-d64a8232d7cc",
    "url": "/aws/ec2/group/sig-98765",
    "method": "DELETE",
    "time": "2015-06-28T15:52:45.772Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    }
  }
}

Status
GET/aws/ec2/group/{GROUP_ID}/status

Describes the current status of a specific Elastigroup


Example URI

GET https://api.spotinst.io/aws/ec2/group/sig-12345/status

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup id you want to get a status for


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "c090574f-2168-4a4c-b097-99be6d3d5dbc",
    "url": "/aws/ec2/group/sig-12345/status",
    "method": "GET",
    "time": "2015-06-28T15:45:36.881Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:group",
    "items": [
      {
        "createdAt": "2015-06-28T15:45:31.000Z",
        "instanceId": null,
        "spotRequestId": "sir-02b5n3tx",
        "instanceType": "r3.large",
        "availabilityZone": "us-east-1e",
        "product": "Linux/UNIX",
        "status": "pending-evaluation"
      },
      {
        "createdAt": "2015-06-28T15:45:31.000Z",
        "instanceId": "i-123abcd",
        "spotRequestId": "sir-02ef26dk",
        "instanceType": "c3.large",
        "availabilityZone": "us-east-1b",
        "product": "Linux/UNIX",
        "status": "pending-evaluation"
      }
    ],
    "count": 2
  }
}

Scale Up
PUT/aws/ec2/group/{GROUP_ID}/scale/up{?adjustment}

Add instances to your Elastigroup


Example URI

PUT https://api.spotinst.io/aws/ec2/group/sig-12345/scale/up?adjustment=1

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup id you want to query

    adjustment
    int (required) Example: 1

    The number of instances to add to the Elastigroup


Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Scale Down
PUT/aws/ec2/group/{GROUP_ID}/scale/down{?adjustment}

Remove instances from your Elastigroup

Note: Scale Advanced expression Remove instances from your Elastigroup


Example URI

PUT https://api.spotinst.io/aws/ec2/group/sig-12345/scale/down?adjustment=1

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup id you want to query

    adjustment
    int (required) Example: 1

    The number of instances to remove from the Elastigroup


Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "ff3e1e5b-91b8-42fa-8267-b988efc7f662",
    "url": "/aws/ec2/group/sig-12345/scale/down?adjustment=1",
    "method": "PUT",
    "time": "2015-06-29T13:01:55.060Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "items": [
      {
        "victimSpotRequests": [
          {
            "spotInstanceRequestId": "sir-02447qg2",
            "instanceId": "i-933esr1"
          }
        ],
        "victimInstances": [
          {
            "instanceId": "i-02447t22"
          }
        ]
      }
    ],
    "count": 1
  }
}

Detach Instance
PUT/aws/ec2/group/{GROUP_ID}/detachInstances

Detach instances from your Elastigroup


Example URI

PUT https://api.spotinst.io/aws/ec2/group/sig-12345/detachInstances

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup ID you want to detach instances from.


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "instancesToDetach": [
    "i-123456",
    "i-456798"
  ],
  "shouldTerminateInstances": true,
  "shouldDecrementTargetCapacity": false,
  "drainingTimeout": 300
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "3213e42e-455e-4901-a185-cc3eb65fac5f",
    "url": "/aws/ec2/group/sig-12345/detachInstances",
    "method": "PUT",
    "time": "2015-06-28T15:49:11.911Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:ec2:detachInstances"
  }
}

Deploy
PUT/aws/ec2/group/{GROUP_ID}/roll

Deploy your Elastigroup (triggers Blue/Green Deployment that replace the existing instances in the Elastigroup)

Body parameters:

  • batchSizePercentage - int - (required) Indicates (in percentage) the batch size of the deployment (meaning, how many instances to replace in each batch)

  • gracePeriod - int - (required) Indicates (in seconds) the timeout to wait until instance become healthy in the ELB

  • healthCheckType - string - (optional) Define a health check type. valid values: ELB, TARGET_GROUP, MULTAI_TARGET_SET, HCS, EC2, NONE (wait the entire grace period for each batch). If no value is set the roll will use the group’s auto-healing health check.

  • strategy - object - (optional) The roll strategy

  • strategy.action - string - (optional) The roll action to perform. valid values: REPLACE_SERVER, RESTART_SERVER Default action is REPLACE_SERVER


Example URI

PUT https://api.spotinst.io/aws/ec2/group/sig-12345/roll

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup ID you want to deploy


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "batchSizePercentage": 20,
  "gracePeriod": 300,
  "healthCheckType": "EC2",
  "strategy": {
    "action": "REPLACE_SERVER"
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "3213e42e-455e-4901-a185-cc3eb65fac5f",
    "url": "/aws/ec2/group/sig-12345/roll",
    "method": "PUT",
    "time": "2016-02-10T15:49:11.911Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:ec2:group:roll"
  }
}

Deploy Status
GET/aws/ec2/group/{GROUP_ID}/roll/{ROLL_ID}

Get status of a specific deployment


Example URI

GET https://api.spotinst.io/aws/ec2/group/sig-12345/roll/sbgd-9876

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup ID you want to get the deployments status for

    ROLL_ID
    string (required) Example: sbgd-9876

    The deployment id you want to query


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "57f6db69-35ba-4e58-be37-290d6df72bb5",
    "url": "/aws/ec2/group/sig-12345/roll/sbgd-dfb956b4",
    "method": "GET",
    "timestamp": "2017-02-02T00:27:01.023Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:ec2:group:roll",
    "items": [
      {
        "id": "sbgd-9876",
        "status": "finished",
        "progress": {
          "unit": "percent",
          "value": 100
        },
        "createdAt": "2017-01-31T13:54:53.000+0000",
        "updatedAt": "2017-01-31T14:26:37.000+0000"
      }
    ],
    "count": 1
  }
}

Group's Deployments Status
GET/aws/ec2/group/{GROUP_ID}/roll

Get list of all the deployments of a specific Elastigroup and their status


Example URI

GET https://api.spotinst.io/aws/ec2/group/sig-12345/roll

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup ID you want to get the deployments status for


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "d1232cde-57ce-4abe-b276-ff2924ff67e0",
    "url": "/aws/ec2/group/sig-12345/roll?limit=5",
    "method": "GET",
    "timestamp": "2017-02-02T00:28:00.690Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:ec2:group:roll",
    "items": [
      {
        "id": "sbgd-06e59445",
        "status": "stopped",
        "progress": {
          "unit": "percent",
          "value": 0
        },
        "createdAt": "2017-01-05T15:07:22.000+0000",
        "updatedAt": "2017-01-05T15:20:44.000+0000"
      },
      {
        "id": "sbgd-54bd2a73",
        "status": "finished",
        "progress": {
          "unit": "percent",
          "value": 100
        },
        "createdAt": "2017-01-09T13:50:39.000+0000",
        "updatedAt": "2017-01-09T14:22:21.000+0000"
      }
    ],
    "count": 5
  }
}

Stop Deployment
PUT/aws/ec2/group/{GROUP_ID}/roll/{ROLL_ID}

Stop an existing deployment.

Body parmaters

  • roll.status - sting - (required) set the status of the group to “STOPPED”

Example URI

PUT https://api.spotinst.io/aws/ec2/group/sig-12345/roll/sbgd-9876

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup ID you want to deploy

    ROLL_ID
    string (required) Example: sbgd-9876

    The deployment id you want to stop


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "roll": {
    "status": "STOPPED"
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "3213e42e-455e-4901-a185-cc3eb65fac5f",
    "url": "/aws/ec2/group/sig-12345/roll/sbgd-dfb956b4",
    "method": "PUT",
    "time": "2016-02-10T15:49:11.911Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:ec2:group:roll"
  }
}

Deployment Actions
POST/aws/ec2/group/{GROUP_ID}/roll/{ROLL_ID}/action

Apply a Detach action to a deployment.

Body parameters:

  • actionType - string - (required) Sets the action that will take place, Accepted values are: DETACH_OLD, DETACH_NEW

  • shouldHandleAllBatches - boolean - (optional) Indicator if the action should apply to all batches of the deployment or only the latest batch (default - false)

  • drainingTimeout - int - (optional) Indicates (in seconds) the timeout to wait until instance are detached (default - The Elastigroups draining time out)

  • shouldDecrementTargetCapacity - boolean - (optional) Decrementing the group target capacity after detaching the instances (default - true)


Example URI

POST https://api.spotinst.io/aws/ec2/group/sig-12345/roll/sbgd-9876/action

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup ID you want to deploy

    ROLL_ID
    string (required) Example: sbgd-9876

    The deployment id you want to stop


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "actionType": "DETACH_NEW",
  "shouldHandleAllBatches": "true",
  "drainingTimeout": "600",
  "shouldDecrementTargetCapacity": "true"
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "9ea37b98-32f7-48ea-8ec3-14e3f396e50e",
    "url": "/aws/ec2/group/sig-1b656b92/roll/sbgd-aafb7671/action",
    "method": "POST",
    "timestamp": "2017-04-02T11:09:40.652Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:ec2:group:roll:action",
    "items": [
      {
        "groupId": "sig-1b656b92",
        "rollId": "sbgd-aafb7671",
        "actionType": "DETACH_NEW",
        "detachedInstances": [
          "i-0b6974ad592f8d9ba"
        ]
      }
    ],
    "count": 1
  }
}

Create Instance Signal
POST/aws/ec2/instance/signal

The instance signal API is used for notifying Spotinst about the instance state, so Spotinst can act accordingly. Supported signals are: INSTANCE_READY - Whenever the this signal is sent, Spotinst will register the instance to the ELB INSTANCE_READY_TO_SHUTDOWN - Whenever the this signal is sent, Spotinst will terminate the instance after it was market for termination.

IMPORTANT: You need to define the expected signals for your Elastigroup in the group configuration.

Available Body parameters

  • instanceId - string - (required) The instance ID the signal refers to.

  • signal - string - (required) The specific signal you want to trigger. Valid Values: INSTANCE_READY, INSTANCE_READY_TO_SHUTDOWN


Example URI

POST https://api.spotinst.io/aws/ec2/instance/signal

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "instanceId": "i-123456",
  "signal": "INSTANCE_READY"
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "3213e42e-455e-4901-a185-cc3eb65fac5f",
    "url": "/aws/ec2/instance/signal",
    "method": "POST",
    "time": "2016-02-10T15:49:11.911Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    }
  }
}

Suspend Processes
POST/aws/ec2/group/{GROUP_ID}/suspension

Suspend specific process in Elastigroup

Available Body parameters

  • processes - array - (required) The list of processes to suspend. Valid values are: AUTO_SCALE,AUTO_HEALING

Example URI

POST https://api.spotinst.io/aws/ec2/group/sig-12345/suspension

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup ID you want to suspend


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "processes": [
    "AUTO_SCALE",
    "AUTO_HEALING"
  ]
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "0bb5db74-2457-4a34-b8f3-174e6bf5578e",
    "url": "/aws/ec2/group/sig-12345/suspension",
    "method": "POST",
    "timestamp": "2016-06-19T08:41:57.516Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:ec2:suspension",
    "items": [
      {
        "groupId": "sig-12345",
        "processes": [
          "AUTO_SCALE"
        ]
      }
    ],
    "count": 1
  }
}

Remove Suspended Processes
DELETE/aws/ec2/group/{GROUP_ID}/suspension

Remove active suspension from Elastigroup

Available Body parameters:

processes - array - (required) The list of processes to remove from suspension. Valid values are: AUTO_SCALE, AUTO_HEALING


Example URI

DELETE https://api.spotinst.io/aws/ec2/group/sig-12345/suspension

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup ID you want to remove the suspension from


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "processes": [
    "AUTO_SCALE"
  ]
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "da68053f-12ac-4046-b8b4-e1dea20f4c21",
    "url": "/aws/ec2/group/sig-12345/suspension",
    "method": "DELETE",
    "timestamp": "2016-06-15T15:46:44.612Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:ec2:suspension",
    "items": [],
    "count": 0
  }
}

List Suspended Processes
GET/aws/ec2/group/{GROUP_ID}/suspension

List all active Suspended processes for specific Elastigroup


Example URI

GET https://api.spotinst.io/aws/ec2/group/sig-12345/suspension

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup ID you want to list all the suspended processes


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "fa110d60-bdc0-49b2-974c-19a68ae03ec9",
    "url": "/aws/ec2/group/sig-12345/suspension",
    "method": "GET",
    "timestamp": "2016-06-15T15:40:28.917Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:ec2:suspension",
    "items": [
      {
        "groupId": "sig-12345",
        "processes": [
          "AUTO_SCALE"
        ]
      }
    ],
    "count": 1
  }
}

Lock Instances
POST/aws/ec2/instance/{INSTANCE_ID}/lock?ttlInMinutes={TTL}

The Lock Instance API is used for protecting an instance from termination due to the following processes

  • Replace Expensive instances

  • Fix group Strategy (opportunistically replace the on-demand instances with spot instances to adjust the group’s strategy)

  • Scale Down (after manual instance capacity changes, or automatically according to scaling policies)


Example URI

POST https://api.spotinst.io/aws/ec2/instance/i-123456/lock?ttlInMinutes=23

Parameters

  • INSTANCE_ID
    string (required) Example: i-123456

    The instance ID you want to protect

    TTL
    string (optional) Example: 23

    Specify a TTL (in minutes) for this lock, meaning, for how long the protection will be valid for.


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "3213e42e-455e-4901-a185-cc3eb65fac5f",
    "url": "/aws/ec2/instance/i-123456/lock",
    "method": "POST",
    "time": "2016-02-10T15:49:11.911Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    }
  }
}

Unlock Instances
POST/aws/ec2/instance/{INSTANCE_ID}/unlock

Remove the termination protection from specific instance


Example URI

POST https://api.spotinst.io/aws/ec2/instance/i-123456/unlock

Parameters

  • INSTANCE_ID
    string (required) Example: i-123456

    The instance ID you want to remove the protectection from


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "3213e42e-455e-4901-a185-cc3eb65fac5f",
    "url": "/aws/ec2/instance/i-123456/unlock",
    "method": "POST",
    "time": "2016-02-10T15:49:11.911Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    }
  }
}

Instance Standby
POST/aws/ec2/instance/{INSTANCE_ID}/standby/enter

Instance Standby enables you to put an instance in Standby state , update or troubleshoot the instance, and then return the instance to service. Instances that are on standby are still part of the Elastigroup, but they don’t get application traffic.

Whenever instance is standby state:

  • It will be de-registered from all the ELBs / ALBs in the Elastigroup

  • It won’t be affected from Scale down activities in the Elastigroup

  • The instance health won’t be checked, and it won’t be replaced

When the instance exits the Standby state:

  • The instance will be register back to all the ELBs / ALBs that are defined in the Elastigroup

  • It will be considered and affected from all the Elastigroup activities (helth checks, scaling, etc.)


Example URI

POST https://api.spotinst.io/aws/ec2/instance/i-123456/standby/enter

Parameters

  • INSTANCE_ID
    string (required) Example: i-123456

    The instance ID you want to put in standby state


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "4d7f52d7-c784-4ebf-be49-f1bd54844c0d",
    "url": "/aws/ec2/instance/i-123456/standby/enter",
    "method": "POST",
    "timestamp": "2016-11-17T19:07:00.439Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    }
  }
}

Exit Instance Standby
POST/aws/ec2/instance/{INSTANCE_ID}/standby/exit

Exit standby by mode


Example URI

POST https://api.spotinst.io/aws/ec2/instance/i-123456/standby/exit

Parameters

  • INSTANCE_ID
    string (required) Example: i-123456

    The instance ID that will exit the standby mode


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "4d7f52d7-c784-4ebf-be49-f1bd54844c0d",
    "url": "/aws/ec2/instance/i-123456/standby/exit",
    "method": "POST",
    "timestamp": "2016-11-17T19:07:00.439Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    }
  }
}

Instance Status
GET/aws/ec2/instance/{INSTANCE_ID}

Get the current instance status Possible status values: Active and Terminating


Example URI

GET https://api.spotinst.io/aws/ec2/instance/i-123456

Parameters

  • INSTANCE_ID
    string (required) Example: i-123456

    The instance ID you want to query


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "3213e42e-455e-4901-a185-cc3eb65fac5f",
    "url": "/aws/ec2/instance/i-123456",
    "method": "GET",
    "timestamp": "2016-12-18T14:06:04.866Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:ec2:instance",
    "items": [
      {
        "instanceId": "i-123456789",
        "lifeCycleState": "ACTIVE"
      }
    ],
    "count": 1
  }
}

Costs
GET/aws/ec2/group/{GROUP_ID}/costs?fromDate={fromDATE}&toDate={toDATE}

Get financial information on a specific Elastigroup


Example URI

GET https://api.spotinst.io/aws/ec2/group/sig-12345/costs?fromDate=2016-11-20&toDate=1494751821472

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup ID you want to query

    fromDATE
    string (required) Example: 2016-11-20

    (string) - data values following either a date format (yyyy-mm-dd ; 2016-11-20) or Unix Timestamp (1494751821472)

    toDATE
    string (required) Example: 1494751821472

    (string) - data values following either a date format (yyyy-mm-dd ; 2016-11-20) or Unix Timestamp (1494751821472)


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "8ce51c56-6971-4783-8e15-b92438f7a65d",
    "url": "/aws/ec2/group/sig-12345/costs",
    "method": "GET",
    "timestamp": "2015-07-06T11:44:27.963Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:group",
    "item": {
      "running": {
        "value": "6.00",
        "unit": "hours"
      },
      "savings": {
        "value": "72.8937",
        "unit": "percentage"
      },
      "costs": {
        "actual": "0.2681",
        "potential": "1.5330"
      }
    },
    "count": 1
  }
}

Group Detailed Cost
GET/aws/ec2/group/{GROUP_ID}/costs/detailed?fromDate={fromDATE}&toDate={toDATE}

Get detailed financial information on a specific Elastigroup


Example URI

GET https://api.spotinst.io/aws/ec2/group/sig-12345/costs/detailed?fromDate=2016-11-20&toDate=1494751821472

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup ID you want to query

    fromDATE
    string (required) Example: 2016-11-20

    (string) - data values following either a date format (yyyy-mm-dd ; 2016-11-20) or Unix Timestamp (1494751821472)

    toDATE
    string (required) Example: 1494751821472

    (string) - data values following either a date format (yyyy-mm-dd ; 2016-11-20) or Unix Timestamp (1494751821472)


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "14c3ab17-47ca-4081-aa55-c94955002ed8",
    "url": "/aws/ec2/group/sig-12345/costs/detailed",
    "method": "GET",
    "timestamp": "2015-07-14T15:36:41.423Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:ec2:group",
    "items": [
      {
        "groupId": "sig-12345",
        "instanceId": "i-326129e1",
        "spotInstanceRequestId": null,
        "instanceType": "m3.medium",
        "availabilityZone": "us-east-1a",
        "running": {
          "value": 4,
          "unit": "hours"
        },
        "savings": {
          "value": 0,
          "unit": "percentage"
        },
        "costs": {
          "actual": 0.268,
          "potential": 0.268
        }
      },
      {
        "groupId": "sig-d56b9e37",
        "instanceId": "i-c7793114",
        "spotInstanceRequestId": "sir-02epa938",
        "instanceType": "m3.large",
        "availabilityZone": "us-east-1a",
        "running": {
          "value": 4,
          "unit": "hours"
        },
        "savings": {
          "value": 89.3233,
          "unit": "percentage"
        },
        "costs": {
          "actual": 0.0568,
          "potential": 0.532
        }
      }
    ],
    "count": 2
  }
}

Activity Events
GET/aws/ec2/group/{GROUP_ID}/events?fromDate={START_DATE}

Get historical data on events that happened in a specific Elastigroup like update, scaling activities, creation of new instances, etc.


Example URI

GET https://api.spotinst.io/aws/ec2/group/sig-12345/events?fromDate=2016-10-01

Parameters

  • GROUP_ID
    int (required) Example: sig-12345

    The Elastigroup id you want to query

    START_DATE
    Date- ISO8601 (required) Example: 2016-10-01

    Starting date to fetch the events from


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "46642c7d-bc29-417d-8ce4-79626f00c63c",
    "url": "/aws/ec2/group/sig-12345/events?fromDate=2016-10-01",
    "method": "GET",
    "timestamp": "2016-01-21T17:12:51.451Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:ec2:group:event",
    "items": [
      {
        "groupId": "sig-12345",
        "eventType": "Update",
        "createdAt": "2016-01-21T17:10:04.000+0000",
        "subEvents": [
          {
            "type": "scaleUp",
            "newSpots": [
              {
                "spotInstanceRequestId": "sir-0294dbzt"
              },
              {
                "spotInstanceRequestId": "sir-02940b7h"
              },
              {
                "spotInstanceRequestId": "sir-028z1age"
              },
              {
                "spotInstanceRequestId": "sir-028z456e"
              },
              {
                "spotInstanceRequestId": "sir-028wg6gr"
              },
              {
                "spotInstanceRequestId": "sir-0294a9v5"
              }
            ],
            "newInstances": []
          }
        ]
      },
      {
        "groupId": "sig-12345",
        "eventType": "Scale",
        "createdAt": "2016-01-21T17:03:17.000+0000",
        "subEvents": [
          {
            "type": "scaleUp",
            "newSpots": [
              {
                "spotInstanceRequestId": "sir-02960nmw"
              }
            ],
            "newInstances": []
          }
        ]
      },
      {
        "groupId": "sig-12345",
        "eventType": "Scale",
        "createdAt": "2016-01-21T16:51:09.000+0000",
        "subEvents": [
          {
            "type": "scaleDown",
            "terminatedSpots": [
              {
                "spotInstanceRequestId": "sir-029404xk",
                "instanceId": "i-7fb4facc"
              }
            ],
            "terminatedInstances": []
          }
        ]
      },
      {
        "groupId": "sig-12345",
        "eventType": "Scale",
        "createdAt": "2016-01-21T16:40:13.000+0000",
        "subEvents": [
          {
            "type": "scaleUp",
            "newSpots": [
              {
                "spotInstanceRequestId": "sir-0291mt56"
              }
            ],
            "newInstances": []
          }
        ]
      },
      {
        "groupId": "sig-12345",
        "eventType": "Scale",
        "createdAt": "2016-01-21T15:52:18.000+0000",
        "subEvents": [
          {
            "type": "scaleDown",
            "terminatedSpots": [
              {
                "spotInstanceRequestId": "sir-028zqc5c",
                "instanceId": "i-9de8e51c"
              }
            ],
            "terminatedInstances": []
          }
        ]
      },
      {
        "groupId": "sig-12345",
        "eventType": "DetachInstances",
        "createdAt": "2016-01-21T15:48:10.000+0000",
        "subEvents": [
          {
            "type": "detachedInstance",
            "instanceId": "i-0f8533303dc4aa5d5"
          }
        ]
      },
      {
        "groupId": "sig-12345",
        "eventType": "Scale",
        "createdAt": "2016-01-21T15:41:18.000+0000",
        "subEvents": [
          {
            "type": "scaleUp",
            "newSpots": [
              {
                "spotInstanceRequestId": "sir-0294le2m"
              }
            ],
            "newInstances": []
          }
        ]
      }
    ],
    "count": 6
  }
}

Instance healthiness
GET/aws/ec2/group/{GROUP_ID}/instanceHealthiness

Get a list of instances with health status.


Example URI

GET https://api.spotinst.io/aws/ec2/group/sig-12345/instanceHealthiness

Parameters

  • GROUP_ID
    int (required) Example: sig-12345

    The Elastigroup id you want to query


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
      "request": {
            "id": "c31e4f9a-e6b0-4177-8899-6c327368b640",
        "url": "/aws/ec2/group/sig-1b656b92/instanceHealthiness",
        "method": "GET",
        "timestamp": "2017-03-26T13:13:57.762Z"
      },
      "response": {
        "status": {
          "code": 200,
          "message": "OK"
        },
        "kind": "spotinst:aws:ec2:group:instanceHealthiness",
        "items": [
          {
            "instanceId": "i-07593cd9173cd9667",
            "spotRequestId": "sir-xjag9yqp",
            "groupId": "sig-1b656b92",
            "availabilityZone": "us-west-2b",
            "lifeCycle": "SPOT",
            "healthStatus": "HEALTHY"
          }
        ],
        "count": 1
  }

Beanstalk reimport
PUT/aws/ec2/group/{GROUP_ID}/beanstalk/reimport

Re-import the beanstalk configuration


Example URI

PUT https://api.spotinst.io/aws/ec2/group/sig-12345/beanstalk/reimport

Parameters

  • GROUP_ID
    int (required) Example: sig-12345

    The Elastigroup id you want to query


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "6daf7587-3bfd-4d93-9d84-16b516f173e9",
    "url": "/aws/ec2/group/sig-123456/beanstalk/reimport",
    "method": "PUT",
    "timestamp": "2017-03-30T08:14:30.976Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:ec2:group",
    "items": [
      {
        "id": "sig-123456",
        "compute": {
          "launchSpecification": {
            "securityGroupIds": [
              "sg-b75343cf"
            ],
            "monitoring": false,
            "imageId": "ami-3c873e5c",
            "iamRole": {
              "name": "aws-elasticbeanstalk-ec2-role"
            },
            "userData": "Q29udGVudC1UeXBlOiBtdWx0aXBhcnQvbWl4ZWQ7IGJvdW5kYXJ5PSI9PT09PT09PT09PT09PT01MTg5MDY1Mzc3MjIyODk4NDA3PT0iCk1JTUUtVmVyc2lvbjogMS4wCgotLT09PT09PT09PT09PT09PTUxODkwNjUzNzcyMjI4OTg0MDc9PQpDb250ZW50LVR5cGU6IHRleHQvY2xvdWQtY29uZmlnOyBjaGFyc2V0PSJ1cy1hc2NpaSIKTUlNRS1WZXJzaW9uOiAxLjAKQ29udGV",
            "blockDeviceMappings": [
              {
                "deviceName": "/dev/xvdcz",
                "ebs": {
                  "deleteOnTermination": true,
                  "volumeSize": 12,
                  "volumeType": "gp2"
                }
              }
            ]
          }
        }
      }
    ],
    "count": 1
  }
}

Pause Stateful Instance
PUT/aws/ec2/group/{GROUP_ID}/statefulInstance/{STATEFUL_INSTANCE_ID}/pause?accountId={ACCOUNT_ID}

Pause a stateful instance


Example URI

PUT https://api.spotinst.io/aws/ec2/group/sig-12345/statefulInstance/ssi-227a0005/pause?accountId=act-12345

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup id you want to query

    STATEFUL_INSTANCE_ID
    string (required) Example: ssi-227a0005

    The stateful instance id you want to pause

    ACCOUNT_ID
    string (required) Example: act-12345

    (required) Your account id in spotinst


Request
HideShow
Headers
Content-Type: application/json
Body
Parameters  ACCOUNT_ID: act-12345 (string) - (required) The account id. 
    + Headers

        Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "2d4c44d3-a175-4876-a7bd-06141ca9b4f2",
          "url": "/aws/ec2/group/sig-8c8be13a/statefulInstance/ssi-7ccf5af5/pause?accountId=act-57765941",
          "method": "PUT",
          "timestamp": "2017-08-22T15:41:33.255Z"
  },
  "response": {
          "status": {
              "code": 200,
              "message": "OK"
          }
      }

Resume Stateful Instance
PUT/aws/ec2/group/{GROUP_ID}/statefulInstance/{STATEFUL_INSTANCE_ID}/resume?accountId={ACCOUNT_ID}

Resume a stateful instance


Example URI

PUT https://api.spotinst.io/aws/ec2/group/sig-12345/statefulInstance/ssi-227a0005/resume?accountId=act-12345

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup id you want to query

    STATEFUL_INSTANCE_ID
    string (required) Example: ssi-227a0005

    The stateful instance id you want to pause

    ACCOUNT_ID
    string (required) Example: act-12345

    (required) Your account id in spotinst


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "2d4c44d3-a175-4876-a7bd-06141ca9b4f2",
          "url": "/aws/ec2/group/sig-8c8be13a/statefulInstance/ssi-7ccf5af5/resume?accountId=act-57765941",
          "method": "PUT",
          "timestamp": "2017-08-22T15:41:33.255Z"
  },
  "response": {
          "status": {
              "code": 200,
              "message": "OK"
          }
      }

Recycle Stateful Instance
PUT/aws/ec2/group/{GROUP_ID}/statefulInstance/{STATEFUL_INSTANCE_ID}/recycle?accountId={ACCOUNT_ID}

Recycle a stateful instance - restart the instance, original instance will terminate and a new instance will spin up with the same ip and data\root volumes (according to the groups stateful strategy)


Example URI

PUT https://api.spotinst.io/aws/ec2/group/sig-12345/statefulInstance/ssi-227a0005/recycle?accountId=act-12345

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup id you want to query

    STATEFUL_INSTANCE_ID
    string (required) Example: ssi-227a0005

    The stateful instance id you want to pause

    ACCOUNT_ID
    string (required) Example: act-12345

    (required) Your account id in spotinst


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "2d4c44d3-a175-4876-a7bd-06141ca9b4f2",
          "url": "/aws/ec2/group/sig-8c8be13a/statefulInstance/ssi-7ccf5af5/recycle?accountId=act-57765941",
          "method": "PUT",
          "timestamp": "2017-08-22T15:41:33.255Z"
  },
  "response": {
          "status": {
              "code": 200,
              "message": "OK"
          }
      }

De-allocate Stateful Instance
PUT/aws/ec2/group/{GROUP_ID}/statefulInstance/{STATEFUL_INSTANCE_ID}/deallocate?accountId={ACCOUNT_ID}

De-allocate a stateful instance - delete all the resources associated with the instance (network interface,snapshots,volumes)


Example URI

PUT https://api.spotinst.io/aws/ec2/group/sig-12345/statefulInstance/ssi-227a0005/deallocate?accountId=act-12345

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup id you want to query

    STATEFUL_INSTANCE_ID
    string (required) Example: ssi-227a0005

    The stateful instance id you want to pause

    ACCOUNT_ID
    string (required) Example: act-12345

    (required) Your account id in spotinst


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "2d4c44d3-a175-4876-a7bd-06141ca9b4f2",
          "url": "/aws/ec2/group/sig-8c8be13a/statefulInstance/ssi-7ccf5af5/deallocate?accountId=act-57765941",
          "method": "PUT",
          "timestamp": "2017-08-22T15:41:33.255Z"
  },
  "response": {
          "status": {
              "code": 200,
              "message": "OK"
          }
      }

List Stateful Instances
GET/aws/ec2/group/{GROUP_ID}/statefulInstance?accountId={ACCOUNT_ID}

List all stateful instances associated with the Elastigroup


Example URI

GET https://api.spotinst.io/aws/ec2/group/sig-12345/statefulInstance?accountId=act-12345

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup id you want to query

    ACCOUNT_ID
    string (required) Example: act-12345

    (required) Your account id in spotinst


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "b36bd842-4d8d-4f30-b665-151936ed4eff",
    "url": "/aws/ec2/group/sig-8c8be13a/statefulInstance?accountId=act-57765941",
    "method": "GET",
    "timestamp": "2017-08-22T15:52:42.105Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:ec2:statefulInstance",
    "items": [
      {
        "id": "ssi-7ccf5af5",
        "instanceId": "i-07d8a71cc865ecaab",
        "privateIp": "172.31.23.191",
        "state": "ACTIVE",
        "devices": [
          {
            "deviceName": "/dev/xvda",
            "volumeId": "vol-0c9c8747b2bf9a497"
          }
        ]
      }
    ],
    "count": 1
  }
}

EMR

A Spotinst MR Scaler gives you the ability to run EMR jobs over Spot instances. MR Scaler can manage an existing cluster or create a new one. With MR Scaler, you can auto scale your cluster by defining up/down scaling policies

List All clusters
GET/aws/emr/mrScaler

Get a list of all MR Scalers and their configuration


Example URI

GET https://api.spotinst.io/aws/emr/mrScaler

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "3779ad1c-2ce6-45be-8c90-a4c7d8c6e99a",
    "url": "/aws/emr/mrScaler",
    "method": "GET",
    "timestamp": "2017-02-02T19:40:05.266Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:emr:mrScaler",
    "items": [
      {
        "id": "simrs-57a38dcc",
        "name": "spotinst-test-emr",
        "region": "us-east-1",
        "strategy": {
          "cloning": {
            "originClusterId": "j-M89YN61FKDQQ",
            "numberOfRetries": 0
          }
        },
        "compute": {
          "availabilityZones": [
            {
              "name": "us-east-1a",
              "subnetId": "subnet-54213"
            },
            {
              "name": "us-east-1c",
              "subnetId": "subnet-2345"
            },
            {
              "name": "us-east-1d",
              "subnetId": "subnet-56533"
            },
            {
              "name": "us-east-1e",
              "subnetId": "subnet-234"
            }
          ],
          "instanceGroups": {
            "masterGroup": {
              "instanceTypes": [
                "m3.2xlarge"
              ],
              "target": 1,
              "lifeCycle": "SPOT"
            },
            "coreGroup": {
              "instanceTypes": [
                "r3.2xlarge"
              ],
              "target": 5,
              "lifeCycle": "SPOT"
            },
            "taskGroup": {
              "instanceTypes": [
                "r3.4xlarge",
                "r3.2xlarge"
              ],
              "capacity": {
                "minimum": 0,
                "maximum": 20,
                "target": 0
              },
              "lifeCycle": "SPOT"
            }
          },
          "tags": null
        },
        "scaling": {
          "up": [
            {
              "policyName": "up Scaling Policy 1",
              "metricName": "YARNMemoryAvailablePercentage",
              "statistic": "average",
              "unit": "percent",
              "threshold": 20,
              "namespace": "AWS/ElasticMapReduce",
              "period": 300,
              "evaluationPeriods": 1,
              "cooldown": 900,
              "dimensions": null,
              "action": {
                "type": "adjustment",
                "adjustment": "5"
              },
              "operator": "lte"
            }
          ],
          "down": [
            {
              "policyName": "down Scaling Policy 1",
              "metricName": "YARNMemoryAvailablePercentage",
              "statistic": "average",
              "unit": "percent",
              "threshold": 10,
              "namespace": "AWS/ElasticMapReduce",
              "period": 600,
              "evaluationPeriods": 1,
              "cooldown": 900,
              "dimensions": null,
              "action": {
                "type": "adjustment",
                "adjustment": "6"
              },
              "operator": "gte"
            }
          ]
        },
        "createdAt": "2017-02-02T00:38:57.000Z",
        "updatedAt": "2017-02-02T00:38:57.000Z"
      },
      {
        "id": "simrs-5d1ddc54",
        "name": "Spotinst-Test",
        "region": "us-east-1",
        "strategy": {
          "cloning": {
            "originClusterId": "j-dfr4Adt5",
            "numberOfRetries": 0
          }
        },
        "compute": {
          "availabilityZones": [
            {
              "name": "us-east-1e",
              "subnetId": "subnet-1231"
            }
          ],
          "instanceGroups": {
            "masterGroup": {
              "instanceTypes": [
                "c3.2xlarge"
              ],
              "target": 1,
              "lifeCycle": "ON_DEMAND"
            },
            "coreGroup": {
              "instanceTypes": [
                "c3.2xlarge"
              ],
              "target": 200,
              "lifeCycle": "SPOT"
            },
            "taskGroup": {
              "instanceTypes": [
                "c3.2xlarge"
              ],
              "capacity": {
                "minimum": 1,
                "maximum": 1,
                "target": 1
              },
              "lifeCycle": "SPOT"
            }
          },
          "tags": null
        },
        "scaling": {},
        "createdAt": "2017-02-01T16:38:53.000Z",
        "updatedAt": "2017-02-01T16:38:53.000Z"
      }
    ],
    "count": 1
  }
}

Create
POST/aws/emr/mrScaler

Optional Body parameters:

  • name - string - (required) MRScaler name

  • description - string - (optional) Describe your Mr Scaler

  • region - string - (required) The region of the source cluster

Strategy

  • strategy.wrapping - object - (Required. Unless strategy.cloning strategy is specified) In wrap mode, MRScaler will manage an existing cluster and will scale up/down cluster task groups only. MRScaler will manage only instance groups that were created by Spotinst

  • strategy.wrapping.sourceClusterId - string - (required in wrap strategy only) The id of the cluster to wrap

  • strategy.cloning - object - (Required. Unless strategy.wrapping strategy is specified) In clone mode, MRScaler will create a new cluster that will be copied from the origin cluster. MRScaler will manage the entire cluster (the origin cluster will not be affected)

  • strategy.cloning.originClusterId - string - (required in clone strategy only) The id of the cluster to clone (required in clone strategy only)

  • strategy.availabilityZones - array - (Required) Information about one or more availability Zones for the cluster (required in clone strategy only)

compute

  • compute.ebsRootVolumeSize - int - (Optional) The EBS root volume size in GB

  • compute.availabilityZones.name - string - (Required) The availability zone name (required in clone strategy only)

  • compute.availabilityZones.subnetId - string - (Required) Specify EC2 \ VPC subnet id (required in clone strategy only)

  • compute.instanceGroups.masterGroup.instanceTypes - array - (Required) The types to choose from for master group (required in clone strategy only)

  • compute.instanceGroups.masterGroup.lifeCycle - string - (Required in clone strategy only) The life cycle of master group. Possible values: SPOT, ON_DEMAND

  • compute.instanceGroups.masterGroup.ebsConfiguration - object - (Optional) information about the EBS configurations that will be attached to each EC2 instance in the instance group.

  • compute.instanceGroups.masterGroup.target - int - (Required) Number of instances in the master group (always set to 1) (required in clone strategy only)

  • compute.instanceGroups.coreGroup.instanceTypes - array - (Required in clone strategy only) The types to choose from for core group

  • compute.instanceGroups.coreGroup.lifeCycle - string - (required in clone strategy only) The life cycle of core group. Possible values: SPOT, ON_DEMAND

  • compute.instanceGroups.coreGroup.target - int - (Required in clone strategy only) Number of instances in the core group

  • compute.instanceGroups.taskGroup.ebsConfiguration - object - (Optional) information about the EBS configurations that will be attached to each EC2 instance in the instance group.

  • compute.instanceGroups.taskGroup.instanceTypes - array - (Required) The types to choose from for task group

  • compute.instanceGroups.coreGroup.capacity.target - int - (Required) Number of desired instances in task groups

  • compute.instanceGroups.coreGroup.capacity.minimum - int - (Required) The lower limit of instances in task groups

  • compute.instanceGroups.coreGroup.capacity.maximum - int - (Required) The upper limit of instances in task groups

  • compute.instanceGroups.coreGroup.ebsConfiguration - object - (Optional) Information about the EBS configurations that will be attached to each EC2 instance in the instance group.

  • compute.configurations - object - (Optional) Information about the configurations file that will be used in the EMR cluster.

  • compute.configurations.file - object - (required) location and name of the configurations file that will be used in the EMR cluster.

  • compute.configurations.file.bucket - string - (required) The S3 bucket where the file is stored.

  • compute.configurations.file.key - string - (required) The key of the file.

EBS Configuration

  • ebsConfiguration.ebsOptimized - boolean - (Optional) Indicates whether an Amazon EBS volume is EBS-optimized.

  • ebsConfiguration.ebsConfigs - array - (Optional) An array of Amazon EBS volume specifications attached to a cluster instance.

  • ebsConfiguration.ebsConfigs.VolumesPerInstance - int - (Optional) Number of EBS volumes with a specific volume configuration that will be associated with every instance in the instance group (required if ebsconfigs is defined)

  • ebsConfiguration.ebsConfigs.VolumeSpecification - object - (Optional) EBS volume specifications such as volume type, IOPS, and size (GiB) that will be requested for the EBS volume attached to an EC2 instance in the cluster (required if ebsConfigs is defined).

  • ebsConfiguration.ebsConfigs.VolumeSpecification.VolumeType - string - (Optional) The volume type. Volume types supported are gp2, io1, standard (required if ebsConfigs is defined).

  • ebsConfiguration.ebsConfigs.VolumeSpecification.Iops - int - (Optional) The number of I/O operations per second (IOPS) that the volume supports.

  • ebsConfiguration.ebsConfigs.VolumeSpecification.SizeInGB - int - (Optional) The volume size, in gibibytes (GiB). This can be a number from 1 - 1024. If the volume type is EBS-optimized, the minimum value is 10 (required if ebsConfigs is defined).

Scaling

  • scaling.up.policyName - string -(Optional) The Scaling policy name

  • scaling.up.metricName - string - (Optional) The name of the metric. Default value is AppsPending.

  • scaling.up.statistic - string - (Optional) The metric statistics to return. Valid Values: average, sum, sampleCount, maximum, minimum

  • scaling.up.unit - string - (Optional) The unit for the alarm’s associated metric. Valid Values: seconds | microseconds | milliseconds | bytes | kilobytes | megabytes | gigabytes | terabytes | bits | kilobits | megabits | gigabits | terabits | percent | count | bytes/second | kilobytes/second | megabytes/second | gigabytes/second | terabytes/second | bits/second | kilobits/second | megabits/second | gigabits/second | terabits/second | count/second | none

  • scaling.up.threshold - double - (Optional) The value against which the specified statistic is compared.

  • scaling.up.action - object - (Optional) The action to take when scale up is needed.

  • scaling.up.action.type - string - (Optional) The type of the action to take when scale up is needed. Valid Values: adjustment | updateCapacity | setMinTarget

  • scaling.up.action.adjustment - int - (Optional) The number associated with the specified adjustment type. Required if using “adjustment” as action type.

  • scaling.up.action.minTargetCapacity - int - (Optional) The number with the target capacity needed. Required if using “setMinTarget” as action type.

  • scaling.up.action.target - int - (Optional) The desired number of instances. Optional, required if using “updateCapacity” as action type and neither “minimum” nor “maximum” are not defined.

  • scaling.up.action.minimum - int - (Optional) The lower limit number of instances that you can scale down to. Optional, required if using “updateCapacity” as action type and neither “target” nor “maximum” are not defined.

  • scaling.up.action.maximum - int - (Optional) The upper limit number of instances that you can scale up to. Optional, required if using “updateCapacity” as action type and neither “target” nor “minimum” are not defined.

  • scaling.up.namespace - string - (Optional) The namespace for the alarm’s associated metric. Default value is AWS/ElasticMapReduce

  • scaling.up.dimensions - array - (Optional) The dimensions for the alarm’s associated metric

  • scaling.up.period - int - (Optional) The period in seconds over which the statistic is applied.

  • scaling.up.evaluationPeriods - int - (Optional) The number of periods over which data is compared to the specified threshold.

  • scaling.up.cooldown - int - (Optional) The amount of time, in seconds, after a scaling activity completes before any further trigger-related scaling activities can start

  • scaling.up.operator - string - (Optional) The operator to use in order to determine if the scaling policy is applicable. Valid values: gt | gte | lt | lte

  • scaling.down.policyName - string - (Optional) The scaling policy name

  • scaling.down.metricName - string - (Optional) The name of the metric. Default value is AppsPending

  • scaling.down.statistic - string - (Optional) The metric statistics to return. Valid Values: average | sum | sampleCount | maximum | minimum

  • scaling.down.unit - string - The unit for the alarm’s associated metric. Valid Values: seconds | microseconds | milliseconds | bytes | kilobytes | megabytes | gigabytes | terabytes | bits | kilobits | megabits | gigabits | terabits | percent | count | bytes/second | kilobytes/second | megabytes/second | gigabytes/second | terabytes/second | bits/second | kilobits/second | megabits/second | gigabits/second | terabits/second | count/second | none

  • scaling.down.action - object - (Optional) The action to take when scale down is needed.

  • scaling.down.action.type - string - (Optional) The type of the action to take when scale down is needed. Valid Values: adjustment | updateCapacity | setMaxTarget

  • scaling.down.action.adjustment - int - (Optional) The number associated with the specified adjustment type. Required if using “adjustment” as action type.

  • scaling.down.action.maxTargetCapacity - int - (Optional) The number with the target capacity needed. Required if using “setMaxTarget” as action type.

  • scaling.down.action.target - int - (Optional) The desired number of instances. Optional, required if using “updateCapacity” as action type and neither “minimum” nor “maximum” are not defined.

  • scaling.down.action.minimum - int - (Optional) The lower limit number of instances that you can scale down to. Optional, required if using “updateCapacity” as action type and neither “target” nor “maximum” are not defined.

  • scaling.down.action.maximum - int - (Optional) The upper limit number of instances that you can scale up to. Optional, required if using “updateCapacity” as action type and neither “target” nor “minimum” are not defined.

  • scaling.down.threshold - double - (Optional) The value against which the specified statistic is compared.

  • scaling.down.namespace - string - (Optional) The namespace for the alarm’s associated metric. Default value is AWS/ElasticMapReduce

  • scaling.down.dimensions - array<object> - (Optional) The dimensions for the alarm’s associated metric

  • scaling.down.period - int - (Optional) The period in seconds over which the statistic is applied

  • scaling.down.evaluationPeriods - int - (Optional) The number of periods over which data is compared to the specified threshold

  • scaling.down.cooldown - int - (Optional) The amount of time, in seconds, after a scaling activity completes before any further trigger-related scaling activities can start

  • scaling.down.operator - string - (Optional) The operator to use in order to determine if the scaling policy is applicable. Valid values: gt | gte | lt | lte


Example URI

POST https://api.spotinst.io/aws/emr/mrScaler

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "mrScaler": {
    "name": "my MRScaler",
    "description": "Spotinst MRScaler",
    "region": "us-west-2",
    "strategy": {
      "cloning": {
        "originClusterId": "j-38EE27G2QY02I"
      }
    },
    "compute": {
      "availabilityZones": [
        {
          "name": "us-west-2a",
          "subnetId": "subnet-3b5b3601"
        },
        {
          "name": "us-west-2b",
          "subnetId": "subnet-6b5c4209"
        }
      ],
      "instanceGroups": {
        "masterGroup": {
          "instanceTypes": [
            "m3.xlarge",
            "m4.large",
            "m4.xlarge",
            "m4.2xlarge"
          ],
          "target": 1,
          "lifeCycle": "ON_DEMAND"
        },
        "coreGroup": {
          "instanceTypes": [
            "m3.xlarge",
            "m4.large",
            "m4.xlarge",
            "m4.2xlarge"
          ],
          "target": 5,
          "lifeCycle": "SPOT",
          "ebsConfiguration": {
            "ebsBlockDeviceConfigs": [
              {
                "volumeSpecification": {
                  "volumeType": "io1",
                  "sizeInGB": 8,
                  "iops": 200
                },
                "volumesPerInstance": 1
              }
            ],
            "ebsOptimized": true
          }
        },
        "taskGroup": {
          "instanceTypes": [
            "m1.medium",
            "c3.xlarge",
            "m3.xlarge"
          ],
          "capacity": {
            "minimum": 0,
            "maximum": 30,
            "target": 15
          },
          "lifeCycle": "SPOT",
          "ebsConfiguration": {
            "ebsBlockDeviceConfigs": [
              {
                "volumeSpecification": {
                  "volumeType": "gp2",
                  "sizeInGB": 8
                },
                "volumesPerInstance": 1
              },
              {
                "volumeSpecification": {
                  "volumeType": "io1",
                  "sizeInGB": 32
                },
                "volumesPerInstance": 2
              }
            ],
            "ebsOptimized": true
          }
        }
      },
      "configurations": {
        "file": {
          "bucket": "spotinst-labs",
          "key": "emr_configurations.json"
        }
      }
    },
    "scaling": {
      "up": [
        {
          "metricName": "AppsPending",
          "statistic": "average",
          "unit": "count",
          "threshold": 100,
          "actionType": "adjustment",
          "adjustment": 2,
          "namespace": "AWS/ElasticMapReduce",
          "period": 300,
          "evaluationPeriods": 1,
          "cooldown": 600,
          "dimensions": [
            {
              "name": "JobFlowId"
            }
          ],
          "operator": "gte"
        }
      ],
      "down": [
        {
          "metricName": "AppsPending",
          "statistic": "average",
          "unit": "count",
          "threshold": 10,
          "actionType": "adjustment",
          "adjustment": 2,
          "namespace": "AWS/ElasticMapReduce",
          "period": 300,
          "evaluationPeriods": 1,
          "cooldown": 600,
          "dimensions": [
            {
              "name": "JobFlowId"
            }
          ],
          "operator": "lte"
        }
      ]
    }
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "24b3159e-e2d9-49bc-bfe2-cc383febd04d",
    "url": "/aws/emr/mrScaler",
    "method": "POST",
    "timestamp": "2016-03-03T19:13:24.062Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:emr:mrScaler",
    "items": [
      {
        "id": "simrs-12345",
        "name": "my MRScaler",
        "description": "Spotinst MRScaler",
        "region": "us-west-2",
        "strategy": {
          "cloning": {
            "originClusterId": "j-38EE27G2QY02I"
          }
        },
        "compute": {
          "availabilityZones": [
            {
              "name": "us-west-2a",
              "subnetId": "subnet-3b5b3601"
            },
            {
              "name": "us-west-2b",
              "subnetId": "subnet-6b5c4209"
            }
          ],
          "instanceGroups": {
            "masterGroup": {
              "instanceTypes": [
                "m3.xlarge",
                "m4.large",
                "m4.xlarge",
                "m4.2xlarge"
              ],
              "target": 1,
              "lifeCycle": "ON_DEMAND"
            },
            "coreGroup": {
              "instanceTypes": [
                "m3.xlarge",
                "m4.large",
                "m4.xlarge",
                "m4.2xlarge"
              ],
              "target": 5,
              "lifeCycle": "SPOT"
            },
            "taskGroup": {
              "instanceTypes": [
                "m1.medium",
                "c3.xlarge",
                "m3.xlarge"
              ],
              "capacity": {
                "minimum": 0,
                "maximum": 30,
                "target": 15
              },
              "lifeCycle": "SPOT"
            }
          },
          "configurations": {
            "file": {
              "bucket": "spotinst-labs",
              "key": "emr_configurations.json"
            }
          }
        },
        "scaling": {
          "up": [
            {
              "metricName": "AppsPending",
              "statistic": "average",
              "unit": "count",
              "threshold": 100,
              "minTargetCapacity": 20,
              "namespace": "AWS/ElasticMapReduce",
              "period": 300,
              "evaluationPeriods": 1,
              "cooldown": 600,
              "dimensions": [
                {
                  "name": "JobFlowId"
                }
              ],
              "operator": "gte"
            }
          ],
          "down": [
            {
              "metricName": "AppsPending",
              "statistic": "average",
              "unit": "count",
              "threshold": 10,
              "maxTargetCapacity": 5,
              "namespace": "AWS/ElasticMapReduce",
              "period": 300,
              "evaluationPeriods": 1,
              "cooldown": 600,
              "dimensions": [
                {
                  "name": "JobFlowId"
                }
              ],
              "operator": "lte"
            }
          ]
        }
      }
    ],
    "count": 1
  }
}

Update
PUT/aws/emr/mrScaler/{MRSCALER_ID}

Update Mr Scaler


Example URI

PUT https://api.spotinst.io/aws/emr/mrScaler/simrs-12223456789

Parameters

  • MRSCALER_ID
    string (required) Example: simrs-12223456789

    The MRScaler id you want to update


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "mrScaler": {
    "compute": {
      "instanceGroups": {
        "taskGroup": {
          "capacity": {
            "target": 0,
            "minimum": 0,
            "maximum": 0
          }
        }
      }
    }
  }
}

List Cluster
GET/aws/emr/mrScaler/{MRSCALER_ID}

Get a description of a specific MR Scaler and its configuration


Example URI

GET https://api.spotinst.io/aws/emr/mrScaler/simrs-123456

Parameters

  • MRSCALER_ID
    string (required) Example: simrs-123456

    The MRScaler id you want to query


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "3779ad1c-2ce6-45be-8c90-a4c7d8c6e99a",
    "url": "/aws/emr/mrScaler/simrs-123456",
    "method": "GET",
    "timestamp": "2017-02-02T19:40:05.266Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:emr:mrScaler",
    "items": [
      {
        "id": "simrs-57a38dcc",
        "name": "spotinst-test-emr",
        "region": "us-east-1",
        "strategy": {
          "cloning": {
            "originClusterId": "j-M89YN61FKDQQ",
            "numberOfRetries": 0
          }
        },
        "compute": {
          "availabilityZones": [
            {
              "name": "us-east-1a",
              "subnetId": "subnet-54213"
            },
            {
              "name": "us-east-1c",
              "subnetId": "subnet-2345"
            },
            {
              "name": "us-east-1d",
              "subnetId": "subnet-56533"
            },
            {
              "name": "us-east-1e",
              "subnetId": "subnet-234"
            }
          ],
          "instanceGroups": {
            "masterGroup": {
              "instanceTypes": [
                "m3.2xlarge"
              ],
              "target": 1,
              "lifeCycle": "SPOT"
            },
            "coreGroup": {
              "instanceTypes": [
                "r3.2xlarge"
              ],
              "target": 5,
              "lifeCycle": "SPOT"
            },
            "taskGroup": {
              "instanceTypes": [
                "r3.4xlarge",
                "r3.2xlarge"
              ],
              "capacity": {
                "minimum": 0,
                "maximum": 20,
                "target": 0
              },
              "lifeCycle": "SPOT"
            }
          },
          "tags": null
        },
        "scaling": {
          "up": [
            {
              "policyName": "up Scaling Policy 1",
              "metricName": "YARNMemoryAvailablePercentage",
              "statistic": "average",
              "unit": "percent",
              "threshold": 20,
              "namespace": "AWS/ElasticMapReduce",
              "period": 300,
              "evaluationPeriods": 1,
              "cooldown": 900,
              "dimensions": null,
              "action": {
                "type": "adjustment",
                "adjustment": "5"
              },
              "operator": "lte"
            }
          ],
          "down": [
            {
              "policyName": "down Scaling Policy 1",
              "metricName": "YARNMemoryAvailablePercentage",
              "statistic": "average",
              "unit": "percent",
              "threshold": 10,
              "namespace": "AWS/ElasticMapReduce",
              "period": 600,
              "evaluationPeriods": 1,
              "cooldown": 900,
              "dimensions": null,
              "action": {
                "type": "adjustment",
                "adjustment": "6"
              },
              "operator": "gte"
            }
          ]
        },
        "createdAt": "2017-02-02T00:38:57.000Z",
        "updatedAt": "2017-02-02T00:38:57.000Z"
      },
      {
        "id": "simrs-5d1ddc54",
        "name": "Spotinst-Test",
        "region": "us-east-1",
        "strategy": {
          "cloning": {
            "originClusterId": "j-dfr4Adt5",
            "numberOfRetries": 0
          }
        },
        "compute": {
          "availabilityZones": [
            {
              "name": "us-east-1e",
              "subnetId": "subnet-1231"
            }
          ],
          "instanceGroups": {
            "masterGroup": {
              "instanceTypes": [
                "c3.2xlarge"
              ],
              "target": 1,
              "lifeCycle": "ON_DEMAND"
            },
            "coreGroup": {
              "instanceTypes": [
                "c3.2xlarge"
              ],
              "target": 200,
              "lifeCycle": "SPOT"
            },
            "taskGroup": {
              "instanceTypes": [
                "c3.2xlarge"
              ],
              "capacity": {
                "minimum": 1,
                "maximum": 1,
                "target": 1
              },
              "lifeCycle": "SPOT"
            }
          },
          "tags": null
        },
        "scaling": {},
        "createdAt": "2017-02-01T16:38:53.000Z",
        "updatedAt": "2017-02-01T16:38:53.000Z"
      }
    ],
    "count": 1
  }
}

Delete MR Scaler
DELETE/aws/emr/mrScaler/{MRSCALER_ID}

Delete MR Scaler


Example URI

DELETE https://api.spotinst.io/aws/emr/mrScaler/simrs-123456

Parameters

  • MRSCALER_ID
    string (required) Example: simrs-123456

    The MRScaler id you want to delete


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "4a0d5084-0b41-4255-82e5-d64a8232d7cc",
    "url": "/aws/emr/mrScaler/simrs-123456",
    "method": "DELETE",
    "time": "2015-06-28T15:52:45.772Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    }
  }
}

List Instances
GET/aws/emr/mrScaler/{MRSCALER_ID}/instance

Get a list of all instances and instances groups in the cluster


Example URI

GET https://api.spotinst.io/aws/emr/mrScaler/simrs-12223456789/instance

Parameters

  • MRSCALER_ID
    string (required) Example: simrs-12223456789

    The MRScaler id you want to get instances for


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "91f7f580-2c9d-42dc-b3c2-463514e406d7",
    "url": "/aws/emr/mrScaler/simrs-12223456789/instance",
    "method": "GET",
    "timestamp": "2015-08-02T09:11:16.356Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:emr:mrScaler:instance",
    "items": [
      {
        "instanceId": "i-asdfjk3989",
        "instanceGroupId": "ig-asdfjl2",
        "instanceGroupRole": "MASTER",
        "instanceType": "m1.medium",
        "availabilityZone": "us-east-1a",
        "status": "Running",
        "updatedAt": "2015-08-02T09:11:16.356Z"
      },
      {
        "instanceId": "i-13ft257wdas",
        "instanceGroupId": "ig-dsfjk3",
        "instanceGroupRole": "CORE",
        "instanceType": "m1.medium",
        "availabilityZone": "us-east-1a",
        "status": "Running",
        "updatedAt": "2015-08-02T09:11:16.356Z"
      },
      {
        "instanceId": "i-ajlkj209218",
        "instanceGroupId": "ig-dasdf2",
        "instanceGroupRole": "TASK",
        "instanceType": "m1.medium",
        "availabilityZone": "us-east-1a",
        "status": "Running",
        "updatedAt": "2015-08-02T09:11:16.356Z"
      }
    ],
    "count": 3
  }
}

MR Scaler Clusters
GET/aws/emr/mrScaler/{MRSCALER_ID}/cluster

Get Mr Scaler cluster list


Example URI

GET https://api.spotinst.io/aws/emr/mrScaler/simrs-12223456789/cluster

Parameters

  • MRSCALER_ID
    string (required) Example: simrs-12223456789

    The MRScaler id you want to get a cluster information for


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "91f7f580-2c9d-42dc-b3c2-12223456789",
    "url": "/aws/emr/mrScaler/simrs-12223456789/cluster",
    "method": "GET",
    "timestamp": "2015-08-02T09:11:16.356Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:emr:mrScaler:cluster",
    "items": [
      {
        "id": "j-3N7WPI3R0D1R7",
        "availabilityZone": "us-east-1a",
        "state": "terminated",
        "createdAt": "2015-08-02T09:11:16.356Z",
        "updatedAt": "2015-08-02T10:11:16.356Z"
      }
    ],
    "count": 1
  }
}

MR Scaler Costs
GET/aws/emr/mrScaler/{MRSCALER_ID}/costs?fromDate={fromDATE}&toDate={toDATE}

Get financial information on a specific cluster costs


Example URI

GET https://api.spotinst.io/aws/emr/mrScaler/simrs-12223456789/costs?fromDate=2016-11-20&toDate=1494751821472

Parameters

  • MRSCALER_ID
    string (required) Example: simrs-12223456789

    The MRScaler id you want to get costs for

    fromDATE
    string (required) Example: 2016-11-20

    (string) - data values following either a date format (yyyy-mm-dd ; 2016-11-20) or Unix Timestamp (1494751821472)

    toDATE
    string (required) Example: 1494751821472

    (string) - data values following either a date format (yyyy-mm-dd ; 2016-11-20) or Unix Timestamp (1494751821472)


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "bee3589d-2194-4724-81d2-16eaf80589d6",
    "url": "/aws/emr/mrScaler/simrs-12223456789/costs",
    "method": "GET",
    "timestamp": "2015-08-02T09:14:15.884Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:emr:mrScaler:costs",
    "items": [
      {
        "running": {
          "value": "13.00",
          "unit": "hours"
        },
        "savings": {
          "value": "86.3245",
          "unit": "percentage"
        },
        "costs": {
          "actual": "0.4729",
          "potential": "3.4580"
        }
      }
    ],
    "count": 1
  }
}

Scale Up
PUT/aws/emr/mrScaler/{MRSCALER_ID}/scale/up?adjustment={NUMBER_OF_INSTANCES}

Scale up MR Scaler instances


Example URI

PUT https://api.spotinst.io/aws/emr/mrScaler/simrs-123456789/scale/up?adjustment=3

Parameters

  • MRSCALER_ID
    string (required) Example: simrs-123456789

    The MRScaler id you want to Scale up

    NUMBER_OF_INSTANCES
    int (required) Example: 3

    Amount of instances to add to MR Scaler


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "3213e42e-455e-4901-a185-cc3eb65fac5f",
    "url": "/aws/emr/mrScaler/simrs-123456789/scale/up?adjustment=3",
    "method": "PUT",
    "time": "2015-06-28T15:49:11.911Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:emr:mrScaler:scale",
    "items": [
      {
        "modifiedInstanceGroups": [
          "ig-9870IUVXMYYW9",
          "ig-2470IUVXLJ652S"
        ],
        "newInstanceGroups": [
          "ig-0570LPWAZXBSR3"
        ]
      }
    ],
    "count": 1
  }
}

Scale Down
PUT/aws/emr/mrScaler/{MRSCALER_ID}/scale/down?adjustment={NUMBER_OF_INSTANCES}

Scale down


Example URI

PUT https://api.spotinst.io/aws/emr/mrScaler/simrs-123456789/scale/down?adjustment=1

Parameters

  • MRSCALER_ID
    string (required) Example: simrs-123456789

    The MRScaler id you want to Scale up

    NUMBER_OF_INSTANCES
    int (required) Example: 1

    Amount of instances to remove from MR Scaler


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "3213e42e-455e-4901-a185-123456789",
    "url": "/aws/emr/mrScaler/simrs-c148c3c6/scale/down?adjustment=1",
    "method": "PUT",
    "time": "2015-06-28T15:49:11.911Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:emr:mrScaler:scale",
    "items": [
      {
        "modifiedInstanceGroups": [
          "ig-9870IUVXMYYW9"
        ],
        "victimInstances": [
          "i-1234GBWAZXDSR3"
        ]
      }
    ],
    "count": 1
  }
}

Radius

Create a Radius Elastigroups

Radius integrates directly with RDS and provides a single interface to manage and create slave and read replica nodes that can run on Spot instances.

List all
GET/aws/radius

Get a list of all Radius


Example URI

GET https://api.spotinst.io/aws/radius

Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Create Radius
POST/aws/radius

Create a new Radius. Optional Body parameters:

  • name - string - (required) Radius name

  • description - string - (optional) Describe your Radius

Master

  • master - object - (Required) The master connection configurations

  • master.rdsIdentifier - string - (Required) The RDS master’s name

  • master.username - string - (Required) The username that Spotinst will use to connect with the master and slaves

  • master.password - string - (Required) The user password

Proxy

  • proxy - object - (Optional) Configuration for a proxy that Spotinst will use to connect with Radius slaves and master (in case it is in private subnet)

  • proxy.lambda - object - (Optional) Configurations for a lambda function as a proxy for Radius

  • proxy.lambda.name - string - (Optional) The lambda function name

compute

  • compute.availabilityZones - array<object> - (Required) One or more availability zones for Radius to provision the instances

  • compute.availabilityZones.name - string - (Required) The availability zone name (e.g: us-east-1a \ us-east-1b)

  • compute.availabilityZones.subnetId - array<string> - (Required) Specify a subnet ID in

  • compute.instanceTypes.onDemand - string - (Required) On-demand instance type that will be provisioned

  • compute.instanceTypes.spot - array - (Required) Spot instance type that will be provisioned. The following instance types are not supported for Spot: T2, I2, HS1

  • compute.launchSpecification.securityGroupIds - array<string> - (Required) One or more security group IDs

  • compute.launchSpecification.keyPair - string - (Required) An existing key pair name


Example URI

POST https://api.spotinst.io/aws/radius

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "radius": {
    "name": "sample-radius",
    "region": "us-west-2",
    "master": {
      "rdsIdentifier": "dummy-master",
      "username": "myUsername",
      "password": "myPassword"
    },
    "proxy": {
      "lambda": {
        "name": "radius-stack-lambda-Lambda-FTIALDC12LFJ"
      }
    },
    "compute": {
      "launchSpecifications": {
        "keyPair": "spotinst-keypair",
        "securityGroupIds": [
          "sg-1234567"
        ]
      },
      "availabilityZones": [
        {
          "name": "us-west-2c",
          "subnetIds": [
            "subnet-21b5ef79"
          ]
        }
      ],
      "instanceTypes": {
        "onDemand": "c3.large",
        "spot": [
          "c3.large",
          "c3.xlarge",
          "c3.2xlarge"
        ]
      }
    }
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "faab3520-fa30-40e8-8d17-0a6776147e11",
    "url": "/aws/radius",
    "method": "POST",
    "time": "2017-01-14T15:41:48.102Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:radius",
    "items": [
      {
        "radius": {
          "id": "spr-ai73882he",
          "name": "sample-radius",
          "region": "us-west-2",
          "master": {
            "rdsIdentifier": "dummy-master",
            "username": "myUsername",
            "password": "myPassword"
          },
          "proxy": {
            "lambda": {
              "name": "radius-stack-lambda-Lambda-FTIALDC12LFJ"
            }
          },
          "compute": {
            "launchSpecifications": {
              "keyPair": "spotinst-keypair",
              "securityGroupIds": [
                "sg-1234567"
              ]
            },
            "availabilityZones": [
              {
                "name": "us-west-2c",
                "subnetIds": [
                  "subnet-21b5ef79"
                ]
              }
            ],
            "instanceTypes": {
              "onDemand": "c3.large",
              "spot": [
                "c3.large",
                "c3.xlarge",
                "c3.2xlarge"
              ]
            }
          }
        }
      }
    ],
    "count": 1
  }
}

List specific Radius
GET/aws/radius/{RADIUS_ID}

Get a description of a specific Radius


Example URI

GET https://api.spotinst.io/aws/radius/spr-1234567

Parameters

  • RADIUS_ID
    string (required) Example: spr-1234567

    The Radius ID you want to get a description for


Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Delete Radius
DELETE/aws/radius/{RADIUS_ID}

Delete an existing Radius cluster


Example URI

DELETE https://api.spotinst.io/aws/radius/spr-1234567

Parameters

  • RADIUS_ID
    string (required) Example: spr-1234567

    The Radius ID you want to get delete


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "4a0d5084-0b41-4255-82e5-d64a8232d7cc",
    "url": "/aws/radius/spr-1234567",
    "method": "DELETE",
    "time": "2015-06-28T15:52:45.772Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    }
  }
}

Radius Signal
POST/aws/radius/{RADIUS_ID}/signal

The Radius signal API is used for notifying Spotinst about certain event. For example: after running radius init_script on a slave instance

Available Body paramaters

  • radiusInstanceId - string - (Required) The Radius instance ID identified that you want to the send a signal for Use this or ‘ec2InstanceId’

  • ec2InstanceId - string - (Required) The EC2 instance ID identified with the signal Use this or ‘radiusInstanceId’

  • signalType - string - (Required) The signal you want to apply. Valid Values: INSTANCE_READY


Example URI

POST https://api.spotinst.io/aws/radius/spr-1234567/signal

Parameters

  • RADIUS_ID
    string (required) Example: spr-1234567

    The Radius id of the instance


Request
HideShow
Headers
Authorization: Bearer ${token}
Body
{
  "radiusInstanceId": "spri-833cadb4af",
  "ec2InstanceId": "i-5e4befc5",
  "signalType": "INSTANCE_READY"
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "3213e42e-455e-4901-a185-cc3eb65fac5f",
    "url": "/aws/radius/spr-1234567/signal",
    "method": "POST",
    "time": "2016-02-10T15:49:11.911Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    }
  }
}

Radius Status
GET/aws/radius/{RADIUS_ID}/status

Get the status of a specific Radius


Example URI

GET https://api.spotinst.io/aws/radius/spr-1234567/status

Parameters

  • RADIUS_ID
    string (required) Example: spr-1234567

    The Radius id you want to sample


Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "3ac9a243-7901-4316-ba0d-330ee9bc1d1b",
    "url": "/aws/radius/spr-1234567/status",
    "method": "GET",
    "timestamp": "2017-01-25T14:04:28.225Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:radius:status",
    "items": [
      {
        "dns": {
          "name": "radius-sample.spr-c227815c.radius.multai.io.",
          "value": "rds-sample.ctzaz8wbpxxa.us-west-2.rds.amazonaws.com"
        },
        "instances": [
          {
            "createdAt": "2017-01-25T09:49:46.000Z",
            "updatedAt": "2017-01-25T12:26:10.000Z",
            "deletedAt": null,
            "id": "spri-833cadb4af",
            "rdsIdentifier": "rds-sample",
            "radiusId": "spr-c227815c",
            "availabilityZone": "us-west-2a",
            "source": "RDS",
            "endpoint": "rds-sample.ctzaz8wbpxxa.us-west-2.rds.amazonaws.com",
            "port": 3306,
            "status": "HEALTHY",
            "currentReplicationRole": "MASTER",
            "designatedReplicationRole": "MASTER",
            "dbEngine": "MYSQL",
            "dbVersion": "5.6.27"
          },
          {
            "createdAt": "2017-01-25T10:08:08.000Z",
            "updatedAt": "2017-01-25T13:38:04.000Z",
            "deletedAt": null,
            "id": "spri-dde47d1283",
            "ec2InstanceId": "i-0df84f5cc351fe80c",
            "radiusId": "spr-c227815c",
            "availabilityZone": "us-west-2c",
            "source": "EC2",
            "endpoint": "ec2-35-163-19-2.us-west-2.compute.amazonaws.com",
            "port": 3306,
            "status": "HEALTHY",
            "currentReplicationRole": "SLAVE",
            "designatedReplicationRole": "SLAVE",
            "dbEngine": "MYSQL",
            "dbVersion": "5.6.27"
          }
        ]
      }
    ],
    "count": 1
  }
}

Radius Validate
POST/aws/radius/validate

Verify that your master and proxy settings are valid

Optional Body paramaters

  • master - object - (Required) The master configurations (see Radius create)

  • proxy - object - (Required) The proxy configurations (see Radius create)

  • region - string - (Required) The master Region

  • validateTargets - array<string> - (Required) The validation you want to check. Supported values: ENGINE, PERMISSIONS, CONNECTIVITY, READ_REPLICA


Example URI

POST https://api.spotinst.io/aws/radius/validate

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "region": "us-west-2",
  "validateTargets": [
    "ENGINE",
    "PERMISSIONS",
    "CONNECTIVITY",
    "READ_REPLICA"
  ],
  "master": {
    "rdsIdentifier": "sample-master",
    "username": "myUsername",
    "password": "myPassword"
  },
  "proxy": {
    "lambda": {
      "name": "sample-stack-lambda-Lambda-FTIALDC12LFJ"
    }
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "3213e42e-455e-4901-a185-cc3eb65fac5f",
    "url": "/aws/radius/validate",
    "method": "POST",
    "time": "2016-02-10T15:49:11.911Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    }
  }
}

Radius Costs
GET/aws/radius/{RADIUS_ID}/costs

Get cost information for specific Radius


Example URI

GET https://api.spotinst.io/aws/radius/spr-1234567/costs

Parameters

  • RADIUS_ID
    string (required) Example: spr-1234567

    The Radius ID you want to get costs for


Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "0545c095-ca83-4958-8535-c363b1ae7db2",
    "url": "/aws/radius/spr-c227815c/costs",
    "method": "GET",
    "timestamp": "2017-01-25T16:44:45.602Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:aws:radius:costs",
    "items": [
      {
        "running": {
          "value": 6,
          "unit": "hours"
        },
        "savings": {
          "value": "83.8571",
          "unit": "percentage"
        },
        "costs": {
          "actual": 0.1017,
          "potential": 0.63
        }
      }
    ],
    "count": 1
  }
}
Next  Previous


Google Cloud

Elastigroups

List Groups
GET/gcp/gce/group

Describe all the Elastigroups and their full JSONs


Example URI

GET https://api.spotinst.io/gcp/gce/group

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Create
POST/gcp/gce/group

Create a GCP Elastigroup

Available Body parameters

  • name - string - (Required) Elastigroup Name

  • description - String - (Optional) Elastigroup description

Strategy

  • strategy.preemptiblePercentage - int - (Required) The percentage of Preemptible VMs that would spin up from the “capcity.target” (range: 0 - 100)

  • strategy.onDemandCount - string - (Required) Number of regular VMs to launch in the group. The rest will be Preemptible VMs. When this parameter is specified, the preemptiblePercentage parameter is being ignored.

  • strategy.drainingTimeout - Int - (Optional) The time (in seconds) the instance is allowed to run after detached from the group. This is to allow the instance time to drain all current TCP connections before terminating it

Capacity

  • capacity.target - Int - (Required) The number of VMs to launch

  • capacity.minimum - Int - (Required) The lower limit number of VMs that the group can scale down to

  • capacity.maximum - Int - (Required) The upper limit number of VMs that the group can scale up to

Compute

  • compute.instanceTypes.ondemand - String - (Required) The regular VM instance type. Available machine types

  • compute.instanceTypes.preemptible - Array<String> - (Required) The Preemptible VMs instance types. Available machine types

  • compute.availabilityZones - Array<String> - (Required) Availability Zones for the group

SCALING

  • scaling.up.policyName - String - (Optional) Scaling policy name

  • scaling.up.metricName - String - (Optional) The name of the metric. Default value is instance/cpu/utilization

  • scaling.up.statistic - String - (Optional) The metric aggregator to return. Valid values: mean, sum, min, max

  • scaling.up.threshold - Double - (Optional) The value against which the specified statistic is compared

  • scaling.up.action - Object - (Optional) The action to take when scale up is needed.

  • scaling.up.action.type - String - (Optional) The type of the action to take when scale up is needed. Valid value: adjustment

  • scaling.up.action.adjustment - Int - (Optional) The number associated with the specified adjustment type. Required if using adjustment as action type.

  • scaling.up.namespace - String - (Optional) The namespace for the associated metric. Valid value: compute

  • scaling.up.dimensions - Array<Object> - (Optional) The short labels names for filtering associated metric. For example, the metric instance/disk/read_ops_count is associated with the label compute.googleapis.com/storage_type, the short label name is storage_type

  • scaling.up.period - Int - (Optional) The period in seconds over which the statistic is applied

  • scaling.up.evaluationPeriods - Int - (Optional) The number of periods over which data is compared to the specified threshold

  • scaling.up.cooldown - Int - (Optional) The amount of time (in seconds) after a scaling activity completes before any further trigger-related scaling activities can start

  • scaling.down.policyName - String - (Optional) The policy name

  • scaling.down.metricName - String - (Optional) The name of the metric. Default value is instance/cpu/utilization.

  • scaling.down.statistic - String - (Optional) The metric aggregator to return. Valid values: mean, sum, min, max

  • scaling.down.threshold - Double - (Optional) The value against which the specified statistic is compared

  • scaling.down.action - Object - (Optional) The action to take when scale up is needed

  • scaling.down.action.type - String - (Optional) The type of the action to take when scale up is needed. Valid value: adjustment

  • scaling.down.action.adjustment - Int - (Optional) The number associated with the specified adjustment type. Required if using adjustment as action type

  • scaling.down.namespace - String - (Optional) The namespace for the associated metric. Valid Value: compute

  • scaling.down.dimensions - Array<Object> - (Optional) The short labels names for filtering associated metric. For example, the metric instance/disk/read_ops_count is associated with the label compute.googleapis.com/storage_type, the short label name is storage_type

  • scaling.down.period - Int - (Optional) The period in seconds over which the statistic is applied

  • scaling.down.evaluationPeriods - Int - (Optional) The number of periods over which data is compared to the specified threshold.

  • scaling.down.cooldown - Int - (Optional) The amount of time (in seconds) after a scaling activity completes before any further trigger-related scaling activities can start.

launch Specification

  • compute.launchSpecification.backendServices - Array<String> - (Optional) Backend Service resource list that will serve traffic for load balancing

  • compute.launchSpecification.startupScript - String - (Optional) Create and run your own startup scripts on your virtual machines to perform automated tasks every time your instance boots up.

  • compute.launchSpecification.serviceAccount - String The email of the service account in which the group instances will be launched with

  • compute.launchSpecification.disks - Array<Object> - (Required) Array of disks associated with this instance. Persistent disks must be created before you can assign them

  • compute.launchSpecification.disks.autoDelete - Boolean - (Optional) Specifies whether the disk will be auto-deleted when the instance is deleted.

  • compute.launchSpecification.disks.boot - Boolean - (Optional) Indicates that this is a boot disk. The virtual machine will use the first partition of the disk for its root filesystem

  • compute.launchSpecification.disks.deviceName - String - (Optional) Specifies a unique device name of your choice

  • compute.launchSpecification.disks.interface - String - (Optional) Specifies the disk interface to use for attaching this disk, which is either SCSI or NVME. The default is SCSI

  • compute.launchSpecification.disks.mode - String - (Optional) The mode in which to attach this disk, either READ_WRITE or READ_ONLY. If not specified, the default is to attach the disk in READ_WRITE mode

  • compute.launchSpecification.disks.source - String - (Optional) Specifies a valid partial or full URL to an existing Persistent Disk resource. This field is only applicable for persistent disks.

  • compute.launchSpecification.disks.type - String - (Optional) Specifies the type of the disk, either SCRATCH or PERSISTENT. If not specified, the default is PERSISTENT

  • compute.launchSpecification.disks.initializeParams - Object - (Optional) Specifies the parameters for a new disk that will be created alongside the new instance. Use initialization parameters to create boot disks or local SSDs attached to the new instance

  • compute.launchSpecification.disks.initializeParams.diskSizeGb - Int - (Optional) Specifies the size of the disk in base-2 GB

  • compute.launchSpecification.disks.initializeParams.diskType - String - (Optional) Specifies the disk type to use to create the instance. the default is pd-standard. Valid values: pd-ssd, local-ssd

  • compute.launchSpecification.disks.initializeParams.sourceImage - String - (Required) A source image used to create the disk. You can provide a private (custom) image, and Compute Engine will use the corresponding image from your project

  • compute.launchSpecification.networkInterfaces - Array<Object> - (Required) An array of the following objects, representing network configuration for the created instances

  • compute.launchSpecification.networkInterfaces.network - String - (Required) Network resource for this instance elastic for the created instances

  • compute.launchSpecification.networkInterfaces.accessConfigs - Array<Object> - (Optional) An array of configurations for this interface

  • compute.launchSpecification.networkInterfaces.accessConfigs.name - String - (Optional) Name of this access configuration

  • compute.launchSpecification.networkInterfaces.accessConfigs.type - String - (Optional) An array of configurations for this interface. Currently, ONE_TO_ONE_NAT is the only access config supported

  • compute.launchSpecification.tags - Array<String> - (Optional) Tags to mark instances created.

  • compute.launchSpecification.metadata - Array<Object> - (Optional) An array of the following objects, representing Key-Value pair meta data for the created instances

  • compute.launchSpecification.metadata.key - String - (Optional) The meta data’s key

  • compute.launchSpecification.metadata.value - String - (Optional) The meta data’s value


Example URI

POST https://api.spotinst.io/gcp/gce/group

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "group": {
    "name": "Spotinst GCP Group",
    "capacity": {
      "minimum": 0,
      "maximum": 0,
      "target": 0
    },
    "strategy": {
      "preemptiblePercentage": 50
    },
    "scaling": {
      "up": [
        {
          "policyName": "scale_up_1",
          "metricName": "instance/disk/read_ops_count",
          "namespace": "compute",
          "statistic": "mean",
          "threshold": 10000,
          "action": {
            "type": "adjustment",
            "adjustment": 1
          },
          "dimensions": [
            {
              "name": "storage_type",
              "value": "pd-ssd"
            }
          ],
          "period": 300,
          "evaluationPeriods": 1,
          "cooldown": 300
        }
      ]
    },
    "compute": {
      "launchSpecification": {
        "serviceAccount": "example@myProject.iam.gserviceaccount.com",
        "tags": [
          "http",
          "https"
        ],
        "backendServices": [
          "spotinst-elb-backend-service"
        ],
        "disks": [
          {
            "deviceName": "device",
            "initializeParams": {
              "diskSizeGb": 10,
              "diskType": "pd-standard",
              "sourceImage": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-7-wheezy-v20151104"
            },
            "mode": "READ_WRITE",
            "type": "PERSISTENT",
            "autoDelete": true,
            "boot": true,
            "interface": "SCSI"
          }
        ],
        "networkInterfaces": [
          {
            "network": "spot-network"
          }
        ],
        "startupScript": null
      },
      "instanceTypes": {
        "ondemand": "n1-standard-1",
        "preemptible": [
          "n1-standard-1",
          "n1-standard-2",
          "n1-standard-4"
        ]
      },
      "availabilityZones": [
        "asia-east1-c",
        "europe-west1-c",
        "us-central1-a"
      ]
    },
    "description": "Spotinst GCP Group"
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "47d61ee1-db18-4b3d-bb97-955d0a215d55",
    "url": "/gcp/gce/group",
    "method": "POST",
    "timestamp": "2016-02-14T09:15:09.381Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:gcp:gce:group",
    "items": [
      {
        "id": "sig-642b8368",
        "name": "Spotinst GCP Group",
        "description": "Spotinst GCP Group",
        "capacity": {
          "minimum": 0,
          "maximum": 0,
          "target": 0
        },
        "strategy": {
          "preemptiblePercentage": 50
        },
        "compute": {
          "launchSpecification": {
            "serviceAccount": "example@myProject.iam.gserviceaccount.com",
            "tags": [
              "http",
              "https"
            ],
            "backendServices": [
              "spotinst-elb-backend-service"
            ],
            "disks": [
              {
                "deviceName": "device",
                "initializeParams": {
                  "diskSizeGb": 10,
                  "diskType": "pd-standard",
                  "sourceImage": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-7-wheezy-v20151104"
                },
                "mode": "READ_WRITE",
                "type": "PERSISTENT",
                "autoDelete": true,
                "boot": true,
                "interface": "SCSI"
              }
            ],
            "networkInterfaces": [
              {
                "network": "spot-network"
              }
            ]
          },
          "instanceTypes": {
            "ondemand": "n1-standard-1",
            "preemptible": [
              "n1-standard-1",
              "n1-standard-2",
              "n1-standard-4"
            ]
          },
          "availabilityZones": [
            "asia-east1-c",
            "europe-west1-c",
            "us-central1-a"
          ]
        },
        "scaling": {
          "up": [
            {
              "policyName": "scale_up_1",
              "metricName": "instance/disk/read_ops_count",
              "statistic": "mean",
              "threshold": 10000,
              "namespace": "compute",
              "period": 300,
              "evaluationPeriods": 1,
              "cooldown": 300,
              "dimensions": [
                {
                  "name": "storage_type",
                  "value": "pd-standard"
                }
              ],
              "action": {
                "type": "adjustment",
                "adjustment": 1
              }
            }
          ]
        },
        "createdAt": "2016-02-14T09:15:09.000+0000",
        "updatedAt": "2016-02-14T09:15:09.000+0000"
      }
    ],
    "count": 1
  }
}

Update
PUT/gcp/gce/group/{GROUP_ID}

Update one or more parameters in your Elastigroup Use the Elastigroup Json in the body to update the Elastigroup. Only the specified fields will apply.


Example URI

PUT https://api.spotinst.io/gcp/gce/group/sig-98765

Parameters

  • GROUP_ID
    string (required) Example: sig-98765

    The group ID you want to update


Request  Update capacity
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "group": {
    "capacity": {
      "target": 0,
      "minimum": 0,
      "maximum": 0
    }
  }
}

Request  Update Availability Zones
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "group": {
    "compute": {
      "availabilityZones": [
        "asia-east1-a",
        "europe-west1-c",
        "us-central1-a"
      ]
    }
  }
}

Request  Update Security Groups
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "group": {
    "compute": {
      "instanceTypes": {
        "preemptible": [
          "n1-standard-1",
          "n1-standard-2"
        ]
      }
    }
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

List Specific
GET/gcp/gce/group/{GROUP_ID}

Describe a specific Elastigroup JSON


Example URI

GET https://api.spotinst.io/gcp/gce/group/sig-98765

Parameters

  • GROUP_ID
    string (required) Example: sig-98765

    The group ID you want to query


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Delete Group
DELETE/gcp/gce/group/{GROUP_ID}

Delete an existing Elastigroup


Example URI

DELETE https://api.spotinst.io/gcp/gce/group/sig-98765

Parameters

  • GROUP_ID
    string (required) Example: sig-98765

    The group ID you want to delete


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "4a0d5084-0b41-4255-82e5-d64a8232d7cc",
    "url": "/gcp/gce/group/<GROUP_ID>",
    "method": "DELETE",
    "time": "2015-06-28T15:52:45.772Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    }
  }
}

Scale Up
PUT/gcp/gce/group/{GROUP_ID}/scale/up?adjustment={NUMBER_OF_INSTANCES}

Add instances to the Elastigroup


Example URI

PUT https://api.spotinst.io/gcp/gce/group/sig-98765/scale/up?adjustment=1

Parameters

  • GROUP_ID
    string (required) Example: sig-98765

    The group ID you want to query

    NUMBER_OF_INSTANCES
    int (required) Example: 1

    The amount of instances to add the the group


Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "3213e42e-455e-4901-a185-cc3eb65fac5f",
    "url": "/gcp/gce/group/sig-98765/scale/up?adjustment=1",
    "method": "PUT",
    "time": "2015-06-28T15:49:11.911Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:gcp:gce:preemptible",
    "items": [
      {
        "newPreemptibles": [
          {
            "instanceName": "sin-9da52709"
          }
        ],
        "newInstances": [
          {
            "instanceName": "sin-1591c0b6"
          }
        ]
      }
    ],
    "count": 1
  }
}

Scale down
PUT/gcp/gce/group/{GROUP_ID}/scale/down?adjustment={NUMBER_OF_INSTANCES}

Remove instances from the Elastigroup


Example URI

PUT https://api.spotinst.io/gcp/gce/group/sig-98765/scale/down?adjustment=1

Parameters

  • GROUP_ID
    string (required) Example: sig-98765

    The group ID you want to query

    NUMBER_OF_INSTANCES
    int (required) Example: 1

    The amount of instances to remove from the the group


Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "ff3e1e5b-91b8-42fa-8267-b988efc7f662",
    "url": "/gcp/gce/group/sig-98765/scale/down?adjustment=1",
    "method": "PUT",
    "time": "2015-06-29T13:01:55.060Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:gcp:gce:scale",
    "items": [
      {
        "victimPreemptibles": [
          {
            "instanceName": "sin-4ecd5037",
            "zone": "asia-east1-b",
            "machineType": "N1_STANDARD_2"
          },
          {
            "instanceName": "sin-79f99d7c",
            "zone": "europe-west1-c",
            "machineType": "N1_STANDARD_1"
          },
          {
            "instanceName": "sin-5465440e",
            "zone": "asia-east1-b",
            "machineType": "N1_STANDARD_1"
          },
          {
            "instanceName": "sin-824f1d4a",
            "zone": "asia-east1-a",
            "machineType": "N1_STANDARD_2"
          },
          {
            "instanceName": "sin-cf3f148b",
            "zone": "europe-west1-c",
            "machineType": "N1_STANDARD_2"
          },
          {
            "instanceName": "sin-bba1c52e",
            "zone": "us-central1-a",
            "machineType": "N1_STANDARD_2"
          },
          {
            "instanceName": "sin-2aa2e923",
            "zone": "asia-east1-a",
            "machineType": "N1_STANDARD_1"
          }
        ],
        "victimInstances": [
          {
            "instanceName": "sin-31e0596a",
            "zone": "europe-west1-c",
            "machineType": "N1_STANDARD_1"
          },
          {
            "instanceName": "sin-2e41f26b",
            "zone": "asia-east1-a",
            "machineType": "N1_STANDARD_1"
          },
          {
            "instanceName": "sin-1f217b6b",
            "zone": "asia-east1-b",
            "machineType": "N1_STANDARD_1"
          }
        ]
      }
    ],
    "count": 1
  }
}

Detach Instances
PUT/gcp/gce/group/{GROUP_ID}/detachInstances

Detach instances from your Elastigroup

Optional Body parameters:

  • instancesToDetach - Array<String> - (Required) The names of the instances to detach from the group

  • shouldTerminateInstances - boolean - (Optional) Indicates whether to terminate the instances or not. Default - true

  • shouldDecrementTargetCapacity - boolean - (Optional) Indicates whether to terminate the instances or not. Default - true

  • shouldTerminateInstances - boolean - (Optional) Indicates whether to decrement the capacity of the group, so no new instance will be launched instead of the detached one.Default - false

  • drainingTimeout - Integer - (Optional) The draining timeout (in seconds)nbefore terminating the instance (In case the shouldTerminateInstances is on) If no draining timeout is defined, the group’s draining timeout will be used.


Example URI

PUT https://api.spotinst.io/gcp/gce/group/sig-98765/detachInstances

Parameters

  • GROUP_ID
    string (required) Example: sig-98765

    The group ID you want to detach instances from


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "instancesToDetach": [
    "sin-44c02836",
    "sin-ddf71dfa"
  ],
  "shouldTerminateInstances": true,
  "shouldDecrementTargetCapacity": false,
  "drainingTimeout": 300
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "instancesToDetach": ["sin-44c02836", "sin-ddf71dfa"],
    "shouldTerminateInstances" : true,
    "shouldDecrementTargetCapacity" : false,
    "drainingTimeout" : 300
}
{
  "request": {
    "id": "3213e42e-455e-4901-a185-cc3eb65fac5f",
    "url": "/gcp/gce/group/sig-98765/detachInstances",
    "method": "PUT",
    "time": "2015-06-28T15:49:11.911Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:gcp:gce:detachInstances",
  }
}
Next  Previous


Microsoft Azure

Azure scheduler help you reduce your spendings by automatically stopping and resuming VMS at pre-defined time using tasks. Each task has policies which define an action to take at a desired time (using Chrne experssion) You can associate each of your virtual machines to multiple policies and each policy to multiple virtual machines.

Tasks

List All
GET/azure/compute/task

List all tasks and their information


Example URI

GET https://api.spotinst.io/azure/compute/task

Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Create
POST/azure/compute/task

Create a scheduling task

Available Body parameters

  • name - string - (Required) Task Name

  • description - string - (Optional) Desribe your scheudling task

  • policies - array - (Optional) The task policies

  • policies.cron - string - (Required) he time (in UTC) in which the policy action will be executed. For example: 00 20 * * SAT = every Saturday at 20:00 UTC

  • policies.action - string - (Required) The action to take on the task instances on the specified time. Valid values: STOP START

  • instances - array - (Optional) The instances to apply the policies on

  • instances.vmName - string - (Optional) he name of the virtual machine

  • instances.resourceGroupName - string - (Optional) The virtual machine’s resource group name


Example URI

POST https://api.spotinst.io/azure/compute/task

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "name": "My first task",
  "description": "My first task",
  "state": "ENABLED",
  "policies": [
    {
      "cron": "00 20 * * FRI",
      "action": "STOP"
    },
    {
      "cron": "00 08 * * MON",
      "action": "START"
    }
  ],
  "instances": [
    {
      "vmName": "MyVm1",
      "resourceGroupName": "MyGroup1"
    },
    {
      "vmName": "MyVm2",
      "resourceGroupName": "MyGroup2"
    }
  ]
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "faab3520-fa30-40e8-8d17-0a6776147e11",
    "url": "/azure/compute/task",
    "method": "POST",
    "time": "2016-08-28T15:41:48.102Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:azure:compute:task",
    "items": [
      {
        "id": "sat-3f174165",
        "name": "My first task",
        "description": "My first task",
        "state": "ENABLED",
        "policies": [
          {
            "cron": "00 20 * * FRI",
            "action": "STOP"
          },
          {
            "cron": "00 08 * * MON",
            "action": "START"
          }
        ],
        "instances": [
          {
            "vmName": "MyVm1",
            "resourceGroupName": "MyGroup1"
          },
          {
            "vmName": "MyVm2",
            "resourceGroupName": "MyGroup2"
          }
        ],
        "createdAt": "2016-08-28T15:41:48.102Z",
        "updatedAt": "2016-08-28T15:41:48.102Z",
        "deletedAt": null
      }
    ]
  }
}

Update
PUT/azure/compute/task/{TASK_ID}

Update existing Task


Example URI

PUT https://api.spotinst.io/azure/compute/task/sat-65432

Parameters

  • TASK_ID
    string (required) Example: sat-65432

    The task id you want to update


Request  Update instances
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "instances": [
    {
      "vmName": "MyVm1",
      "resourceGroupName": "MyGroup1"
    },
    {
      "vmName": "MyVm2",
      "resourceGroupName": "MyGroup2"
    }
  ]
}

Request  Update State
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "state": "ENABLED"
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

List Task
GET/azure/compute/task/{TASK_ID}

List all tasks and their information


Example URI

GET https://api.spotinst.io/azure/compute/task/sat-65432

Parameters

  • TASK_ID
    string (required) Example: sat-65432

    The task id you want to query


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Delete
DELETE/azure/compute/task/{TASK_ID}

Delete an existing scheduling task


Example URI

DELETE https://api.spotinst.io/azure/compute/task/sat-65432

Parameters

  • TASK_ID
    string (required) Example: sat-65432

    The task id you want to delete


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "4a0d5084-0b41-4255-82e5-d64a8232d7cc",
    "url": "/azure/compute/task/sat-65432",
    "method": "DELETE",
    "time": "2015-06-28T15:52:45.772Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    }
  }
}

Elastigroups

List All
GET/compute/azure/group

Describe all the Elastigroups and their full JSONs


Example URI

GET https://api.spotinst.io/compute/azure/group

Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  items: []
}

Create
POST/compute/azure/group

Create a new Elastigroup cluster

Available Body parameters

  • name - string - (required) Elastigroup name

Capacity

  • capacity.target - int - (Required) The number of nodes to launch

  • capacity.minimum - int - (Required) The lower limit number of nodes that you can scale down to

  • capacity.maximum - int - (Required) The upper limit number of nodes that you can scale up to

Strategy

  • strategy.lowPriorityPercentage - int - (Required if dedicatedCount is not specified) The percentage of Low Priority nodes to launch (range: 0 - 100).

  • strategy.dedicatedCount - int - (Required if risk is not specified) Number of dedicated nodes to launch in the group. All other nodes will be low priority nodes. When this parameter is set the “lowPriorityPercentage” parameter is being ignored.

  • strategy.drainingTimeout - int - (Optional) The time in seconds to allow the node be drained from incoming TCP connections and detached from MLB before terminating it, during a scale down operation

  • strategy.signals - Array - (Optional) The signals defined for this group

  • strategy.signals.name - string - (Optional) The name of the signal defined for the group.Valid Values: NODE_READY

  • strategy.signals.timeout - int - (Optional) The timeout of the signal, if the timeout is passes its equal to recieve a node signal. Min = 60 (seconds)

Compute

  • compute.product - string - (Required) Operation system type. Possible values: Linux, Windows

  • compute.region - string - (Required) The region of the Elastigroup. Possible values: westus, westus, centraleurope

  • compute.resourceGroupName - string - (Required) The resource group that the nodes of the group will be attached to. The resource group must be in the same region as the Elastgroup.

VM Sizes

  • compute.vmSizes.dedicatedSizes - string - (Required) Available VM sizes for dedicated nodes

  • compute.vmSizes.lowPrioritySizes - Array - (Required) Available VM sizes for low priority nodes

Launch Specification

  • compute.launchSpecification.loadBalancersConfig - Object - (Optional) Multai Load Balancers configurations.

  • compute.launchSpecification.loadBalancersConfig.loadBalancers - Array<Object> - (Optional) List of multai load balancers.

  • compute.launchSpecification.loadBalancersConfig.loadBalancers.targetSetId - String - (Optional) The target set ID of the multai load balancer.

  • compute.launchSpecification.loadBalancersConfig.loadBalancers.balancerId - String - (Optional) The balancer ID of the multai load balancer.

  • compute.launchSpecification.health - Object - (Optional) Health configuration of the Elastigroup.

  • compute.launchSpecification.health.healthCheckType - String - (Optional) The service to use for the health check. Valid Values: MLB nodeState

  • compute.launchSpecification.health.gracePeriod - Integer - (Optional) The amount of time, in seconds, after the instance has launched to starts and check its health. Default: 300 seconds

  • compute.launchSpecification.health.autoHealing - Boolean - (Optional) Should Auto Healing be on or off, if set to true: unhealthy nodes will be replaced with new ones.

  • compute.launchSpecification.image - Object - (Required) Health configuration of the Elastigroup.

  • compute.launchSpecification.image.publisher - String - (Required) The publisher of the image. Possible Values: Microsoft, Canonical

  • compute.launchSpecification.image.offer - String - (Required) The offer of the image which belongs to the publisher. Possible Values: Windows Server, Ubuntu

  • compute.launchSpecification.image.sku - String - (Required) The sku of the image, must be according to the publisher and the offer. Possible Values: 2012R2, 16.04

  • compute.launchSpecification.image.sku - String - (Required) The sku of the image, must be according to the publisher and the offer. Possible Values: 2012R2, 16.04

  • compute.launchSpecification.image.customImage - Object - (Optional) Custom image object, must be according to the publisher and the offer.

  • compute.launchSpecification.image.customImage.imageUris - Array<String> - (Required) The URI’s the VHD’s of the custom image. Can be found under the OS Disk in Azures VM.

  • compute.launchSpecification.userData - Object - (Optional) Custom data which the nodes will start with.

  • compute.launchSpecification.userData.commandLine - string - (Optional) A simple bash command line for linux systems. Optinal value: echo 5 > txt

  • compute.launchSpecification.resourceFiles - Array<Object> - (Optional) List of files which will be copied and execute during launch.

  • compute.launchSpecification.userData.resourceFiles.resourceFileUrl - string - (Required) The source file which will be copied to the node. Must be in a blob of a storage account in the same subscription of the Elastgroup.

  • compute.launchSpecification.userData.resourceFiles.resourceFileTargetPath - string - (Required) The destination path which the file will be copied to in the node os. Possible value: /etc/test

  • compute.launchSpecification.network - Object - (Optional) The network configuration of the nodes in the elastigroup.

  • compute.launchSpecification.network.virtualNetworkName - string - (Required) The name of the virtual network which the nodes will be associated to. the VNET must be in the same subscription and regioin as the Elastigroup.

  • compute.launchSpecification.network.subnetId - string - (Required) The subnet ID of the VNET which the nodes will use.

  • compute.launchSpecification.sshPublicKey - string - (Required) The public key which will be configured to access via SSH.

Scaling

  • scaling.up.policyName - string - (Optional) The policy name

  • scaling.up.metricName - string - (Optional) The name of the metric. Default value is CPUUtilization

  • scaling.up.statistic - string - (Optional) The metric statistics to return. Valid Values: average , sum , sampleCount , maximum , minimum , precentile

  • scaling.up.extendedStatistic - string - (Optional) Percentile statistic. Valid values: p0.1 - p100

  • scaling.up.unit - string - (Optional) The unit for the alarm’s associated metric. Valid Values: seconds , microseconds , milliseconds , bytes , kilobytes , megabytes , gigabytes , terabytes , bits , kilobits , megabits , gigabits , terabits , percent , count , bytes/second , kilobytes/second , megabytes/second , gigabytes/second , terabytes/second , bits/second , kilobits/second , megabits/second , gigabits/second , terabits/second , count/second , none

  • scaling.up.threshold - double - (Optional) The value against which the specified statistic is compared

  • scaling.up.action - object - (Optional) The action to take when scale up is needed

  • scaling.up.action.type - string - (Optional) The type of the action to take when scale up is needed. Valid Values: adjustment , updateCapacity setMinTarget , percentageAdjustment

  • scaling.up.action.adjustment - int - (Optional) The number / percentage associated with the specified adjustment type. Required if using “adjustment” or “percentageAdjustment” as action type

  • scaling.up.action.minTargetCapacity - int - (Optional) The number with the target capacity needed. Required if using “setMinTarget” as action type

  • scaling.up.action.target - int - (Optional) The desired number of nodes. Required if using “updateCapacity” as action type and neither “minimum” nor “maximum” are not defined.

  • scaling.up.action.minimum - int - (Optional) The lower limit number of nodes that you can scale down to. Optional, required if using “updateCapacity” as action type and neither “target” nor “maximum” are not defined

  • scaling.up.action.maximum - int - (Optional) The upper limit number of nodes that you can scale up to. Optional, required if using “updateCapacity” as action type and neither “target” nor “minimum” are not defined

  • scaling.up.namespace - string - (Optional) The namespace for the alarm’s associated metric. Default value is AWS/EC2.

  • scaling.up.dimensions - Array<Object> - (Optional) The dimensions for the alarm’s associated metric. If the user mentioned name as nodeId, there is NO value

  • scaling.up.period - int - (Optional) The period in seconds over which the statistic is applied.

  • scaling.up.evaluationPeriods - int - (Optional) The number of periods over which data is compared to the specified threshold.

  • scaling.up.cooldown - int - (Optional) The amount of time, in seconds, after a scaling activity completes before any further trigger-related scaling activities can start.

  • scaling.up.operator - string - (Optional) The operator to use in order to determine if the scaling policy is applicable. Valid values: gt gte lt lte

  • scaling.down.policyName - string - (Optional) The policy name

  • scaling.down.metricName - string - (Optional) The name of the metric. Default value is CPUUtilization

  • scaling.down.statistic - String - (Optional) The metric statistics to return. Valid Values: average sum sampleCount maximum minimum

  • scaling.down.extendedStatistic - string - (Optional) Percentile statistic. Valid values: p0.1 - p100

  • scaling.down.unit - string - (Optional) The unit for the alarm’s associated metric. Valid Values: seconds microseconds milliseconds bytes kilobytes megabytes gigabytes terabytes bits kilobits megabits gigabits terabits percent count bytes/second kilobytes/second megabytes/second gigabytes/second terabytes/second bits/second kilobits/second megabits/second gigabits/second terabits/second count/second none

  • scaling.down.adjustment - /scaling.down.maxTargetCapacity - (Optional) int Deprecated, use “scaling.down.action” instead.

  • scaling.down.action - object - (Optional) The action to take when scale down is needed.

  • scaling.down.action.type - string - (Optional) The type of the action to take when scale down is needed. Valid Values: adjustment updateCapacity setMaxTarget percentageAdjustment

  • scaling.down.action.adjustment - int - (Optional) The number / percentage associated with the specified adjustment type. Required if using “adjustment” or “percentageAdjustment” as action type.

  • scaling.down.action.maxTargetCapacity - int - (Optional) The number with the target capacity needed. Required if using “setMaxTarget” as action type.

  • scaling.down.action.target - int - (Optional) The desired number of instances. Optional, required if using “updateCapacity” as action type and neither “minimum” nor “maximum” are not defined.

  • scaling.down.action.minimum - int - (Optional) The lower limit number of instances that you can scale down to. Optional, required if using “updateCapacity” as action type and neither “target” nor “maximum” are not defined.

  • scaling.down.action.maximum - int - (Optional) The upper limit number of instances that you can scale up to. Optional, required if using “updateCapacity” as action type and neither “target” nor “minimum” are not defined.

  • scaling.down.threshold - double - (Optional) The value against which the specified statistic is compared.

  • scaling.down.namespace - string - (Optional) The namespace for the alarm’s associated metric. Default value is AWS/EC2

  • scaling.down.dimensions - Array<Object> - (Optional) The dimensions for the alarm’s associated metric. If the user mentioned name as instanceId, there is NO value

  • scaling.down.period - int - (Optional) The period in seconds over which the statistic is applied

  • scaling.down.evaluationPeriods - int - (Optional) The number of periods over which data is compared to the specified threshold

  • scaling.down.cooldown - int - (Optional) The amount of time, in seconds, after a scaling activity completes before any further trigger-related scaling activities can start

  • scaling.down.operator - string - (Optional) The operator to use in order to determine if the scaling policy is applicable. Valid values: gt gte lt lte

Scheduling

  • scheduling - object - (Optional) All definitions for using scheduling

  • scheduling.tasks - Array - (Optional) All scheduled tasks for this group

  • scheduling.tasks.isEnabled - boolean - (Optional) Describes whether the task is enabled. When true the task should run when false it should not run.

  • scheduling.tasks.frequency - string - (Optional) The recurrence frequency to run this task. Valid Values: hourly daily weekly. Only one of ‘frequency’ or ‘cronExpression’ should be used at a time

  • scheduling.tasks.cronExpression - String - (Optional) A valid cron expression. For example : " * * * * * ".The cron is running in UTC time zone and is in Unix cron format (http://www.unix.com/man-page/linux/5/crontab/). Only one of ‘frequency’ or ‘cronExpression’ should be used at a time.

  • scheduling.tasks.taskType - string - (Optional) The task type to run. Valid Values: backup_ami scale roll

  • scheduling.tasks.scaleTargetCapcity - Integer - (Optional) The target capacity of the group. Should be used when choosing ‘taskType’ of ‘scale’.

  • scheduling.tasks.scaleMinCapcity - Integer - (Optional) The min capacity of the group. Should be used when choosing ‘taskType’ of ‘scale’.

  • scheduling.tasks.scaleMaxCapcity - Integer - (Optional) The max capacity of the group. Should be used when choosing ‘taskType’ of ‘scale’.

  • scheduling.tasks.batchSizePercentage - Integer - (Optional) The percentage size of each batch in the roll. Should be used when choosing ‘taskType’ of ‘roll’.

Third Parties Integration

  • thirdPartiesIntegration - object - (Optional) All definitions for using 3rd-party Integrations

  • thirdPartiesIntegration.rancher - object - (Optional) All definitions for using Rancher Labs integration

  • thirdPartiesIntegration.rancher.masterHost - string - (Optional) Rancher master url. for example: http://myRancher.com:8080/v1

  • thirdPartiesIntegration.rancher.accessKey - string - (Optional) Rancher API Access Key

  • thirdPartiesIntegration.rancher.secretKey - string - (Optional) Rancher API Secret Key


Example URI

POST https://api.spotinst.io/compute/azure/group

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "group": {
    "name": "spotinst-group",
    "capacity": {
      "target": 2,
      "minimum": 2,
      "maximum": 10
    },
    "strategy": {
      "lowPriorityPercentage": 100,
      "drainingTimeout": 5,
  "signals":
  [
   {
    "name": "NODE_READY",
    "timeout" 100
   }
  ]
        },
        "scaling": {
          "up": [
            {
              "namespace": "AZURE/NODE",
              "metricName": "CPUUtilization",
              "statistic": "average",
              "unit": "percent",
              "threshold": 90,
              "dimensions": [
                {
                  "name": "nodeId"
                  "value" : 1
                }
              ],
              "period": 300,
              "evaluationPeriods": 1,
              "cooldown": 300,
              "action": {
                "type": "percentageAdjustment",
                "adjustment": 20,
                "minTargetCapacity": 2,
                "target": 5,
                "minimum": 5,
                "maximum": 5
              },
              "operator": "minTargetCapacity"
            }
          ],
          "down": [
            {
              "namespace": "AZURE/NODE",
              "metricName": "CPUUtilization",
              "statistic": "average",
              "unit": "percent",
              "threshold": 90,
              "dimensions": [
                {
                  "name": "nodeId"
                  "value" : 1
                }
              ],
              "period": 300,
              "evaluationPeriods": 1,
              "cooldown": 300,
              "action": {
                "type": "percentageAdjustment",
                "adjustment": 20,
                "minTargetCapacity": 2,
                "target": 5,
                "minimum": 5,
                "maximum": 5
              },
              "operator": "minTargetCapacity"
            }
          ]
        },
        "scheduling": {
          "tasks": [
            {
              "frequency": "hourly",
              "taskType": "scale"
            },
            {
              "taskType": "roll",
              "cronExpression": "00 17 * * 3",
              "batchSizePercentage": 30
            },
            {
              "taskType": "scale",
              "cronExpression": "00 22 * * 3",
              "scaleTargetCapcity": 0,
              "scaleMinCapcity": 0,
              "scaleMaxCapcity": 3
            }
          ]
        },
        "compute": {
          "vmSizes": {
          "dedicatedSizes": [
              "Standard_A1",
              "Standard_A2"
            ],
            "lowPrioritySizes": [
             "Standard_A1",
              "Standard_A2"
            ]
          },
          "region": "westus",
          "product": "Linux",
          "resourceGroupName": "name",
          "launchSpecification": {
            "loadBalancersConfig": {
              "loadBalancers": [
                {
                  "targetSetId": "MLB target set Id",
                  "balancerId": "MLB balancer Id"
                }
              ]
            },
            "health":{
                "healthCheckType": "MLB",
                "autoHealing": true,
                "gracePeriod": 5
            }
         "image": : {
        "publisher": "Canonical",
        "offer": "Ubuntu Server",
        "sku": "16.04",
            "customImage": {
                    imageUris: [
                    "vhd_uri"
                    ]                    
            }
        },
        "userData": {
        "commandLine: "echo 5"
        "resourceFiles: [
            {
                "resourceFileUrl": "url",
                "resourceFileTargetPath": "targetPath"
            }
        ]
        },
        "network": {
            "virtualNetworkName": "vname",
            "subnetId": "id"
        },
        "sshPublicKey": "IyEvYmluL2Jhc2gNCnRvdWNoIHRlc3QuZmlsZQ=="
      }
    }
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },

{
  "group": {
    "id": "sig-12345"
    "name": "spotinst-group",
    "capacity": {
      "target": 2,
      "minimum": 2,
      "maximum": 10
    },
    "strategy": {
      "lowPriorityPercentage": 100,
      "drainingTimeout": 5
    },
    "scaling": {
      "up": [
        {
          "namespace": "AZURE/NODE",
          "metricName": "CPUUtilization",
          "statistic": "average",
          "unit": "percent",
          "threshold": 90,
          "dimensions": [
            {
              "name": "nodeId"
              "value" : 1
            }
          ],
          "period": 300,
          "evaluationPeriods": 1,
          "cooldown": 300,
          "action": {
            "type": "percentageAdjustment",
            "adjustment": 20,
            "minTargetCapacity": 2,
            "target": 5,
            "minimum": 5,
            "maximum": 5
          },
          "operator": "minTargetCapacity"
        }
      ],
      "down": [
        {
          "namespace": "AZURE/NODE",
          "metricName": "CPUUtilization",
          "statistic": "average",
          "unit": "percent",
          "threshold": 90,
          "dimensions": [
            {
              "name": "nodeId"
              "value" : 1
            }
          ],
          "period": 300,
          "evaluationPeriods": 1,
          "cooldown": 300,
          "action": {
            "type": "percentageAdjustment",
            "adjustment": 20,
            "minTargetCapacity": 2,
            "target": 5,
            "minimum": 5,
            "maximum": 5
          },
          "operator": "minTargetCapacity"
        }
      ]
    },
    "scheduling": {
      "tasks": [
        {
          "frequency": "hourly",
          "taskType": "scale"
        },
        {
          "taskType": "roll",
          "cronExpression": "00 17 * * 3",
          "batchSizePercentage": 30
        },
        {
          "taskType": "scale",
          "cronExpression": "00 22 * * 3",
          "scaleTargetCapcity": 0,
          "scaleMinCapcity": 0,
          "scaleMaxCapcity": 3
        }
      ]
    },
    "compute": {
      "vmSizes": {
      "dedicatedSizes": [
          "Standard_A1",
          "Standard_A2"
        ],
        "lowPrioritySizes": [
         "Standard_A1",
          "Standard_A2"
        ]
      },
      "region": "westus",
      "product": "Linux",
      "resourceGroupName": "name",
      "launchSpecification": {
        "loadBalancersConfig": {
          "loadBalancers": [
            {
              "targetSetId": "MLB target set Id",
              "balancerId": "MLB balancer Id"
            }
          ]
        },
        "health":{
            "healthCheckType": "MLB",
            "autoHealing": true,
            "gracePeriod": 5
        }

        "image": : {
        "publisher": "Canonical",
        "offer": "Ubuntu Server",
        "sku": "16.04",
            "customImage": {
                    imageUris: [
                    "vhd_uri"
                    ]                    
            }
        },
        "userData": {
        "commandLine: "echo 5"
        "resourceFiles: [
            {
                "resourceFileUrl": "url",
                "resourceFileTargetPath": "targetPath"
            }
        ]
        },
        "network": {
            "virtualNetworkName": "vname",
            "subnetId": "id"
        },
        "sshPublicKey": "IyEvYmluL2Jhc2gNCnRvdWNoIHRlc3QuZmlsZQ=="
      }
    }
  }
}
}

Update
PUT/compute/azure/group/{GROUP_ID}

Update one or more parameters in your Elastigroup Use the Elastigroup Json in the body to update the Elastigroup. Only the specified fields will apply.


Example URI

PUT https://api.spotinst.io/compute/azure/group/sig-12345

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup id you want to update


Request  Update Group
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "group": {
    "name": "spotinst-group",
    "strategy": {
      "lowPriorityPercentage": null,
      "dedicatedCount": 2,
  "drainingTimeout": 60,
   "signals":
  [
   {
    "name": "NODE_READY",
    "timeout" 100
   }
  ]
        },
        "capacity": {
          "target": 0,
          "minimum": 0,
          "maximum": 0
        },
        "compute": {
          "vmSizes": {
              "dedicatedSizes": [
                        "Standard_A1",
                        "Standard_A3"
              ],
            "lowPrioritySizes": [
                        "Standard_A1",
                        "Standard_A5"
            ]
          },
          "health": {
                "healthCheckType": "nodeState",
                "autoHealing": false,
                "gracePeriod": 100
          },
        }
        "scaling": {
          "up": [
            {
              "namespace": "AZURE/NODE",
              "metricName": "CPUUtilization",
              "statistic": "average",
              "unit": "percent",
              "threshold": 90,
              "dimensions": [
                {
                  "name": "nodeId"
                  "value" : 1
                }
              ],
              "period": 300,
              "evaluationPeriods": 1,
              "cooldown": 300,
              "action": {
                "type": "percentageAdjustment",
                "adjustment": 20,
                "minTargetCapacity": 2,
                "target": 5,
                "minimum": 5,
                "maximum": 5
              },
              "operator": "minTargetCapacity"
            }
          ],
          "down": [
            {
              "namespace": "AZURE/NODE",
              "metricName": "CPUUtilization",
              "statistic": "average",
              "unit": "percent",
              "threshold": 90,
              "dimensions": [
                {
                  "name": "nodeId"
                  "value" : 1
                }
              ],
              "period": 300,
              "evaluationPeriods": 1,
              "cooldown": 300,
              "action": {
                "type": "percentageAdjustment",
                "adjustment": 20,
                "minTargetCapacity": 2,
                "target": 5,
                "minimum": 5,
                "maximum": 5
              },
              "operator": "minTargetCapacity"
            }
          ]
        },
        "scheduling": {
          "tasks": [
            {
              "frequency": "hourly",
              "taskType": "scale"
            },
            {
              "taskType": "roll",
              "cronExpression": "00 17 * * 3",
              "batchSizePercentage": 30
            },
            {
              "taskType": "scale",
              "cronExpression": "00 22 * * 3",
              "scaleTargetCapcity": 0,
              "scaleMinCapcity": 0,
              "scaleMaxCapcity": 3
            }
          ]
        }
      }
    }

List Group
GET/compute/azure/group/{GROUP_ID}

Describe a specific Elastigroup JSON


Example URI

GET https://api.spotinst.io/compute/azure/group/sig-98765

Parameters

  • GROUP_ID
    string (required) Example: sig-98765

    The group ID you want to query


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "items": []
}

Delete
DELETE/compute/azure/group/{GROUP_ID}

Delete an existing Elastigroup


Example URI

DELETE https://api.spotinst.io/compute/azure/group/sig-98765

Parameters

  • GROUP_ID
    string (required) Example: sig-98765

    The group ID you want to delete


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Body
{
  "request": {
    "id": "4a0d5084-0b41-4255-82e5-d64a8232d7cc",
    "url": "/compute/azure/group/sig-98765",
    "method": "DELETE",
    "time": "2015-06-28T15:52:45.772Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    }
  }
}

Status
GET/compute/azure/group/{GROUP_ID}/status

Describes the current status of a specific Elastigroup


Example URI

GET https://api.spotinst.io/compute/azure/group/sig-12345/status

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup id you want to get a status for


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "90c94dce-91ba-4f4e-b0df-13bed0303de5",
    "url": "/compute/azure/group/sig-737cc5c5/status",
    "method": "GET",
    "timestamp": "2017-06-25T11:47:40.933Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:compute:azure:group:status",
    "items": [
      {
        "ipAddress": "10.0.0.6",
        "region": "westus",
        "state": "idle",
        "vmSize": "standard_a1",
        "id": "tvm-2434664350_26-20170625t091105z",
        "lifeCycle": "dedicated",
        "createdAt": "2017-06-25T09:12:00.000+0000"
      },
      {
        "ipAddress": "10.0.0.4",
        "region": "westus",
        "state": "idle",
        "vmSize": "standard_a1",
        "id": "tvm-2434664350_27-20170625t111017z",
        "lifeCycle": "dedicated",
        "createdAt": "2017-06-25T11:11:00.000+0000"
      },
      {
        "ipAddress": "10.0.0.6",
        "region": "westus",
        "state": "idle",
        "vmSize": "standard_a1",
        "id": "tvm-3426989531_41-20170625t091117z-p",
        "lifeCycle": "low_priority",
        "createdAt": "2017-06-25T09:12:00.000+0000"
      },
      {
        "ipAddress": "10.0.0.4",
        "region": "westus",
        "state": "idle",
        "vmSize": "standard_a1",
        "id": "tvm-3426989531_42-20170625t111018z-p",
        "lifeCycle": "low_priority",
        "createdAt": "2017-06-25T11:11:00.000+0000"
      }
    ],
    "count": 4
  }
}

Scale Up
PUT/compute/azure/group/{GROUP_ID}/scale/up{?adjustment}

Add nodes to your Elastigroup


Example URI

PUT https://api.spotinst.io/compute/azure/group/sig-12345/scale/up?adjustment=1

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup id you want to query

    adjustment
    int (required) Example: 1

    The number of nodes to add to the Elastigroup


Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Scale Down
PUT/compute/azure/group/{GROUP_ID}/scale/down{?adjustment}

Remove nodes from your Elastigroup

Note: Scale Advanced expression Remove nodes from your Elastigroup


Example URI

PUT https://api.spotinst.io/compute/azure/group/sig-12345/scale/down?adjustment=1

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup id you want to query

    adjustment
    int (required) Example: 1

    The number of nodes to remove from the Elastigroup


Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "f4332904-6f43-4a1c-92e4-dd7bdeb04c6a",
    "url": "/compute/azure/group/sig-f4f73bda/scale/up?adjustment=1",
    "method": "PUT",
    "timestamp": "2017-06-25T11:57:02.557Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    }
  }
}

Detach Node
PUT/compute/azure/group/{GROUP_ID}/detachNodes

Detach nodes from your Elastigroup


Example URI

PUT https://api.spotinst.io/compute/azure/group/sig-12345/detachNodes

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup ID you want to detach nodes from.


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "nodesToDetach": [
    "tvm-2-123456",
    "tvm-1-456798"
  ],
  "shouldDecrementTargetCapacity": false
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "3f806daf-7fd5-41aa-963a-a9c78e002454",
    "url": "/compute/azure/group/sig-c82e58e7/detachNodes",
    "method": "PUT",
    "timestamp": "2017-06-25T11:02:54.627Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:azure:compute:group",
    "items": [
      [
        "tvm-3426989531_2-20170625t104753z-p"
      ]
    ],
    "count": 1
  }
}

Activity Events
GET/compute/azure/group/{GROUP_ID}/events?fromDate={START_DATE}&toDate={END_DATE}

Get historical data on events that happened in a specific Elastigroup like update, scaling activities, creation of new nodes, etc.


Example URI

GET https://api.spotinst.io/compute/azure/group/sig-12345/events?fromDate=2016-10-01&toDate=2017-10-01

Parameters

  • GROUP_ID
    int (required) Example: sig-12345

    The Elastigroup id you want to query

    START_DATE
    Date- ISO8601 (required) Example: 2016-10-01

    Starting date to fetch the events from

    END_DATE
    Date- ISO8601 (required) Example: 2017-10-01

    End date to fetch the events from


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "d7a5d78c-7883-46f5-b1db-5991f4e051d8",
    "url": "/azure/compute/group/sig-88447418/events?spotinstAccountId=act-57762761&fromDate=1420070000000",
    "method": "GET",
    "timestamp": "2017-06-25T12:44:15.340+0000"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "azure:compute:group:event",
    "items": [
      {
        "groupId": "sig-88447418",
        "eventType": "create_group",
        "createdAt": "2017-06-25T12:32:46.000+0000"
      },
      {
        "groupId": "sig-88447418",
        "eventType": "update_group",
        "createdAt": "2017-06-25T12:41:13.000+0000"
      }
    ],
    "count": 2
  }
}

Roll
PUT/compute/azure/group/{GROUP_ID}/roll

Roll your Elastigroup (triggers Blue/Green Roll that replace the existing nodes in the Elastigroup)

Body parameters:

  • batchSizePercentage - int - (required) Indicates (in percentage) the batch size of the roll (meaning, how many nodes to replace in each batch)

  • gracePeriod - int - (required) Indicates (in seconds) the timeout to wait until node become healthy in the ELB

  • healthCheckType - string - (optional) Define a health check type. valid values: mlb, node_state, none (wait the entire grace period for each batch). If no value is set the roll will use the group’s auto-healing health check.

  • strategy - object - (optional) The roll strategy

  • strategy.action - string - (optional) The roll action to perform. valid values: REPLACE_NODE(more strategies soon to be implemented)


Example URI

PUT https://api.spotinst.io/compute/azure/group/sig-12345/roll

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup ID you want to roll


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "batchSizePercentage": 50,
  "gracePeriod": 300,
  "healthCheckType": "mlb",
  "strategy": {
    "action": "REPLACE_NODE"
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "3213e42e-455e-4901-a185-cc3eb65fac5f",
    "url": "/compute/azure/group/sig-12345/roll",
    "method": "PUT",
    "time": "2016-02-10T15:49:11.911Z"
  },
   "response": {
     "status": {
       "code": 200,
       "message": "OK"
     },
     "kind": "spotinst:azure:compute:group:roll",
     "items": [
       {
         "id": "sbgd-9876",
         "status": "ROLL_STARTING",
         "currentBatch": 1,
         "numOfBatches": 2,
         "progress": {
           "unit": "percentage",
           "value": 0
         },
         "groupId": "sig-12345"
       }
     ],
     "count": 1
   }

Roll Status
GET/compute/azure/group/{GROUP_ID}/roll/{ROLL_ID}

Get status of a specific roll


Example URI

GET https://api.spotinst.io/compute/azure/group/sig-12345/roll/sbgd-9876

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup ID you want to get the rolls status for

    ROLL_ID
    string (required) Example: sbgd-9876

    The roll id you want to query


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "57f6db69-35ba-4e58-be37-290d6df72bb5",
    "url": "/compute/azure/group/sig-12345/roll/sbgd-dfb956b4",
    "method": "GET",
    "timestamp": "2017-02-02T00:27:01.023Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:azure:compute:group:roll",
    "items": [
      {
        "id": "sbgd-9876",
        "status": "ROLL_FINISHED",
        "progress": {
          "unit": "percent",
          "value": 100
        },
        "createdAt": "2017-01-31T13:54:53.000+0000",
        "updatedAt": "2017-01-31T14:26:37.000+0000"
      }
    ],
    "count": 1
  }
}

Group's Rolls Status
GET/compute/azure/group/{GROUP_ID}/roll

Get list of all the rolls of a specific Elastigroup and their status


Example URI

GET https://api.spotinst.io/compute/azure/group/sig-12345/roll

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup ID you want to get the rolls status for


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "d1232cde-57ce-4abe-b276-ff2924ff67e0",
    "url": "/compute/azure/group/sig-12345/roll?limit=5",
    "method": "GET",
    "timestamp": "2017-02-02T00:28:00.690Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:azure:compute:group:roll",
    "items": [
      {
        "id": "sbgd-06e59445",
        "status": "roll_stopped",
        "progress": {
          "unit": "percent",
          "value": 0
        },
        "createdAt": "2017-01-05T15:07:22.000+0000",
        "updatedAt": "2017-01-05T15:20:44.000+0000"
      },
      {
        "id": "sbgd-54bd2a73",
        "status": "ROLL_FINISHED",
        "progress": {
          "unit": "percent",
          "value": 100
        },
        "createdAt": "2017-01-09T13:50:39.000+0000",
        "updatedAt": "2017-01-09T14:22:21.000+0000"
      }
    ],
    "count": 5
  }
}

Stop Roll
PUT/compute/azure/group/{GROUP_ID}/roll/{ROLL_ID}

Stop an existing roll.

Body parmaters

  • roll.status - string - (required) set the status of the roll to “ROLL_STOPPED”

Example URI

PUT https://api.spotinst.io/compute/azure/group/sig-12345/roll/sbgd-9876

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup ID you want to deploy

    ROLL_ID
    string (required) Example: sbgd-9876

    The roll id you want to stop


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "roll": {
    "status": "ROLL_STOPPED"
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "3213e42e-455e-4901-a185-cc3eb65fac5f",
    "url": "/compute/azure/group/sig-12345/roll/sbgd-dfb956b4",
    "method": "PUT",
    "time": "2016-02-10T15:49:11.911Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:azure:compute:group:roll"
  }
}

Signal Node
POST/compute/azure/node/signal

Create a signal for a node


Example URI

POST https://api.spotinst.io/compute/azure/node/signal

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "nodeId": "tvm-2-123456",
  "singal": "node_ready"
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "3f806daf-7fd5-41aa-963a-a9c78e002454",
    "url": "/compute/azure/node/signal",
    "method": "POST",
    "timestamp": "2017-06-25T11:02:54.627Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    }
  }
}
Next  Previous


Packet

Elastigroups

List Groups
GET/packet/group

Describe all the Elastigroups and their full JSONs


Example URI

GET https://api.spotinst.io/packet/group

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Create
POST/packet/group

Create a new Packet Elastigroup

Available Body parameters

  • name - string - (required) Elastigroup name

  • description - string - (optional) Describe your Elastigroup

Capacity

  • capacity.target - int - (Required)
    The number of instances to launch

  • capacity.minimum - int - (Required)
    The lower limit number of instances that you can scale down to

  • capacity.maximum - int - (Required)
    The upper limit number of instances that you can scale up to

Strategy

  • strategy.spotPercentage - int - (Required if onDemandCount is not specified)
    The percentage of Spot instances to launch (range: 0 - 100).

  • strategy.onDemandCount - int - (Required if risk is not specified)
    Number of on demand instances to launch in the group. All other instances will be spot instances. When this parameter is set the “risk” parameter is being ignored.

  • strategy.fallbackToOd - boolean - (Optional)
    In case of no spots available, Elastigroup will launch an On-demand instance instead

compute

  • compute.instanceTypes.od - string - (Required)
    List of available On-Demand Instance types

  • compute.instanceTypes.od - string - (Required)
    List of available Spot instance types

  • compute.elasticIps - Array<String> - (Optional)
    Optional - List of ElasticIps Allocation Ids to associate to the group instances.(e.g. “eipalloc-9d4e16f8”).

  • compute.dataCenters - Array<String> - (Required)
    List of available data centers to spin up the instances

  • compute.projectId - String - (Required)
    The packet project Id

Launch Specification

  • compute.launchSpecification.hostName - String - (Required)
    The instances hostname

  • compute.launchSpecification.operatingSystem - String - (Required)
    Valid values:centos_7 | centos_7_image | coreos_stable | coreos_beta | coreos_alpha | debian_8 | ubuntu_14_04 | ubuntu_14_04_image | ubuntu_16_04_image | windows_2012_rc2

  • compute.launchSpecification.userData - String - (Optional)
    The user data (start up script) that will be available for the instances when starting up

  • compute.launchSpecification.tags - Array<string> - (Optional)
    The instances hostname

  • compute.launchSpecification.hostName - String - (Required)
    The tag’s values

Third Parties Integration

  • thirdPartiesIntegration.rancher.masterHost - string - (Optional)
    API Environment Endpoint for the master host. Retrieve from the master host → API Keys → Advanced options → Environment API → Endpoint for example: http://myRancher.com:8080/v1

  • thirdPartiesIntegration.rancher.accessKey - string - (Optional)
    Access key for rancher integration (Can be created on rancher master in which the host will be added)

  • thirdPartiesIntegration.rancher.secretKey - string - (Optional)
    Secret key for rancher integration (Can be created on rancher master in which the host will be added)


Example URI

POST https://api.spotinst.io/packet/group

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "group": {
    "name": "Spotinst GCP Group",
    "capacity": {
      "minimum": 0,
      "maximum": 0,
      "target": 0
    },
    "strategy": {
      "preemptiblePercentage": 50
    },
    "scaling": {
      "up": [
        {
          "policyName": "scale_up_1",
          "metricName": "instance/disk/read_ops_count",
          "namespace": "compute",
          "statistic": "mean",
          "threshold": 10000,
          "action": {
            "type": "adjustment",
            "adjustment": 1
          },
          "dimensions": [
            {
              "name": "storage_type",
              "value": "pd-ssd"
            }
          ],
          "period": 300,
          "evaluationPeriods": 1,
          "cooldown": 300
        }
      ]
    },
    "compute": {
      "launchSpecification": {
        "serviceAccount": "example@myProject.iam.gserviceaccount.com",
        "tags": [
          "http",
          "https"
        ],
        "backendServices": [
          "spotinst-elb-backend-service"
        ],
        "disks": [
          {
            "deviceName": "device",
            "initializeParams": {
              "diskSizeGb": 10,
              "diskType": "pd-standard",
              "sourceImage": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-7-wheezy-v20151104"
            },
            "mode": "READ_WRITE",
            "type": "PERSISTENT",
            "autoDelete": true,
            "boot": true,
            "interface": "SCSI"
          }
        ],
        "networkInterfaces": [
          {
            "network": "spot-network"
          }
        ],
        "startupScript": null
      },
      "instanceTypes": {
        "ondemand": "n1-standard-1",
        "preemptible": [
          "n1-standard-1",
          "n1-standard-2",
          "n1-standard-4"
        ]
      },
      "availabilityZones": [
        "asia-east1-c",
        "europe-west1-c",
        "us-central1-a"
      ]
    },
    "description": "Spotinst GCP Group"
  }
}

Response  200
HideShow
Body
{
  "request": {
    "id": "47d61ee1-db18-4b3d-bb97-955d0a215d55",
    "url": "/gcp/gce/group",
    "method": "POST",
    "timestamp": "2016-02-14T09:15:09.381Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:gcp:gce:group",
    "items": [
      {
        "id": "sig-642b8368",
        "name": "Spotinst GCP Group",
        "description": "Spotinst GCP Group",
        "capacity": {
          "minimum": 0,
          "maximum": 0,
          "target": 0
        },
        "strategy": {
          "preemptiblePercentage": 50
        },
        "compute": {
          "launchSpecification": {
            "serviceAccount": "example@myProject.iam.gserviceaccount.com",
            "tags": [
              "http",
              "https"
            ],
            "backendServices": [
              "spotinst-elb-backend-service"
            ],
            "disks": [
              {
                "deviceName": "device",
                "initializeParams": {
                  "diskSizeGb": 10,
                  "diskType": "pd-standard",
                  "sourceImage": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-7-wheezy-v20151104"
                },
                "mode": "READ_WRITE",
                "type": "PERSISTENT",
                "autoDelete": true,
                "boot": true,
                "interface": "SCSI"
              }
            ],
            "networkInterfaces": [
              {
                "network": "spot-network"
              }
            ]
          },
          "instanceTypes": {
            "ondemand": "n1-standard-1",
            "preemptible": [
              "n1-standard-1",
              "n1-standard-2",
              "n1-standard-4"
            ]
          },
          "availabilityZones": [
            "asia-east1-c",
            "europe-west1-c",
            "us-central1-a"
          ]
        },
        "scaling": {
          "up": [
            {
              "policyName": "scale_up_1",
              "metricName": "instance/disk/read_ops_count",
              "statistic": "mean",
              "threshold": 10000,
              "namespace": "compute",
              "period": 300,
              "evaluationPeriods": 1,
              "cooldown": 300,
              "dimensions": [
                {
                  "name": "storage_type",
                  "value": "pd-standard"
                }
              ],
              "action": {
                "type": "adjustment",
                "adjustment": 1
              }
            }
          ]
        },
        "createdAt": "2016-02-14T09:15:09.000+0000",
        "updatedAt": "2016-02-14T09:15:09.000+0000"
      }
    ],
    "count": 1
  }
}

Update
PUT/packet/group/{GROUP_ID}


Example URI

PUT https://api.spotinst.io/packet/group/sig-98765

Parameters

  • GROUP_ID
    string (required) Example: sig-98765

    The group ID you want to update


Request  Update capacity
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "group": {
    "capacity": {
      "minimum": 0,
      "maximum": 10,
      "target": 3
    }
  }
}

Response  200
HideShow
Body
{
  "request": {
    "id": "b8fadac5-8064-4334-b391-745b71b29d6f",
    "url": "/packet/group/sig-98765",
    "method": "PUT",
    "timestamp": "2016-11-09T10:15:19.483Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:packet:group",
    "count": 1
  }
}

List Specific
GET/packet/group/{GROUP_ID}

Describe a specific Elastigroup JSON


Example URI

GET https://api.spotinst.io/packet/group/sig-98765

Parameters

  • GROUP_ID
    string (required) Example: sig-98765

    The group ID you want to query


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Body
{
  "request": {
    "id": "29663ea1-eaa1-4609-839c-0c07bf44e51f",
    "url": "/packet/group/sig-dba37df2",
    "method": "GET",
    "timestamp": "2016-11-09T10:23:48.564Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:packet:group",
    "items": [
      {
        "id": "sig-dba37df2",
        "name": "packetGroup10",
        "capacity": {
          "minimum": 0,
          "maximum": 10,
          "target": 0
        },
        "strategy": {
          "spotPercentage": 100,
          "fallbackToOd": false
        },
        "compute": {
          "launchSpecification": {
            "operatingSystem": "coreos_stable",
            "userData": null,
            "tags": [
              "database",
              "app"
            ],
            "hostName": "test.myapp.com"
          },
          "instanceTypes": {
            "spot": [
              "baremetal_0"
            ],
            "od": [
              "baremetal_0"
            ]
          },
          "dataCenters": [
            "ewr1",
            "ams1"
          ],
          "projectId": "8632439-9302-1d65-8f1e-qcb4c313c371"
        },
        "createdAt": "2016-11-09T10:15:19.000Z",
        "updatedAt": "2016-11-09T10:15:19.000Z"
      }
    ],
    "count": 1
  }
}

Delete Group
DELETE/packet/group/{GROUP_ID}


Example URI

DELETE https://api.spotinst.io/packet/group/sig-98765

Parameters

  • GROUP_ID
    string (required) Example: sig-98765

    The group ID you want to delete


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Body
{
  "request": {
    "id": "816b6783-c8c8-4845-a96d-02af5726494d",
    "url": "/packet/group/sig-12345",
    "method": "DELETE",
    "timestamp": "2016-11-09T10:20:02.350Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    }
  }
}

Costs
GET/packet/group/{GROUP_ID}/costs

Get financial information on a specific Elastigroup


Example URI

GET https://api.spotinst.io/packet/group/sig-12345/costs

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup ID you want to query


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Body
{
  "request": {
    "id": "abc5d17a-e31a-46db-b0f1-94821c74061b",
    "url": "/packet/group/sig-12345/costs",
    "method": "GET",
    "timestamp": "2016-12-04T17:00:46.527Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:packet:group:stats",
    "items": [
      {
        "running": {
          "value": 8,
          "unit": "hours"
        },
        "savings": {
          "value": 86,
          "unit": "percentage"
        },
        "costs": {
          "actual": 0.056,
          "potential": 0.4
        }
      }
    ],
    "count": 1
  }
}

Group Detailed Cost
GET/packet/group/{GROUP_ID}/costs/detailed

Get detailed financial information on a specific Elastigroup


Example URI

GET https://api.spotinst.io/packet/group/sig-12345/costs/detailed

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup ID you want to query


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Body
{
  "request": {
    "id": "794cda67-c206-4d0b-b355-d24917e349b9",
    "url": "/packet/group/sig-12345/costs/detailed",
    "method": "GET",
    "timestamp": "2016-12-04T17:02:43.439Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:packet:group:stats",
    "items": [
      {
        "running": {
          "value": 7,
          "unit": "hours"
        },
        "savings": {
          "value": 86,
          "unit": "percentage"
        },
        "costs": {
          "actual": 0.049,
          "potential": 0.35
        },
        "groupId": "sig-40611b06",
        "instanceId": "4f25d86b-ccab-423d-bc84-a013d088e94a",
        "spotRequestId": "sir-e43d1822",
        "instanceType": "baremetal_0",
        "dataCenter": "ewr1"
      },
      {
        "running": {
          "value": 1,
          "unit": "hours"
        },
        "savings": {
          "value": 86,
          "unit": "percentage"
        },
        "costs": {
          "actual": 0.007,
          "potential": 0.05
        },
        "groupId": "sig-40611b06",
        "instanceId": "7b20c642-ef6e-42ea-96bf-57ff3a6858b1",
        "spotRequestId": "sir-9e57e2df",
        "instanceType": "baremetal_0",
        "dataCenter": "ewr1"
      }
    ],
    "count": 2
  }
}

Status
GET/packet/group/{GROUP_ID}/status

Describes the current status of a specific Elastigroup


Example URI

GET https://api.spotinst.io/packet/group/sig-12345/status

Parameters

  • GROUP_ID
    string (required) Example: sig-12345

    The Elastigroup id you want to query


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Body
{
  "request": {
    "id": "4056671e-8827-456f-9cff-b8f671597894",
    "url": "/packet/group/sig-12345/status",
    "method": "GET",
    "timestamp": "2016-12-04T17:09:51.153Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:packet:group",
    "items": [
      {
        "spotRequestId": null,
        "instanceId": "14d1eaec-9326-4bd1-ad14-e147055ddb99",
        "instanceType": "baremetal_0",
        "dataCenter": "ewr1",
        "status": "active",
        "createdAt": "2016-12-04T09:57:48.000Z"
      },
      {
        "spotRequestId": "sir-e43d1822",
        "instanceId": "4f25d86b-ccab-423d-bc84-a013d088e94a",
        "instanceType": "baremetal_0",
        "dataCenter": "ewr1",
        "status": "active",
        "createdAt": "2016-12-04T09:57:46.000Z"
      },
      {
        "spotRequestId": "sir-9e57e2df",
        "instanceId": "7b20c642-ef6e-42ea-96bf-57ff3a6858b1",
        "instanceType": "baremetal_0",
        "dataCenter": "ewr1",
        "status": "active",
        "createdAt": "2016-12-04T16:46:38.000Z"
      }
    ],
    "count": 3
  }
}
Next  Previous


Multai Load Balancer

Multai API Documentation

Welcome to Multai API Documentation!

Welcome to the heart and soul of Multai: our API, which allows you to manage and operate your Multai account using conventional RESTful API. Whatever you can do via our portal, you can also do via our API.

Except for content explicitly made available to the general public, access and use of this site and all content herein is restricted to users authorized by Spotinst and may be subject to confidentiality restrictions. Please also note that the information contained herein is for informational purposes only and to the extent it conflicts with the terms of your contractual agreements with Spotinst, the terms of those contracts will govern.

Multai Load Balancer

Multai Load Balancer

Balancer

List All
GET/loadBalancer/balancer

Describe all the balancers and their full JSONs


Example URI

GET https://api.spotinst.io/loadBalancer/balancer

Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "2",
  "items": [
    {
      "id": "lb-12345",
      "name": "best_load_balancer_in_the_world",
      "timeouts": {
        "draining": 300,
        "idle": 60
      },
      "tags": [
        {
          "key": "Environment",
          "value": "Production"
        }
      ]
    },
    {
      "id": "lb-67890",
      "name": "best_load_balancer_in_the_world_2",
      "timeouts": {
        "draining": 300,
        "idle": 60
      },
      "tags": [
        {
          "key": "Environment",
          "value": "Production2"
        }
      ]
    }
  ]
}

Create
POST/loadBalancer/balancer

Create a new balancer.

Body parameters:

  • name - string - (required)
    balancer name. must contain only alphanumeric characters or hyphens, and must not begin or end with a hyphen.

Timeouts

  • timeout.draining - int - (required) The time for the load balancer to keep connections alive before reporting the target as de-registered, in seconds (range: 1 - 3600).

  • timeout.idle - int - (required) The idle timeout value, in seconds. (range: 1 - 3600).

Tags

  • tags.key - string - (optional)
    The tag’s key

  • tags.value - string - (optional)
    The tag’s value


Example URI

POST https://api.spotinst.io/loadBalancer/balancer

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${TOKEN}
Body
{
  "balancer": {
    "name": "best_load_balancer_in_the_world",
    "timeouts": {
      "draining": 300,
      "idle": 60
    },
    "tags": [
      {
        "key": "Environment",
        "value": "Production"
      }
    ]
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "1",
  "items": [
    {
      "id": "lb-12345",
      "name": "best_load_balancer_in_the_world",
      "timeouts": {
        "draining": 300,
        "idle": 60
      },
      "tags": [
        {
          "key": "Environment",
          "value": "Production"
        }
      ]
    }
  ]
}

Update
PUT/loadBalancer/balancer/{BALANCER_ID}

Update one or more parameters in your load balancer. Use the balancer Json in the body to update the balancer. Only the specified fields will be affected.


Example URI

PUT https://api.spotinst.io/loadBalancer/balancer/lb-12345

Parameters

  • BALANCER_ID
    string (required) Example: lb-12345

    (required) The balancer id you want to update


Request  Update Timeouts
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "balancer": {
    "timeouts": {
      "draining": 360,
      "idle": 30
    }
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Read
GET/loadBalancer/balancer/{BALANCER_ID}

Describe a specific balancer


Example URI

GET https://api.spotinst.io/loadBalancer/balancer/lb-12345

Parameters

  • BALANCER_ID
    string (required) Example: lb-12345

    (required) The balancer id you want to get


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "1",
  "items": [
    {
      "id": "lb-12345",
      "name": "best_load_balancer_in_the_world",
      "timeouts": {
        "draining": 300,
        "idle": 60
      },
      "tags": [
        {
          "key": "Environment",
          "value": "Production"
        }
      ]
    }
  ]
}

Delete
DELETE/loadBalancer/balancer/{BALANCER_ID}

Delete an existing balancer.


Example URI

DELETE https://api.spotinst.io/loadBalancer/balancer/lb-12345

Parameters

  • BALANCER_ID
    string (required) Example: lb-12345

    (required) The balancer id you want to delete


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${TOKEN}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  }
}

Target Set

List All
GET/loadBalancer/targetSet

Describe all the target sets and their full JSONs


Example URI

GET https://api.spotinst.io/loadBalancer/targetSet

Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "2",
  items: [{
    "id": "ts-12345",
    "name": "targetSet1",
    "balancerId": "lb-5470a9fb",
    "deploymentId": "de-12345",
    "protocol": "HTTP",
    "weight": 1,
    "healthCheck": {
        "interval" : 10,
        "path": "/healthCheck",
        "port": 80,
        "protocol": "HTTP",
        "timeout": 5,
        "healthyThresholdCount": 2,
        "unhealthyThresholdCount": 3
    },
    "tags": [{
        "key": "Environment",
        "value": "Production"
    }]
    },
    {
    "id": "ts-67890",
    "name": "targetSet2",
    "balancerId": "lb-5470a9fb",
    "deploymentId": "de-12345",
    "protocol": "HTTP",
    "weight": 1,
    "healthCheck": {
        "interval" : 10,
        "path": "/healthCheck",
        "port": 80,
        "protocol": "HTTP",
        "timeout": 5,
        "healthyThresholdCount": 2,
        "unhealthyThresholdCount": 3
    },
    "tags": [{
        "key": "Environment",
        "value": "Production2"
    }]
    }
  ]  
}

Create
POST/loadBalancer/targetSet

Create a new target set


Example URI

POST https://api.spotinst.io/loadBalancer/targetSet

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${TOKEN}
Body
{
  "targetSet": {
    "name": "targetSet1",
    "balancerId": "lb-5470a9fb",
    "deploymentId": "de-12345",
    "protocol": "HTTP",
    "weight": 1,
    "healthCheck": {
      "interval": 10,
      "path": "/healthCheck",
      "port": 80,
      "protocol": "HTTP",
      "timeout": 5,
      "healthyThresholdCount": 2,
      "unhealthyThresholdCount": 3
    },
    "tags": [
      {
        "key": "Environment",
        "value": "Production"
      }
    ]
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "1",
  "items": [
    {
      "id": "ts-12345",
      "name": "targetSet1",
      "balancerId": "lb-5470a9fb",
      "deploymentId": "de-12345",
      "protocol": "HTTP",
      "weight": 1,
      "healthCheck": {
        "interval": 10,
        "path": "/healthCheck",
        "port": 80,
        "protocol": "HTTP",
        "timeout": 5,
        "healthyThresholdCount": 2,
        "unhealthyThresholdCount": 3
      },
      "tags": [
        {
          "key": "Environment",
          "value": "Production"
        }
      ]
    }
  ]
}

Update
PUT/loadBalancer/targetSet/{TARGET_SET_ID}

Update one or more parameters in your target sets. Only the specified fields will be affected.


Example URI

PUT https://api.spotinst.io/loadBalancer/targetSet/ts-12345

Parameters

  • TARGET_SET_ID
    string (required) Example: ts-12345

    (required) The target set id you want to update


Request  Update Weight
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "targetSet": {
    "weight": 1
  }
}

Request  Update Health Check
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "targetSet": {
    "healthCheck": {
      "interval": 10,
      "path": "/healthCheck",
      "port": 80,
      "protocol": "HTTP",
      "timeout": 5,
      "healthyThresholdCount": 2,
      "unhealthyThresholdCount": 3
    }
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Read
GET/loadBalancer/targetSet/{TARGET_SET_ID}

Describe a specific target sets


Example URI

GET https://api.spotinst.io/loadBalancer/targetSet/ts-12345

Parameters

  • TARGET_SET_ID
    string (required) Example: ts-12345

    (required) The target set id you want to get


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "1",
  "items": [
    {
      "id": "ts-12345",
      "name": "targetSet1",
      "balancerId": "lb-5470a9fb",
      "deploymentId": "de-12345",
      "protocol": "HTTP",
      "weight": 1,
      "healthCheck": {
        "interval": 10,
        "path": "/healthCheck",
        "port": 80,
        "protocol": "HTTP",
        "timeout": 5,
        "healthyThresholdCount": 2,
        "unhealthyThresholdCount": 3
      },
      "tags": [
        {
          "key": "Environment",
          "value": "Production"
        }
      ]
    }
  ]
}

Delete
DELETE/loadBalancer/targetSet/{TARGET_SET_ID}

Delete an existing target sets


Example URI

DELETE https://api.spotinst.io/loadBalancer/targetSet/ts-12345

Parameters

  • TARGET_SET_ID
    string (required) Example: ts-12345

    (required) The target set id you want to delete


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${TOKEN}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  }
}

Target

List All
GET/loadBalancer/target

Describe all the targets and their full JSONs


Example URI

GET https://api.spotinst.io/loadBalancer/target

Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "2",
  "items": [
    {
      "id": "t-12345",
      "name": "target1",
      "balancerId": "lb-12345",
      "targetSetId": "ts-12345",
      "address": "http://10.0.0.2:1337",
      "weight": 1,
      "tags": [
        {
          "key": "Environment",
          "value": "Production"
        }
      ]
    },
    {
      "id": "t-67890",
      "name": "target2",
      "balancerId": "lb-67890",
      "targetSetId": "ts-12345",
      "address": "http://10.0.0.3:1337",
      "weight": 1,
      "tags": [
        {
          "key": "Environment",
          "value": "Production"
        }
      ]
    }
  ]
}

Create
POST/loadBalancer/target

Create a new target.

Body parameters:

General

  • name - string - (required)
    The name of the Target . Must contain only alphanumeric characters or hyphens, and must not begin or end with a hyphen.

  • balancerId - string - (required) The id of the balancer

  • targetSetId - string - (required) The id of the Target Set

  • address - string - (required) The address (IP or URL) of the targets to register

  • weight - int - (required) Defined how the traffic is distributed between the Target

Tags

  • tags[].key - string - (optional)
    The tag’s key

  • tags[].value - string - (optional)
    The tag’s value


Example URI

POST https://api.spotinst.io/loadBalancer/target

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${TOKEN}
Body
{
  "target": {
    "name": "target1",
    "balancerId": "lb-12345",
    "targetSetId": "ts-12345",
    "address": "http://10.0.0.2:1337",
    "weight": 1,
    "tags": [
      {
        "key": "Environment",
        "value": "Production"
      }
    ]
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "1",
  "items": [
    {
      "id": "t-12345",
      "name": "target1",
      "balancerId": "lb-12345",
      "targetSetId": "ts-12345",
      "address": "http://10.0.0.2:1337",
      "weight": 1,
      "tags": [
        {
          "key": "Environment",
          "value": "Production"
        }
      ]
    }
  ]
}

Update
PUT/loadBalancer/target/{TARGET_ID}

Update one or more parameters in your targets. Only the specified fields will apply.


Example URI

PUT https://api.spotinst.io/loadBalancer/target/t-12345

Parameters

  • TARGET_ID
    string (required) Example: t-12345

    (required) The target id you want to update


Request  Weight
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "target": {
    "weight": 1
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Get
GET/loadBalancer/target/{TARGET_ID}

Describe a specific target


Example URI

GET https://api.spotinst.io/loadBalancer/target/t-12345

Parameters

  • TARGET_ID
    string (required) Example: t-12345

    (required) The target id you want to get


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "1",
  "items": [
    {
      "id": "t-12345",
      "name": "target1",
      "balancerId": "lb-12345",
      "targetSetId": "ts-12345",
      "address": "http://10.0.0.2:1337",
      "weight": 1,
      "tags": [
        {
          "key": "Environment",
          "value": "Production"
        }
      ]
    }
  ]
}

Delete
DELETE/loadBalancer/target/{TARGET_ID}

Delete an existing target


Example URI

DELETE https://api.spotinst.io/loadBalancer/target/t-12345

Parameters

  • TARGET_ID
    string (required) Example: t-12345

    (required) The target id you want to delete


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${TOKEN}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  }
}

Listener

List All
GET/loadBalancer/listener

Describe all the listeners and their full JSONs


Example URI

GET https://api.spotinst.io/loadBalancer/listener

Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "2",
  items: [{
    "id": "ls-12345",
    "balancerId": "lb-12345",
    "protocol": "HTTP",
    "port":"80",
    "tags": [{
        "key": "Environment",
        "value": "Production"
    }]
  },
  {
    "id": "ls-67890",
    "balancerId": "lb-67890",
    "protocol": "HTTP",
    "port":"81",
    "tags": [{
        "key": "Environment",
        "value": "Production2"
     }]
  }
  ]
}

Create
POST/loadBalancer/listener

Create a new listener.

Body parameters:

General

  • balancerId - int - (required) The id of the balancer

  • protocol - int - (required) The protocol to allow connections to the load balancer

  • port - int - (required) The port on which the load balancer is listening.

  • tlsConfig.minVersion - string - (required) MinVersion contains the minimum SSL/TLS version that is acceptable (1.0 is the minimum)

  • tlsConfig.maxVersion - string - (required) MaxVersion contains the maximum SSL/TLS version that is acceptable.

  • tlsConfig.sessionTicketsDisabled - boolean - (required) May be set to true to disable session ticket (resumption) support

  • tlsConfig.preferServerCipherSuites - boolean - (required) Controls whether the server selects the client’s most preferred ciphersuite, or the server’s most preferred ciphersuite

  • tlsConfig.cipherSuites - string - (required) List of supported cipher suites. If cipherSuites is nil, TLS uses a list of suites supported by the implementation

  • tlsConfig.insecureSkipVerify - int - (required) Controls whether a client verifies the server’s certificate chain and host name. If InsecureSkipVerify is true, TLS accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to man-in-the-middle attacks. (This should be used only for testing)

  • tlsConfig.certificateIds - boolean - (required) Contains one or more certificate chains to present to the other side of the connection.


Example URI

POST https://api.spotinst.io/loadBalancer/listener

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${TOKEN}
Body
{
  "listener": {
    "balancerId": "lb-5470a9fb",
    "protocol": "HTTP",
    "port": "443",
    "tlsConfig": {
      "minVersion": "TLS10",
      "maxVersion": "TLS12",
      "sessionTicketsDisabled": true,
      "preferServerCipherSuites": true,
      "cipherSuites": [
        "TLS_RSA_WITH_AES_256_CBC_SHA",
        "TLS_RSA_WITH_AES_128_CBC_SHA256"
      ],
      "insecureSkipVerify": false,
      "certificateIds": [
        "ce-12345",
        "ce-67890"
      ]
    },
    "tags": [
      {
        "key": "Environment",
        "value": "Production"
      }
    ]
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "1",
  "items": [
    {
      "id": "ls-12345",
      "balancerId": "lb-5470a9fb",
      "protocol": "HTTP",
      "port": "443",
      "tlsConfig": {
        "minVersion": "TLS10",
        "maxVersion": "TLS12",
        "sessionTicketsDisabled": true,
        "preferServerCipherSuites": true,
        "cipherSuites": [
          "TLS_RSA_WITH_AES_256_CBC_SHA",
          "TLS_RSA_WITH_AES_128_CBC_SHA256"
        ],
        "insecureSkipVerify": false,
        "certificateIds": [
          "ce-12345",
          "ce-67890"
        ]
      },
      "tags": [
        {
          "key": "Environment",
          "value": "Production"
        }
      ]
    }
  ]
}

Update
PUT/loadBalancer/listener/{LISTENER_ID}

Update one or more parameters in your listeners. Only the specified fields will be affected.


Example URI

PUT https://api.spotinst.io/loadBalancer/listener/ls-12345

Parameters

  • LISTENER_ID
    string (required) Example: ls-12345

    (required) The listener id you want to update


Request  Update Port
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "listener": {
    "port": "8080"
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Read
GET/loadBalancer/listener/{LISTENER_ID}

Describe a specific listener


Example URI

GET https://api.spotinst.io/loadBalancer/listener/ls-12345

Parameters

  • LISTENER_ID
    string (required) Example: ls-12345

    (required) The listener id you want to get


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "1",
  "items": [
    {
      "id": "ls-12345",
      "balancerId": "lb-12345",
      "protocol": "HTTP",
      "port": "80",
      "tags": [
        {
          "key": "Environment",
          "value": "Production"
        }
      ]
    }
  ]
}

Delete
DELETE/loadBalancer/listener/{LISTENER_ID}

Delete an existing listener


Example URI

DELETE https://api.spotinst.io/loadBalancer/listener/ls-12345

Parameters

  • LISTENER_ID
    string (required) Example: ls-12345

    (required) The listener id you want to delete


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${TOKEN}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  }
}

Routing Rule

List All
GET/loadBalancer/routingRule

Describe all the routing rules and their full JSONs


Example URI

GET https://api.spotinst.io/loadBalancer/routingRule

Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "2",
  "items": [
    {
      "id": "rr-12345",
      "balancerId": "lb-12345",
      "route": "PathRegexp(`/v1`)",
      "targetSetIds": [
        "ts-12345",
        "ts-67890"
      ],
      "middlewareIds": [],
      "listenerId": "ls-12345",
      "tags": [
        {
          "key": "Environment",
          "value": "Production"
        }
      ]
    },
    {
      "id": "rr-67890",
      "balancerId": "lb-12345",
      "route": "PathRegexp(`/v2`)",
      "targetSetIds": [
        "ts-12345",
        "ts-67890"
      ],
      "middlewareIds": [],
      "listenerId": "ls-12345",
      "tags": [
        {
          "key": "Environment",
          "value": "Production"
        }
      ]
    }
  ]
}

Create
POST/loadBalancer/routingRule

Create a new routing rule

Body parameters:

General

  • balancerId - string - (required) The id of the balancer

  • route - string - (required) Route defines a simple language for matching HTTP requests and route the traffic accordingly. Route provides series of matchers that follow the syntax:

Path matcher: — Path("/foo/bar") // trie-based PathRegexp(“/foo/.*”) // regexp-based

Method matcher: — Method(“GET”) // trie-based MethodRegexp(“POST|PUT”) // regexp based

Header matcher: — Header(“Content-Type”, “application/json”) // trie-based HeaderRegexp(“Content-Type”, “application/.*”) // regexp based

Matchers can be combined using && operator: — Method(“POST”) && Path("/v1")

  • targetSetIds - string - (required) The id of the Target Set

  • middlewareIds - string - (optional) The id of the Middleware

  • listenerId - string - (required) The id of the Listener

Tags

  • tags[].key - string - (optional)
    The tag’s key

  • tags[].value - string - (optional)
    The tag’s value


Example URI

POST https://api.spotinst.io/loadBalancer/routingRule

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${TOKEN}
Body
{
  "routingRule": {
    "balancerId": "lb-12345",
    "route": "PathRegexp(`/`)",
    "targetSetIds": [
      "ts-12345",
      "ts-67890"
    ],
    "middlewareIds": [
      "mw-23456",
      "mw-7890"
    ],
    "listenerId": "ls-12345",
    "tags": [
      {
        "key": "Environment",
        "value": "Production"
      }
    ]
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "1",
  "items": [
    {
      "id": "rr-12345",
      "balancerId": "lb-12345",
      "route": "PathRegexp(`/`)",
      "targetSetIds": [
        "ts-12345",
        "ts-67890"
      ],
      "middlewareIds": [
        "mw-23456",
        "mw-7890"
      ],
      "listenerId": "ls-12345",
      "tags": [
        {
          "key": "Environment",
          "value": "Production"
        }
      ]
    }
  ]
}

Update
PUT/loadBalancer/routingRule/{ROUTING_RULE_ID}

Update one or more parameters in your routing rule. Only the specified fields will be affected. Please notice that targetSetIds and middlewareIds are optional and will override the exiting mappings. If you want to add / remove mapping you need to send the complete up to date mapping list.


Example URI

PUT https://api.spotinst.io/loadBalancer/routingRule/rr-12345

Parameters

  • ROUTING_RULE_ID
    string (required) Example: rr-12345

    (required) The routing rule id you want to update


Request  Update Route
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "routingRule":{
    "route": "HeaderRegexp(`User-Defined-Header`, `application1`)",
    "targetSetIds": ["ts-1234","ts-2345"],
    "middlewareIds": ["mw-2222"]
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Read
GET/loadBalancer/routingRule/{ROUTING_RULE_ID}

Describe a specific routing rule


Example URI

GET https://api.spotinst.io/loadBalancer/routingRule/rr-12345

Parameters

  • ROUTING_RULE_ID
    string (required) Example: rr-12345

    (required) The routing rule id you want to get


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "1",
  "items": [
    {
      "id": "rr-12345",
      "balancerId": "lb-12345",
      "route": "PathRegexp(`/v1`)",
      "targetSetIds": [
        "ts-12345",
        "ts-67890"
      ],
      "middlewareIds": [],
      "listenerId": "ls-12345",
      "tags": [
        {
          "key": "Environment",
          "value": "Production"
        }
      ]
    }
  ]
}

Delete
DELETE/loadBalancer/routingRule/{ROUTING_RULE_ID}

Delete an existing routing rule


Example URI

DELETE https://api.spotinst.io/loadBalancer/routingRule/rr-12345

Parameters

  • ROUTING_RULE_ID
    string (required) Example: rr-12345

    (required) The routing rule id you want to delete


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${TOKEN}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  }
}

Middleware

List All
GET/loadBalancer/middleware

Describe all middlewares and their full JSONs


Example URI

GET https://api.spotinst.io/loadBalancer/middleware

Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": 2,
  "kind": "spotinst:lb:middleware",
  "items": [
    {
      "id": "mw-01c4ec988f3d",
      "balancerId": "lb-57e0dad0627c",
      "type": "ACL",
      "priority": 1,
      "spec": {
        "action": "ALLOW",
        "conditions": [
          {
            "type": "HTTP_REQUEST_IP",
            "values": [
              "1.2.3.4",
              "1.2.3.5"
            ]
          }
        ]
      },
      "tags": [],
      "updatedAt": "2017-06-26T06:06:38.000Z",
      "createdAt": "2017-06-26T06:06:38.000Z"
    },
    {
      "id": "mw-01c4ec988f3s",
      "balancerId": "lb-57e0dad0627c",
      "type": "ACL",
      "priority": 2,
      "spec": {
        "action": "DENY",
        "conditions": [
          {
            "type": "HTTP_REQUEST_COOKIE",
            "values": [
              "username=John Doe"
            ]
          }
        ]
      },
      "tags": [],
      "updatedAt": "2017-06-26T06:06:38.000Z",
      "createdAt": "2017-06-26T06:06:38.000Z"
    }
  ]
}

Create
POST/loadBalancer/middleware

Create a new middleware

Body parameters:

General

  • balancerId - string - (required) The id of the balancer

  • priority - integer - (required) The priority of the Middleware on the RoutingRule middleware chain.

  • type - string - (required) Middleware type can be one of the following:

    • ACL:

    An Access Control List (ACL) is a security enhancement available for Multai Load Balancer. An ACL provides the ability to selectively permit, deny or limit traffic for Balancer’s Routing Rule.

    • LUA:

    Lua is a powerful and fast programming language that is easy to learn and use and to embed into your Balancer. Lua is designed to be a lightweight embeddable scripting language. It is used for all sorts of applications, from games to web applications and image processing.

  • spec - string - (required) The spec of the Middleware. The spec should be according to the middleware type as follow:

ACL:

“spec”:{ “action”: “ALLOW/DENY”, “conditions”: [ { “type”: “HTTP_REQUEST_IP/HTTP_REQUEST_HEADER/HTTP_REQUEST_METHOD/HTTP_REQUEST_COOKIE”, “values”: [ “1.2.3.5”/“username=John Doe”/“POST”/ ] } ] }

LUA:

“spec”:{ “name”:“Lua Hello World”, “code”:“cHJpbnQoJ2hlbGxvLXdvcmxkJyk=”, //Base64 “timeout”:60 //Timeout in seconds (optional) }

Tags

  • tags[].key - string - (optional)
    The tag’s key

  • tags[].value - string - (optional)
    The tag’s value


Example URI

POST https://api.spotinst.io/loadBalancer/middleware

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${TOKEN}
Body
{
  "middleware": {
    "balancerId": "lb-6acf2ff362ac",
    "type": "ACL",
    "priority": 1,
    "spec": {
      "action": "ALLOW",
      "conditions": [
        {
          "type": "HTTP_REQUEST_IP",
          "values": [
            "1.2.3.4",
            "1.2.3.5"
          ]
        }
      ]
    },
    "tags": [
      {
        "key": "Environment",
        "value": "Production"
      }
    ]
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "1",
  "items": [
    {
      "id": "mw-d13133e1eab0",
      "balancerId": "lb-57e0dad0627c",
      "type": "ACL",
      "priority": 1,
      "spec": {
        "action": "ALLOW",
        "conditions": [
          {
            "type": "HTTP_REQUEST_IP",
            "values": [
              "1.2.3.4",
              "1.2.3.5"
            ]
          }
        ]
      },
      "tags": [
        {
          "key": "Environment",
          "value": "Production"
        }
      ],
      "updatedAt": "2017-07-03T13:41:23.398Z",
      "createdAt": "2017-07-03T13:41:23.398Z"
    }
  ]
}

Update
PUT/loadBalancer/middleware/{MIDDLEWARE_ID}

Update one or more parameters in your middleware. Only the specified fields will be affected.


Example URI

PUT https://api.spotinst.io/loadBalancer/middleware/mw-12345

Parameters

  • MIDDLEWARE_ID
    string (required) Example: mw-12345

    (required) The middleware id you want to update


Request  Update priority and spec
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "middleware": {
    "type": "ACL",
    "priority": 5,
    "spec": {
      "action": "ALLOW",
      "conditions": [
        {
          "type": "HTTP_REQUEST_IP",
          "values": [
            "1.2.3.34",
            "1.2.3.35"
          ]
        }
      ]
    }
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Read
GET/loadBalancer/middleware/{MIDDLEWARE_ID}

Describe a specific middleware


Example URI

GET https://api.spotinst.io/loadBalancer/middleware/mw-12345

Parameters

  • MIDDLEWARE_ID
    string (required) Example: mw-12345

    (required) The middleware id you want to get


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "1",
  "items": [
    {
      "id": "mw-01c4ec988f3s",
      "balancerId": "lb-57e0dad0627c",
      "type": "ACL",
      "priority": 4,
      "spec": {
        "action": "DENY",
        "conditions": [
          {
            "type": "HTTP_REQUEST_COOKIE",
            "values": [
              "blabla=123",
              "blabla=124"
            ]
          }
        ]
      },
      "tags": [
        {
          "key": "Environment",
          "value": "Production"
        }
      ],
      "updatedAt": "2017-06-26T06:06:38.000Z",
      "createdAt": "2017-06-26T06:06:38.000Z"
    }
  ]
}

Delete
DELETE/loadBalancer/middleware/{MIDDLEWARE_ID}

Delete an existing middleware


Example URI

DELETE https://api.spotinst.io/loadBalancer/middleware/mw-12345

Parameters

  • MIDDLEWARE_ID
    string (required) Example: mw-12345

    (required) The middleware id you want to delete


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${TOKEN}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  }
}
Next  Previous


Spectrum

Multai Spectrum

Metrics

Report
POST/spectrum/metrics/metricData

Publishes metric data points to Spotinst spectrum

Body parameters:

  • namespace - string - (required)
    The name of the namespace.

  • dimensions - array - (required at least one)
    The dimension(s) to query on, associated with the metric.

  • metrics - array - (required at least one)

Metrics:

  • metrics[].name - string - (required) The name of the metric.

  • metrics[].value - double - (required)
    The value of the metric.

  • metrics[].unit - string - (required)
    The unit of the metric using one of the following Units: Seconds | Microseconds | Milliseconds | Bytes | Kilobytes | Megabytes | Gigabytes | Terabytes | Bits | Kilobits | Megabits | Gigabits | Terabits | Percent | Count | Bytes/Second | Kilobytes/Second | Megabytes/Second | Gigabytes/Second | Terabytes/Second | Bits/Second | Kilobits/Second | Megabits/Second | Gigabits/Second | Terabits/Second | Count/Second | Custom

Dimensions:

  • dimensions[].name - string - (required)
    The name of the dimension.

  • dimensions[].value - string - (required)
    The value representing the dimension.


Example URI

POST https://api.spotinst.io/spectrum/metrics/metricData

Request
HideShow
Headers
Authorization: Bearer ${token}
Body
{
  "metricData": [
    {
      "namespace": "myNamespace",
      "dimensions": [
        {
          "name": "dimensionName",
          "value": "dimensionValue"
        }
      ],
      "metrics": [
        {
          "name": "metricName",
          "value": 1,
          "unit": "metricUnit"
        }
      ]
    },
    ...
  ]
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "cb6509c2-84a9-4e1e-a6b4-5b91fa5f2450",
    "url": "/spectrum/metrics/metricData",
    "method": "POST",
    "timestamp": "1970-01-01T01:00:00.000+0000"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:spectrum:metricData",
    "items": [],
    "count": 0
  }
}

Query

Query
POST/spectrum/metrics/metricStatisticsQuery

Query for specific metric statistics

Body parameters:

  • namespace - string - (required)
    The name of the namespace.

  • metricName - string - (required)
    The name of the metric.

  • statistic - string - (required) The metric statistic. Allowed values: average, count, minimum, maximum, sum

  • dimensions - array - (required at least one)
    The dimension(s) to report.

  • timeInterval - string
    The time interval granularity of the returned data points.
    Allowed values: 1m, 5m, 15m, 30m, 1h, 2h, 6h, 12h, 24h

  • dateRange - array - (required)
    Dates containing the range to determine the data points to return.

Date Range:

  • from - date - (required)
    The Unix time stamp that determines the first data point to return.

  • to - date - (required)
    The Unix time stamp that determines the last data point to return.

Dimensions:

  • dimensions[].name - string - (required)
    The name of the dimension.

  • dimensions[].value - string - (required)
    The value representing the dimension.


Example URI

POST https://api.spotinst.io/spectrum/metrics/metricStatisticsQuery

Request
HideShow
Headers
Authorization: Bearer ${token}
Body
{
  "namespace": "myNamespace",
  "metricName": "metricName",
  "timeInterval": "1m",
  "statistic": "average",
  "dateRange": {
    "from": 1490860688,
    "to": 1490860688
  },
  "dimensions": [
    {
      "name": "dimensionName",
      "value": "dimensionValue"
    }
  ]
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "cb6509c2-84a9-4e1e-a6b4-5b91fa5f2450",
    "url": "/spectrum/metrics/metricStatisticsQuery",
    "method": "POST",
    "timestamp": "1970-01-01T01:00:00.000+0000"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:spectrum:queryMetricStatistics",
    "items": [
      {
        "aggregations": [
          {
            "dimensions": [
              {
                "name": "dimensionName",
                "value": "dimensionValue"
              }
            ],
            "datapoints": [
              {
                "timestamp": "2017-08-22T00:00:00.000Z",
                "statistics": {
                  "average": 21.2000007629
                }
              },
              {
                "timestamp": "2017-08-22T00:01:00.000Z",
                "statistics": {
                  "average": 18.3999996185
                }
              }
              ...
            ]
          }
        ]
      }
    ]
  }
}

Metric Metadata

Metric Metadata
GET/spectrum/metrics/metricMetadata?namespace={NAMESPACE}&dimension={DIMENSION}&metric={METRIC}]

Get metric metadata by filters


Example URI

GET https://api.spotinst.io/spectrum/metrics/metricMetadata?namespace=myNamespace&dimension=myDimension&metric=myMetric]

Parameters

  • NAMESPACE
    string (required) Example: myNamespace

    The name of the namespace

    DIMENSION
    string (required) Example: myDimension

    The name of the dimension

    METRIC
    string (required) Example: myMetric

    The name of the metric


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "request": {
        "id": "6a8b8af3-ee67-4351-8ba4-428dc12e6136",
        "url": "/spectrum/metrics/metricMetadata",
        "method": "GET",
        "timestamp": "1970-01-01T00:00:00.000+0000"
    },
    "response": {
        "status": {
            "code": 200,
            "message": "OK"
        },
        "kind": "spotinst:spectrum:metricMetadata",
        "items": [
            {
                "namespace": "myNamespace",
                "dimension": "myDimension",
                "metric": "MyMetric",
                "updatedAt": "1970-01-01T00:00:00.000+0000",
                "createdAt": "1970-01-01T00:00:00.000+0000"
            }
            ...
        }
    }
}

Alerts

Create Action
POST/spectrum/metrics/action

Creates an Action

Body parameters:

Action

  • enabled - ‘string’ - (required)

    Allowed values:can be either ‘true’ or ‘false’

  • name - ‘string’ - (required)

    A name of your choice

  • type - ‘string’ (required)

    Allowed values: ‘EMAIL’,‘SNS’

    • Params

      Email - recipient email address


Example URI

POST https://api.spotinst.io/spectrum/metrics/action

Request
HideShow
Headers
Authorization: Bearer ${token}
Body
{
  "action": {
    "enabled": true,
    "name": "DemoAction",
    "type": "EMAIL",
    "params": {
      "email": "demo@spotinst.com"
    }
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "6304d238-80e8-4743-92c1-971389272be2",
    "url": "/spectrum/metrics/action?accountId={AccountId}",
    "method": "POST",
    "timestamp": "2017-08-20T16:36:52.796Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:lb:action",
    "items": [
      {
        "id": "ac-664d6979ccbb",
        "enabled": true,
        "name": "DemoAction",
        "type": "EMAIL",
        "params": {
          "email": "demo@spotinst.com"
        },
        "updatedAt": "2017-08-20T16:36:52.764Z",
        "createdAt": "2017-08-20T16:36:52.764Z"
      }
    ],
    "count": 1
  }
}

Create Alert
POST/spectrum/metrics/alert

Creates an Alert

Body parameters:

action

  • enabled - ‘string’ - (required)

    can be either ‘true’ or ‘false’

  • name - ‘string’ - (required)

    a name of your choice

  • description - ‘string’ (required)

    a description of your choice

  • documentation - ‘string’ (required)

  • namespace - ‘string’ (required)

    metric namespace

  • metricName - ‘string’ (required)

    metric name

  • dimensions - ‘array’ (required)

    array of dimensions

  • name - ‘string’ (required)

    filter criteria

  • value - ‘string’ (required)

    filter value

  • statistic - ‘string’ (required)

    can be either ‘sum’ / ‘maximum’ / ‘minimum’ / ‘avg’

  • consecutivePeriods - ‘string’ (required)

    consecutive checks before triggering the alert

conditions

  • critical

    • threshold - ‘int’ (optional)

      Alert threshold

    • operator - ‘string’ (optional)

      Allowed values: ‘gt’ / ‘lt’ / ‘eq’ / ‘ge’ / ‘le’ / ‘ne’

  • error

    Same as critical

  • warning

    Same as critical

  • ok

    Same as critical

  • unknown

    Same as critical

  • actionsEnabled

    can be either ‘true’ or ‘false’

actions

  • unknownActionIds - ‘array’ (required)

    array containing 0 or more actions for this severity level

  • okActionIds - ‘array’ (required)

    array containing 0 or more actions for this severity level

  • warningActionId - ‘array’ (required)

    array containing 0 or more actions for this severity level

  • errorActionId - ‘array’ (required)

    array containing 0 or more actions for this severity level

  • criticalActionId - ‘array’ (required)

    array containing 0 or more actions for this severity level


Example URI

POST https://api.spotinst.io/spectrum/metrics/alert

Request
HideShow
Headers
Authorization: Bearer ${token}
Body
{
  "alert": {
    "enabled": true,
    "name": "Spotinst - High CPU load",
    "description": "One or more of the instances have high CPU utilization",
    "documentation": "",
    "namespace": "spotinst/compute",
    "metricName": "cpu_load",
    "dimensions": [
      {
        "name": "instance_id",
        "value": "i-0972be94f00afef3c"
      }
    ],
    "statistic": "sum",
    "period": "1m",
    "consecutivePeriods": 1,
    "conditions": {
      "critical": {
        "threshold": 80,
        "operator": "gt"
      }
    },
    "actionsEnabled": true,
    "actions": {
      "unknownActionIds": [],
      "okActionIds": [],
      "warningActionIds": [],
      "errorActionIds": [],
      "criticalActionIds": [
        "ac-664d6979ccbb"
      ]
    }
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "id": "c0e12178-6b0d-42f0-8a6e-701d8a55de5c",
    "url": "/spectrum/metrics/alert?accountId={AccountId}",
    "method": "POST",
    "timestamp": "2017-08-20T16:37:34.225Z"
  },
  "response": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "kind": "spotinst:lb:alert",
    "items": [
      {
        "id": "al-d185c7706b22",
        "status": "UNKNOWN",
        "enabled": true,
        "name": "Spotinst - High CPU load",
        "namespace": "spotinst/compute",
        "metricName": "cpu_load",
        "period": "1m",
        "consecutivePeriods": 1,
        "statistic": "sum",
        "conditions": {
          "error": null,
          "warning": null,
          "critical": {
            "threshold": 80,
            "operator": "gt"
          }
        },
        "dimensions": [
          {
            "name": "instance_id",
            "value": "i-0972be94f00afef3c"
          }
        ],
        "description": "One or more of the instances have high CPU utilization",
        "documentation": "",
        "actionsEnabled": true,
        "actions": {
          "okActionIds": [],
          "warningActionIds": [],
          "errorActionIds": [],
          "criticalActionIds": [
            "ac-664d6979ccbb"
          ],
          "unknownActionIds": []
        },
        "updatedAt": "2017-08-20T16:37:34.213Z",
        "createdAt": "2017-08-20T16:37:34.213Z"
      }
    ],
    "count": 1
  }
}

Job

List all Jobs
GET/spectrum/events/job?resourceId={RESOURCE_ID}&action={ACTION}&isEnabled={ENABLED}&accountId={ACCOUNT_ID}

Describe all Jobs


Example URI

GET https://api.spotinst.io/spectrum/events/job?resourceId=fx-12223456789&action=INVOKE_FUNCTION&isEnabled=true&accountId=act-12223456789

Parameters

  • RESOURCE_ID
    string (required) Example: fx-12223456789

    (Optional) The Spotinst Resource ID

    ACTION
    string (required) Example: INVOKE_FUNCTION

    (Optional) The Action type you wish to get the list for

    ENABLED
    BOOLEAN (required) Example: true

    (Optional) The state of the JOB

    ACCOUNT_ID
    string (required) Example: act-12223456789

    (Optional) The Spotinst Account ID - required if not the default account for the Organization.


Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "sej-12345678",
    "resourceId": "fx-1234567",
    "action": "INVOKE_FUNCTION",
    "config": {
      "body": "foo",
      "queryParams": [
        {
          "key": "foo",
          "value": "bar"
        }
      ]
    },
    "isEnabled": true,
    "cronExpression": "0 23 * * *",
    "createdAt": "2017-02-10T15:49:11.911Z"
  },
  {....}
  ]

Create
POST/spectrum/events/job

Create a new Job.

Body parameters:

  • job - object - (required)
    Contains the Job properties

  • job.resourceId - string - (required)
    The Spotinst resource that the Job will affect. For example, if the job is “INVOKE_FUNCTION” then the resource id will be an id of a function.

  • job.action - string - (required)
    The Type of action. Currently we support “INVOKE_FUNCTION”

Config

  • job.config - object - (required)
    the config is a json object. for each action, the config will have different fields.

Config for INVOKE_FUNCTION action

  • job.config.body - string - (optional)
    The Body the function will recive

  • job.config.queryParams - opbject - (optional)
    The Query Params the function will recive in Key Value format

  • job.config.queryParams.key - String - (optional)
    the Key for the Parameter

  • job.config.queryParams.value - String - (optional)
    the value for the key

isEnabled

  • job.isEnabled - Boolean - (required)
    The state of the Job - true for enabling the Job

Cron

  • job.cronExpression - String - (required)
    The Cron Expression ("* * * * *") that will set the schedualing of the Job (does not support seconds). Please use [https://crontab.guru/] to validate you expression.

Example URI

POST https://api.spotinst.io/spectrum/events/job

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${TOKEN}
Body
{
  "job": {
    "resourceId": "fx-1234567",
    "action": "INVOKE_FUNCTION",
    "config": {
      "body": "foo",
      "queryParams": [
        {
          "key": "foo",
          "value": "bar"
        }
      ]
    },
    "isEnabled": true,
    "cronExpression": "0 23 * * *"
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "sej-12345678",
  "resourceId": "fx-1234567",
  "action": "INVOKE_FUNCTION",
  "config": {
    "body": "foo",
    "queryParams": [
      {
        "key": "foo",
        "value": "bar"
      }
    ]
  },
  "isEnabled": true,
  "cronExpression": "0 23 * * *",
  "createdAt": "2017-02-10T15:49:11.911Z"
}

Update
PUT/spectrum/events/job/{JOB_ID}

Update one or more parameters in your Job. Use the Job Json in the call body to update the Job. Only the specified fields will be affected.

Please note: while updating the config fields, the action property must be supplied in each update request and it cannot be updated. i.e it must be equal to the existing job’s action.


Example URI

PUT https://api.spotinst.io/spectrum/events/job/sej-12345678

Parameters

  • JOB_ID
    string (required) Example: sej-12345678

    (required) The Job id you want to update


Request  Update cron
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
        "job" : { 
            "cronExpression" : "30 * * * *"
    }

Request  Update config
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
    “job” : { 
        "action" : "INVOKE_FUNCTION" 
        "config": {
        "queryParams" : [
                {
                "key" : "Foo",
                "value" : "Bar"
                }, ..
                ],
}
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  }
}

List Job
GET/spectrum/events/job/{JOB_ID}

Describe a specific Job


Example URI

GET https://api.spotinst.io/spectrum/events/job/sej-12345678

Parameters

  • JOB_ID
    string (required) Example: sej-12345678

    (required) The Job id you want to get


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "sej-12345678",
  "resourceId": "fx-1234567",
  "action": "INVOKE_FUNCTION",
  "config": {
    "body": "foo",
    "queryParams": [
      {
        "key": "foo",
        "value": "bar"
      }
    ]
  },
  "isEnabled": true,
  "cronExpression": "0 23 * * *",
  "createdAt": "2017-02-10T15:49:11.911Z"
}

Delete
DELETE/spectrum/events/job/{JOB_ID}

Delete an existing balancer.


Example URI

DELETE https://api.spotinst.io/spectrum/events/job/sej-12345678

Parameters

  • JOB_ID
    string (required) Example: sej-12345678

    (required) The Job id you want to delete


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${TOKEN}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  }
}
Next  Previous


Functions

Spotinst Functions API Documentation

Welcome to Spotinst Functions API Documentation!

Welcome to the heart and soul of Spotinst Functions: our API, which allows you to manage and operate your functions using conventional RESTful API. Whatever you can do via our portal, you can also do via our API.

Except for content explicitly made available to the general public, access and use of this site and all content herein is restricted to users authorized by Spotinst and may be subject to confidentiality restrictions. Please also note that the information contained herein is for informational purposes only and to the extent it conflicts with the terms of your contractual agreements with Spotinst, the terms of those contracts will govern.

Application

List All
GET/functions/application?accountId={ACCOUNT_ID}

Describe all the applications and their full JSONs


Example URI

GET https://api.spotinst.io/functions/application?accountId=act-12345

Parameters

  • ACCOUNT_ID
    string (required) Example: act-12345

    (required) The account id.


Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "2",
  "items": [{
    "id": "app-12345",
    "name": "my first application",
  },
  {
    "id": "app-67890",
    "name": "my second application",
  }]                         
}

Create
POST/functions/application?accountId={ACCOUNT_ID}

Create a new application.

Body parameters:

  • name - string - (required)
    application name. must contain only alphanumeric characters or hyphens, and must not begin or end with a hyphen.

Example URI

POST https://api.spotinst.io/functions/application?accountId=act-12345

Parameters

  • ACCOUNT_ID
    string (required) Example: act-12345

    (required) The account id


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}
Body
{
  "application": {
    "name": "my application name"
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "1",
  "items": [
    {
      "id": "app-12345",
      "name": "my application name"
    }
  ]
}

Read
GET/functions/application/{APPLICATION_ID}?accountId={ACCOUNT_ID}

Describe a specific application


Example URI

GET https://api.spotinst.io/functions/application/app-12345?accountId=act-12345

Parameters

  • APPLICATION_ID
    string (required) Example: app-12345

    (required) The application id you want to view

    ACCOUNT_ID
    string (required) Example: act-12345

    (required) The account id.


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${TOKEN}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "1",
  "items": [{
    "id": "app-12345",
    "name": "my first application",
  }]                         
}

Environment

List All
GET/functions/environment?applicationId={APPLICATION_ID}&accountId={ACCOUNT_ID}

Describe all the environments and their full JSONs


Example URI

GET https://api.spotinst.io/functions/environment?applicationId=app-12345&accountId=act-12345

Parameters

  • APPLICATION_ID
    string (required) Example: app-12345

    (optional) Application id.

    ACCOUNT_ID
    string (required) Example: act-12345

    (required) The account id.


Request
HideShow
Headers
Authorization: Bearer ${TOKEN}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "2",
  items: [{
    "id": "env-12345",
    "name": "testing",
    "applicationId": "app-12345",
    "locations": [
        "us-east"
    ],
    "providers": [{
        "azure"
    }]
    },
    {
      "id": "env-98765",
      "name": "production",
      "applicationId": "app-12345",
      "locations": [
          "us-east"
      ],
      "providers": [{
          "azure"
      }]
    }
  ]  
}

Create
POST/functions/environment?accountId={ACCOUNT_ID}

Create a new environment

Body parameters:

General

  • name - string - (required)
    The name of the Environment. Must contain only alphanumeric characters or hyphens, and must not begin or end with a hyphen.

  • applicationId - string - (required) The id of the corresponding application

Preferences

  • locations - string - (required)
    A list of the request locations on which the function will be present

  • providers - string - (required)
    A list of the request cloud providers on which the function will be present


Example URI

POST https://api.spotinst.io/functions/environment?accountId=act-12345

Parameters

  • ACCOUNT_ID
    string (required) Example: act-12345

    (required) The account id.


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${TOKEN}
Body
{
  "environment": {
    "name": "testing",
    "applicationId": "app-5470a9fb",
    "preferences": {
      "locations": [
        "us-east",
        "eu-west"
      ],
      "providers": [
        "azure"
      ]
    }
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "1",
  "items": [
    {
      "id": "env-12345",
      "name": "testing",
      "applicationId": "app-5470a9fb",
      "preferences": {
        "locations": [
          "us-east",
          "eu-west"
        ],
        "providers": [
          "azure"
        ]
      }
    }
  ]
}

Read
GET/functions/environment/{ENVIRONMENT_ID}?accountId={ACCOUNT_ID}

Describe a specific environment


Example URI

GET https://api.spotinst.io/functions/environment/env-12345?accountId=act-12345

Parameters

  • ENVIRONMENT_ID
    string (required) Example: env-12345

    (required) The environment id you want to view

    ACCOUNT_ID
    string (required) Example: act-12345

    (required) The account id.


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "count": "1",
    items: [{
        "id": "env-12345",
        "name": "testing",
        "applicationId": "app-5470a9fb",
        "preferences": {
           "locations": [
               "us-east"
           ],
           "providers": [{
               "azure"
           }]
        }
    }]
  }

Function

List All
GET/functions/function?environmentId={Env_ID}&accountId={ACCOUNT_ID}

Describe all the user functions and their full JSONs


Example URI

GET https://api.spotinst.io/functions/function?environmentId=env-123456&accountId=act-12345

Parameters

  • Env_ID
    string (required) Example: env-123456

    (optional) The function environment

    ACCOUNT_ID
    string (required) Example: act-12345

    (optional) The account id.


Request
HideShow
Headers
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "2",
  "items": [{
    "Id": "fx-12345"
    "name": "my_first_function",
    "environmentId": "env-123456",
    "code": {
      "handler": "hello.HelloJava",
      "source": "INLINE",
    },
    "runtime": "java8",
    “limits": {
        "timeout": 60,
        "memory": 128
    },
    "environmentVariables": {
        "envTest":"abcdefg"
    },
    "url": "http://app-8f9x02-testing.execute-function.multai.io/fx-12345"
  },
  {
    "Id": "fx-98765"
    "name": "my_second_function",
    "environmentId": "env-123456",
    "code": {
      "handler": "main",
      "source": "INLINE",
    },
    "runtime": "nodejs48",
    "limits": {
       "timeout": 60,
       "memory": 128
     },
    "environmentVariables": null,
    "url": "http://app-8f9x02-testing.execute-function.multai.io/fx-98765"
  }]
}

Create
POST/functions/function?accountId={ACCOUNT_ID}

Create a new function.

Body parameters:

General

  • name - string - (required)
    The name of the Function. Must contain only alphanumeric characters or hyphens, and must not begin or end with a hyphen.

  • environmentId - string - (required) The id of the environment

  • runtime - string - (required) The type of the requested runtime

  • limits - object - (required) The Memory and Timeout settings

  • limits.timeout - int - (required) The timeout of the function invocation in seconds (max: 300)

  • limits.memory - int - (required) The memory of the function in units of 64Mb (max: 1536)

  • access - string - (Optional) Possible values: “public”, “private” - Where public indicates this function is configured to be executed without the token. default value: “private”

  • environmentVariables - map<string,string> - (Optional) Environment variables as key-value to be set on function context

Code

  • code.handler - string - (required)
    A pointer to the function main handler, should be in the format: ‘fileName.handlerName’. In Java - The class name including your main function, should be in the format: ‘className’.

  • code.source - string - (required)
    Base64 representation of the archived user code. For additional information about Functions templates please see: [https://help.spotinst.com/hc/en-us/articles/115004930285]


Example URI

POST https://api.spotinst.io/functions/function?accountId=act-12345

Parameters

  • ACCOUNT_ID
    string (required) Example: act-12345

    (required) The account id.


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${TOKEN}
Body
{
  "function": {
    "name": "my_first_function",
    "environmentId": "env-123456",
    "code": {
      "handler": "hello.HelloJava",
      "source": "{{base64}}"
    },
    "runtime": "java8",
    "limits": {
      "timeout": 60,
      "memory": 128
    },
    "access": "public",
    "environmentVariables": {
      "envTest": "abcdefg"
    }
  }
}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "count": "1",
  "items": [{
    "id": "fx-12345"
    "name": "my_first_function",
    "environmentId": "env-123456",
    "code": {
      "handler": "hello.HelloJava",
      "source": "INLINE",
    },
    "runtime": "java8",
    "limits": {
        "timeout": 60,
        "memory":128
    },
    "environmentVariables":{
        "envTest": "abcdefg"
    },
    "url": "http://app-8f9x02-testing.execute-function.multai.io/fx-12345"
  }]
}

Update
PUT/functions/function/{FUNCTION_ID}?accountId={ACCOUNT_ID}


Example URI

PUT https://api.spotinst.io/functions/function/env-12345?accountId=act-12345

Parameters

  • FUNCTION_ID
    string (required) Example: env-12345

    (required) The function id you want to update

    ACCOUNT_ID
    string (required) Example: act-12345

    (required) The account id.


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${TOKEN}
Body
{
  "function": {
    "code": {
      "handler": "hello.HelloJava",
      "source": "{{base64}}"
    },
    "runtime": "java8",
    "limits": {
      "timeout": 60,
      "memory": 128
    },
    "environmentVariables": {
      "envTest": "efg"
    }
  }
}

Response  200
HideShow
Headers
Content-Type: application/json

Get
GET/functions/function/{FUNCTION_ID}?accountId={ACCOUNT_ID}

Describe a specific function


Example URI

GET https://api.spotinst.io/functions/function/fx-12345?accountId=act-12345

Parameters

  • FUNCTION_ID
    string (required) Example: fx-12345

    (required) The function id you want to view

    ACCOUNT_ID
    string (required) Example: act-12345

    (required) The account id.


Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer ${token}

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": {
      "code": 200,
      "message": "OK"
  },
  "count": "1",
  "items": [{
    "id": "fx-12345"
    "name": "my_first_function",
    "environmentId": "env-123456",
    "code": {
      "handler": "hello.HelloJava",
      "source": "INLINE",
    },
    "runtime": "java8",
    "limits": {
        "timeout": 60,
        "memory"