API Documentation

Since Gridspot is designed for large-scale compute, you'll need software to manage the instances as they are added and removed. The Gridspot API allows you to list compute instances.

API Keys

Each API call requires an API key to identify and authenticate your user account. You can create new API keys from your Account page. It will look like this: apikey_A2iG6Uvrug2B-qsmWuwX5g.

Listing Instances

To list all active instances, send an HTTP GET request to https://gridspot.com/compute_api/v1/list_instances?api_key=foo. Be sure to replace foo in the URL with your own API key.

The response body will be a JSON dictionary like the following:

    {
       "instances": [
          {
             "instance_id": "inst_vOsVC2U4DxcSi_P8XxTbQA",
             "vm_num_logical_cores": 4,
             "vm_num_physical_cores": 2,
             "winning_bid_id": "bid_iXwNYJzuF9DSy9GZDnKqvw",
             "vm_ram": 1891628851,
             "start_state_time": 1332208799,
             "vm_ssh_wan_ip_endpoint": null,
             "current_state": "Starting",
             "ended_state_time": null,
             "running_state_time": null
          },
          {
             "instance_id": "inst_-1EmFAq7moxi0mN_Lp5veA",
             "vm_num_logical_cores": 1,
             "vm_num_physical_cores": 1,
             "winning_bid_id": "bid_iXwNYJzuF9DSy9GZDnKqvw",
             "vm_ram": 698302218,
             "start_state_time": 1332198459,
             "vm_ssh_wan_ip_endpoint": "69.4.239.78:63922",
             "current_state": "Running",
             "ended_state_time": null,
             "running_state_time": 1332198622
          }
       ],
       "exception_name":""
    }
        

Many of the fields for each instance should be self explanitory. All times are in UNIX timestamp format. The possible states for instances are Starting, Running, or Ended.

Accessing Instances

Each running instance returned by list_instances provides an SSH IP endpoint that is an IPv4 public Internet address followed by a colon and a TCP port number. You'll be able to SSH into each instance using the private key corresponding to the public key you provided while creating the relevant bid. Log in as the user gridspot_user.

So, for example, to SSH into the second instance mentioned in the JSON example above, you would enter ssh gridspot_user@69.4.239.78 -p 63922 at the command line, assuming your SSH key is set up in your ~/.ssh folder.

Of course, you'll want to automate the process of sending commands to each new instance. We recommend doing this by periodically polling list_instances, identifying new running instances, and sending them a script to run using a command like ssh gridspot_user@xyz -p xyz 'bash' < local_script_file.sh.

Some points about each instance:

  • The gridspot_user user on each instance has root privileges.
  • Each instance starts in the same state each time. You may modify the instance however you wish.
  • Each instance can make outgoing HTTP, HTTPS, and SSH connections. Other ports are blocked. All network traffic is proxied through a central data center we maintain.
  • Each instance has an environment variable INSTANCE_ID set to the same instance_id returned by calls to list_instances. You can use this to distinguish between different instances from within scripts, for example if your script communicates with a central control server.
Stopping instances

Most bulk compute users won't want to deliberately stop instances, but you can stop instances if your use case requires it.

You can stop an instance by sending a GET, or POST, request to https://gridspot.com/compute_api/v1/stop_instance?api_key=foo&instance_id=bar where foo is your API key (as above) and bar is the id for the instance you'd like to stop.