stem 0.2

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2010 Peter van Hardenberg
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,44 @@
+#Stem
+##EC2 made easy.
+
+##Introduction
+
+Stem is a thin, light-weight EC2 instance management library which abstracts the Amazon EC2 API and provides an intuitive interface for designing, launching, and managing running instances.
+
+Stem is named after the model it encourages -- simple AMIs created on demand with many running copies derived from that.
+
+##Usage
+
+You can use Stem to manage your instances either from the commandline or directly via the library. You should create an instance which will serve as your "stem" and be converted into an AMI. Once you have tested this instance, create a snapshot of the instance, then use it by name to launch new instances with their own individual configuration.
+
+Here's a simple example from the command line. Begin by launching the example prototype instance.
+
+    $ bin/stem launch chrysanthemum/postgres-prototype/config.json chrysanthemum/postgres-prototype/userdata.sh
+
+The config.json file specifies which AMI to start from, and what kind of EBS drive configuration to use. It is important that the drives are specified in the configuration file as any drives attached to the instance after launch will not become part of the eventual AMI you are creating 
+
+You can monitor the instance's fabrication process via
+
+    $ stem list
+
+The instance you created will boot, install some packages on top of a stock Ubuntu 10.4 AMI, then (if everything goes according to plan) shut itself down and go into a "stopped" state that indicates success. If any part of the stem fabrication fails, the instance will remain running. Once the instance reaches stopped, type
+
+    $ stem create postgres-server <instance-id>
+
+The AMI may take as long as half an hour to build, depending on how the gremlins in EC2 are behaving on any given day. You can check on their progress with
+
+    $ bin/amy
+
+If the AMI fabrication reaches the state "failed" you will have to manually reissue the `create` command and hope that the gremlins are more forgiving the second time around.
+
+Now that you have a simple postgres-server, you'll want to boot it up and create a database on it with some unique credentials! One of the simplest ways to solve this problem is to provide the instance with a templated userdata script which will perform per-instance configuration. I like mustache for this purpose.
+
+    $ mustache userdata.sh.yaml postgres-server/userdata.sh.mustache > postgres-server/userdata.sh
+    $ stem launch postgres-server/config.json postgres-server/userdata.sh
+
+You can, of course, delete the produced userdata.sh once the instance is launched.
+
+##Inspiration and Thanks
+
+Stem is almost entirely based on Orion Henry's Judo gem, and Blake Mizerany's work on variously patton, carealot, napkin, and several other experiments. Thanks also for feedback, testing and patches from Adam Wiggins, Mark McGranahan, Noah Zoschke, and Jason Dusek.
+

data/bin/stem

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+$:.unshift File.dirname(__FILE__) + "/../lib"
+require 'stem'
+
+# Help is the default.
+ARGV << '-h' if ARGV.empty? && $stdin.tty?
+
+# Process options
+Stem::CLI.parse_options(ARGV) if $stdin.tty?
+
+# Still here - run the command
+Stem::CLI.dispatch_command(ARGV.shift, ARGV)
+

data/lib/stem/cli.rb

@@ -0,0 +1,91 @@
+require 'optparse'
+
+module Stem
+  Version = 0.2
+
+  module CLI
+    extend self
+
+    # Return a structure describing the options.
+    def parse_options(args)
+      opts = OptionParser.new do |opts|
+        opts.banner = "Usage: stem COMMAND ..."
+
+        opts.separator " "
+
+        opts.separator "Examples:"
+        opts.separator "  $ stem launch prototype.config prototype-userdata.sh"
+        opts.separator "  $ stem list"
+        opts.separator "  $ stem create ami-name instance-id"
+
+        opts.separator " "
+        opts.separator "Options:"
+
+        opts.on("-v", "--version", "Print the version") do |v|
+          puts "Stem v#{Stem::Version}"
+          exit
+        end
+
+        opts.on_tail("-h", "--help", "Show this message") do
+          puts opts
+          exit
+        end
+      end
+
+      opts.separator ""
+
+      opts.parse!(args)
+    end
+
+    def dispatch_command command, arguments
+      case command
+        when "launch"
+          launch(*arguments)
+        when "create"
+          create(*arguments)
+        when "list"
+          list(*arguments)
+        when "describe"
+          describe(*arguments)
+        when "destroy"
+          destroy(*arguments)
+        when nil
+          puts "Please provide a command."
+        else
+          puts "Command \"#{command}\" not recognized."
+      end
+    end
+
+    def launch config_file = nil, userdata_file = nil
+      abort "No config file" unless config_file
+      userdata = File.new(userdata_file).read() if userdata_file
+      instance = Stem::Instance::launch(JSON.parse(File.new(config_file).read()), userdata)
+      puts "New instance ID: #{instance}"
+    end
+
+    def create name = nil, instance = nil
+      abort "Usage: create ami-name instance-to-capture" unless name && instance
+      image_id = Stem::Image::create(name, instance)
+      puts "New image ID: #{image_id}"
+    end
+
+    def describe what
+      require 'pp'
+      if (what[0..2] == "ami")
+        pp Stem::Image::describe(what)
+      elsif
+        pp Stem::Instance::describe(what)
+      end
+    end
+
+    def destroy instance = nil
+      abort "Usage: destroy instance-id" unless instance
+      Stem::Instance::destroy(instance)
+    end
+
+    def list *arguments
+      Stem::Instance::list(*arguments)
+    end
+  end
+end
+

data/lib/stem/image.rb

@@ -0,0 +1,25 @@
+module Stem
+  module Image
+    include Util
+    extend self
+
+    def create name, instance
+      description = {}
+      swirl.call("CreateImage", "InstanceId" => instance, "Name" => name, "Description" => "%%" + description.to_json)["imageId"]
+    end
+
+    def deregister image
+      swirl.call("DeregisterImage", "ImageId" => image)["return"]
+    end
+
+    def named name
+        i = swirl.call "DescribeImages", "Owner" => "self"
+        ami = i["imagesSet"].select {|m| m["name"] == name }.map { |m| m["imageId"] }.first
+    end
+
+    def describe image
+      swirl.call("DescribeImages", "ImageId" => image)["imagesSet"][0]
+    end
+  end
+end
+

data/lib/stem/instance.rb

@@ -0,0 +1,111 @@
+module Stem
+  module Instance
+    include Util
+    extend self
+
+    def launch config, userdata = nil
+      throw "No config provided" unless config
+
+      ami = nil
+      if config["ami"]
+        ami = config["ami"]
+      elsif config["ami-name"]
+        ami = Image::named(config["ami-name"])
+        throw "AMI named #{config["ami-name"]} was not found. (Does it need creating?)" unless ami
+      end
+      throw "No AMI specified." unless ami
+
+      opt = {
+        "MinCount" => "1",
+        "MaxCount" => "1",
+        "KeyName" => config["key_name"] || "default",
+        "InstanceType" => config["instance_type"] || "m1.small",
+        "ImageId" => ami
+      }
+      if config["availability_zone"]
+        opt.merge! "Placement.AvailabilityZone" => config["availability_zone"]
+      end
+
+      if config["volumes"]
+        devices = []
+        sizes = []
+        config["volumes"].each do |v|
+          puts "Adding a volume of #{v["size"]} to be mounted at #{v["device"]}."
+          devices << v["device"]
+          sizes << v["size"].to_s
+        end
+
+        opt.merge! "BlockDeviceMapping.#.Ebs.VolumeSize" => sizes,
+                   "BlockDeviceMapping.#.DeviceName" => devices
+      end
+
+      if userdata
+        puts "Userdata provided, encoded and sent to the instance."
+        opt.merge!({ "UserData" => Base64.encode64(userdata)})
+      end
+
+      response = swirl.call "RunInstances", opt
+
+      puts "Success!"
+      response["instancesSet"].each do |i|
+        return i["instanceId"]
+      end
+    end
+    def restart instance_id
+      swirl.call "RebootInstances", "InstanceId" => instance_id
+    end
+
+    def destroy instance_id
+      swirl.call "TerminateInstances", "InstanceId" => instance_id
+    end
+
+    def stop instance_id
+      swirl.call "StopInstances", "InstanceId" => instance_id
+    end
+
+    def describe instance
+      throw "You must provide an instance ID to describe" unless instance
+      swirl.call("DescribeInstances", "InstanceId" => instance)["reservationSet"][0]["instancesSet"][0]
+    end
+
+    def list
+      instances = swirl.call("DescribeInstances")
+
+      lookup = {}
+      instances["reservationSet"].each do |r|
+        r["instancesSet"].each do |i|
+          lookup[i["imageId"]] = nil
+        end
+      end
+      amis = swirl.call("DescribeImages", "ImageId" => lookup.keys)["imagesSet"]
+
+      amis.each do |ami|
+        name = ami["name"] || ami["imageId"]
+        if !ami["description"] || ami["description"][0..1] != "%%"
+          # only truncate ugly names from other people (never truncate ours)
+          name.gsub!(/^(.{8}).+(.{8})/) { $1 + "..." + $2 }
+          name = "(foreign) " + name
+        end
+        lookup[ami["imageId"]] = name
+      end
+
+      puts "------------------------------------------"
+      puts "Instances"
+      puts "------------------------------------------"
+      instances["reservationSet"].each do |r|
+        r["instancesSet"].each do |i|
+            name = lookup[i["imageId"]]
+            puts "%-15s %-15s %-15s %s" % [ i["instanceId"], i["ipAddress"] || "no ip", i["instanceState"]["name"], name
+        end
+      end
+
+      puts "------------------------------------------"
+      puts "AMIs"
+      puts "------------------------------------------"
+      images = c.call "DescribeImages", "Owner" => "self"
+      images["imagesSet"].each do
+        puts "%-15s %s" % [ img["name"], img["imageId"] ]
+      end
+    end
+  end
+end

data/lib/stem/ip.rb

@@ -0,0 +1,19 @@
+module Stem
+  module Ip
+    include Util
+
+    extend self
+    def allocate
+      swirl.call("AllocateAddress")["publicIp"]
+    end
+
+    def associate ip, instance
+      result = swirl.call("AssociateAddress", "InstanceId" => instance, "PublicIp" => ip)["return"]
+      result == "true"
+    end
+
+    def release ip
+      result = swirl.call("ReleaseAddress", "PublicIp" => ip)
+    end
+  end
+end

data/lib/stem/util.rb

@@ -0,0 +1,11 @@
+module Stem
+  module Util
+    def swirl
+      @swirl ||= Swirl::EC2.new(
+        :aws_access_key_id => ENV['AWS_ACCESS_KEY_ID'],
+        :aws_secret_access_key => ENV['AWS_SECRET_ACCESS_KEY']
+      )
+    end
+  end
+end
+

data/lib/stem.rb

@@ -0,0 +1,11 @@
+$:.unshift File.dirname(__FILE__)
+
+require 'swirl'
+require 'json'
+
+require 'stem/cli'
+require 'stem/util'
+require 'stem/instance'
+require 'stem/image'
+require 'stem/ip'
+

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification 
+name: stem
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  version: "0.2"
+platform: ruby
+authors: 
+- Peter van Hardenberg
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-08-12 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: swirl
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 5
+        - 2
+        version: 1.5.2
+  type: :runtime
+  version_requirements: *id001
+description: minimalist EC2 instance management
+email: 
+- pvh@heroku.com
+executables: 
+- stem
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- LICENSE
+- README.md
+- lib/stem/cli.rb
+- lib/stem/image.rb
+- lib/stem/instance.rb
+- lib/stem/ip.rb
+- lib/stem/util.rb
+- lib/stem.rb
+has_rdoc: true
+homepage: http://github.com/pvh/stem
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 2
+summary: an EC2 instance management library designed to get out of your way and give you instances
+test_files: []
+