2013-02-06 04:30:14 +00:00
|
|
|
# Vagrant AWS Provider
|
2014-12-01 17:20:35 +00:00
|
|
|
[![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/mitchellh/vagrant-aws?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
2013-02-06 04:30:14 +00:00
|
|
|
|
2013-09-23 11:31:27 +00:00
|
|
|
<span class="badges">
|
|
|
|
[![Gem Version](https://badge.fury.io/rb/vagrant-aws.png)][gem]
|
|
|
|
[![Dependency Status](https://gemnasium.com/mitchellh/vagrant-aws.png)][gemnasium]
|
|
|
|
</span>
|
|
|
|
|
|
|
|
[gem]: https://rubygems.org/gems/vagrant-aws
|
|
|
|
[gemnasium]: https://gemnasium.com/mitchellh/vagrant-aws
|
|
|
|
|
2013-04-16 21:56:39 +00:00
|
|
|
This is a [Vagrant](http://www.vagrantup.com) 1.2+ plugin that adds an [AWS](http://aws.amazon.com)
|
2013-02-06 04:30:14 +00:00
|
|
|
provider to Vagrant, allowing Vagrant to control and provision machines in
|
|
|
|
EC2 and VPC.
|
|
|
|
|
2013-04-16 21:56:39 +00:00
|
|
|
**NOTE:** This plugin requires Vagrant 1.2+,
|
2013-02-06 04:30:14 +00:00
|
|
|
|
2013-02-06 04:43:20 +00:00
|
|
|
## 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`.
|
2014-11-11 08:30:56 +00:00
|
|
|
* Define region-specific configurations so Vagrant can manage machines
|
2013-02-06 04:43:20 +00:00
|
|
|
in multiple regions.
|
2014-07-17 06:01:27 +00:00
|
|
|
* Package running instances into new vagrant-aws friendly boxes
|
2013-02-06 04:43:20 +00:00
|
|
|
|
2013-02-06 04:37:38 +00:00
|
|
|
## 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.
|
|
|
|
|
2013-02-07 01:31:24 +00:00
|
|
|
## 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:
|
|
|
|
|
|
|
|
```
|
2013-02-07 01:32:04 +00:00
|
|
|
$ vagrant box add dummy https://github.com/mitchellh/vagrant-aws/raw/master/dummy.box
|
2013-02-07 01:31:24 +00:00
|
|
|
...
|
|
|
|
```
|
|
|
|
|
|
|
|
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"
|
|
|
|
|
2013-04-16 21:56:39 +00:00
|
|
|
config.vm.provider :aws do |aws, override|
|
2013-02-07 01:31:24 +00:00
|
|
|
aws.access_key_id = "YOUR KEY"
|
|
|
|
aws.secret_access_key = "YOUR SECRET KEY"
|
2014-11-20 04:43:07 +00:00
|
|
|
aws.session_token = "SESSION TOKEN"
|
2013-02-07 01:31:24 +00:00
|
|
|
aws.keypair_name = "KEYPAIR NAME"
|
|
|
|
|
|
|
|
aws.ami = "ami-7747d01e"
|
2013-04-16 21:56:39 +00:00
|
|
|
|
|
|
|
override.ssh.username = "ubuntu"
|
|
|
|
override.ssh.private_key_path = "PATH TO YOUR PRIVATE KEY"
|
2013-02-07 01:31:24 +00:00
|
|
|
end
|
|
|
|
end
|
|
|
|
```
|
|
|
|
|
|
|
|
And then run `vagrant up --provider=aws`.
|
|
|
|
|
2013-02-07 01:34:20 +00:00
|
|
|
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.
|
|
|
|
|
2013-04-09 22:06:34 +00:00
|
|
|
If you have issues with SSH connecting, make sure that the instances
|
|
|
|
are being launched with a security group that allows SSH access.
|
|
|
|
|
2016-01-27 11:38:32 +00:00
|
|
|
Note: if you don't configure `aws.access_key_id` or `aws_secret_access_key`
|
|
|
|
it will attempt to read credentials from environment variables first and then
|
|
|
|
from `$HOME/.aws/`. You can choose your AWS profile and files location by using
|
2016-01-27 12:50:45 +00:00
|
|
|
`aws.aws_profile` and `aws.aws_dir`, however environment variables will always
|
|
|
|
have precedence as defined by the [AWS documentation](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html).
|
2016-01-27 13:55:41 +00:00
|
|
|
To use profile `vagrantDev` from your AWS files:
|
|
|
|
```ruby
|
|
|
|
# this first line can actually be omitted
|
|
|
|
aws.aws_dir = ENV['HOME'] + "/.aws/"
|
|
|
|
aws.aws_profile = "vagrantDev"
|
|
|
|
```
|
|
|
|
|
2016-01-27 11:38:32 +00:00
|
|
|
|
2013-02-06 04:30:14 +00:00
|
|
|
## 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.
|
|
|
|
|
2013-02-06 04:37:38 +00:00
|
|
|
## 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"
|
2013-02-08 03:46:01 +00:00
|
|
|
* `availability_zone` - The availability zone within the region to launch
|
|
|
|
the instance. If nil, it will use the default set by Amazon.
|
2016-01-27 11:38:32 +00:00
|
|
|
* `aws_profile` - AWS profile in your config files. Defaults to *default*.
|
|
|
|
* `aws_dir` - AWS config and credentials location. Defaults to *$HOME/.aws/*.
|
2013-04-16 21:52:42 +00:00
|
|
|
* `instance_ready_timeout` - The number of seconds to wait for the instance
|
|
|
|
to become "ready" in AWS. Defaults to 120 seconds.
|
2015-08-12 09:35:48 +00:00
|
|
|
* `instance_check_interval` - The number of seconds to wait to check the instance's
|
|
|
|
state
|
2014-07-17 06:01:27 +00:00
|
|
|
* `instance_package_timeout` - The number of seconds to wait for the instance
|
|
|
|
to be burnt into an AMI during packaging. Defaults to 600 seconds.
|
2014-08-14 03:34:21 +00:00
|
|
|
* `instance_type` - The type of instance, such as "m3.medium". The default
|
|
|
|
value of this if not specified is "m3.medium". "m1.small" has been
|
|
|
|
deprecated in "us-east-1" and "m3.medium" is the smallest instance
|
|
|
|
type to support both paravirtualization and hvm AMIs
|
2013-02-06 04:37:38 +00:00
|
|
|
* `keypair_name` - The name of the keypair to use to bootstrap AMIs
|
|
|
|
which support it.
|
2015-11-23 18:38:47 +00:00
|
|
|
* `monitoring` - Set to "true" to enable detailed monitoring.
|
2014-11-30 22:10:30 +00:00
|
|
|
* `session_token` - The session token provided by STS
|
2013-02-06 04:37:38 +00:00
|
|
|
* `private_ip_address` - The private IP address to assign to an instance
|
|
|
|
within a [VPC](http://aws.amazon.com/vpc/)
|
2014-08-27 00:51:19 +00:00
|
|
|
* `elastic_ip` - Can be set to 'true', or to an existing Elastic IP address.
|
|
|
|
If true, allocate a new Elastic IP address to the instance. If set
|
|
|
|
to an existing Elastic IP address, assign the address to the instance.
|
2013-02-06 04:37:38 +00:00
|
|
|
* `region` - The region to start the instance in, such as "us-east-1"
|
|
|
|
* `secret_access_key` - The secret access key for accessing AWS
|
2013-02-08 03:55:03 +00:00
|
|
|
* `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
|
2014-07-23 19:22:49 +00:00
|
|
|
Name. For a nondefault VPC, you must use security group IDs instead (http://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html).
|
2013-05-02 23:05:11 +00:00
|
|
|
* `iam_instance_profile_arn` - The Amazon resource name (ARN) of the IAM Instance
|
|
|
|
Profile to associate with the instance
|
|
|
|
* `iam_instance_profile_name` - The name of the IAM Instance Profile to associate
|
|
|
|
with the instance
|
2013-02-06 04:37:38 +00:00
|
|
|
* `subnet_id` - The subnet to boot the instance into, for VPC.
|
2014-04-17 13:41:48 +00:00
|
|
|
* `associate_public_ip` - If true, will associate a public IP address to an instance in a VPC.
|
2015-02-26 06:13:37 +00:00
|
|
|
* `ssh_host_attribute` - If `:public_ip_address`, `:dns_name`, or
|
|
|
|
`:private_ip_address`, will use the public IP address, DNS name, or private
|
|
|
|
IP address, respectively, to SSH to the instance. By default Vagrant uses the
|
|
|
|
first of these (in this order) that is known. However, this can lead to
|
|
|
|
connection issues if, e.g., you are assigning a public IP address but your
|
|
|
|
security groups prevent public SSH access and require you to SSH in via the
|
|
|
|
private IP address; specify `:private_ip_address` in this case.
|
2015-06-25 19:36:01 +00:00
|
|
|
* `tenancy` - When running in a VPC configure the tenancy of the instance. Supports 'default' and 'dedicated'.
|
2013-02-08 04:13:15 +00:00
|
|
|
* `tags` - A hash of tags to set on the machine.
|
2014-12-30 06:48:14 +00:00
|
|
|
* `package_tags` - A hash of tags to set on the ami generated during the package operation.
|
2013-04-16 21:52:42 +00:00
|
|
|
* `use_iam_profile` - If true, will use [IAM profiles](http://docs.aws.amazon.com/IAM/latest/UserGuide/instance-profiles.html)
|
|
|
|
for credentials.
|
2014-05-26 12:48:50 +00:00
|
|
|
* `block_device_mapping` - Amazon EC2 Block Device Mapping Property
|
2014-06-26 19:08:56 +00:00
|
|
|
* `elb` - The ELB name to attach to the instance.
|
2015-08-17 21:19:28 +00:00
|
|
|
* `unregister_elb_from_az` - Removes the ELB from the AZ on removal of the last instance if true (default). In non default VPC this has to be false.
|
2015-06-08 18:51:50 +00:00
|
|
|
* `terminate_on_shutdown` - Indicates whether an instance stops or terminates
|
|
|
|
when you initiate shutdown from the instance.
|
2013-02-06 04:37:38 +00:00
|
|
|
|
|
|
|
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"
|
|
|
|
|
2013-04-09 21:53:08 +00:00
|
|
|
# Simple region config
|
2013-02-06 04:37:38 +00:00
|
|
|
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
|
|
|
|
```
|
|
|
|
|
2013-02-06 04:41:55 +00:00
|
|
|
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.
|
|
|
|
|
2014-11-28 03:40:00 +00:00
|
|
|
See [Vagrant Synced folders: rsync](https://docs.vagrantup.com/v2/synced-folders/rsync.html)
|
2014-07-17 06:01:27 +00:00
|
|
|
|
2014-08-06 01:19:34 +00:00
|
|
|
|
2013-04-25 21:38:12 +00:00
|
|
|
## Other Examples
|
|
|
|
|
|
|
|
### Tags
|
|
|
|
|
2013-04-21 07:05:46 +00:00
|
|
|
To use tags, simply define a hash of key/value for the tags you want to associate to your instance, like:
|
|
|
|
|
|
|
|
```ruby
|
|
|
|
Vagrant.configure("2") do |config|
|
|
|
|
# ... other stuff
|
|
|
|
|
2013-04-25 21:38:12 +00:00
|
|
|
config.vm.provider "aws" do |aws|
|
|
|
|
aws.tags = {
|
|
|
|
'Name' => 'Some Name',
|
|
|
|
'Some Key' => 'Some Value'
|
|
|
|
}
|
|
|
|
end
|
2013-04-21 07:05:46 +00:00
|
|
|
end
|
|
|
|
```
|
|
|
|
|
2013-04-25 21:38:12 +00:00
|
|
|
### User data
|
|
|
|
|
|
|
|
You can specify user data for the instance being booted.
|
2013-04-21 09:05:44 +00:00
|
|
|
|
|
|
|
```ruby
|
|
|
|
Vagrant.configure("2") do |config|
|
|
|
|
# ... other stuff
|
|
|
|
|
2013-04-25 21:38:12 +00:00
|
|
|
config.vm.provider "aws" do |aws|
|
|
|
|
# Option 1: a single string
|
|
|
|
aws.user_data = "#!/bin/bash\necho 'got user data' > /tmp/user_data.log\necho"
|
|
|
|
|
|
|
|
# Option 2: use a file
|
|
|
|
aws.user_data = File.read("user_data.txt")
|
|
|
|
end
|
2013-04-21 09:05:44 +00:00
|
|
|
end
|
|
|
|
```
|
|
|
|
|
2014-02-13 10:53:41 +00:00
|
|
|
### Disk size
|
|
|
|
|
|
|
|
Need more space on your instance disk? Increase the disk size.
|
|
|
|
|
|
|
|
```ruby
|
|
|
|
Vagrant.configure("2") do |config|
|
|
|
|
# ... other stuff
|
|
|
|
|
|
|
|
config.vm.provider "aws" do |aws|
|
|
|
|
aws.block_device_mapping = [{ 'DeviceName' => '/dev/sda1', 'Ebs.VolumeSize' => 50 }]
|
|
|
|
end
|
|
|
|
end
|
|
|
|
```
|
|
|
|
|
2014-06-26 19:08:56 +00:00
|
|
|
### ELB (Elastic Load Balancers)
|
2013-06-07 16:05:46 +00:00
|
|
|
|
|
|
|
You can automatically attach an instance to an ELB during boot and detach on destroy.
|
|
|
|
|
|
|
|
```ruby
|
|
|
|
Vagrant.configure("2") do |config|
|
|
|
|
# ... other stuff
|
|
|
|
|
|
|
|
config.vm.provider "aws" do |aws|
|
|
|
|
aws.elb = "production-web"
|
|
|
|
end
|
|
|
|
end
|
|
|
|
```
|
|
|
|
|
2013-02-06 04:30:14 +00:00
|
|
|
## 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)
|
2013-07-23 21:54:59 +00:00
|
|
|
and add the following line to your `Vagrantfile`
|
|
|
|
```ruby
|
2013-07-23 21:57:11 +00:00
|
|
|
Vagrant.require_plugin "vagrant-aws"
|
2013-07-23 21:54:59 +00:00
|
|
|
```
|
2013-07-23 21:57:11 +00:00
|
|
|
Use bundler to execute Vagrant:
|
2013-02-06 04:30:14 +00:00
|
|
|
```
|
|
|
|
$ bundle exec vagrant up --provider=aws
|
|
|
|
```
|