kitchen-cloudformation

Gem Version Build Status

A Test Kitchen Driver for Amazon AWS Cloudformation.

This driver uses the [aws sdk gem][aws_sdk_gem] to create and delete Amazon AWS Cloudformation stacks to orchestrate your cloud resources for your infrastructure testing, dev or production setup.

It works best using AWS VPC where the servers have fixed IP addresses or in AWS Clasic using known Elastic IP Addresses. This allow the IP address of each of the servers to be specified as a hostname in the suite definition (see example below).

So you can deploy and test say a Mongodb High Availability cluster by using cloud formation to create the servers and then converge each of the servers in the cluster and run tests.

WARNING: This is a pre-release version. I'm sure the code does not handle all error conditions etc.

Requirements

There are no external system requirements for this driver. However you will need access to an [AWS][aws_site] account.

Configuration Options

key default value Notes
region ENV["AWS_REGION"] or "us-east-1" Aws Region
shared_credentials_profile nil Specify Credentials Using a Profile Name
aws_access_key_id nil Deprecated see Authenticating with AWS
aws_secret_access_key nil Deprecated see Authenticating with AWS
aws_session_token nil Deprecated see Authenticating with AWS
ssl_cert_file ENV["SSL_CERT_FILE"] SSL Certificate required on Windows platforms
stack_name Name of the Cloud Formation Stack to create
template_file File containing the Cloudformation template to run
template_url URL of the file containing the Cloudformation template to run
parameters {} Hash of parameters value to apply to the templates
disable_rollback false If the template gets an error don't rollback changes
timeout_in_minutes 0 Timeout if the stack is not created in the time

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][credentials_docs] 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 http://docs.aws.amazon.com/sdkforruby/api/index.html#Configuration

In summary it searches the following locations for credentials:

   ENV['AWS_ACCESS_KEY_ID'] and ENV['AWS_SECRET_ACCESS_KEY']
   The shared credentials ini file at ~/.aws/credentials (more information)
   From an instance profile when running on EC2

and it searches the following locations for a region:

   ENV['AWS_REGION']

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.

SSL Certificate File Issues

On windows you can get errors SSLv3 read server certificate B: certificate verify failed as per https://github.com/aws/aws-sdk-core-ruby/issues/93 .

To overcome this problem set the parameter ssl_cert_file or the environment variable SSL_CERT_FILE to a a SSL CA bundle.

A file ca-bundle.crt is supplied inside this gem for this purpose so you can set it to something like: <RubyHome>/lib/ruby/gems/2.1.0/gems/kitchen-cloudformation-0.0.1/ca-bundle.crt

Example

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

---
driver:
  name: cloudformation
  stack_name: mystack
  template_file: /test/example.template
  parameters:
    - base_package: wget

provisioner:
  name: chef_zero

platforms:
  - name: centos-6.4
    driver:  Cloudformation

suites:
  - name: default
    driver_config:
      ssh_key: /mykeys/mykey.pem
      username: root
      hostname: '10.53.191.70'

License

Apache 2.0 (see [LICENSE][license])

[author]: https://github.com/neillturner [issues]: https://github.com/neillturner/kitchen-cloudformation/issues [license]: https://github.com/neillturner/kitchen-cloudformation/blob/master/LICENSE [repo]: https://github.com/neillturner/kitchen-cloudformation [driver_usage]: http://docs.kitchen-ci.org/drivers/usage [chef_omnibus_dl]: http://www.getchef.com/chef/install/

[aws_site]: http://aws.amazon.com/ [credentials_docs]: http://blogs.aws.amazon.com/security/post/Tx3D6U6WSFGOK2H/A-New-and-Standardized-Way-to-Manage-Credentials-in-the-AWS-SDKs [aws_sdk_gem]: http://docs.aws.amazon.com/sdkforruby/api/index.html [cloud_formation_docs]: http://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/Welcome.html

TO DO

-More testing and error handling.

-implement all the options of cloud formation.

-We also need plugins for: OpenStack Heat Azure Resource Manager Google Cloud Deployment Manager but i'm not aware of any ruby sdks for these yet.