####Table of Contents
- Overview
- Description - What the module does and why it is useful
- Setup - Getting started
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
##Overview
Puppet module for managing Amazon Web Services (AWS) resources to build out cloud infrastructure.
##Description
Amazon Web Services exposes a powerful API for creating and managing its Infrastructure as a Service platform. This module allows you to drive that API using Puppet code. In the simplest case this allows you to create new EC2 instances from Puppet code, but more importantly it allows you to describe your entire AWS infrastructure and to model the relationships between different components.
##Setup
The module relies on the Amazon AWS Ruby SDK, so first install this. The SDK is available as a gem so install it into the same Ruby as used by Puppet.
gem install aws-sdk-core
Once the library is installed you'll need to set a few environment variables for your AWS access credentials.
export AWS_ACCESS_KEY_ID=your_access_key_id
export AWS_SECRET_ACCESS_KEY=your_secret_access_key
Alternatively, you can place the credentials in a file at ~/.aws/credentials based on the following template:
[default]
aws_access_key_id = your_access_key_id
aws_secret_access_key = your_secret_access_key
And finally you can install the module with:
puppet module install puppetlabs-aws
By default the module will look through all regions in AWS when determining if something is available. This can be a little slow. If you know what you're doing you can speed things up by targeting a single region using an environment variable.
export AWS_REGION=eu-west-1
##Usage
Let's start with an example. Let's aim to create the following simple stack in AWS.
WWW
+
|
+----------------|-----------------+
| +----------v-----------+ |
lb-sg | | lb-1 | |
| +----+------------+----+ |
+----------|------------|----------+
+----------|------------|----------+
| +----v----+ +----v----+ |
| | | | | |
web-sg | | web-1 | | web-2 | |
| | | | | |
| +----+----+ +----+----+ |
+----------|------------|----------+
+----------|------------|----------+
| +----v----+ | |
| | | | |
db-sg | | db-1 <-------+ |
| | | |
| +---------+ |
+----------------------------------+
Running the provided sample code with Puppet apply:
puppet apply tests/create.pp --test
If you want to try this out from this directory without installing the
module with puppet module
or similar you can run the following:
puppet apply tests/create.pp --modulepath ../ --test
To destroy the resources created by the above you can run the following:
puppet apply tests/destroy.pp --test
The examples directory contains other examples which should give an idea of what's possible.
The module also has basic puppet resource
support, so for example the
following will list all the security groups:
puppet resource ec2_securitygroup
We can also create new resources:
puppet resource ec2_securitygroup test-group ensure=present description="test description" region=us-east-1
and then destroy them, all from the command line:
puppet resource ec2_securitygroup test-group ensure=absent region=sa-east-1
##Reference
The following shows each of the new types along with a full list of their parameters.
ec2_instance { 'name-of-instance':
ensure => present,
region => 'us-east-1',
availability_zone => 'us-east-1a',
image_id => 'ami-123456',
instance_type => 't1.micro',
monitoring => true,
key_name => 'name-of-existing-key',
security_groups => ['name-of-security-group'],
user_data => template('module/file-path.sh.erb'),
tags => {
tag_name => 'value',
},
}
ec2_securitygroup { 'name-of-group':
ensure => present,
region => 'us-east-1',
description => 'a description of the group',
ingress => [{
protocol => 'tcp',
port => 80,
cidr => '0.0.0.0/0',
},{
security_group => 'other-security-group',
}],
tags => {
tag_name => 'value',
},
}
elb_loadbalancer { 'name-of-load-balancer':
ensure => present,
region => 'us-east-1',
availability_zones => ['us-east-1a', 'us-east-1b'],
instances => ['name-of-instance', 'another-instance'],
security_groups => ['name-of-security-group'],
listeners => [{
protocol => 'tcp',
port => 80,
}],
tags => {
tag_name => 'value',
},
}
##Limitations
At the moment this module only supports a small number of the resources
in the AWS API. These resources also exist a little bit outside the
normal host level resources like package
, file
, user
, etc. We're
really interested to see how people use these new resources, and what
else you would like to be able to do with the module.
Note that this module also requires at least Ruby 1.9 and is only tested on Puppet versions from 3.4. If this is too limiting please let us know.