fum 0.1.0

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+.idea
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,7 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in fum.gemspec
+gemspec
+
+#gem "fog", :git => "git://github.com/fog/fog.git"
+gem "fog", :path => "~/ruby/fog"

data/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) 2012 George Scott, RumbleWare Inc.
+
+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.rdoc

@@ -0,0 +1,219 @@
+
+fum is a tool for managing Amazon Web Services Elastic beanstalk lifecycle stages.  fum assists with the following:
+
+* Managing DNS changes associated with deployments
+* Application version management and deployment
+* Maintaing multiple lifecycle stages (test/staging/production) of an application.
+
+== Getting started
+
+fum is a Ruby DSL (Domain Specific Language) similar to rake, chef, and other tools.  You declare application lifecycle
+stages using the fum language, and then use the fum command to manage those stages.
+
+Installing fum is simple:
+
+  sudo gem install fum
+
+Create a file named +hello.fum+ with the following:
+
+  application_name 'HelloWorld'
+
+  stage :hello do
+    solution_stack "32bit Amazon Linux running Tomcat 7"
+  end
+
+Tell fum about your credentials by creating a file named +.fum+ in your home directory with your AWS credentials (Note,
+we recommend running these examples only in a development account until you are comfortable using fum):
+
+  access_key_id: <YOUR_ACCESS_KEY>
+  secret_access_key: <YOUR_SECRET_KEY>
+
+Now, let's go ahead and launch it:
+
+  fum hello.fum launch --create hello
+
+This command tells fum to launch a new environment using the "hello" stage definition you have provided in +hello.fum+.
+By default fum will not create new applications or versions, but if you specify the +--create+ flag, then fum will
+create the application and a sample version for you if none exists.  In this example, fum will create an application
+named "HelloWorld".  It will also create an environment named "hello" corresponding to the stage you specified.
+
+== Adding DNS support.
+
+The previous examle was simple, and possibly a time saver, but is not particularly interesting.  If you are developing
+an app on elastic beanstalk, you most likely don't want your end users to access your app using
+"example.elasticbeantalk.com" as the URL.  Instead, you most likely want them to access your app using your own
+hostname such as "www.example.com" or even "example.com" directly.  The most flexible way to accomplish this is to use
+AWS Route 53 which supports alias records that map a domain name to an elastic load balancer.  The example below shows
+how one can map a few different records types to an AWS Route 53 zone name 'example.com':
+
+  stage :hello do
+    solution_stack "32bit Amazon Linux running Tomcat 7"
+
+    zone 'example.com'
+      elb_alias :apex # Create an alias entry to the load balancer at the zone apex 'myapp.com.'
+      elb_alias 'www' # Create an alias entry to the load balancer at 'www.myapp.com.'
+      elb_cname 'www2' # Create a CNAME to the load balancer rather than an alias record.
+      cname 'www3' # Create a CNAME to the elastic beanstalk CNAME (useful when using swap cname feature)
+    end
+
+  end
+
+Each stage declaration can have multiple zones and each zone can declare multiple records to create/update when a stage
+is launched.  The +elb_alias+ directive provides a domain name that should be mapped, you can specify +:apex+ if you
+would like to map an alias to the zone apex, in this case 'example.com'.  The +elb_cname+ creates a CNAME record to
+the load balancer's DNS name, while the +cname+ record creates a CNAME record pointing to the elastic beanstalk
+environment's cname.
+
+To run this configuration create a zone named 'example.com' using the AWS Managmenent Console and run the following
+command:
+
+  fum hello_r53.fum launch hello
+
+When you run the command, you will notice a few differences in the output from before.  First, the newly created
+environment is
+
+As an alternative to using AWS Route 53, you can use elastic beanstalk's cname prefix and swapping features to manage
+your environments. This is configured as follows:
+
+  stage :hello do
+      solution_stack "32bit Amazon Linux running Tomcat 7"
+
+      cname_prefix "example", :swap => true
+    end
+
+The +cname_prefix+ declaration tells fum what prefix to request for the beanstalk environment when it is launched.
+By default, fum does not specify a prefix, and lets AWS assign a name dynamically.  If you specify a cname prefix,
+then you must ensure that the name is unique across all AWS customers.  You can also specify an option to +cname_prefix+
+to turn on cname swapping.  By specifying +:swap => true+ as an option, a newly launched environment will always try
+to take over the CNAME from any currently running environments.
+
+Let's try it (Note, if you want to run this sample, you will most likely need to pick a cname prefix other than
+"example" as it likely not available.):
+
+  fum hello_cname.fum launch hello
+
+Login to the AWS Management Console and observe your environment is launched correctly and has the correct CNAME, take
+note of the environment name created, and then launch another:
+
+  fum hello_cname.fum launch hello
+
+Afer the command is complete, login to the AWS Management Console and observe the newly created environemnt now
+is using the specified CNAME, while the previously created environment is using a dynamically assigned CNAME.
+
+
+== Multiple environments per stage
+
+Stages typically have only one elastic beanstalk environment active at any given time. However, fum uses multiple
+environments per stage combined with DNS to mask lifecycle changes from the end users of the application.  When
+deploying a new version of your application, or updaing an environment configuration, fum manages the environments
+and DNS records to provide a seamless rollout for your users.
+
+  stage :multi
+    solution_stack "32bit Amazon Linux running Tomcat 7"
+    name timestamp_name('multi')
+    matcher timestamp_name_matcher('multi')
+    description "Environment multi launched on #{Time.now}."
+
+  end
+
+The name directive tells fum what name to give an environment upon launch.  You can provide a string as an argument
+to the +name+ directive, but then fum will only be able to launch.
+
+Launch two instances:
+
+  fum multi.fum launch multi
+
+And the launch another:
+
+  fum multi.fum launch multi
+
+You can login to the AWS Managment Console to view them, but you can also use the fum list command as follow:
+
+  fum multi.fum status multi
+
+You will notice that the status command displays the name of each environment, followed by
+
+  fum multi.fm terminate --all multi
+
+This will terminate all environments that match the
+
+== Configuration templates
+
+  stage :production
+    template "production-config"
+  end
+
+  stage :latest
+    template "latest-config"
+  end
+
+== Version promotion
+
+Up to this point, we haven't talked about how fum handles application versions.  You can specify what version a
+particular stage uses using the +version+ directive as follows:
+
+  stage :last_release
+    version "last-release-label"
+  end
+
+If you run:
+
+  fum launch last_release
+
+It will launch an environment.
+In a typical application environment, you will
+
+  # An environment that whose version is automatically updated via a build server.
+  stage :build do
+    template 'build-config'
+
+    zone 'example.com'
+      elb_alas 'build' # build.myapp.com will point to this environment.
+    end
+  end
+
+  stage :staging do
+    template 'staging-config'
+
+    version :from_stage => :build
+
+    zone 'example.com'
+      elb_alias 'staging'
+    end
+  end
+
+  stage :production do
+    template 'produciton-config'
+
+    version :from_stage => :staging
+
+    zone 'example.com'
+      elb_alias :apex
+      elb_alias 'www'
+    end
+  end
+
+Let's launch it:
+
+
+In this example, the "build" stage is
+
+== Utility commands
+
+Fum also provides a number of utility commands to aid in manging elastic beanstalk.
+
+The *list* command allows you to list various beanstalk components.  For example:
+
+  fum list stacks # List all solutions stacks
+  fum list env # Lists all environments
+
+The *tail* command allows you to tail the event log
+
+  fum tail
+
+The *template* command allows for manipulating configuration templates
+
+== Why is the tool called "fum"?
+
+Because fum is the {final word}[http://en.wikipedia.org/wiki/Fee-fi-fo-fum] in managing your
+{AWS Elastic Beanstalk}[http://aws.amazon.com/elasticbeanstalk/] infrastructure.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/fum

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'fum'
+
+Fum::Application.new.start

data/examples/hello.fum

@@ -0,0 +1,6 @@
+
+application_name 'HelloWorld'
+
+stage :hello do
+  solution_stack "32bit Amazon Linux running Tomcat 7"
+end

data/fum.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "fum/version"
+
+Gem::Specification.new do |s|
+  s.name        = "fum"
+  s.version     = Fum::VERSION
+  s.authors     = ["George Scott", "RumbleWare Inc."]
+  s.email       = ["foss@rumbleware.com"]
+  s.homepage    = "http://github.com/rumbleware/fum"
+  s.summary     = "Management tool for AWS Elastic Beanstalk"
+  s.description = "fum helps you manage your AWS Elastic Beanstalk environments"
+
+  s.rubyforge_project = "fum"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  # s.add_development_dependency "rspec"
+  s.add_runtime_dependency "fog", "~>1.3.1"
+  s.add_runtime_dependency "trollop", "~>1.16.2"
+  s.add_runtime_dependency "json", "~>1.6.5"
+  #s.add_runtime_dependency "highline", "~>1.6.0"
+end

data/lib/fum.rb

@@ -0,0 +1,12 @@
+
+require 'fum/version'
+
+require 'fum/util'
+require 'fum/command_manager'
+require 'fum/command'
+require 'fum/dns'
+require 'fum/stage_analyzer'
+
+require 'fum/application'
+
+require 'pp'

data/lib/fum/application.rb

@@ -0,0 +1,117 @@
+
+require 'rubygems'
+require 'fum/lang/fum_file'
+require 'trollop'
+require 'fog'
+
+
+module Fum
+
+  def die(msg)
+    puts msg
+    exit 1
+  end
+
+  class Application
+    include CommandManager
+
+    attr_accessor :main_decl
+
+    command :events
+    command :launch
+    command :list
+    command :repair
+    command :status
+    command :tail
+    command :template
+    command :terminate
+
+    def start
+      global_options = process_command_line
+
+      @beanstalk = Fog::AWS[:beanstalk]
+
+      command = commands[@command_name.to_sym]
+
+      if global_options[:verbose]
+        puts "Loading definition file #{@filename}"
+      end
+
+      @main_decl = load_file(@filename)
+
+      if command
+        options = parse_command_options(@command_name.to_sym)
+        options.merge!(global_options)
+        run_command(@command_name.to_sym, options)
+      else
+        parser.die "Unknown command '#{@command_name}'", nil
+      end
+
+    end
+
+    def process_command_line
+      #global_options = Trollop::options do
+
+      sub_commands = commands.keys.map { |c| c.to_s }
+
+      parser = Trollop::Parser.new do
+        version "fum #{VERSION}"
+        banner <<-EOS
+usage: fum <filename> [options] <command> [command-options]
+
+Commands are (use --help after command to see additional usage):
+  launch
+  list
+
+where [options] are:
+        EOS
+
+        opt :credentials, "File containing AWS credentials to use", :type => :string
+        opt :noop, "Do nothing, print steps to be executed.", :default => false
+        opt :verbose, "Print verbose output.", :default => false
+        stop_on sub_commands #commands.keys.map { |c| c.to_s }
+      end
+
+      global_options = Trollop::with_standard_exception_handling parser do
+        o = parser.parse ARGV
+        raise Trollop::HelpNeeded if ARGV.empty?
+        @filename = ARGV.shift
+        raise Trollop::HelpNeeded if ARGV.empty?
+        @command_name = ARGV.shift
+        o
+      end
+
+      config = load_credentials
+
+      Fog.credentials = {
+          :aws_access_key_id => config[:access_key_id],
+          :aws_secret_access_key => config[:secret_access_key]
+      }
+
+      global_options
+    end
+
+
+    def load_file(filename)
+      Fum::Lang::FumFile.load(filename)
+    end
+
+    def load_credentials
+      require 'yaml'
+
+      config_file = File.expand_path('~/.fum')
+
+      options = YAML.load(File.read(config_file))
+
+      # Convert to symbols
+      options.each { |key, value|
+        options.delete(key)
+        options[key.to_sym] = value
+      }
+      options
+    end
+
+  end
+
+end
+

data/lib/fum/command.rb

@@ -0,0 +1,21 @@
+module Fum
+
+  class Command
+    include Fum::Util
+
+    def initialize(application)
+      @application = application
+    end
+
+    def parse_options
+      {}
+    end
+
+    # Return the stage declaration given app and name.
+    def stage(app, name)
+      app.stages[name.to_s] || die("Unknown stage '#{name}'")
+    end
+
+  end
+
+end