WARNING

DO NOT use this code in production, it is no longer maintained or supported.

Instead please see puppetlabs-aws if you really want to do this sort of thing in puppet (which I no longer recommend), or Terraform for a generally (in my opinion) better solution.

####Table of Contents

1. Overview
2. Module Description - What the module does and why it is useful
3. Setup - The basics of getting started with aws_api
   • What aws_api affects
   • Setup requirements
   • Beginning with aws_api
4. Usage - Common assumptions and functionality for all types
5. Reference - ALl available types and their properties
6. Limitations - OS compatibility, etc.
7. Development - Guide for contributing to the module

##Overview

This module provides a bridge allowing you to setup Amazon Web Services resources (such as VPCs and Subnets) using the puppet DSL.

NOTE: This module should be considered ALPHA quality - it's likely full of bugs, missing features and going to change drastically before v1.0.0

##Module Description

This module adds 'puppet resource' support for a number of AWS data types, allowing you to query the amazon API interactively from your puppet command line, and then save parts of the configuration into manifests which you can then re-apply.

This can/will eventually be used for auditing current environments and deploying new environments.

##Setup

###What aws_api affects

This module can be used to re-configure (and purge!) your AWS configs, and so acts as the AWS user setup (see below).

Please be extremely careful when using this module to make changes!.

###Setup Requirements

Pluginsync must be enabled to use this module with a puppet master, or you can use it by running standalone

The 'aws-sdk' rubygem is presumed to be available on the system (if running in a puppetmaster), but can be installed via bundler (if running standalone/from a checkout)

You also need an AWS API account with permissions to do any of the tasks you want to perform, and you'll need to have the following environment variables setup:

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY

Alternatively (and recommended) is to run this code from an Amazon machine with an IAM role allowing it API access.

FIXME - further IAM details here..

###Beginning with aws_api

Try exploring using puppet resource, in a checkout:

git clone https://github.com/bobtfish/puppet-aws_api
cd puppet-aws_api
bundle install
bundle exec puppet resource aws_subnet --libdir lib

##Usage

All objects in AWS are taggable, and you are strongly encouraged to use the 'Name' tag to give objects a unique name. If this has not been done (or for auto-generated objects) then the Amazon assigned unique ID will be used instead - these should be possible to use interchangably with names in manifests.

All resources generated by this module will have the 'Name' tag set to the value of the name property (by default the resource title).

It is recommended that any resources which you would like to manage with puppet by given a unique name rather than using the autogenerated ids in manifests, but use of the autogenerated IDs is supported.

All types support additional user set tags in the 'tags' property. FIXME describe tags behaviour.

Types Reference

aws_vpc

Creation/deletion/enumeration supported.

Immutable properties:

• region ( String )
• cidr ( String )
• instance_tenancy ( String )

Mutable properties:

• dhcp_options (ref to aws_dopts)

aws_subnet

Creation/deletion/enumeration supported.

Immutable properties:

• vpc ( ref to aws_vpc )
• cidr ( String )
• az ( String )
• route_table ( ref to aws_routetable ) - FIXME make mutable

aws_cgw

Creation/deletion/enumeration supported.

Immutable properties:

• region
• ip_address
• bgp_asn
• type

aws_dopts

Creation/deletion/enumeration supported, with caveat below:

It would/should be possible to replace user created dhcp options sets, without having to remove and create a new one (as puppet could do this under the hood). This is not yet supported.

Immutable properties:

• region
• domain_name
• domain_name_servers (Array)
• ntp_servers (Array)
• netbios_name_servers (Array)
• netbios_node_type

aws_igw

Creation/deletion/enumeration supported.

Immutable properties:

• vpc ( ref to aws_vpc )

aws_routetable

Only useable for enumeration, i.e. 'puppet resource' currently, do not try to manage resources or demons may fly out of your nose.

Immutable properties:

• subnets ( ref to aws_subnet )
• routes
• vpc ( ref to aws_vpc )

aws_vgw

Creation/deletion/enumeration supported.

Immutable properties:

• vpc ( ref to aws_vpc )
• vpn_type
• availability_zone

aws_vpn

Creation/deletion/enumeration supported.

Immutable properties:

• vgw ( ref to aws_vgw )
• cgw ( ref to aws_cgw )
• type
• routing
• static_routes

aws_iam_user

Creation/deletion/enumeration supported.

Immutable properties:

• path
• name
• arn

Mutable properties:

• groups (Array of refs to aws_iam_group)

aws_iam_group

Creation/deletion/enumeration supported.

Immutable properties:

• arn
• name

Mutable properties:

• policies (Hash of hashes - http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/IAM/Policy.html)

##Limitations

This module is currently pretty dumb in many ways, and doesn't manage the whole set of available options even for the subset of the amazon API which is currently covered. I plan to improve on / fix this and welcome help.

Insisting that the 'Name' tag is unique per object type is a design assumption/limitation, and I'm not interested in changes to that...

##Development

Patches are generally very welcome! Please submit a pull request on github, preferably in a branch :)

Bug reports are also very welcome - please feel free to report an issue and I'll see what I can do about fixing it for you :)