aws-ec2 0.8.4 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ecc2b042e1fabbb3a4a343edb5766601a51e54259f5029c19d37f93ebed7443
-  data.tar.gz: d0a388114c37362c2f8b1590f71d1e2d16d54dee0631bd36a42c9f5ed89fd877
+  metadata.gz: 195f128cedbd5bf833767064b92f8f0a81fa3cc24ae131d9a932a7b714e7e3b3
+  data.tar.gz: 408ad9efbdbcbc7008db3267cf7ed68617bb01c437ffd8d4b410dfe43dfd0516
 SHA512:
-  metadata.gz: c77a9ba413bec00c46b387370df141d10e64286ac94689c194437ff0aeecd3e8ccfbcb50a548549090344df3628affe8210014a4c902e40466da4360cc66bb6a
-  data.tar.gz: 63e9c1864910f2a8c7d57a7005e64297272e6c1764642c29ba55fde4722073d46fd854a5f6afe7f08763e47f9d454e66fafdd790ff4599660dc02a1723738a67
+  metadata.gz: 06af930c02065bcd7a88a3c14ba72c0716738faa663c8cd59cba9900719614d7bb328b84620d41dd4823aed56333dcccf19261c9ca11c988fdcf162991bfaebf
+  data.tar.gz: e13dd0da82d53d71ab2fe955e08ac7f1fe622981024361f1c926475159e7c4749d28a92e9ade7aa258ba92398f605a327da26b41674f29191b6857a2cf44e83b

data/CHANGELOG.md

@@ -3,6 +3,11 @@
 All notable changes to this project will be documented in this file.
 This project *tries* to adhere to [Semantic Versioning](http://semver.org/), even before v1.0.
 
+## [0.9.0]
+- much improved error messaging
+- rename docs folder
+- update readme
+
 ## [0.8.4]
 - add doc/example
 - rename to commands to compile and upload

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    aws-ec2 (0.8.3)
+    aws-ec2 (0.8.4)
       activesupport
       aws-sdk-ec2
       colorize

data/README.md

@@ -12,20 +12,7 @@ Example:
 aws-ec2 create myserver --profile myserver
 ```
 
-In a nutshell, the profile parameters are passed to the ruby aws-sdk [AWS::EC2::Client#run_instances](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/EC2/Client.html#run_instances-instance_method) method.  This allows you to specify any parameter you wish that is available in the aws-sdk. To check out what a profile looks like check out [example default](example/profiles/default.yml)
-
-You can use ERB in the profile files. Some useful helper methods are documented here:
-
-Helper  | Description
-------------- | -------------
-user_data | Allows you to embed a generated user_data script.  More details on the user-data are provided in the user data section below.
-config | Access to the variables set in config/[AWS_EC2_ENV].yml.  Examples are `config/development.yml`, `config/staging.yml`, and `config/production.yml`.
-latest_ami | Returns an AMI id by searching the ami name pattern and sorting in reverse older.  Example: `latest_ami("ruby-2.5.0_*")` would return the latest ruby AMIs are named with timestamps at the end like so: `ruby-2.5.0_2018-01-30-05-36-02` and `ruby-2.5.0_2018-01-29-05-36-02`.
-search_ami | Returns a collection of AMI image objects based on a search pattern. The query searches on the AMI name.
-
-For a full list of all the template helpers checkout: [aws_ec2/template_helper](lib/aws_ec2/template_helper).
-
-You can also define custom helpers in the `app/helpers` folder as ruby modules with the naming convention `*_helper.rb`.  Example, you would define a `module FooHelper` in `app/helpers/foo_helper.rb`.  Custom helpers are first-class citizens and have access to the same variables, methods and scope as built-in helpers.
+In a nutshell, the profile parameters are passed to the ruby aws-sdk [AWS::EC2::Client#run_instances](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/EC2/Client.html#run_instances-instance_method) method.  This allows you to specify any parameter you wish that is available in the aws-sdk. To check out what a profile looks like check out [example default](docs/example/profiles/default.yml)
 
 ## Noop mode
 
@@ -40,13 +27,28 @@ cat tmp/user-data.txt # to view generated user-data script
 
 Directory  | Description
 ------------- | -------------
-app/helpers  | Custom helpers methods.  Define them as modules and their methods available whenever ERB is available: `config`, `profiles`, `app/scripts`, `app/user-data` files, etc. Example, you would define a `module FooHelper` in `app/helpers/foo_helper.rb`.
-app/partials  | Your partials that can be use to be included in other scripts.  This is used in conjunction with the `partial` helper method.
+app/helpers  | Custom helpers methods.  Define them as modules and their methods are made available whenever ERB is available: `profiles`, `app/scripts`, `app/user-data` files, etc. For example, you would define a `module FooHelper` in `app/helpers/foo_helper.rb`.
+app/partials  | Your partials that can to be included in other scripts.  This is used in conjunction with the `partial` helper method.
 app/scripts  | Where you define common scripts that can be used to configure the server. These scripts can be automatically uploaded to an s3 bucket for later downloading in your user-data script by setting the `scripts_s3_bucket` config option.
 app/user-data  | Your user-data scripts that are used to bootstrap EC2 instance.
-config/[AWS_EC2_ENV].yml  | The config file where you set configs that you want available in your templating logic.  Examples are: `config/development.yml`, `config/staging.yml`, or `config/production.yml`. You access the config with the `<%= config["var"] %>` helper.
-profiles  | Your profile files.  These files mainly contain parameters that are passed to the aws-sd2 run_instances API.
-tmp  | Where the generated scripts get compiled to. You can manually invoke the complilation via `aws-ec2 compile` if you wish to inspect what is generated, though this is automatically done as part of the `aws-ec2` create command.
+config/[AWS_EC2_ENV].yml  | The config file where you set configs that you want available in your templating logic.  Examples are: `config/development.yml` and `config/production.yml`. You access the config variables with the `<%= config["var"] %>` helper.
+profiles  | Your profile files.  These files mainly contain parameters that are passed to the aws-sd2 run_instances API method.
+tmp  | Where the generated scripts get compiled to. You can manually invoke the complilation via `aws-ec2 compile` to inspect what is generated.  This is automatically done as part of the `aws-ec2` create command.
+
+## Helpers
+
+You can use ERB in the profile files. Some useful helper methods are documented here:
+
+Helper  | Description
+------------- | -------------
+user_data | Allows you to embed a generated user_data script.  More details on the user-data are provided in the user data section below.
+config | Access to the variables set in config/[AWS_EC2_ENV].yml.  Examples are `config/development.yml` and `config/production.yml`.
+latest_ami | Returns an AMI id by searching the AMI name pattern and sorting in reverse older.  Example: `latest_ami("ruby-2.5.0_*")` would return the latest ruby AMIs are named with timestamps at the end like so: `ruby-2.5.0_2018-01-30-05-36-02` and `ruby-2.5.0_2018-01-29-05-36-02`.
+search_ami | Returns a collection of AMI image objects based on a search pattern. The query searches on the AMI name.
+
+For a full list of all the template helpers check out: [aws_ec2/template_helper](lib/aws_ec2/template_helper).
+
+You can also define custom helpers in the `app/helpers` folder as ruby modules with the naming convention `*_helper.rb`.  For example, you would define a `module FooHelper` in `app/helpers/foo_helper.rb`.  Custom helpers are first-class citizens and have access to the same variables, methods, and scope as built-in helpers.
 
 ## User-Data
 
@@ -54,20 +56,20 @@ You can provide a user-data script to customize the server upon launch.  The use
 
 * app/user-data/myserver.yml
 
-The user-data script is generated on the machine that is running the aws-ec2 command. If this is your local macosx machine, then the context of your local macosx machine is available. To see the generated user-data script, you can use the run the create command in noop mode and then inspect the generated script.  Example:
+The user-data script is generated on the machine that is running the aws-ec2 command. If this is your local macosx machine, then the context of your local macosx machine is available. To see the generated user-data script, you can run the create command in noop mode and then inspect the generated script.  Example:
 
 ```sh
 aws-ec2 create myserver --noop
-cat /tmp/aws-ec2/user-data.txt
+cat tmp/user-data.txt
 ```
 
-Another way of viewing the generated user-data scripts is the `aws-ec2 compile` command.  It generates the files in the tmp folder.  Example:
+Another way to view the generated user-data scripts is the `aws-ec2 compile` command.  It generates the files in the tmp folder.  Example:
 
 ```
 aws-ec2 compile # generates files in tmp folder
 ```
 
-To use the user-data script when creating an EC2 instance, you use the `user_data` helper method in the profile.  Here's a grep of an example profile that uses the helper to show you want it looks like:
+To use the user-data script when creating an EC2 instance, use the `user_data` helper method in the profile file.  Here's a grep of an example profile that uses the helper to show you want it looks like. Be sure to surround the ERB call with quotes because the user-data script context is base64 encoded.
 
 ```
 $ grep user_data profiles/default.yml
@@ -76,12 +78,12 @@ user_data: "<%= user_data("bootstrap") %>"
 
 ### Config
 
-You can set variables in a config file and they are available when ERB is available, which are your profiles, user_data, scripts, etc.  Example `config/development.yml`:
+You can set variables in a config file and they are available when ERB is available: profiles, user-data, scripts, etc.  Example `config/development.yml`:
 
 ```yaml
 ---
 vpc_id: vpc-123
-db_subnet_group_name: default
+subnets:
   - subnet-123
   - subnet-456
   - subnet-789
@@ -92,7 +94,7 @@ scripts_s3_bucket: mybucket # enables s3 uploading of generated app/scripts
                       # compiled scripts in tmp after aws-ec2 create
 ```
 
-The variables are accessed via the `config` helper method. Here's a filtered example where it shows shows the relevant part of a profile: `profiles/default.yml`:
+The variables are accessed via the `config` helper method. Here's a filtered example where it shows the relevant part of a profile: `profiles/default.yml`:
 
 ```yaml
 image_id: ami-4fffc834 # Amazon Lambda AMI
@@ -108,15 +110,11 @@ There are some config options that change the behavior of the ec2-aws:
 
 Option | Description
 --- | ---
-scripts_s3_bucket | Set this to the bucket name where you want the generated scripts in app/scripts and app/user-data to be automatically sync.  The sync happens right before the the internal call to run_instances that launches the instance.  If you need more custom logic, you can use the `before_run_instances` hook, covered in the Hooks section.
-
-## Dotenv File Support
-
-You can set and configure environment variables in `.env*` files.  Examples of this is in the [doc/example](doc/example) project.
+scripts_s3_bucket | Set this to the bucket name where you want the generated scripts in app/scripts and app/user-data to be uploaded to.  The upload sync happens right before the internal to run_instances call that launches the instance.  If you need more custom logic, you can use the `before_run_instances` hook, covered in the Hooks section.
 
 ### Hooks
 
-There is only one hook: before_run_instances.  You can configure this with `config/hooks.yml`:  Example:
+There is only one hook: `before_run_instances`.  You can configure this with `config/hooks.yml`:  Example:
 
 ```
 ---
@@ -125,11 +123,21 @@ before_run_instances: /path/to/my/script.sh
 
 This will run `/path/to/my/script.sh` as a shelled out command before the `run_instances` call.
 
+## Dotenv File Support
+
+You can set and configure environment variables in `.env*` files.  Examples of this are in the [example](docs/example) project.
+
 ## AMI Creation
 
-To create AMIs you can use the `aws-ec2 ami` command.  This command launches an EC2 instance with the specified profile and create an AMI after the user-data script completes successfully. It does this by adding an AMI creation script at the end of the user-data script.  It is recommended to use the `set -e` option so that any error halts the script and the AMI does not get created.
+To create AMIs you can use the `aws-ec2 ami` command.  This command launches an EC2 instance with the specified profile and creates an AMI after the user-data script successfully completes. It does this by appending an AMI creation script at the end of the user-data script.  It is recommended to use the `set -e` option in your user-data script so that any error halts the script and the AMI does not get created.
+
+After the AMI is successfully created, the instance will also terminate itself automatically so you do not have to worry about cleanup.  This is also done with an appended script. For more help run `aws-ec2 ami help`.
+
+For the instance to image and terminate itself, the EC2 IAM role for the instance requires IAM permissions for:
 
-After the AMI is created successfully, the instance will also terminate itself automatically so you do not have to worry about cleanup.  For more help run `aws-ec2 ami help`.
+* aws ec2 create-image
+* aws ec2 cancel-spot-instance-requests # in case a spot instance was used
+* aws ec2 terminate-instances
 
 ## Spot Instance Support
 
@@ -138,7 +146,7 @@ Spot instance is natively supported by the AWS run_instances command.  So, simpl
 * [https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_LaunchTemplateSpotMarketOptionsRequest.html](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_LaunchTemplateSpotMarketOptionsRequest.html)
 * [https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/EC2/Types/SpotMarketOptions.html](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/EC2/Types/SpotMarketOptions.html)
 
-An example of a spot instance profile is provided in [doc/example/profiles/spot.yml](doc/example/profiles/spot.yml).
+An example of a spot instance profile is provided in [example/profiles/spot.yml](docs/example/profiles/spot.yml).
 
 ## More Help
 
@@ -149,7 +157,7 @@ aws-ec2 compile help
 aws-ec2 help # general help
 ```
 
-Examples are in the [doc/example](doc/example) folder.  You will have to update settings like your subnet and security group ids.
+Examples are in the [example](docs/example) folder.  You will have to update settings like your subnet and security group ids.
 
 ## Installation
 
@@ -159,7 +167,7 @@ gem install aws-ec2
 
 ### Dependencies
 
-This tool mainly uses the ruby aws-sdk but it does use the aws cli to check your region: `aws configure get region`. So it is dependent on the the `aws cli`.
+This tool mainly uses the ruby aws-sdk. Though it does use the aws cli to check your region: `aws configure get region`. It also the uses `aws s3 sync` to perform the scripts upload. So it is dependent on the the `aws cli`.
 
 ## Contributing
 

data/lib/aws_ec2/create.rb

@@ -4,8 +4,10 @@ require 'active_support/core_ext/hash'
 module AwsEc2
   class Create < Base
     autoload :Params, "aws_ec2/create/params"
+    autoload :ErrorMessages, "aws_ec2/create/error_messages"
 
     include AwsServices
+    include ErrorMessages
 
     def run
       puts "Creating EC2 instance #{@options[:name]}..."
@@ -17,11 +19,17 @@ module AwsEc2
 
       Hook.run(:before_run_instances, @options)
       sync_scripts_to_s3
-      resp = ec2.run_instances(params)
+      run_instances(params)
       puts "EC2 instance #{@options[:name]} created! 🎉"
       puts "Visit https://console.aws.amazon.com/ec2/home to check on the status"
     end
 
+    def run_instances(params)
+      resp = ec2.run_instances(params)
+    rescue Aws::EC2::Errors::ServiceError => e
+      handle_ec2_service_error!(e)
+    end
+
     # Configured by config/[AWS_EC2_ENV].yml.
     # Example: config/development.yml:
     #

data/lib/aws_ec2/create/error_messages.rb

@@ -0,0 +1,58 @@
+require "active_support/core_ext/string"
+
+class AwsEc2::Create
+  module ErrorMessages
+    def handle_ec2_service_error!(exception)
+      meth = map_exception_to_method(exception)
+      if respond_to?(meth)
+        message = send(meth) # custom specific error message
+        message = print_error_message(exception, message)
+      else
+        # generic error message
+        print_error_message(exception, <<-EOL)
+There was an error with the parameters used for the run_instance method.
+EOL
+      end
+    end
+
+    # Examples:
+    #   Aws::EC2::Errors::InvalidGroupNotFound => invalid_group_not_found!
+    #   Aws::EC2::Errors::InvalidParameterCombination => invalid_parameter_combination!
+    def map_exception_to_method(exception)
+      class_name = File.basename(exception.class.to_s).sub(/.*::/,'')
+      method_name = class_name.underscore
+    end
+
+    def print_error_message(exception, message)
+      puts "ERROR: Unable to launch the instance.".colorize(:red)
+      puts message
+      puts exception.message
+      puts "For the full internal backtrace re-run the command with DEBUG=1"
+      puts exception.backtrace if ENV['DEBUG']
+      exit 1
+    end
+
+    #######################################################
+    # specific messages with a little more info for more common error cases below:
+    def invalid_group_not_found
+      <<-EOL
+The security group passed in does not exit.
+Please double check that security group exists in the VPC.
+EOL
+    end
+
+    def invalid_parameter_combination
+      <<-EOL
+The parameters passed to the run_instances method were invalid.
+Please double check that the parameters are all valid.
+EOL
+    end
+
+    def invalid_subnet_id_not_found
+      <<-EOL
+The provided subnets ids were were not found.
+Please double check that the subnets exists.
+EOL
+    end
+  end
+end

data/lib/aws_ec2/help/ami.md

@@ -6,7 +6,7 @@ Launches an EC2 instance to create an AMI.  An AMI creation script is appended t
 
 It is useful to include to timestamp as a part of the AMI name with the date command.
 
-  $ aws-ec2 ami $(date "+ruby-2.5.0_%Y-%m-%d-%H-%M") --profile ruby --noop
+  $ aws-ec2 ami ruby-2.5.0_$(date "+%Y-%m-%d-%H-%M") --profile ruby --noop
 
 The instance also automatically gets terminated and cleaned up by a termination script appended to user-data.
 

data/lib/aws_ec2/profile.rb

@@ -25,7 +25,7 @@ module AwsEc2
     def load_profile(file)
       return {} unless File.exist?(file)
 
-      puts "Using profile: #{file}"
+      puts "Using profile: #{file}".colorize(:green)
       data = YAML.load(erb_result(file))
       data ? data : {} # in case the file is empty
       data.has_key?("run_instances") ? data["run_instances"] : data

data/lib/aws_ec2/script/compile.rb

@@ -13,7 +13,7 @@ class AwsEc2::Script
     end
 
     def compile_folder(folder)
-      puts "Compiling app/#{folder}:"
+      puts "Compiling app/#{folder}:".colorize(:green)
       Dir.glob("#{AwsEc2.root}/app/#{folder}/**/*").each do |path|
         next if File.directory?(path)
         result = erb_result(path)

data/lib/aws_ec2/script/upload.rb

@@ -15,7 +15,7 @@ class AwsEc2::Script
     end
 
     def sync_scripts_to_s3
-      puts "Uploading tmp/app to s3..."
+      puts "Uploading tmp/app to s3...".colorize(:green)
       s3_bucket = AwsEc2.config["scripts_s3_bucket"]
       s3_path = AwsEc2.config["scripts_s3_path"] || "ec2/app"
       sh "aws s3 sync tmp/app s3://#{s3_bucket}/#{s3_path}"

data/lib/aws_ec2/version.rb

@@ -1,3 +1,3 @@
 module AwsEc2
-  VERSION = "0.8.4"
+  VERSION = "0.9.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aws-ec2
 version: !ruby/object:Gem::Version
-  version: 0.8.4
+  version: 0.9.0
 platform: ruby
 authors:
 - Tung Nguyen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-01-30 00:00:00.000000000 Z
+date: 2018-02-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -197,14 +197,14 @@ files:
 - README.md
 - Rakefile
 - aws-ec2.gemspec
-- doc/example/.env
-- doc/example/.env.development
-- doc/example/.env.production
-- doc/example/app/scripts/hello.sh
-- doc/example/app/user-data/bootstrap.sh
-- doc/example/config/development.yml
-- doc/example/profiles/default.yml
-- doc/example/profiles/spot.yml
+- docs/example/.env
+- docs/example/.env.development
+- docs/example/.env.production
+- docs/example/app/scripts/hello.sh
+- docs/example/app/user-data/bootstrap.sh
+- docs/example/config/development.yml
+- docs/example/profiles/default.yml
+- docs/example/profiles/spot.yml
 - exe/aws-ec2
 - lib/aws-ec2.rb
 - lib/aws_ec2/ami.rb
@@ -215,6 +215,7 @@ files:
 - lib/aws_ec2/config.rb
 - lib/aws_ec2/core.rb
 - lib/aws_ec2/create.rb
+- lib/aws_ec2/create/error_messages.rb
 - lib/aws_ec2/create/params.rb
 - lib/aws_ec2/dotenv.rb
 - lib/aws_ec2/help.rb