####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 :)

For developers: Puppetx::Bobtfish::Aws_api explained

(If you are not making changes or adding to the aws_api ruby code, it is enitrely safe to ignore this section).

All AWS resource providers share a common base class that provides much of the heavy lifitng and dealing with the various pecularities of exposing the AWS API as a puppet resource. This includes (among other things):

• Knowing which region's API endpoint to query and avoiding API calls to regions far-off regions not present in our manifests.
• Dealing with the fact that most AWS API operations are not synchronous - manifest changes have to know how and when to wait and ensure AWS resources are actually "ready" before attempting to continue setting up dependent resources.
• Efficiently handling state changes of arbitrary subsets of properties which can span over several different APIs for the same resource.
• Making it easier to work with AWS' interconnected graph of dependent or related resources.

In impelmentation terms, this broadly speaking boils down to:

• Assigning each resource to a particular AWS API (see primary_api)
• Making sure each resource knows what region it's in and how to collect instances of itself for that region (see find_region_from and aws_items_for_region)
• Making puppet aware of all possible resource states and transitional states (see ensure_from_state).
• Using a slightly modified version of the flush pattern to apply state changes in bulk as efficiently as possible (see flushing_resource_methods, flush_when_ready and the flushing helper).

The Aws_ec2_instance provider implementation illustrates all the above concepts and is a good starting point for new resources.

Please consult aws_api.rb for further details.