EC2 library
CoffeeScript JavaScript
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
docs
lib
src
.gitignore
README.md
makefile
package.json

README.md

Features

  • Easily migrate images to other AWS regions
  • Mongodb-like terminal utility
  • Ability to chain ec2 commands
  • Built-in terminal helpers
    • ssh directly into instances via instances().find(query).limit(1).ssh()
    • ability to save key-pairs to disc via keyPairs().create(name).save()
    • make your own!
  • Support for key pair, instance, image, security group, and address APIs

TODO

  • ability to clone instances
  • spot requests
    • watch spot pricing

Terminal Usage

Usage: ectwo [commands...] -c [config] -p [profile] -r [regions]

Options:
  -r  regions to use        
  -i  interactive             [default: false]
  -c  configuration location  [required]  [default: "/usr/local/etc/ectwo/conf"]
  -p  profile to use          [required]  [default: "default"]

You'll first need to define your configuration file in /usr/local/etc/ectwo/conf.js. Here's a template:

module.exports = {
  "profiles": {
    "default": {
      "regions": ["us-east-1", "us-west-1"],
      "key": "AWS_KEY",
      "secret": "AWS_SECRET"
    },
    "another-profile": {
      "key": "AWS_KEY",
      "secret": "AWS_SECRET"
    }
  }
}

profiles are used to help ectwo determine what account to use.

Examples

Creating a new key-pair, and saving to disc:

$ ectwo -r us-east-1 "keyPairs().create('some-key').save()" ↩
------------------------------------

Profile: default
Regions: us-east-1

------------------------------------

us-east-1.keyPairs() 
us-east-1.keypairs.create("some-key") .. 2.79 s
us-east-1.some-key.save() 
[
  {
    "_id": "some-key",
    "name": "some-key",
    "region": "us-east-1",
    "fingerprint": "FINGERPRINT",
    "material": "MATERIAL"
  }
]
save keypair to /Users/craig/keys/us-east-1/some-key.pem

Finding all images across all regions:

$ ectwo -r us-east-1 "images().find()"
------------------------------------

Profile: default
Regions: us-west-1, us-west-2, us-east-1, eu-west-1, sa-east-1, 
ap-southeast-1, ap-southeast-2, ap-northeast-1

------------------------------------

us-west-1.images() 
us-west-2.images() 
us-east-1.images() 
eu-west-1.images() 
sa-east-1.images() 
ap-southeast-1.images() 
ap-southeast-2.images() 
ap-northeast-1.images() 
us-west-1.images.find() 
us-west-2.images.find() 
us-east-1.images.find() 
eu-west-1.images.find() 
sa-east-1.images.find() 
ap-southeast-1.images.find() 
ap-southeast-2.images.find() 
ap-northeast-1.images.find() 
[
  {
    "_id": "ami-4d6f2724",
    "state": "available",
    "ownerId": "258306512238",
    "isPublic": "false",
    "region": "us-east-1",
    "name": "test",
    "type": "machine",
    "kernelId": "aki-825ea7eb",
    "platform": "linux",
    "architecture": "x86_64",
    "virtualizationType": "paravirtual",
    "tags": {
      "abbaa": "ff",
      "fds": "fds",
      "abba": "fdsfs",
      "fdsfs": "fdsfs"
    }
  }
]

You can also run ectwo in interactive mode by adding the -i flag. For example:

$ ectwo -r us-east-1 -i ↩
------------------------------------

Profile: default
Regions: us-east-1

------------------------------------

> addresses().find({ instanceId: undefined }).one().attach("i-b43313de")
us-east-1.addresses() 
us-east-1.addresses.find({}) 
us-east-1.54.225.244.40.attach("i-b43313de") .. 2.50 s
[
  {
    "_id": "54.225.244.40",
    "publicIp": "54.225.244.40",
    "domain": "standard",
    "region": "us-east-1",
    "instanceId": "i-b43313de"
  }
]
> instances().find({ _id: "i-b43313de" }).pluck("address")
us-east-1.instances() 
us-east-1.instances.find({"_id":"i-b43313de"}) 
us-east-1.i-b43313de.pluck("address") 
[
  {
    "address": "54.225.244.40"
  }
]
>

Node API

ectwo(config)

  • config - configuration
    • regions - (optional) - regions to use
    • key - AWS key
    • secret - AWS secret
var ectwo = require("ectwo")({
  regions: ["us-east-1"],
  key: "AWS_KEY",
  secret: "AWS_SECRET"
});

Collections API

collection.findOne(query, cb)

Performs a search for an item. The query parameter expects a mongodb query.

//find all US regions
ectwo.regions.findOne({ name: "us-east-1" }, function (err, region) {
  
  //find all staging instances
  region.instances.find({ "tags.cluster": "staging" }, function(err, instances) {
    console.log(instances);
  });
});

collection.find(query, cb)

Finds multiple items

collection.wait(query, cb)

Wait for the query condition to be met before calling cb.

collection.reload(cb)

reloads the collection. Collections are cached by default.

Regions API

region.instances

instances collection

//return all instances
region.instances.all(function(err, instances) {
  
});

region.images

images collection

region.addresses

addresses collection

region.keyPairs

keyPairs in a region

region.securityGroups

security groups in a region

Instances API

instances.create(options, next)

creates one, or many instances

  • options
    • imageId - image ID to use
    • count - (optional) number of instances to create
    • keyName - (optional) key name to use
    • securityGroupId - (optional) security group ID to use
    • flavor - (optional) flavor of instance (t1.micro, m1.small, etc.)
instances.create({ tags: { type: "redis" }, imageId: "ami-id" }, function(err, instance) {
  console.log(instance.get("state")); //running
});

value instance.get(property)

returns a propertly value of the instance.

  • _id - id of the instance
  • imageId - the image id
  • region - the region this instance is in
  • state - the state of the instance. Possible states:
    • running - instance is running
    • pending - initializing
    • stopped - instance is stopped
    • terminated - instance is terminated
    • shutting-down - instance is shutting down
    • stopping - instance is stopping
  • type - the instance type (t1.micro, m1.medium, m1.small, etc.)
  • address - assigned address
  • dnsName - dns name
  • architecture - i386, x86_64
  • tags - instance tags (array)
    • key - tag key
    • value - tag value

instance.start(cb)

Starts an instance

instance.start(function() {
  console.log(instance.get("state")); //running
});

instance.stop(cb)

Stops an instance

instance.stop(function() {
  console.log(instance.get("state")); //stop
})

instance.restart(cb)

Restarts an instance

instance.restart(function() {
  console.log(instance.get("state")); //running
})

instance.destroy(cb)

Destroys an instance

instance.destroy(function() {
    console.log(instance.get("terminated")); 
});

instance.createImage(cb)

Creates an image out of the instance

instance.tag(key, value, cb)

Creates / deletes / updates tag.

//create
instance.tag("type", "mongodb", function() {
  
  //update
  instance.tag({ type: "another type" }, function() {
  
    //delete
    instance.tag("type", undefined, function() {
    });
  });
});

instance.address(cb)

Returns the address assigned to the instance. If no address is assigned, the result will be null.

instance.address(function(err, address) {
  console.log(address.get("publicIp"));
});

instance.image(cb)

returns the image associated with the instance

instance.image(function(err, image) {
  console.log("image");
});

instance.resize(type, cb)

resizes an instance

instance.resize("m1.small", function() {
  
});

instance.status(cb)

returns the status of the instance

Images API

value image.get(property)

  • _id - id of the image
  • region - the region this image is in
  • state - image state - pending, or completed
  • name - name of the image
  • type - type of image
  • kernelId - image kernel ID
  • platform - windows, or linux
  • architecture - i386, x86_64
  • descrption - description of the image
  • tags - image tags - same format as instances

image.migrate(regions, cb)

Migrates the image to another region

images.findOne({ _id: "ami-id" }, function(err, image) {
  image.migrate(["us-west-1", "us-west-2"], function(err, images) {
  });
});

image.createInstance(options, cb)

Creates an instance out of the image. Options are the same as instance.create.

Addresses API

addresses.create(cb)

creates a new address

region.addresses.create(function(err, address) {
  region.instances.findOne({ "tags.type": "site" }, function(err, instance) {
    address.attach(instance.get("_id"), function(err, result) {
    });
  });
});

value address.get(property)

  • _id - id of the address
  • publicIp - public IP
  • instanceId - the instance this address is assigned to

address.attach(instanceId, cb)

associates an address with an instance

address.detach(cb)

disassociate an address with an instance

instance.address(function(err, address) {
  address.detach(function(err) {
  });
});

Key Pair API

keyPairs.create(name, cb)

Creates a new key pair.

region.keyPairs.create("test", function(err, keyPair) {
  
  //put this somewhere safe
  console.log(keyPair.get("material")); 
});

value keyPair.get(property)

  • _id - the key pair ID
  • name - the key pair name
  • fingerPrint - the key pair finger print
  • region - the region this keyPair belongs to
  • material - the key material - only returned on keyPairs.create()

Security Group API

securityGroups.create(name, cb)

region.securityGroups.create("something", function(){});

value securityGroup.get(property)

  • _id - the security group ID
  • name - the security group name
  • descrption - the security group description
  • permissions - security group permissions

securityGroup.authorize(portOrOptions, cb);

securityGroup.authorize(4343, function(){});
securityGroup.authorize({ from: 8080, to: 8090 }, function(){});

securityGroup.revoke(portOrOptions, cb);

Opposite of authorize.

Chaining

ectwo also supports chaining. Here are a few examples:

//find ALL images, migrate them to us-west-2, then launch them
ectwo.chain().regions().find().images().find().migrate(["us-west-2"]).createInstance({ flavor: "m1.small" });

//stop redis instances
ectwo.chain().regions().find({ "tags.type": "redis" }).instances().stop()