Class: AWS::CloudFormation

Inherits:
Object
  • Object
show all
Includes:
AWS::Core::ServiceInterface
Defined in:
lib/aws/cloud_formation.rb,
lib/aws/cloud_formation/stack.rb,
lib/aws/cloud_formation/client.rb,
lib/aws/cloud_formation/errors.rb,
lib/aws/cloud_formation/request.rb,
lib/aws/cloud_formation/stack_event.rb,
lib/aws/cloud_formation/stack_output.rb,
lib/aws/cloud_formation/stack_options.rb,
lib/aws/cloud_formation/stack_resource.rb,
lib/aws/cloud_formation/stack_collection.rb,
lib/aws/cloud_formation/stack_event_collection.rb,
lib/aws/cloud_formation/stack_summary_collection.rb,
lib/aws/cloud_formation/stack_resource_collection.rb,
lib/aws/cloud_formation/stack_resource_summary_collection.rb

Overview

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

Defined Under Namespace

Modules: Errors Classes: Client, Stack, StackCollection, StackEvent, StackEventCollection, StackOutput, StackResource, StackResourceCollection, StackResourceSummaryCollection, StackSummaryCollection

Instance Method Summary collapse

Methods included from AWS::Core::ServiceInterface

#initialize, #inspect

Instance Method Details

#estimate_template_cost(template, parameters = {}) ⇒ String

Returns a URL to the AWS Simple Monthly Calculator with a query string that describes the resources required to run the template.

Parameters:

  • parameters (Hash) (defaults to: {}) —

    A hash that specifies the input parameters for the template.

Returns:

  • (String) —

    Returns a URL to the AWS Simple Monthly Calculator with a query string that describes the resources required to run the template.



261
262
263
264
265
266
267
 
# File 'lib/aws/cloud_formation.rb', line 261

def estimate_template_cost template, parameters = {}
  client_opts = {}
  client_opts[:template] = template
  apply_template(client_opts)  
  apply_parameters(client_opts)  
  client.estimate_template_cost(client_opts).url
end

#stack_resource(physical_resource_id) ⇒ StackResource #stack_resource(stack_name, logical_resource_id) ⇒ StackResource

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')

Overloads:

  • #stack_resource(physical_resource_id) ⇒ StackResource

    Parameters:

    • physical_resource_id (String) —

      The physical resource id of the stack resource you want returned.

  • #stack_resource(stack_name, logical_resource_id) ⇒ StackResource

    Parameters:

    • stack_name (String)
    • logical_resource_id (String)

Returns:

  • (StackResource) —

    Returns the stack resource with the given physical resource id.



195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
 
# File 'lib/aws/cloud_formation.rb', line 195

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 ⇒ StackSummaryCollection

Returns:



171
172
173
 
# File 'lib/aws/cloud_formation.rb', line 171

def stack_summaries
  StackSummaryCollection.new(:config => config)
end

#stacks ⇒ StackCollection

Returns:



166
167
168
 
# File 'lib/aws/cloud_formation.rb', line 166

def stacks
  StackCollection.new(:config => config)
end

#validate_template(template) ⇒ Hash

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+

Returns:

  • (Hash) 


234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/aws/cloud_formation.rb', line 234

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