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.



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

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.



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

def name
  @name
end

Instance Method Details

#cancel_update ⇒ Symbol

Cancel update in-progress.

Returns:

  • (Symbol) —

    :update_cancelled if successful

Raises:



160
161
162
163
164
165
166
167
168
 
# File 'lib/stackup/stack.rb', line 160

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 an Array of Aws::CloudFormation::Types::Parameter structures

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

    stack tags, either as a Hash, or an Array of Aws::CloudFormation::Types::Tag 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:



101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/stackup/stack.rb', line 101

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] = Parameters.new(parameters).to_a
  end
  if (tags = options[:tags])
    options[:tags] = normalize_tags(tags)
  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:



136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/stackup/stack.rb', line 136

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



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

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) 


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

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:



215
216
217
 
# File 'lib/stackup/stack.rb', line 215

def outputs
  extract_hash(:outputs, :output_key, :output_value)
end

#parameters ⇒ Hash

Get the current parameters.

Returns:

  • (Hash) —

    current stack parameters

Raises:



197
198
199
 
# File 'lib/stackup/stack.rb', line 197

def parameters
  extract_hash(:parameters, :parameter_key, :parameter_value)
end

#resources ⇒ Hash<String, String>

Get stack outputs.

Returns:

  • (Hash<String, String>) —

    mapping of logical resource-name to physical resource-name

Raises:



225
226
227
 
# File 'lib/stackup/stack.rb', line 225

def resources
  extract_hash(:resource_summaries, :logical_resource_id, :physical_resource_id)
end

#status ⇒ String

Returns the current stack status.

Returns:

  • (String) —

    the current stack status

Raises:



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

def status
  handling_validation_error do
    cf_stack.stack_status
  end
end

#tags ⇒ Hash

Get the current tags.

Returns:

  • (Hash) —

    current stack tags

Raises:



206
207
208
 
# File 'lib/stackup/stack.rb', line 206

def tags
  extract_hash(:tags, :key, :value)
end

#template ⇒ Hash

Get the current template.

Returns:

  • (Hash) —

    current stack template, as Ruby data

Raises:



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

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



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

def wait
  modify_stack do
    # nothing
  end
end

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

Yields:

  • (watcher) 


229
230
231
232
233
 
# File 'lib/stackup/stack.rb', line 229

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