Fork me on GitHub

Node EC2

Synopsis

Installing

Reference

ec2

createClient

AmazonEC2Client

call

poll

execute

"error"

"end"

Docco

amazon.coffee

request.coffee

response.coffee

Node EC2

Evended Node.js bindings to the EC2 Query API.

Synopsis

Node EC2 is a thin layer over the Amazon Query API.

Because node-ec2 is a thin layer over the Amazon Query API, you can use the Amazon API Reference to find your way around. Node EC2 calls translate directly to Amazon Query API.

Other than converting parameter maps to signed query strings and converting the XML responses to JSON objects, there is no syntactic sugar. See Rationale.

Here's an example using RunInstances.

var ec2 = require("ec2");

// Create an instance of the AmazonEC2Client.
var client = ec2.createClient(
{ key:      process.env["AWS_ACCESS_KEY_ID"]
, secret:   process.env["AWS_SECRET_ACCESS_KEY"]
});

// Track the progress of the API invocation in the lexical scope.
var instanceId, 
    reservationId;

// Call the "RunInstances" action to create a new EC2 instance. The Amazon Query
// API call will return immediately, but the instance will take a while to boot.
client.call("RunInstances", {
  ImageId: "ami-2d4aa444", KeyName: "launch_key"
}, function (response) {
  reservationId   = response.reservationId;
  instanceId      = response.instancesSet[0].instanceId;
});

// Therefore, we poll the  "DescribeInstances" action, calling it once every
// second until the instance state indicates that it is running.
client.poll("DescribeInstances", function (struct) {
  var reservation = struct.reservationSet.filter(function (reservation) {
    return reservation.reservationId == reservationId;
  })[0];
  var instance = reservation.instancesSet.filter(function (instance) {
    return instance.instanceId == instanceId;
  })[0];
  return instance.instanceState.name == "running";
});

// When all of the Amazon Query API calls and polls complete, we know that our
// Amazon EC2 instance is ready for use.
client.on("end", function () {
  console.log("Instance created with id: " + instanceId);
});

// Run the trasaction described above.
client.execute();

Installing

The easiest way to install is using npm.

npm install ec2

You can also checkout the source code for incusion in your NODE_PATH using git.

Reference

ec2

Node EC2 exports the ec2 namespace, which includes a single factory method to crate the Amazon EC2 Query API client object.

var ec2 = require("ec2");

ec2.createClient()

Creates an {{AmazonEC2Client}} object for use in

ec2.AmazonEC2Client()

Communicates with the Amazon Query API.

call(name[, parameters][, callback])

name

The Amazon EC2 Query API action to perform.

parameters

Named parameters for the Amazon EC2 Query API action.

callback

A callback function that is called with JSON object containing the Amazon EC2 Query API repsonse when the Amazon EC2 Query API action completes.

Call an Amazon Query API action.

poll(name[, parameters][, callback])

name

The Amazon EC2 Query API action to perform.

parameters

Named parameters for the Amazon EC2 Query API action.

callback

A callback function that is called with JSON object containing the Amazon EC2 Query API repsonse when the Amazon EC2 Query API action completes. If the callback function returns false the query is performed again.

Call an Amazon Query API action while a condition is false.

execute()

Run the query.

on("error", function (error, statusCode) {})

error

The error response structure.

statusCode

The HTTP status code for the error response.

Called when there is any error, both network errors, and exceptions thrown by callbacks, so that you have a chance to release instances if things go wrong.

on("end", function () {})

Called when all queries have completed successfully.