class AWS::CloudFormation

# AWS::CloudFormation

Provides an expressive, object-oriented interface to AWS CloudFormation.

## Credentials

You can setup default credentials for all AWS services via AWS.config:

AWS.config(
  :access_key_id => 'YOUR_ACCESS_KEY_ID',
  :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')

Or you can set them directly on the CloudFormation interface:

cf = AWS::CloudFormation.new(
  :access_key_id => 'YOUR_ACCESS_KEY_ID',
  :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')

# Stacks

This is the starting point for working with CloudFormation.

## Creating a Stack

You can create a CloudFormation stack with a name and a template.

template = <<-TEMPLATE
{
  "AWSTemplateFormatVersion" : "2010-09-09",
  "Description": "A simple template",
  "Resources": {
    "web": {
      "Type": "AWS::EC2::Instance",
      "Properties": {
        "ImageId": "ami-41814f28"
      }
    }
  }
}
TEMPLATE

cfm = AWS::CloudFormation.new
stack = cfm.stacks.create('stack-name', template)

See {StackCollection#create} for more information on creating templates with capabilities and parameters.

## Getting a Stack

Given a name, you can fetch a {Stack}.

stack = cfm.stacks['stack-name']

## Enumerating Stacks

You can enumerate stacks in two ways. You can enumerate {Stack} objects or stack summaries (simple hashes). You can filter the stack summary collection by a status.

# enumerating all stack objects
cfm.stacks.each do |stack|
  # ...
end

# enumerating stack summaries (hashes)
cfm.stack_summaries.each do |stack_summary|
  # ...
end

# filtering stack summaries by status
cfm.stack_summaries.with_status(:create_failed).each do |summary|
  puts summary.to_yaml
end

## Template

You can fetch the template body for a stack as a JSON string.

cfm.stacks['stack-name'].template
#=> "{...}"

You can update the template for a {Stack} with the {Stack#update} method:

cfm.stacks['stack-name'].update(:template => new_template)

## Stack Events

You can enumerate events for a stack.

stack.events.each do |event|
  puts "#{event.physical_resource_id}: #{event.resource_status}"
end

See {StackEvent} for a complete list of event attributes.

## Stack Resources

You can enumerate stack resources or request a stack resource by its logical resource id.

# enumerating stack resources
stack.resources.each do |resource|
  # ...
end

# getting a resource by its logical id
res = stack.resources['logical-resource-id']
puts res.physical_resource_id

If you need a stack resource, but only have its physical resource id, then you can call {CloudFormation#stack_resource}.

stack_resource = cfm.stack_resource('physical-resource-id')

## Stack Resource Summaries

As an alternative to stack resources, you can enumerate stack resource summaries (hashes).

# enumerate all resources, this collection can not be filtered
stack.resource_summaries.each do |summary|
  # ...
end

@!attribute [r] client

@return [Client] the low-level CloudFormation client object

Public Instance Methods

estimate_template_cost(template, parameters = {}) click to toggle source

@param (see Stack#template=)

@param [Hash] parameters A hash that specifies the input

parameters for the template.

@return [String] Returns a URL to the AWS Simple Monthly Calculator

with a query string that describes the resources required to run
the template.
# File lib/aws/cloud_formation.rb, line 262
def estimate_template_cost template, parameters = {}
  client_opts = {}
  client_opts[:template] = template
  client_opts[:parameters] = parameters
  apply_template(client_opts)
  apply_parameters(client_opts)
  client.estimate_template_cost(client_opts).url
end
stack_resource(*args) click to toggle source

Returns a stack resource with the given physical resource id.

resource = cfm.stack_resource('i-123456789')

Alternatively, you may pass a stack name and logical resource id:

resource = cfm.stack_resource('stack-name', 'logical-resource-id')

@overload #stack_resource(physical_resource_id)

@param [String] physical_resource_id The physical resource id
  of the stack resource you want returned.

@overload #stack_resource(stack_name, logical_resource_id)

@param [String] stack_name
@param [String] logical_resource_id

@return [StackResource] Returns the stack resource with the

given physical resource id.
# File lib/aws/cloud_formation.rb, line 196
def stack_resource *args

  client_opts = {}

  if args.size == 1
    client_opts[:physical_resource_id] = args.first
  else
    client_opts[:stack_name] = args[0]
    client_opts[:logical_resource_id] = args[1]
  end

  response = client.describe_stack_resources(client_opts)

  details = response.stack_resources.first

  StackResource.new_from(
    :describe_stack_resource, details,
    Stack.new(details.stack_name, :config => config),
    details.logical_resource_id)

end
stack_summaries() click to toggle source

@return [StackSummaryCollection]

# File lib/aws/cloud_formation.rb, line 172
def stack_summaries
  StackSummaryCollection.new(:config => config)
end
stacks() click to toggle source

@return [StackCollection]

# File lib/aws/cloud_formation.rb, line 167
def stacks
  StackCollection.new(:config => config)
end
validate_template(template) click to toggle source

Validates the template and returns a hash. If the template is valid, the returned hash may/will contain the following keys (actual key list depends on the template).

* `:description`
* `:capabilities`
* `:capabilities_reason`
* `:parameters`

If the template is not parseable, then a hash will the following keys will be returned:

* `:code`
* `:message`

@return [Hash]

# File lib/aws/cloud_formation.rb, line 235
def validate_template template
  begin

    client_opts = {}
    client_opts[:template] = template
    apply_template(client_opts)
    client.validate_template(client_opts).data

  rescue CloudFormation::Errors::ValidationError => e

    results = {}
    results[:code] = e.code
    results[:message] = e.message
    results

  end
end