Skip to content


Subversion checkout URL

You can clone with
Download ZIP
A Test Kitchen Driver for Amazon EC2
Latest commit ed68c6f @tyler-ball tyler-ball Merge pull request #177 from zl4bv/ami_lookup
Add support for looking up AMIs with the EC2 API

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

Gem Version Build Status Code Climate

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!


There are no external system requirements for this driver. However you will need access to an AWS account. IAM users should have, at a minimum, permission to manage the lifecycle of an EC2 instance along with modifying components specified in kitchen driver configs. Consider using a permissive managed IAM policy like arn:aws:iam::aws:policy/AmazonEC2FullAccess or tailor one specific to your security requirements.

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.

For Windows instances the generated Administrator password is fetched automatically from Amazon EC2 with the same private key as we use for SSH logins to Linux.

Currently, the following platform names are supported:

  - 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
  - name: windows-2012r2
  - name: windows-2008r2

This will effectively generate a configuration similar to:

  - name: ubuntu-10.04
      image_id: ami-1ab3ce73
      username: ubuntu
  # ...
  - name: centos-6.4
      image_id: ami-bf5021d6
      username: root
  # ...
  - name: windows-2012r2
      image_id: ami-28bc7428
      username: administrator
  # ...

For specific default values, please consult amis.json.

Authenticating with AWS

There are 3 ways you can authenticate against AWS, and we will try them in the following order:

  1. You can specify the access key and access secret (and optionally the session token) through config. See the aws_access_key_id and aws_secret_access_key config sections below to see how to specify these in your .kitchen.yml or through environment variables. If you would like to specify your session token use the environment variable AWS_SESSION_TOKEN.
  2. The shared credentials ini file at ~/.aws/credentials. You can specify multiple profiles in this file and select one with the AWS_PROFILE environment variable or the shared_credentials_profile driver config. Read this for more information.
  3. From an instance profile when running on EC2. This accesses the local metadata service to discover the local instance's IAM instance profile.

This precedence order is taken from

The first method attempted that works will be used. IE, if you want to auth using the instance profile, you must not set any of the access key configs or environment variables, and you must not specify a ~/.aws/credentials file.

Because the Test Kitchen test should be checked into source control and ran through CI we no longer recommend storing the AWS credentials in the .kitchen.yml file. Instead, specify them as environment variables or in the ~/.aws/credentials file.

Windows Configuration

If you specify a platform name of windows-2012r2 or windows-2008 Test Kitchen will pull a default AMI out of amis.json if one is not specified.

The default user_data will add any username with its associated password from the transport options to the Aministrator group. If no username is specified then the default administrator is available.

AWS automatically generates an administrator password in the default Windows AMIs. Test Kitchen fetches this and stores it in the .kitchen/#{platform}.json file. If you need to kitchen login to the instance and you have not specified your own username and password you can use the administrator user and the password from this file. Unfortunately we cannot auto-fill the RDP password at this point.

General Configuration


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

The default is "#{region}b".


Deprecated It is recommended to use the AWS_ACCESS_KEY_ID or the ~/.aws/credentials file instead.

The AWS access key id to use.


Deprecated It is recommended to use the AWS_SECRET_ACCESS_KEY or the ~/.aws/credentials file instead.

The AWS secret access key to use.


The EC2 profile name to use when reading credentials out of ~/.aws/credentials. If it is not specified AWS will read the Default profile credentials (if using this method of authentication).

Can also be specified as ENV['AWS_PROFILE'].


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.


Deprecated It is recommended to use the AWS_SESSION_TOKEN or the ~/.aws/credentials file instead.

The AWS session token to use.


Deprecated See instance_type below.


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

The default is "m1.small".


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

The default is ["default"].


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.


Searches the EC2 API for the latest AMI ID that matches the given filters.

For example, a search for the latest AMI that matches a given image name looks like:

  name: Windows_Server-2012-R2_RTM-English-64Bit-Base-*


Required The AWS region to use.

If the environment variable AWS_REGION is populated that will be used. Otherwise the default is "us-east-1".


The EC2 subnet to use.

The default is unset, or nil.


The Hash of EC tag name/value pairs which will be applied to the instance.

The default is { "created-by" => "test-kitchen" }.


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!

On linux instances the default is unset, or nil.

On Windows instances we specify a default that enables winrm and adds a non-administrator user specified in the username transport options to the Administrator's User Group.


The EC2 IAM profile name to use.

The default is nil.


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.


Specify a proxy to send AWS requests through. Should be of the format http://<host>:<port>.

The default is ENV["HTTPS_PROXY"] || ENV["HTTP_PROXY"]. If you have these environment variables set and do not want to use a proxy when contacting aws set http_proxy: nil.

Note - The AWS command line utility allow you to specify two proxies, one for HTTP and one for HTTPS. The AWS Ruby SDK only allows you to specify 1 proxy and because all requests are https:// this proxy needs to support HTTPS.

Disk Configuration


Deprecated See block_device_mappings below.

Size of ebs volume in GB.


Deprecated See block_device_mappings below.

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


Deprecated See block_device_mappings below.

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


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

  - ebs_device_name: /dev/sda
    ebs_volume_size: 20
    ebs_delete_on_termination: true
  - ebs_device_name: /dev/sdb
    ebs_volume_type: gp2
    ebs_virtual_name: test
    ebs_volume_size: 15
    ebs_delete_on_termination: true
    ebs_snapshot_id: snap-0015d0bc
  - ebs_device_name: /dev/sdc
    ebs_volume_size: 100
    ebs_delete_on_termination: true
    ebs_volume_type: io1
    ebs_iops: 100

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 specify io1 you must also specify ebs_iops.

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.


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


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.


The primary private IP address of your instance.

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


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:

  1. DNS Name
  2. Public IP Address
  3. Private IP Address

The default is unset.


Deprecated Instead use the ssh_key transport option like

  ssh_key: ~/.ssh/id_rsa

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

The default is unset, or nil.


Deprecated Instead use the connection_timeout transport key like

  connection_timeout: 60

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

The default is 1.


Deprecated Instead use the connection_retries transport key like

  connection_retries: 10

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

The default is 3.


Deprecated Instead use the username transport key like

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

On Windows hosts with the default user_data this user is added to the Administrator's group.


The following could be used in a .kitchen.yml or in a .kitchen.local.yml to override default configuration.

  name: ec2
  aws_ssh_key_id: id_rsa-aws
  security_group_ids: ["sg-1a2b3c4d"]
  region: us-west-2
  availability_zone: b
  require_chef_omnibus: true
  subnet_id: subnet-6e5d4c3b
  iam_profile_name: chef-client
  instance_type: m3.medium
  associate_public_ip: true
  interface: dns

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

  - name: ubuntu-12.04
  - name: centos-6.4
  - name: ubuntu-15.04
      image_id: ami-83211eb3
        - ebs_device_name: /dev/sda1
          ebs_volume_type: standard
          ebs_virtual_name: test
          ebs_volume_size: 15
          ebs_delete_on_termination: true
  - name: centos-7
      image_id: ami-c7d092f7
        - ebs_device_name: /dev/sdb
          ebs_volume_type: gp2
          ebs_virtual_name: test
          ebs_volume_size: 8
          ebs_delete_on_termination: true
      username: centos
  - name: windows-2012r2
  - name: windows-2008r2

# ...


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


Created and maintained by Fletcher Nichol (


Apache 2.0 (see LICENSE)

Something went wrong with that request. Please try again.