Class: AWS::CloudFormation

Inherits:
Object
  • Object
show all
Includes:
StackOptions, 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_summary.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 = "{\n  \"AWSTemplateFormatVersion\" : \"2010-09-09\",\n  \"Description\": \"A simple template\",\n  \"Resources\": {\n    \"web\": {\n      \"Type\": \"AWS::EC2::Instance\",\n      \"Properties\": {\n        \"ImageId\": \"ami-41814f28\"\n      }\n    }\n  }\n}\n"

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, StackOptions Classes: Client, Request, Stack, StackCollection, StackEvent, StackEventCollection, StackOutput, StackResource, StackResourceCollection, StackResourceSummaryCollection, StackSummary, StackSummaryCollection

Instance Method Summary collapse

Methods included from AWS::Core::ServiceInterface

included, #initialize, #inspect

Instance Method Details

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



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



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 



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

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

#stacks ⇒ StackCollection 



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+



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