eb_deployer 0.0.12 → 0.1.0

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2013 tworker
+Copyright (c) 2013 Thoughtworks Inc.
 
 MIT License
 
@@ -19,4 +19,4 @@ 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.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,6 +1,8 @@
 # EbDeployer
 
-TODO: Write a gem description
+Low friction deployments should be a breeze. Elastic Beanstalk provides a great foundation for performing Blue-Green deployments, and EbDeployer add a missing top to automate the whole flow out of box.
+
+ElasticBeanstalk Deployer thus allows you to do continuous delivery on AWS.
 
 ## Installation
 
@@ -18,7 +20,84 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Step One: AWS Account Setup
+
+Create an AWS IAM user for deploy and give it privilege to operate Elastic Beanstalk. Download the access keys for executing the deployment tasks later.
+
+### Step Two: Packaging
+
+You need package your application for Elastic Beanstalk stack first. For Java app an warball is appropriate. For Ruby on Rails app a tar.gz file is good. You can also package a Rails/Sinatra app as war ball using warbler and deploy to Java stack.
+
+
+### Step Three: Define the task
+Add a deploy task for deployment in your Rakefile
+
+    require 'digest'
+
+    desc "deploy our beloved app to elastic beanstalk"
+    task :deploy, [:package] do |t, args|
+      EbDeployer.deploy(:application => "MYAPP",
+                        :environment => "production",
+                        :solution_stack_name => <SOLUTION_STACK_NAME>
+                        :package => args[:package],
+                        :version_label => "dev-" + Digest::MD5.file(args[:package]).hexdigest)
+    end
+
+### Step Four: Fasten your seat belt
+run deploy task:
+
+    rake deploy[<package built>] AWS_ACCESS_KEY_ID=<deployers_aws_key> AWS_SECRET_ACCESS_KEY=<secret>
+Then open aws console for Elastic Beanstalk to see what happened.
+
+
+### Smoke Testing your stack
+
+EB_Deployer allows you to automate your deployment and then some. You can also add smoke tests to your deployment - thus ensuring that the app you deployed is also working correctly. 
+Adding a smoke test suite is also simple. All that you need to do is edit your rake task as follows:
+
+    desc "deploy our simple java app with one page"
+    task :deploy, [:package] do |t, args|
+      EbDeployer.deploy(:application => "MYAPP",
+                        :environment => "production",
+                        :solution_stack_name => <SOLUTION_STACK_NAME>
+                        :package => args[:package],
+                        :version_label => "dev-" + Digest::MD5.file(args[:package]).hexdigest)
+                        :smoke_test => lambda { |host|
+                          Timeout.timeout(600) do
+                            until `curl http://#{host}`.include?('Hello, World')
+                              sleep 5
+                            end
+                          end
+                        })
+    end                
+You can add more smoke tests by calling arbitrary tasks from this rake task.
+Smoke testing gets you one step closer to continuous delivery.
+                      
+### Blue-Green deployment
+Since every deployment now runs smoke test, you now have a better safety net around your deployments. This allows us to trigger automatic blue-green deployments. 
+
+To do this you need not do anything special. So far we have deployed the application only once. Let's call this the 'green' stack. Any subsequent calls to deployment will deployment a copy of this application to a new stack - the 'blue' stack. Smoke tests will be run on it and once everything passes the 'blue'(new) stack will be switched to the 'green' stack. Thus your new code will now be on the active stack and the user will experience no downtime. 
+
+Once this new stack is stable or has run for a while you can choose to delete the old stack. Or if you are doing continuous delivery you may be ready to another 'blue' deployment. You could just trigger another deployment and repeat this every hour/day/week... you get the idea.
+
+
+
+### Destroying a stack
+So you are done with this application or environment, you can destroy it easily as well.
+
+    desc "clean up everything"
+    task :teardown do |t, args|
+      EbDeployer.destroy(:application => "ebtest-simple")
+    end
+    
+and you are done!
+
+Later tutorials coming soon will cover
+* how to setup multiple environment suites: production, staging, and how to manage configurations for them
+* how to setup RDS or other AWS resource and share them between blue green environments
+
+Take a look at code if you can not wait for the documentation.
+
 
 ## Contributing
 

data/eb_deployer.gemspec

@@ -4,14 +4,14 @@ require File.expand_path('../lib/eb_deployer/version', __FILE__)
 Gem::Specification.new do |gem|
   gem.authors       = ["wpc", "betarelease"]
   gem.email         = ["alex.hal9000@gmail.com", "sudhindra.r.rao@gmail.com"]
-  gem.description   = %q{Elastic Beanstalk Deployer with different deployment strategies.}
-  gem.summary       = %q{Pick strategies like InplaceUpdate, Blue/Green.}
+  gem.description   = %q{For automate blue green deployment flow on Elasti Beanstalk.}
+  gem.summary       = %q{Low friction deployments should be a breeze. Elastic Beanstalk provides a great foundation for performing Blue-Green deployments, and EbDeployer add a missing top to automate the whole flow out of box.}
   gem.homepage      = "https://github.com/ThoughtWorksStudios/eb_deployer"
 
   gem.add_runtime_dependency 'aws-sdk'
   gem.add_development_dependency 'minitest'
 
-  gem.files         = `git ls-files`.split($\)
+  gem.files         = `git ls-files`.split($\).reject {|f| f =~ /^samples\// }
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.name          = "eb_deployer"

data/lib/eb_deployer.rb

@@ -28,6 +28,88 @@ module EbDeployer
     provisioner.output(key)
   end
 
+
+  #
+  # Options available:
+  #
+  # :application (required)
+  # Application name, this used for isolate packages and contribute
+  # to your elastic beanstalk cname for environments
+  #
+  # :environment (required)
+  # Environment for same application, e.g. testing, staging,
+  # production. This will map to 2 elastic beanstalk environments
+  # (env-a-xxx, env-b-xxx) if blue-green deployment strategy specified
+  #
+  # :package (required)        package for the application which should be
+  # suitable for elastic beanstalk deploying. For example, a war file
+  # should be provided for java solution stacks and a tar gz file
+  # should be provided for rails stack.
+  #
+  # :version_label (required)
+  # Version label give the package uploaded a unique identifier.
+  # Should use something related to pipeline counter if you have build
+  # pipeline setup to build the installer. For the convient of dev we
+  # recommend use md5 digest of the installer so that everytime you
+  # upload new installer it forms a new version. e.g.
+  #
+  #     :version_label => ENV['MY_PIPELINE_COUNTER']
+  #                      || "dev-" + Digest::MD5.file(my_package).hexdigest
+  #
+  # :solution_stack_name (optional default "64bit Amazon Linux running Tomcat 7")
+  # The elastic beanstalk solution stack you want to deploy on top of.
+  # Current possible values include:
+  #
+  # :settings  (optional)
+  # Elastic Beanstalk settings that will apply to the environments you
+  # deploying. Value should be array of hash with format such as:
+  #     [{
+  #        :namespace => 'aws:autoscaling:launchconfiguration',
+  #        :option_name => 'InstanceType',
+  #        :value => 'm1.small' }]
+  # When there are many, Using an external yaml file to hold those
+  # configuration is recommended. Such as:
+  #     YAML.load(File.read("my_settings_file.yml"))
+  # For all available options take a look at
+  # http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/command-options.html
+  #
+  # :resources (optional)
+  # If :resources specified, EBDeployer will use the CloudFormation
+  # template you provide to create a default CloudFormation stack with
+  # name <application_name>-<env-name> for the environment current
+  # deploying.  Value of resources need to be hash with following
+  # keys:
+  #    :template => CloudFormation template file with JSON format
+  #    :parameters => A Hash, input values for the CloudFormation
+  # template
+  #    :transforms => A Hash with key map to your CloudFormation
+  # template outputs and value as lambda that return a single or array of
+  # elastic beanstalk settings.
+  #    :capabilities => An array. You need set it to ['CAPABILITY_IAM']
+  # if you want to provision IAM Instance Profile.
+  #
+  # :smoke_test (optional)
+  # Value should be a proc or a lambda which accept single argument that will
+  # passed in as environment DNS name. Smoke test proc or lambda will be
+  # called at the end of the deployment for inplace-update deployment
+  # strategy. For blue-green deployment it will run after inactive
+  # environment update finish and before switching.
+  # Defining a smoke test is high recommended for serious usage. The
+  # simplest one could just be checking the server is up using curl, e.g.
+  #
+  #  :smoke_test => lambda { |host|
+  #    curl_http_code = "curl -k -s -o /dev/null -w \"%{http_code}\" https://#{host}"
+  #    Timeout.timeout(600) do
+  #      while `#{curl_http_code}`.strip != '200'
+  #        sleep 5
+  #      end
+  #    end
+  #  }
+  #
+  #
+  # deploy a package to specfied environments on elastic beanstalk
+  #
+
   def self.deploy(opts)
     # AWS.config(:logger => Logger.new($stdout))
     if region = opts[:region]
@@ -43,7 +125,7 @@ module EbDeployer
     version_label = opts[:version_label].to_s.strip
     cname = opts[:cname]
     env_settings = opts[:settings] || []
-    strategy_name = opts[:strategy] || :inplace_update
+    strategy_name = opts[:strategy] || :blue_green
     cname_prefix = opts[:cname_prefix] || [app, env_name].join('-')
     smoke_test = opts[:smoke_test] || Proc.new {}
 
@@ -64,4 +146,16 @@ module EbDeployer
     strategy.deploy(version_label, env_settings)
   end
 
+  def self.destroy(opts)
+    if region = opts[:region]
+      AWS.config(:region => region)
+    end
+
+    app = opts[:application]
+    bs = opts[:bs_driver] || Beanstalk.new
+    s3 = opts[:s3_driver] || S3Driver.new
+    cf = opts[:cf_driver] || CloudFormationDriver.new
+    Application.new(app, bs, s3).delete
+  end
+
 end

data/lib/eb_deployer/application.rb

@@ -17,6 +17,16 @@ module EbDeployer
       end
     end
 
+    def delete
+      if @eb_driver.application_exists?(@name)
+        @eb_driver.environment_names_for_application(@name).each do |env|
+          @eb_driver.delete_environment(@name, env)
+        end
+
+        @eb_driver.delete_application(@name)
+      end
+    end
+
     private
 
     def create_application_if_not_exists

data/lib/eb_deployer/beanstalk.rb

@@ -9,6 +9,10 @@ module EbDeployer
       @client.create_application(:application_name => app)
     end
 
+    def delete_application(app)
+      @client.delete_application(:application_name => app)
+    end
+
     def application_exists?(app)
       @client.describe_applications(:application_names => [app])[:applications].any?
     end
@@ -24,6 +28,10 @@ module EbDeployer
       alive_envs(app_name, [env_name]).any?
     end
 
+    def environment_names_for_application(app_name)
+      alive_envs(app_name).collect { |env| env[:environment_name] }
+    end
+
     def create_environment(app_name, env_name, stack_name, cname_prefix, version, settings)
       request = {:application_name => app_name,
         :environment_name => env_name,
@@ -34,6 +42,10 @@ module EbDeployer
       @client.create_environment(request)
     end
 
+    def delete_environment(app_name, env_name)
+      @client.terminate_environment(:environment_name => env_name)
+    end
+
     def create_application_version(app_name, version_label, source_bundle)
       @client.create_application_version(:application_name => app_name,
                                          :source_bundle => source_bundle,

data/lib/eb_deployer/version.rb

@@ -1,3 +1,3 @@
 module EbDeployer
-  VERSION = "0.0.12"
+  VERSION = "0.1.0"
 end

data/test/aws_driver_stubs.rb

@@ -10,6 +10,11 @@ class EBStub
     @apps << app
   end
 
+  def delete_application(app)
+    raise "there are environments running for this app" unless environment_names_for_application(app).empty?
+    @apps.delete(app)
+  end
+
   def application_exists?(app)
     @apps.include?(app)
   end
@@ -17,13 +22,19 @@ class EBStub
   def create_environment(app, env, solution_stack, cname_prefix, version, settings)
     raise 'cname prefix is not avaible' if @envs.values.detect { |env| env[:cname_prefix] == cname_prefix }
     raise "env name #{env} is longer than 23 chars" if env.size > 23
+    raise "app not exists" unless application_exists?(app)
     @envs[env_key(app, env)] = {
+      :application => app,
       :solution_stack => solution_stack,
       :version => version,
       :cname_prefix => cname_prefix,
       :settings => settings}
   end
 
+  def delete_environment(app, env)
+    @envs.delete(env)
+  end
+
   def update_environment(app, env, version, settings)
     @envs[env_key(app, env)].merge!(:version => version, :settings => settings)
   end
@@ -78,7 +89,16 @@ class EBStub
     @envs[env_key(app_name, env_name)][:settings]
   end
 
+  def environment_names_for_application(app)
+    @envs.inject([]) do |memo, pair|
+      env_name, env = pair
+      memo << env_name if env[:application] == app
+      memo
+    end
+  end
+
   private
+
   def env_key(app, name)
     [app, name].join("-")
   end

data/test/deploy_test.rb

@@ -19,6 +19,13 @@ class DeployTest < Minitest::Test
     assert @eb_driver.application_exists?('simple')
   end
 
+  def test_destroy_should_clean_up_eb_application_and_env
+    deploy(:application => 'simple', :environment => "production")
+    destroy(:application => 'simple')
+    assert !@eb_driver.application_exists?('simple')
+    assert !@eb_driver.environment_exists?('simple', eb_envname('simple', 'production'))
+  end
+
   def test_first_deployment_create_environment
     assert !@eb_driver.environment_exists?('simple', eb_envname('simple', 'production'))
     deploy(:application => 'simple', :environment => "production")
@@ -246,10 +253,20 @@ class DeployTest < Minitest::Test
 
   def deploy(opts)
     EbDeployer.deploy({:package => @sample_package,
-                        :bs_driver => @eb_driver,
-                        :s3_driver => @s3_driver,
-                        :cf_driver => @cf_driver,
-                        :version_label => 1}.merge(opts))
+                        :strategy => :inplace_update,
+                        :version_label => 1}.merge(opts).merge(stubs))
+  end
+
+  def destroy(opts)
+    EbDeployer.destroy(opts.merge(stubs))
+  end
+
+
+  def stubs
+    { :bs_driver => @eb_driver,
+      :s3_driver => @s3_driver,
+      :cf_driver => @cf_driver
+    }
   end
 
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: eb_deployer
 version: !ruby/object:Gem::Version
-  version: 0.0.12
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-08 00:00:00.000000000 Z
+date: 2013-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk
@@ -44,7 +44,7 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: Elastic Beanstalk Deployer with different deployment strategies.
+description: For automate blue green deployment flow on Elasti Beanstalk.
 email:
 - alex.hal9000@gmail.com
 - sudhindra.r.rao@gmail.com
@@ -91,10 +91,12 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
-summary: Pick strategies like InplaceUpdate, Blue/Green.
+summary: Low friction deployments should be a breeze. Elastic Beanstalk provides a
+  great foundation for performing Blue-Green deployments, and EbDeployer add a missing
+  top to automate the whole flow out of box.
 test_files:
 - test/aws_driver_stubs.rb
 - test/deploy_test.rb