Kitchen::Ec2: A Test Kitchen Driver for Amazon EC2

A Test Kitchen Driver for Amazon EC2.

This driver uses the aws sdk 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 account.

Installation and Setup

Please read the 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:

---
platforms:
  - name: ubuntu-10.04
  - name: ubuntu-12.04
  - name: ubuntu-12.10
  - name: ubuntu-13.04
  - name: ubuntu-13.10
  - name: ubuntu-14.04
  - name: centos-6.4
  - name: debian-7.1.0

This will effectively generate a configuration similar to:

---
platforms:
  - name: ubuntu-10.04
    driver:
      image_id: ami-1ab3ce73
      username: ubuntu
  - name: ubuntu-12.04
    driver:
      image_id: ami-2f115c46
      username: ubuntu
  # ...
  - name: centos-6.4
    driver:
      image_id: ami-bf5021d6
      username: root
  # ...

For specific default values, please consult amis.json.

General Configuration

availability_zone

Required The AWS availability zone to use. Only request the letter designation - will attach this to the region used.

The default is "#{region}b".

aws_access_key_id

Required The AWS access key id 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 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 to use.

The default will be read from the AWS_SSH_KEY_ID environment variable if set, or nil otherwise.

aws_session_token

The AWS session token to use.

The default will be read from the AWS_SESSION_TOKEN environment variable if set, or nil otherwise.

flavor_id

Deprecated See instance_type below.

instance_type

The EC2 instance type (also known as size) to use.

The default is "m1.small".

security_group_ids

An Array of EC2 security groups which will be applied to the instance.

The default is ["default"].

image_id

Required The EC2 AMI id 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.

region

Required The AWS region to use.

The default is "us-east-1".

subnet_id

The EC2 subnet to use.

The default is unset, or nil.

user_data

The user_data script or the path to a script to feed the instance. Use bash to install dependencies or download artifacts before chef runs. This is just for some cases. If you can do the stuff with chef, then do it with chef!

The default is unset, or nil.

iam_profile_name

The EC2 IAM profile name to use.

The default is nil.

price

The price you bid in order to submit a spot request. An additional step will be required during the spot request process submission. If no price is set, it will use an on-demand instance.

The default is nil.

Disk Configuration

ebs_volume_size

Deprecated See block_device_mappings below.

Size of ebs volume in GB.

ebs_delete_on_termination

Deprecated See block_device_mappings below.

true if you want ebs volumes to get deleted automatically after instance is terminated, false otherwise

ebs_device_name

Deprecated See block_device_mappings below.

name of your ebs device, for example: /dev/sda1

block_device_mappings

A list of block device mappings for the machine. An example of all available keys looks like:

block_device_mappings:
  - ebs_device_name: /dev/sda1
    ebs_volume_size: 20
    ebs_delete_on_termination: true
  - ebs_device_name: /dev/sda2
    ebs_volume_type: gp2
    ebs_virtual_name: test
    ebs_volume_size: 15
    ebs_delete_on_termination: true
    ebs_snapshot_id: snap-0015d0bc

The keys ebs_device_name, ebs_volume_size and ebs_delete_on_termination are required for every mapping. For backwards compatiability a default block_device_mappings will be created if none are listed and the deprecated storage config keys are present.

The keys ebs_volume_type, ebs_virtual_name and ebs_snapshot_id are optional. See Amazon EBS Volume Types to find out more about volume types. ebs_volume_type defaults to standard but can also be gp2 or io1.

If you have a block device mapping with a ebs_device_name equal to the root storage device name on your image then the provided mapping will replace the settings in the image.

If this is not provided it will use the default block_device_mappings from the AMI.

ebs_optimized

Option to launch EC2 instance with optimized EBS volume. See Amazon EC2 Instance Types to find out more about instance types that can be launched as EBS-optimized instances.

The default is false.

Network and Communication Configuration

associate_public_ip

AWS does not automatically allocate public IP addresses for instances created within non-default subnets. Set this option to true to force allocation of a public IP and associate it with the launched instance.

If you set this option to false when launching into a non-default subnet, Test Kitchen will be unable to communicate with the instance unless you have a VPN connection to your Virtual Private Cloud.

The default is true if you have configured a subnet_id, or false otherwise.

private_ip_address

The primary private IP address of your instance.

If you don't set this it will default to whatever DHCP address EC2 hands out.

interface

The place from which to derive the hostname for communicating with the instance. May be dns, public or private. If this is unset, the driver will derive the hostname by failing back in the following order:

DNS Name
Public IP Address
Private IP Address

The default is unset.

ssh_key

Deprecated Instead use the transport.ssh_key like

transport:
  ssh_key: ~/.ssh/id_rsa

Path to the private SSH key used to connect to the instance.

The default is unset, or nil.

ssh_timeout

Deprecated Instead use the transport.connection_timeout like

transport:
  connection_timeout: 60

The number of seconds to sleep before trying to SSH again.

The default is 1.

ssh_retries

Deprecated Instead use the transport.connection_retries like

transport:
  connection_retries: 10

The number of times to retry SSH-ing into the instance.

The default is 3.

username

Deprecated Instead use the transport.username like

transport:
  username: ubuntu

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). 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.

---
driver:
  name: ec2
  aws_access_key_id: KAS...
  aws_secret_access_key: 3UK...
  aws_ssh_key_id: id_rsa-aws
  security_group_ids: ["sg-1a2b3c4d"]
  region: us-east-1
  availability_zone: b
  require_chef_omnibus: true
  subnet_id: subnet-6d6...
  iam_profile_name: chef-client
  instance_type: t2.micro
  associate_public_ip: true
  private_ip_address: 10.0.0.27
  interface: dns
  block_device_mappings:
    - ebs_device_name: /dev/sda0
      ebs_volume_type: gp2
      ebs_virtual_name: test
      ebs_volume_size: 15
      ebs_delete_on_termination: true

transport:
  ssh_key: /path/to/id_rsa-aws
  connection_timeout: 10
  connection_retries: 5
  username: ubuntu

platforms:
  - name: ubuntu-12.04
    driver:
      image_id: ami-fd20ad94
      username: ubuntu
  - name: centos-6.3
    driver:
      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:

---
driver:
  name: ec2
  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') %>
  security_group_ids: ["sg-1a2b3c4d"]
  region: us-east-1
  availability_zone: b
  require_chef_omnibus: true

platforms:
  - name: ubuntu-12.04
    driver:
      image_id: ami-fd20ad94
      username: ubuntu
  - name: centos-6.3
    driver:
      image_id: ami-ef5ff086
      username: ec2-user

suites:
# ...

Development

Source hosted at GitHub
Report issues/questions/feature requests on GitHub 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:

Fork the repo
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Added some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

Authors

Created and maintained by Fletcher Nichol (fnichol@nichol.ca)

License

Apache 2.0 (see LICENSE)

mfischer-zd/kitchen-ec2

Kitchen::Ec2: A Test Kitchen Driver for Amazon EC2

Requirements

Installation and Setup

Default Configuration

General Configuration

availability_zone

aws_access_key_id

aws_secret_access_key

aws_ssh_key_id

aws_session_token

flavor_id

instance_type

security_group_ids

image_id

region

subnet_id

tags

user_data

iam_profile_name

price

Disk Configuration

ebs_volume_size

ebs_delete_on_termination

ebs_device_name

block_device_mappings

ebs_optimized

Network and Communication Configuration

associate_public_ip

private_ip_address

interface

ssh_key

ssh_timeout

ssh_retries

username

Example

Development

Authors

License