Low commit activity in last 3 years
No release in over a year
A Test Kitchen Driver for Amazon AWS CloudFormation
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
 Dependencies

Runtime

 Project Readme

kitchen-cloudformation

Gem Version Build Status

A Test Kitchen Driver for Amazon AWS Cloudformation.

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

If you wish to use servers specified as a hostname in the converge step then use a AWS VPC where the servers have fixed IP addresses or Elastic IP Addresses.

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.

This can be used with kitchen-inspec or kitchen-verifier-awspec to do verification of AWS infrastructure.

Requirements

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

AWS Configuration Options

key default value Notes
region env_var AWS_REGION The AWS region to use. defaults to 'us-east-1' if no AWS_REGION env var.
shared_credentials_profile nil Specify Credentials Using a Profile Name

CloudFormation Configuration Options

key default value Notes
capabilities Array of capabilities that must be specified before creating or updating certain stacks accepts CAPABILITY_IAM, CAPABILITY_NAMED_IAM
change_set_name Name of the Cloud Formation Change Set to create and then execute at converge time
change_set_template_file File containing the Cloudformation template to use to create the change set
change_set_type UPDATE Cloud Formation Change Set can be CREATE or UPDATE
disable_rollback If the template gets an error don't rollback changes. true/false. default false.
notification_arns [] The Simple Notification Service (SNS) topic ARNs to publish stack related events. Array of Strings.
on_failure Determines what action will be taken if stack creation fails. accepts DO_NOTHING, ROLLBACK, DELETE. You can specify either on_failure or disable_rollback, but not both.
parameters {} Hash of parameters {key: value} to apply to the templates
resource_types [] The template resource types that you have permissions to work with. Array of Strings.
role_arn The Amazon Resource Name (ARN) of an AWS Identity and Access Management (IAM) role that AWS CloudFormation assumes to create the stack.
stack_name Name of the Cloud Formation Stack to create
stack_policy_body Structure containing the stack policy body.
stack_policy_url Location of a file containing the stack policy.
tags {} Hash of tags for stack TagKey: TagValue
template_file File containing the Cloudformation template to run
template_url URL of the file containing the Cloudformation template to run
timeout_in_minutes 0 Timeout if the stack is not created in the time

See http://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html for parameter details.

AWS Authentication

In order to connect to AWS, you must specify the AWS access key id and secret key for your account. There are 3 ways you do this, 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. The aws_access_key_id and aws_secret_access_key parameters can be configured in the .kitchen.yml but its recommended to use 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. This is the file populated by aws configure command line and used by AWS tools in general, so if you are set up for any other AWS tools, you probably already have this. 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 http://docs.aws.amazon.com/sdkforruby/api/index.html#Configuration

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.

Change Sets

Normally kitchen-cloudformation creates the stack from the template file when the kitchen create command if run.

If you specify a change_set_name and a change_set_template_file

  template_file: TestSecurityGroup.template
  change_set_name: mystack-cs
  change_set_template_file: TestSecurityGroupCs.template

then it will also create the change set from the change_set_template_file.

Then when the kitchen converge is run it will apply the change-set so it can be tested.

SSL Certificate File Issues

On windows you can get errors SSLv3 read server certificate B: certificate verify failed as per amazon-archives/aws-sdk-core-ruby#93 .

To overcome this problem set 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

See example at https://github.com/neillturner/cloudformation_repo

kitchen create default-test -l debug

Create the stack if it does not exist and creates a change set if one is specified.

kitchen converge default-test -l debug

Executes the change set if one has been created

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
  change_set_name: mystack-cs
  change_set_template_file: TestSecurityGroupCs.template

provisioner:
  name: Cloudformation

platforms:
  - name: test
    driver:  Cloudformation

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

Apache 2.0 (see LICENSE)

TO DO

-More testing and error handling.

-implement all the options of cloud formation.