The Spotinst package allows you to create, manage and destroy Spotinst ElastiGroups.

Environment Variables

SPOTINST_DEBUG:If set, then every single response body from Spotinst will be printed out in the debug logs for Kingpin. This can include credentials, and can be extremely verbose, so use with caution.
SPOINST_TOKEN:SpotInst API Token generated at
 SpotInst API Account ID - used optionally when you have multiple accounts under a single Organization. This can also be set on a per-actor basis.,header:header-organizations-with-a-single-account


class kingpin.actors.spotinst.ElastiGroupSchema[source]

Light validation against the Spotinst ElastiGroup schema.

For full description of the JSON data format, please see:

This schema handles the following validation cases:

  • Only allow a single SubnetID for each availabilityZone object.
  • Disallow t2|hc1 instance types for the spot instance section.
  • Ensure that the scaling.up and scaling.down arrays are either null or contain at least 1 record.
class kingpin.actors.spotinst.ElastiGroup(*args, **kwargs)[source]

Manages an ElastiGroup in Spotinst.

Spotinst ElastiGroups act as smarter EC2 AutoScalingGroups that scale up and down leveraging Amazon Spot instances wherever possible. These ElastiGroups are completely configurable through a JSON Blob.

For a fully functional example JSON config, see this one. You can also write your files in YAML if you prefer – Kingpin will handle the conversion.

UserData Startup Script

The Spotinst API wants the instances UserData script to be supplied as a Base64-encoded string – which you can do if you wish. However, there is no need, as Kingpin will automatically convert your plain-text script into a Base64 blob for you behind the scenes.

Rolling out Group Changes

We will trigger the “roll group” API if the roll_on_change parameter is set to True after any change to an ElastiGroup. It is difficult to know which changes may or may not require a replacement of your existing hosts, so we leave this up to the user to decide on the behavior.

Known Limitations

  • The Spotinst API does not allow you to change an ElastiGroup scaling ‘unit’ (ie, CPU Count or Instance Count). You can also not change an ElastiGroup’s basic platform (ie, VPC Linux vs Non VPC Linux). We warn about this on each change.



The desired name of the ElastiGroup. Note that this will override whatever value is inside your configuration JSON/YAML blob.


The SpotInst Account ID that the action is taking place in - this overrides the SPOTINST_ACCOUNT_ID environment variable (if its set).


Path to the ElastiGroup configuration blob (JSON or YAML) file. Token-replacement can be used inside of your configuration files allowing environment variables to replace %VAR% strings.

This file will be checked against a light-schema defined in ElastiGroupSchema before any authentication is required. The file will be further validated against the Spotinst API during the DRY run, but this requires authentication.


A dict of key/value pairs that can be used to swap in variables into a common ElastiGroup template. These are added to (and override) the Environment variables that Kingpin already uses for variables swapping (as described in the Token-replacement section.


Whether or not to forcefully roll out changes to the ElastiGroup. If True, we will issue a ‘roll call’ to SpotInst and trigger all of the instances to be replaced. Defaults to False.


Indicates in percentage the amount of instances should be replaced in each batch. Defaults to 20.


Indicates in seconds the timeout to wait until instance become healthy in the ELB. Defaults to 600.


If set to True, Kingpin will loop until the ElastiGroup has fully launched – this only applies if the group is being created from scratch. On updates, see the wait_on_roll setting below. Defaults to False.


If set to True, Kingpin will loop until the rollout of any changes has completed. This can take a long time, depending on your rollout settings. Defaults to False.


{ "actor": "spotinst.ElastiGroup",
  "options": {
    "name": "my-group",
    "config": "./group_config.json",

Dry Mode

Will discover the current state of the ElastiGroup (present, absent), and whether or not the current configuration is different than the desired configuration. Will also validate the desired configuration against the SpostInst API to give you a heads up about any potential failures up front.