vagrant-aws is a plugin for Vagrant 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.
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 internally, and you will need to
specify your Amazon AWS credentials in a "fog" file. Create
--- 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,
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
::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:
::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.
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.