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

#name ⇒ Object (readonly)

Returns the value of attribute name.



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

def name
  @name
end

Instance Method Details

#cancel_update ⇒ Symbol

Cancel update in-progress.

Returns:

  • (Symbol) —

    :update_cancelled if successful

Raises:



153
154
155
156
157
158
159
160
161
 
# File 'lib/stackup/stack.rb', line 153

def cancel_update
  status = modify_stack do
    cf_stack.cancel_update
  end
  fail StackUpdateError, "update cancel failed" unless status =~ /_COMPLETE$/
  status
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: ROLLBACK —

    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

  • :stack_policy (Hash) —

    stack policy, as Ruby data

  • :stack_policy_body (String) —

    stack policy, as JSON

  • :stack_policy_url (String) —

    location of stack policy

  • :stack_policy_during_update (Hash) —

    temporary stack policy, as Ruby data

  • :stack_policy_during_update_body (String) —

    temporary stack policy, as JSON

  • :stack_policy_during_update_url (String) —

    location of temporary stack policy

  • :template (Hash) —

    stack template, as Ruby data

  • :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:



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/stackup/stack.rb', line 97

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
  if (policy_data = options.delete(:stack_policy))
    options[:stack_policy_body] = MultiJson.dump(policy_data)
  end
  if (policy_data = options.delete(:stack_policy_during_update))
    options[:stack_policy_during_update_body] = MultiJson.dump(policy_data)
  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:



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/stackup/stack.rb', line 129

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"
  status
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:



205
206
207
208
209
210
211
212
213
 
# File 'lib/stackup/stack.rb', line 205

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:



190
191
192
193
194
195
196
197
198
 
# File 'lib/stackup/stack.rb', line 190

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:



221
222
223
224
225
226
227
228
229
 
# File 'lib/stackup/stack.rb', line 221

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:



178
179
180
181
182
183
 
# File 'lib/stackup/stack.rb', line 178

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

#wait ⇒ String

Wait until stack reaches a stable state

Returns:

  • (String) —

    status, once stable



167
168
169
170
171
 
# File 'lib/stackup/stack.rb', line 167

def wait
  modify_stack do
    # nothing
  end
end

#watch(zero = true) {|watcher| ... } ⇒ Object

Yields:

  • (watcher) 


231
232
233
234
235
 
# File 'lib/stackup/stack.rb', line 231

def watch(zero = true)
  watcher = Stackup::StackWatcher.new(cf_stack)
  watcher.zero if zero
  yield watcher
end