You are viewing documentation for version 1 of the AWS SDK for Ruby. Version 2 documentation can be found here.

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/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 Attribute Summary collapse

Instance Method Summary collapse

Methods included from AWS::Core::ServiceInterface

included, #initialize, #inspect

Instance Attribute Details

#client ⇒ Client (readonly)

Returns the low-level CloudFormation client object

Returns:

  • (Client) —

    the low-level CloudFormation client object



146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
 
# File 'lib/aws/cloud_formation.rb', line 146

class CloudFormation

  autoload :Client, 'aws/cloud_formation/client'
  autoload :Errors, 'aws/cloud_formation/errors'
  autoload :Stack, 'aws/cloud_formation/stack'
  autoload :StackCollection, 'aws/cloud_formation/stack_collection'
  autoload :StackEvent, 'aws/cloud_formation/stack_event'
  autoload :StackEventCollection, 'aws/cloud_formation/stack_event_collection'
  autoload :StackOptions, 'aws/cloud_formation/stack_options'
  autoload :StackOutput, 'aws/cloud_formation/stack_output'
  autoload :StackSummaryCollection, 'aws/cloud_formation/stack_summary_collection'
  autoload :StackResource, 'aws/cloud_formation/stack_resource'
  autoload :StackResourceCollection, 'aws/cloud_formation/stack_resource_collection'
  autoload :StackResourceSummaryCollection, 'aws/cloud_formation/stack_resource_summary_collection'

  include Core::ServiceInterface
  include StackOptions

  endpoint_prefix 'cloudformation'

  # @return [StackCollection]
  def stacks
    StackCollection.new(:config => config)
  end

  # @return [StackSummaryCollection]
  def stack_summaries
    StackSummaryCollection.new(:config => config)
  end

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

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

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

end

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.



262
263
264
265
266
267
268
269
 
# 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(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.



196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# 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 ⇒ StackSummaryCollection

Returns:



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

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

#stacks ⇒ StackCollection

Returns:



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

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) 


235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
 
# 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