Class: Stackup::Stack

Inherits:
Object
  • Object
show all
Includes:
ErrorHandling
Defined in:
lib/stackup/stack.rb

Overview

An abstraction of a CloudFormation stack.

Constant Summary collapse

ALMOST_DEAD_STATUSES = 
%w(CREATE_FAILED ROLLBACK_COMPLETE)

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from ErrorHandling

#handling_validation_error

Constructor Details

#initialize(name, client = {}, options = {}) ⇒ Stack

Returns a new instance of Stack.



13
14
15
16
17
18
19
20
 
# File 'lib/stackup/stack.rb', line 13

def initialize(name, client = {}, options = {})
  client = Aws::CloudFormation::Client.new(client) if client.is_a?(Hash)
  @name = name
  @cf_client = client
  options.each do |key, value|
    public_send("#{key}=", value)
  end
end

Instance Attribute Details

#cf_client ⇒ Object (readonly)

Returns the value of attribute cf_client.



22
23
24
 
# File 'lib/stackup/stack.rb', line 22

def cf_client
  @cf_client
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



22
23
24
 
# File 'lib/stackup/stack.rb', line 22

def name
  @name
end

#watcher ⇒ Object (readonly)

Returns the value of attribute watcher.



22
23
24
 
# File 'lib/stackup/stack.rb', line 22

def watcher
  @watcher
end

Instance Method Details

#cancel_update ⇒ Symbol

Cancel update in-progress.

Returns:

  • (Symbol) —

    :update_cancelled if successful

Raises:



143
144
145
146
147
148
149
150
151
 
# File 'lib/stackup/stack.rb', line 143

def cancel_update
  status = modify_stack do
    cf_stack.cancel_update
  end
  fail StackUpdateError, "update cancel failed" unless status =~ /_COMPLETE$/
  :update_cancelled
rescue InvalidStateError
  nil
end

#create_or_update(options) ⇒ Symbol Also known as: up

Create or update the stack.

Parameters:

Options Hash (options):

  • :capabilities (Array<String>) — default: CAPABILITY_IAM —

    list of capabilities required for stack template

  • :disable_rollback (boolean) — default: false —

    if true, disable rollback if stack creation fails

  • :notification_arns (String) —

    ARNs for the Amazon SNS topics associated with this stack

  • :on_failure (String) — default: DO_NOTHING —

    if stack creation fails: DO_NOTHING, ROLLBACK, or DELETE

  • :parameters (Hash, Array<Hash>) —

    stack parameters, either as a Hash, or as an Array of Aws::CloudFormation::Types::Parameter structures

  • :resource_types (Array<String>) —

    resource types that you have permissions to work with

  • :template (Hash) —

    stack template, as Ruby data

  • :stack_policy_body (String) —

    stack policy, as JSON

  • :stack_policy_url (String) —

    location of stack policy

  • :stack_policy_during_update_body (String) —

    temporary stack policy, as JSON

  • :stack_policy_during_update_url (String) —

    location of temporary stack policy

  • :template_body (String) —

    stack template, as JSON

  • :template_url (String) —

    location of stack template

  • :timeout_in_minutes (Integer) —

    stack creation timeout

  • :use_previous_template (boolean) —

    if true, reuse the existing template

Returns:

  • (Symbol) —

    :created or :updated if successful

Raises:



93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/stackup/stack.rb', line 93

def create_or_update(options)
  options = options.dup
  if (template_data = options.delete(:template))
    options[:template_body] = MultiJson.dump(template_data)
  end
  if (parameters = options[:parameters])
    options[:parameters] = normalise_parameters(parameters)
  end
  options[:capabilities] ||= ["CAPABILITY_IAM"]
  delete if ALMOST_DEAD_STATUSES.include?(status)
  update(options)
rescue NoSuchStack
  create(options)
end

#delete ⇒ Symbol Also known as: down

Delete the stack.

Parameters:

  • template (String) —

    template JSON

  • parameters (Array<Hash>) —

    template parameters

Returns:

  • (Symbol) —

    :deleted if successful

Raises:



119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/stackup/stack.rb', line 119

def delete
  begin
    @stack_id = handling_validation_error do
      cf_stack.stack_id
    end
  rescue NoSuchStack
    return nil
  end
  status = modify_stack do
    cf_stack.delete
  end
  fail StackUpdateError, "stack delete failed" unless status == "DELETE_COMPLETE"
  :deleted
ensure
  @stack_id = nil
end

#exists? ⇒ boolean

Returns true iff the stack exists.

Returns:

  • (boolean) —

    true iff the stack exists



46
47
48
49
50
51
 
# File 'lib/stackup/stack.rb', line 46

def exists?
  status
  true
rescue NoSuchStack
  false
end

#on_event(event_handler = nil, &block) ⇒ Object

Register a handler for reporting of stack events.

Parameters:

  • event_handler (Proc) (defaults to: nil) 


27
28
29
30
31
 
# File 'lib/stackup/stack.rb', line 27

def on_event(event_handler = nil, &block)
  event_handler ||= block
  fail ArgumentError, "no event_handler provided" if event_handler.nil?
  @event_handler = event_handler
end

#outputs ⇒ Hash<String, String>

Get stack outputs.

Returns:

  • (Hash<String, String>) —

    stack outputs

Raises:



185
186
187
188
189
190
191
192
193
 
# File 'lib/stackup/stack.rb', line 185

def outputs
  handling_validation_error do
    {}.tap do |h|
      cf_stack.outputs.each do |o|
        h[o.output_key] = o.output_value
      end
    end
  end
end

#parameters ⇒ Hash

Get the current parameters.

Returns:

  • (Hash) —

    current stack parameters

Raises:



170
171
172
173
174
175
176
177
178
 
# File 'lib/stackup/stack.rb', line 170

def parameters
  handling_validation_error do
    {}.tap do |h|
      cf_stack.parameters.each do |p|
        h[p.parameter_key] = p.parameter_value
      end
    end
  end
end

#resources ⇒ Hash<String, String>

Get stack outputs.

Returns:

  • (Hash<String, String>) —

    mapping of logical resource-name to physical resource-name

Raises:



201
202
203
204
205
206
207
208
209
 
# File 'lib/stackup/stack.rb', line 201

def resources
  handling_validation_error do
    {}.tap do |h|
      cf_stack.resource_summaries.each do |r|
        h[r.logical_resource_id] = r.physical_resource_id
      end
    end
  end
end

#status ⇒ String

Returns the current stack status.

Returns:

  • (String) —

    the current stack status

Raises:



38
39
40
41
42
 
# File 'lib/stackup/stack.rb', line 38

def status
  handling_validation_error do
    cf_stack.stack_status
  end
end

#template ⇒ Hash

Get the current template.

Returns:

  • (Hash) —

    current stack template, as Ruby data

Raises:



158
159
160
161
162
163
 
# File 'lib/stackup/stack.rb', line 158

def template
  handling_validation_error do
    template_json = cf_client.get_template(:stack_name => name).template_body
    MultiJson.load(template_json)
  end
end