Class: Cfer::Core::Stack

Inherits:
Block
  • Object
show all
Includes:
Functions, Hooks
Defined in:
lib/cfer/core/stack.rb

Overview

Defines the structure of a CloudFormation stack

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Hooks

included, #post_block, #pre_block

Methods included from Functions

#and, #cidr, #equals, #find_in_map, #get_att, #get_azs, #if, #join, #not, #notification_arns, #or, #ref, #select, #split, #sub

Methods inherited from Block

#build_from_block, #build_from_file, #build_from_string, #include_file, #post_block, #pre_block

Constructor Details

#initialize(options = {}) ⇒ Stack

Returns a new instance of Stack.



30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/cfer/core/stack.rb', line 30

def initialize(options = {})
  self[:AWSTemplateFormatVersion] = '2010-09-09'
  self[:Description] = ''

  @options = options

  self[:Metadata] = {
    :Cfer => {
      :Version => Cfer::SEMANTIC_VERSION.to_h.delete_if { |k, v| v === nil }
    }
  }

  self[:Parameters] = {}
  self[:Mappings] = {}
  self[:Conditions] = {}
  self[:Resources] = {}
  self[:Outputs] = {}

  if options[:client] && git = options[:client].git
    begin
      @git_state = git.object('HEAD^')
      self[:Metadata][:Cfer][:Git] = {
        Rev: git_state.sha,
        Clean: git.status.changed.empty?
      }
    rescue => e
      Cfer::LOGGER.warn("Unable to add Git information to CloudFormation Metadata. #{e}")
    end
  end

  @parameters = HashWithIndifferentAccess.new
  @input_parameters = HashWithIndifferentAccess.new

  if options[:client]
    begin
      @parameters.merge! options[:client].fetch_parameters
    rescue Cfer::Util::StackDoesNotExistError
      Cfer::LOGGER.debug "Can't include current stack parameters because the stack doesn't exist yet."
    end
  end

  if options[:parameters]
    options[:parameters].each do |key, val|
      @input_parameters[key] = @parameters[key] = val
    end
  end
end

Instance Attribute Details

#git_state ⇒ Object (readonly)

Returns the value of attribute git_state.



16
17
18
 
# File 'lib/cfer/core/stack.rb', line 16

def git_state
  @git_state
end

#input_parameters ⇒ Object (readonly)

The parameters strictly as passed via command line



9
10
11
 
# File 'lib/cfer/core/stack.rb', line 9

def input_parameters
  @input_parameters
end

#options ⇒ Object (readonly)

Returns the value of attribute options.



14
15
16
 
# File 'lib/cfer/core/stack.rb', line 14

def options
  @options
end

#parameters ⇒ Object (readonly)

The fully resolved parameters, including defaults and parameters fetched from an existing stack during an update



12
13
14
 
# File 'lib/cfer/core/stack.rb', line 12

def parameters
  @parameters
end

Class Method Details

.extend_stack(&block) ⇒ Object 



200
201
202
 
# File 'lib/cfer/core/stack.rb', line 200

def extend_stack(&block)
  class_eval(&block)
end

Instance Method Details

#client ⇒ Object

Gets the Cfn client, if one exists, or throws an error if one does not



171
172
173
 
# File 'lib/cfer/core/stack.rb', line 171

def client
  @options[:client] || raise('No client set on this stack')
end

#condition(name, expr) ⇒ Object

Adds a condition to the template.

Parameters:



133
134
135
 
# File 'lib/cfer/core/stack.rb', line 133

def condition(name, expr)
  self[:Conditions][name] = expr
end

#converge!(options = {}) ⇒ Object 



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

def converge!(options = {})
  client.converge self, options
end

#description(desc) ⇒ Object

Sets the description for this CloudFormation stack



79
80
81
 
# File 'lib/cfer/core/stack.rb', line 79

def description(desc)
  self[:Description] = desc
end

#include_template(*files) ⇒ Object

Includes template code from one or more files, and evals it in the context of this stack. Filenames are relative to the file containing the invocation of this method.



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

def include_template(*files)
  include_base = options[:include_base] || File.dirname(caller.first.split(/:\d/,2).first)
  files.each do |file|
    path = File.join(include_base, file)
    include_file(path)
  end
end

#lookup_output(stack, out) ⇒ Object

Looks up a specific output of another CloudFormation stack in the same region.

Parameters:

  • stack (String) —

    The name of the stack to fetch an output from

  • out (String) —

    The name of the output to fetch from the stack



188
189
190
 
# File 'lib/cfer/core/stack.rb', line 188

def lookup_output(stack, out)
  lookup_outputs(stack).fetch(out)
end

#lookup_outputs(stack) ⇒ Object

Looks up a hash of all outputs from another CloudFormation stack in the same region.

Parameters:

  • stack (String) —

    The name of the stack to fetch outputs from



194
195
196
197
 
# File 'lib/cfer/core/stack.rb', line 194

def lookup_outputs(stack)
  client = @options[:client] || raise(Cfer::Util::CferError, "Can not fetch stack outputs without a client")
  client.fetch_outputs(stack)
end

#mappings(mappings) ⇒ Object

Sets the mappings block for this stack. See The CloudFormation Documentation for more details



126
127
128
 
# File 'lib/cfer/core/stack.rb', line 126

def mappings(mappings)
  self[:Mappings] = mappings
end

#output(name, value, options = {}) ⇒ Object

Adds an output to the CloudFormation stack.

Parameters:

  • name (String) —

    The Logical ID of the output parameter

  • value (String) —

    Value to return

  • options (Hash) (defaults to: {}) —

    Extra options for this output parameter

Options Hash (options):

  • :Description (String) —

    Information about the value



156
157
158
 
# File 'lib/cfer/core/stack.rb', line 156

def output(name, value, options = {})
  self[:Outputs][name] = options.merge('Value' => value)
end

#parameter(name, options = {}) ⇒ Object

Declares a CloudFormation parameter

Parameters:

  • name (String) —

    The parameter name

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :type (String) —

    The type for the CloudFormation parameter

  • :default (String) —

    A value of the appropriate type for the template to use if no value is specified when a stack is created. If you define constraints for the parameter, you must specify a value that adheres to those constraints.

  • :no_echo (String) —

    Whether to mask the parameter value whenever anyone makes a call that describes the stack. If you set the value to true, the parameter value is masked with asterisks (*****).

  • :allowed_values (String) —

    An array containing the list of values allowed for the parameter.

  • :allowed_pattern (String) —

    A regular expression that represents the patterns you want to allow for String types.

  • :max_length (Number) —

    An integer value that determines the largest number of characters you want to allow for String types.

  • :min_length (Number) —

    An integer value that determines the smallest number of characters you want to allow for String types.

  • :max_value (Number) —

    A numeric value that determines the largest numeric value you want to allow for Number types.

  • :min_value (Number) —

    A numeric value that determines the smallest numeric value you want to allow for Number types.

  • :description (String) —

    A string of up to 4000 characters that describes the parameter.

  • :constraint_description (String) —

    A string that explains the constraint when the constraint is violated. For example, without a constraint description, a parameter that has an allowed pattern of [A-Za-z0-9]+ displays the following error message when the user specifies an invalid value:

    Malformed input-Parameter MyParameter must match pattern [A-Za-z0-9]+

    By adding a constraint description, such as must only contain upper- and lowercase letters, and numbers, you can display a customized error message:

    Malformed input-Parameter MyParameter must only contain upper and lower case letters and numbers



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

def parameter(name, options = {})
  param = {}
  options.each do |key, v|
    next if v === nil

    k = key.to_s.camelize.to_sym
    param[k] =
      case k
      when :AllowedPattern
        if v.class == Regexp
          v.source
        end
      when :Default
        @parameters[name] ||= v
      end
    param[k] ||= v
  end
  param[:Type] ||= 'String'
  self[:Parameters][name] = param
end

#resource(name, type, options = {}, &block) ⇒ Object

Creates a CloudFormation resource

Parameters:

  • name (String) —

    The name of the resource (must be alphanumeric)

  • type (String) —

    The type of CloudFormation resource to create.

  • options (Hash) (defaults to: {}) —

    Additional attributes to add to the resource block (such as the UpdatePolicy for an AWS::AutoScaling::AutoScalingGroup)



141
142
143
144
145
146
147
148
149
 
# File 'lib/cfer/core/stack.rb', line 141

def resource(name, type, options = {}, &block)
  Preconditions.check_argument(/[[:alnum:]]+/ =~ name, "Resource name must be alphanumeric")

  clazz = Cfer::Core::Resource.resource_class(type)
  rc = clazz.new(name, type, self, options, &block)

  self[:Resources][name] = rc
  rc.handle
end

#tail!(options = {}, &block) ⇒ Object 



26
27
28
 
# File 'lib/cfer/core/stack.rb', line 26

def tail!(options = {}, &block)
  client.tail self, options, &block
end

#to_cfn ⇒ String

Renders the stack into a CloudFormation template.

Returns:

  • (String) —

    The final template



162
163
164
165
166
167
168
 
# File 'lib/cfer/core/stack.rb', line 162

def to_cfn
  if @options[:pretty_print]
    JSON.pretty_generate(to_h)
  else
    to_h.to_json
  end
end