vagrant-aws 0.0.1 → 0.1.0

data/.gitignore

@@ -1,5 +1,14 @@
+# OS-specific
+.DS_Store
+
+# Bundler/Rubygems
 *.gem
 .bundle
-Gemfile.lock
 pkg/*
-.rvmrc
+tags
+Gemfile.lock
+
+# Vagrant
+.vagrant
+Vagrantfile
+!example_box/Vagrantfile

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+# 0.1.0 (March 14, 2013)
+
+* Initial release.

data/Gemfile

@@ -1,4 +1,10 @@
-source "http://rubygems.org"
+source "https://rubygems.org"
 
-# Specify your gem's dependencies in vagrant-aws.gemspec
 gemspec
+
+group :development do
+  # We depend on Vagrant for development, but we don't add it as a
+  # gem dependency because we expect to be installed within the
+  # Vagrant environment itself using `vagrant plugin`.
+  gem "vagrant", :git => "git://github.com/mitchellh/vagrant.git"
+end

data/LICENSE

@@ -0,0 +1,8 @@
+The MIT License (MIT)
+Copyright (c) 2013 Mitchell Hashimoto
+
+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

@@ -1,65 +1,192 @@
-# vagrant-aws
-
-`vagrant-aws` is a plugin for [Vagrant](http://vagrantup.com) which allows the user
-to instantiate the Vagrant environment on Amazon AWS (using EC2). This document assumes
-you are familiar with Vagrant, if not, the project has excellent [documentation](http://vagrantup.com/docs/index.html).
-
-**NOTE:** This plugin is "pre-alpha", see below for the caveats
-
-## Installing / Getting Started
-
-To use this plugin, first install Vagrant, then install the plugin gem. It should be
-picked up automatically by vagrant. You can then use the `vagrant aws` commands.
-
-`vagrant-aws` uses [fog](https://github.com/geemus/fog) internally, and you will need to
-specify your Amazon AWS credentials in a "fog" file. Create `~/.fog` with:
-
-	---
-	default: 
-		aws_access_key_id:  <YOUR ACCESS KEY>
-		aws_secret_access_key: <YOUR SECRET KEY>
-
-If you already have an Amazon key pair (created when you signed-up, or
-someother time), you can specify the key name and the path the associated
-private key. Alternately, if no key name is specified, `vagrant-aws` will
-automatically create and register a key pair for you with the name
-`vagrant_<MAC ADDRESS>`. If you want to use your pre-existing key, you can
-specify the key name and path on a per-environment basis (i.e., in each
-Vagrantfile) or in a single Vagrantfile in your `~/.vagrant` directory. In the
-latter case, create `~/.vagrant/Vagrantfile` with:
-
-	Vagrant::Config.run do |config|
-		config.aws.key_name = "<KEY NAME>"
-		config.aws.private_key_path = "<PATH/TO/KEY>"
-	end
-	
-With the above in place you should be ready instantiate your Vagrant environment on 
-Amazon AWS. See below for additional information on configuration, caveats, etc..
-
-## Configuration and Image Boxes
-
-`vagrant-aws` defines a new configuration class for use in your Vagrantfile. An example
-usage (showing the defaults) would be:
-
-	Vagrant::Config.run do |config|
-		config.aws.region = "us-east-1"
-		config.aws.availability_zone = nil  # Let AWS choose
-		config.aws.image = "ami-2ec83147"   # EBS-backed Ubuntu 10.04 64-bit
-		config.aws.username = "ubuntu"
-		config.aws.security_groups = ["default"]
-		config.aws.flavor = "t1.micro"
-	end
-
-Alternately you can work with "image boxes" using the `vagrant aws box_*` commands. These are 
-similar to Vagrant's native boxes, and have a similar API, but wrap AWS ami IDs. The major 
-difference is that box creation and removal can optionally reregister and deregister AMIs
-with AWS. Note that AMI creation is only supported for EBS-backed instances.
-
-## Caveats
-
-`vagrant-aws` is "pre-alpha" and currently only supports creation, suspension, resumption
-and descruction of the Vagrant environment. Provisioning should be supported for shell,
-chef-server and chef-solo, but has only been tested with chef-solo and on an Ubuntu guest. 
-Only a subset of Vagrant features are supported. Currently port forwarding and shared 
-directories are not implemented, nor is host networking (although that is less relevant for AWS). 
-`vagrant-aws` in general has only been tested for a single VM, on OSX 10.6, with chef-solo.	
+# Vagrant AWS Provider
+
+This is a [Vagrant](http://www.vagrantup.com) 1.1+ plugin that adds an [AWS](http://aws.amazon.com)
+provider to Vagrant, allowing Vagrant to control and provision machines in
+EC2 and VPC.
+
+**NOTE:** This plugin requires Vagrant 1.1+,
+
+## Features
+
+* Boot EC2 or VPC instances.
+* SSH into the instances.
+* Provision the instances with any built-in Vagrant provisioner.
+* Minimal synced folder support via `rsync`.
+* Define region-specifc configurations so Vagrant can manage machines
+  in multiple regions.
+
+## Usage
+
+Install using standard Vagrant 1.1+ plugin installation methods. After
+installing, `vagrant up` and specify the `aws` provider. An example is
+shown below.
+
+```
+$ vagrant plugin install vagrant-aws
+...
+$ vagrant up --provider=aws
+...
+```
+
+Of course prior to doing this, you'll need to obtain an AWS-compatible
+box file for Vagrant.
+
+## Quick Start
+
+After installing the plugin (instructions above), the quickest way to get
+started is to actually use a dummy AWS box and specify all the details
+manually within a `config.vm.provider` block. So first, add the dummy
+box using any name you want:
+
+```
+$ vagrant box add dummy https://github.com/mitchellh/vagrant-aws/raw/master/dummy.box
+...
+```
+
+And then make a Vagrantfile that looks like the following, filling in
+your information where necessary.
+
+```
+Vagrant.configure("2") do |config|
+  config.vm.box = "dummy"
+
+  config.vm.provider :aws do |aws|
+    aws.access_key_id = "YOUR KEY"
+    aws.secret_access_key = "YOUR SECRET KEY"
+    aws.keypair_name = "KEYPAIR NAME"
+    aws.ssh_private_key_path = "PATH TO YOUR PRIVATE KEY"
+
+    aws.ami = "ami-7747d01e"
+    aws.ssh_username = "ubuntu"
+  end
+end
+```
+
+And then run `vagrant up --provider=aws`.
+
+This will start an Ubuntu 12.04 instance in the us-east-1 region within
+your account. And assuming your SSH information was filled in properly
+within your Vagrantfile, SSH and provisioning will work as well.
+
+Note that normally a lot of this boilerplate is encoded within the box
+file, but the box file used for the quick start, the "dummy" box, has
+no preconfigured defaults.
+
+## Box Format
+
+Every provider in Vagrant must introduce a custom box format. This
+provider introduces `aws` boxes. You can view an example box in
+the [example_box/ directory](https://github.com/mitchellh/vagrant-aws/tree/master/example_box).
+That directory also contains instructions on how to build a box.
+
+The box format is basically just the required `metadata.json` file
+along with a `Vagrantfile` that does default settings for the
+provider-specific configuration for this provider.
+
+## Configuration
+
+This provider exposes quite a few provider-specific configuration options:
+
+* `access_key_id` - The access key for accessing AWS
+* `ami` - The AMI id to boot, such as "ami-12345678"
+* `availability_zone` - The availability zone within the region to launch
+  the instance. If nil, it will use the default set by Amazon.
+* `instance_type` - The type of instance, such as "m1.small"
+* `keypair_name` - The name of the keypair to use to bootstrap AMIs
+   which support it.
+* `private_ip_address` - The private IP address to assign to an instance
+  within a [VPC](http://aws.amazon.com/vpc/)
+* `region` - The region to start the instance in, such as "us-east-1"
+* `secret_access_key` - The secret access key for accessing AWS
+* `ssh_private_key_path` - The path to the SSH private key. This overrides
+  `config.ssh.private_key_path`.
+* `ssh_username` - The SSH username, which overrides `config.ssh.username`.
+* `security_groups` - An array of security groups for the instance. If this
+  instance will be launched in VPC, this must be a list of security group
+  IDs.
+* `subnet_id` - The subnet to boot the instance into, for VPC.
+* `tags` - A hash of tags to set on the machine.
+
+These can be set like typical provider-specific configuration:
+
+```ruby
+Vagrant.configure("2") do |config|
+  # ... other stuff
+
+  config.vm.provider :aws do |aws|
+    aws.access_key_id = "foo"
+    aws.secret_access_key = "bar"
+  end
+end
+```
+
+In addition to the above top-level configs, you can use the `region_config`
+method to specify region-specific overrides within your Vagrantfile. Note
+that the top-level `region` config must always be specified to choose which
+region you want to actually use, however. This looks like this:
+
+```ruby
+Vagrant.configure("2") do |config|
+  # ... other stuff
+
+  config.vm.provider :aws do |aws|
+    aws.access_key_id = "foo"
+    aws.secret_access_key = "bar"
+    aws.region = "us-east-1"
+
+    # Simply region config
+    aws.region_config "us-east-1", :ami => "ami-12345678"
+
+    # More comprehensive region config
+    aws.region_config "us-west-2" do |region|
+      region.ami = "ami-87654321"
+      region.keypair_name = "company-west"
+    end
+  end
+end
+```
+
+The region-specific configurations will override the top-level
+configurations when that region is used. They otherwise inherit
+the top-level configurations, as you would probably expect.
+
+## Networks
+
+Networking features in the form of `config.vm.network` are not
+supported with `vagrant-aws`, currently. If any of these are
+specified, Vagrant will emit a warning, but will otherwise boot
+the AWS machine.
+
+## Synced Folders
+
+There is minimal support for synced folders. Upon `vagrant up`,
+`vagrant reload`, and `vagrant provision`, the AWS provider will use
+`rsync` (if available) to uni-directionally sync the folder to
+the remote machine over SSH.
+
+This is good enough for all built-in Vagrant provisioners (shell,
+chef, and puppet) to work!
+
+## Development
+
+To work on the `vagrant-aws` plugin, clone this repository out, and use
+[Bundler](http://gembundler.com) to get the dependencies:
+
+```
+$ bundle
+```
+
+Once you have the dependencies, verify the unit tests pass with `rake`:
+
+```
+$ bundle exec rake
+```
+
+If those pass, you're ready to start developing the plugin. You can test
+the plugin without installing it into your Vagrant environment by just
+creating a `Vagrantfile` in the top level of this directory (it is gitignored)
+that uses it, and uses bundler to execute Vagrant:
+
+```
+$ bundle exec vagrant up --provider=aws
+```

data/Rakefile

@@ -1,10 +1,21 @@
-require 'bundler/gem_tasks'
-require 'rake/testtask'
+require 'rubygems'
+require 'bundler/setup'
+require 'rspec/core/rake_task'
 
-task :default => :test
+# Immediately sync all stdout so that tools like buildbot can
+# immediately load in the output.
+$stdout.sync = true
+$stderr.sync = true
 
-Rake::TestTask.new do |t|
-  t.libs << "test"
-  t.pattern = 'test/**/*_test.rb'
-end
+# Change to the directory of this file.
+Dir.chdir(File.expand_path("../", __FILE__))
 
+# This installs the tasks that help with gem creation and
+# publishing.
+Bundler::GemHelper.install_tasks
+
+# Install the `spec` task so that we can run tests.
+RSpec::Core::RakeTask.new
+
+# Default task is to run the unit tests
+task :default => "spec"

data/example_box/README.md

@@ -0,0 +1,13 @@
+# Vagrant AWS Example Box
+
+Vagrant providers each require a custom provider-specific box format.
+This folder shows the example contents of a box for the `aws` provider.
+To turn this into a box:
+
+```
+$ tar cvzf aws.box ./metadata.json ./Vagrantfile
+```
+
+This box works by using Vagrant's built-in Vagrantfile merging to setup
+defaults for AWS. These defaults can easily be overwritten by higher-level
+Vagrantfiles (such as project root Vagrantfiles).

data/example_box/metadata.json

@@ -0,0 +1,3 @@
+{
+    "provider": "aws"
+}

data/lib/vagrant-aws.rb

@@ -1,14 +1,18 @@
-require 'vagrant'
-require 'vagrant-aws/version'
-require 'vagrant-aws/errors'
-require 'vagrant-aws/environment'
-require 'vagrant-aws/vm'
-require 'vagrant-aws/config'
-require 'vagrant-aws/middleware'
-require 'vagrant-aws/command'
-require 'vagrant-aws/system'
-require 'vagrant-aws/box'
-require 'vagrant-aws/box_collection'
+require "pathname"
 
-# Add our custom translations to the load path
-I18n.load_path << File.expand_path("../../locales/en.yml", __FILE__)
+require "vagrant-aws/plugin"
+
+module VagrantPlugins
+  module AWS
+    lib_path = Pathname.new(File.expand_path("../vagrant-aws", __FILE__))
+    autoload :Action, lib_path.join("action")
+    autoload :Errors, lib_path.join("errors")
+
+    # This returns the path to the source of this plugin.
+    #
+    # @return [Pathname]
+    def self.source_root
+      @source_root ||= Pathname.new(File.expand_path("../../", __FILE__))
+    end
+  end
+end

data/lib/vagrant-aws/action.rb

@@ -0,0 +1,107 @@
+require "pathname"
+
+require "vagrant/action/builder"
+
+module VagrantPlugins
+  module AWS
+    module Action
+      # Include the built-in modules so we can use them as top-level things.
+      include Vagrant::Action::Builtin
+
+      # This action is called to terminate the remote machine.
+      def self.action_destroy
+        Vagrant::Action::Builder.new.tap do |b|
+          b.use ConfigValidate
+          b.use ConnectAWS
+          b.use TerminateInstance
+        end
+      end
+
+      # This action is called when `vagrant provision` is called.
+      def self.action_provision
+        Vagrant::Action::Builder.new.tap do |b|
+          b.use ConfigValidate
+          b.use Call, IsCreated do |env, b2|
+            if !env[:result]
+              b2.use MessageNotCreated
+              next
+            end
+
+            b2.use Provision
+            b2.use SyncFolders
+          end
+        end
+      end
+
+      # This action is called to read the SSH info of the machine. The
+      # resulting state is expected to be put into the `:machine_ssh_info`
+      # key.
+      def self.action_read_ssh_info
+        Vagrant::Action::Builder.new.tap do |b|
+          b.use ConfigValidate
+          b.use ConnectAWS
+          b.use ReadSSHInfo
+        end
+      end
+
+      # This action is called to read the state of the machine. The
+      # resulting state is expected to be put into the `:machine_state_id`
+      # key.
+      def self.action_read_state
+        Vagrant::Action::Builder.new.tap do |b|
+          b.use ConfigValidate
+          b.use ConnectAWS
+          b.use ReadState
+        end
+      end
+
+      # This action is called to SSH into the machine.
+      def self.action_ssh
+        Vagrant::Action::Builder.new.tap do |b|
+          b.use ConfigValidate
+          b.use Call, IsCreated do |env, b2|
+            if !env[:result]
+              b2.use MessageNotCreated
+              next
+            end
+
+            b2.use SSHExec
+          end
+        end
+      end
+
+      # This action is called to bring the box up from nothing.
+      def self.action_up
+        Vagrant::Action::Builder.new.tap do |b|
+          b.use ConfigValidate
+          b.use ConnectAWS
+          b.use Call, IsCreated do |env, b2|
+            if env[:result]
+              b2.use MessageAlreadyCreated
+              next
+            end
+
+            b2.use TimedProvision
+            b2.use SyncFolders
+            b2.use WarnNetworks
+            b2.use RunInstance
+          end
+        end
+      end
+
+      # The autoload farm
+      action_root = Pathname.new(File.expand_path("../action", __FILE__))
+      autoload :ConnectAWS, action_root.join("connect_aws")
+      autoload :IsCreated, action_root.join("is_created")
+      autoload :MessageAlreadyCreated, action_root.join("message_already_created")
+      autoload :MessageNotCreated, action_root.join("message_not_created")
+      autoload :ReadSSHInfo, action_root.join("read_ssh_info")
+      autoload :ReadState, action_root.join("read_state")
+      autoload :RunInstance, action_root.join("run_instance")
+      autoload :SyncFolders, action_root.join("sync_folders")
+      autoload :TimedProvision, action_root.join("timed_provision")
+      autoload :WarnNetworks, action_root.join("warn_networks")
+      autoload :TerminateInstance, action_root.join("terminate_instance")
+    end
+  end
+end