# Kitchen::Ec2: A Test Kitchen Driver for Amazon EC2
[](http://badge.fury.io/rb/kitchen-ec2)
[](https://travis-ci.org/opscode/kitchen-ec2)
[](https://codeclimate.com/github/opscode/kitchen-ec2)
A Test Kitchen Driver for Amazon EC2.
This driver uses the [fog gem][fog_gem] to provision and destroy EC2
instances. Use Amazon's cloud for your infrastructure testing!
## Requirements
There are **no** external system requirements for this driver. However you
will need access to an [AWS][aws_site] account.
## Installation and Setup
Please read the [Driver usage][driver_usage] page for more details.
## Default Configuration
This driver can determine AMI and username login for a select number of
platforms in each region. Currently, the following platform names are
supported:
```ruby
---
platforms:
- name: ubuntu-10.04
- name: ubuntu-12.04
- name: ubuntu-12.10
- name: ubuntu-13.04
- name: centos-6.4
- name: debian-7.1.0
```
This will effectively generate a configuration similar to:
```ruby
---
platforms:
- name: ubuntu-10.04
driver_config:
image_id: ami-1ab3ce73
username: ubuntu
- name: ubuntu-12.04
driver_config:
image_id: ami-2f115c46
username: ubuntu
# ...
- name: centos-6.4
driver_config:
image_id: ami-bf5021d6
username: root
# ...
```
For specific default values, please consult [amis.json][amis_json].
## Configuration
### availability\_zone
**Required** The AWS [availability zone][region_docs] to use.
The default is `"us-east-1b"`.
### aws\_access\_key\_id
**Required** The AWS [access key id][credentials_docs] to use.
The default will be read from the `AWS_ACCESS_KEY` environment variable if set,
or `nil` otherwise.
### aws\_secret\_access\_key
**Required** The AWS [secret access key][credentials_docs] to use.
The default will be read from the `AWS_SECRET_KEY` environment variable if set,
or `nil` otherwise.
### aws\_ssh\_key\_id
**Required** The EC2 [SSH key id][key_id_docs] to use.
The default will be read from the `AWS_SSH_KEY_ID` environment variable if set,
or `nil` otherwise.
### flavor\_id
The EC2 [instance type][instance_docs] (also known as size) to use.
The default is `"m1.small"`.
### groups
An Array of EC [security groups][group_docs] which will be applied to the
instance.
The default is `["default"]`.
### image\_id
**Required** The EC2 [AMI id][ami_docs] to use.
The default will be determined by the `aws_region` chosen and the Platform
name, if a default exists (see [amis.json][ami_json]). If a default cannot be
computed, then the default is `nil`.
### port
The SSH port number to be used when communicating with the instance.
The default is `22`.
### region
**Required** The AWS [region][region_docs] to use.
The default is `"us-east-1"`.
### require\_chef\_omnibus
Determines whether or not a Chef [Omnibus package][chef_omnibus_dl] will be
installed. There are several different behaviors available:
* `true` - the latest release will be installed. Subsequent converges
will skip re-installing if chef is present.
* `latest` - the latest release will be installed. Subsequent converges
will always re-install even if chef is present.
* `` (ex: `10.24.0`) - the desired version string will
be passed the the install.sh script. Subsequent converges will skip if
the installed version and the desired version match.
* `false` or `nil` - no chef is installed.
The default value is unset, or `nil`.
### ssh\_key
Path to the private SSH key used to connect to the instance.
The default is unset, or `nil`.
### subnet\_id
The EC2 [subnet][subnet_docs] to use.
The default is unset, or `nil`.
### sudo
Whether or not to prefix remote system commands such as installing and
running Chef with `sudo`.
The default is `true`.
### tags
The Hash of EC tag name/value pairs which will be applied to the instance.
The default is `{ "created-by" => "test-kitchen" }`.
### username
The SSH username that will be used to communicate with the instance.
The default will be determined by the Platform name, if a default exists (see
[amis.json][amis_json]). If a default cannot be computed, then the default is
`"root"`.
## Example
The following could be used in a `.kitchen.yml` or in a `.kitchen.local.yml`
to override default configuration.
```yaml
---
driver_plugin: ec2
driver_config:
aws_access_key_id: KAS...
aws_secret_access_key: 3UK...
aws_ssh_key_id: id_rsa-aws
ssh_key: /path/to/id_rsa-aws
region: us-east-1
availability_zone: us-east-1b
require_chef_omnibus: true
subnet_id: subnet-6d6...
platforms:
- name: ubuntu-12.04
driver_config:
image_id: ami-fd20ad94
username: ubuntu
- name: centos-6.3
driver_config:
image_id: ami-ef5ff086
username: ec2-user
suites:
# ...
```
Both `.kitchen.yml` and `.kitchen.local.yml` files are pre-processed through
ERB which can help to factor out secrets and credentials. For example:
```yaml
---
driver_plugin: ec2
driver_config:
aws_access_key_id: <%= ENV['AWS_ACCESS_KEY'] %>
aws_secret_access_key: <%= ENV['AWS_SECRET_KEY'] %>
aws_ssh_key_id: <%= ENV['AWS_SSH_KEY_ID'] %>
ssh_key: <%= File.expand_path('~/.ssh/id_rsa') %>
region: us-east-1
availability_zone: us-east-1b
require_chef_omnibus: true
platforms:
- name: ubuntu-12.04
driver_config:
image_id: ami-fd20ad94
username: ubuntu
- name: centos-6.3
driver_config:
image_id: ami-ef5ff086
username: ec2-user
suites:
# ...
```
## Development
* Source hosted at [GitHub][repo]
* Report issues/questions/feature requests on [GitHub Issues][issues]
Pull requests are very welcome! Make sure your patches are well tested.
Ideally create a topic branch for every separate change you make. For
example:
1. Fork the repo
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Added some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request
## Authors
Created and maintained by [Fletcher Nichol][author] ()
## License
Apache 2.0 (see [LICENSE][license])
[author]: https://github.com/fnichol
[issues]: https://github.com/opscode/kitchen-ec2/issues
[license]: https://github.com/opscode/kitchen-ec2/blob/master/LICENSE
[repo]: https://github.com/opscode/kitchen-ec2
[driver_usage]: http://docs.kitchen-ci.org/drivers/usage
[chef_omnibus_dl]: http://www.opscode.com/chef/install/
[amis_json]: https://github.com/opscode/kitchen-ec2/blob/master/data/amis.json
[ami_docs]: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ComponentsAMIs.html
[aws_site]: http://aws.amazon.com/
[credentials_docs]: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/SettingUp_CommandLine.html#using-credentials-access-key
[fog_gem]: http://fog.io/
[group_docs]: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html
[instance_docs]: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html
[key_id_docs]: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/verifying-your-key-pair.html
[region_docs]: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html
[subnet_docs]: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-subnet.html