cloudformation-ruby-dsl 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4d86a3e1c9ae992f10540eb8bc343c788a111089
-  data.tar.gz: 388ea8ad0dd651ff9889e3dbe068ecec4ae4a4a4
+  metadata.gz: ddd63bd7d011689a102e8a40eaa4104cc4c41014
+  data.tar.gz: c6f98b6601e0e24022b99d6b5e94682b5f2fd943
 SHA512:
-  metadata.gz: b8f8a87b3e8af88daaf3752f95047c6e1aa124ba49c994c7d918b185960c323cdaf796d950b0ac50c5eff43774cfba4818cd2697f0a0ca0f28492ac6c157c818
-  data.tar.gz: 42ad392c8638195e397e6ea59529aac1cec3bc97fdcfd4d14eb22d232a787921e831f3eb9647841c6a8fbcef4954d8bec15cb3f6ebf8cc74b66eccadbfb88f15
+  metadata.gz: 42c017c5ed7f1ed8633b157adf374a20a84c67e2419e6bf2118700d9cfbf26510b80718163257882f1baae537e75943ab6857131e848915b7fe1b9b52b4eb760
+  data.tar.gz: 0f7af272130c77afc3188de7c0b245570ffd3df02861c9febb6909ba83abf843d804c6ba3b416e55f2ebb1bb5b0a56115b86124c5a6a7c423ce2dad335d6b63d

data/README.md

@@ -38,10 +38,19 @@ You may need to preface this with `bundle exec` if you installed via Bundler.
 
 Make the resulting file executable (`chmod +x [NEW_NAME.rb]`). It can respond to the following subcommands (which are listed if you run without parameters):
 - `expand`: output the JSON template to the command line (takes optional `--nopretty` to minimize the output)
-- `diff`: compare an existing stack with your template
+- `diff`: compare an existing stack with your template. Produces following exit codes:
+```
+    0 - no differences, nothing to update
+    1 - stack does not exist, template Validation error
+    2 - there are differences between an existing stack and your template
+```
 - `validate`: run validation against the stack definition
 - `create`: create a new stack from the output
-- `update`: update an existing stack from the output
+- `update`: update an existing stack from the output. Produces following exit codes:
+```
+    0 - update finished successfully
+    1 - no updates to perform, stack doesn't exist, unable to update immutable parameter or tag, AWS ServiceError exception
+```
 - `cancel-update`: cancel updating a stack
 - `delete`: delete a stack (with prompt)
 - `describe`: get output of an existing stack and output it (takes optional `--nopretty` to minimize output)
@@ -89,7 +98,7 @@ Reference a CloudFormation pseudo parameter.
 ### Utility Functions
 
 Additional capabilities for file inclusion, etc.
-- `tag(tag)`: add tags to the stack, which are inherited by all resources in that stack; can only be used at launch
+- `tag(tag_name, tag_options_hash)`: add tags to the stack, which are inherited by all resources in that stack. `tag_options_hash` includes `:Value=>value` and `:Immutable=>true` properties. `tag(tag_value_hash)` is deprecated and will be removed in a future version.
 - `file(name)`: return the named file as a string, for further use
 - `load_from_file(filename)`: load the named file by a given type; currently handles YAML, JSON, and Ruby
 - `interpolate(string)`: embed CFN references into a string (`{{ref('Service')}}`) for later interpretation by the CFN engine

data/examples/cloudformation-ruby-script.rb

@@ -111,17 +111,29 @@ template do
 
 
   # The tag type is a DSL extension; it is not a property of actual CloudFormation templates.
-  #   These tags are excised from the template and used to generate a series of --tag arguments which are passed to CloudFormation when a stack is created.
+  #   These tags are excised from the template and used to generate a series of --tag arguments
+  #   which are passed to CloudFormation when a stack is created.
   #   They do not ultimately appear in the expanded CloudFormation template.
-  #   The diff subcommand will compare tags with the running stack and identify any changes, but a stack update will do the diff and throw an error on any
-  #   changes. The tags are propagated to all resources created by the stack, including the stack itself.
+  #   The diff subcommand will compare tags with the running stack and identify any changes, 
+  #   but a stack update will do the diff and throw an error on any immutable tags update attempt.
+  #   The tags are propagated to all resources created by the stack, including the stack itself.
+  #   If a resource has its own tag with the same name as CF's it's not overwritten.
   #
   # Amazon has set the following restrictions on CloudFormation tags:
   #   => limit 10
-  #   => immutable (you may not update a stack with new tags or different values for existing tags -- they will be rejected)
-  #
-  tag :MyTag => 'MyValue'
-  tag :MyOtherTag => 'My Value With Spaces'
+  # CloudFormation tags declaration examples:
+
+  tag 'My:New:Tag',
+      :Value => 'ImmutableTagValue',
+      :Immutable => true
+
+  tag :MyOtherTag,
+      :Value => 'My Value With Spaces'
+
+  tag(:"tag:name", :Value => 'tag_value', :Immutable => true)
+
+  # Following format is deprecated and not advised. Please declare CloudFormation tags as described above.
+  tag :TagName => 'tag_value'    # It's immutable.
 
   resource 'SecurityGroup', :Type => 'AWS::EC2::SecurityGroup', :Properties => {
       :GroupDescription => 'Lets any vpc traffic in.',

data/lib/cloudformation-ruby-dsl/cfntemplate.rb

@@ -36,6 +36,7 @@ class AwsCfn
 
   def initialize(args)
     Aws.config[:region] = args[:region] if args.key?(:region)
+    Aws.config[:credentials] = Aws::SharedCredentials.new(profile_name: args[:aws_profile]) unless args[:aws_profile].nil?
   end
 
   def cfn_client
@@ -72,6 +73,7 @@ def parse_args
   stack_name = nil
   parameters = {}
   region     = default_region
+  profile    = nil
   nopretty   = false
   ARGV.slice_before(/^--/).each do |name, value|
     case name
@@ -81,11 +83,13 @@ def parse_args
       parameters = Hash[value.split(/;/).map { |pair| pair.split(/=/, 2) }]  #/# fix for syntax highlighting
     when '--region'
       region = value
+    when '--profile'
+      profile = value
     when '--nopretty'
       nopretty = true
     end
   end
-  [stack_name, parameters, region, nopretty]
+  [stack_name, parameters, region, profile, nopretty]
 end
 
 def validate_action(action)
@@ -132,7 +136,7 @@ def validate_action(action)
 end
 
 def cfn(template)
-  aws_cfn = AwsCfn.new({:region => template.aws_region})
+  aws_cfn = AwsCfn.new({:region => template.aws_region, :aws_profile => template.aws_profile})
   cfn_client = aws_cfn.cfn_client
 
   action = validate_action( ARGV[0] )
@@ -145,6 +149,12 @@ def cfn(template)
   # Remove them from the template as well, so that the template is valid.
   cfn_tags = template.excise_tags!
 
+  # Find tags where extension attribute `:Immutable` is true then remove it from the
+  # tag's properties hash since it can't be passed to CloudFormation.
+  immutable_tags = template.get_tag_attribute(cfn_tags, :Immutable)
+
+  cfn_tags.each {|k, v| cfn_tags[k] = v[:Value].to_s}
+
   if action == 'diff' or (action == 'expand' and not template.nopretty)
     template_string = JSON.pretty_generate(template)
   else
@@ -152,7 +162,7 @@ def cfn(template)
   end
 
   # Derive stack name from ARGV
-  _, options = extract_options(ARGV[1..-1], %w(--nopretty), %w(--stack-name --region --parameters --tag))
+  _, options = extract_options(ARGV[1..-1], %w(--nopretty), %w(--profile --stack-name --region --parameters --tag))
   # If the first argument is not an option and stack_name is undefined, assume it's the stack name
   # The second argument, if present, is the resource name used by the describe-resource command
   if template.stack_name.nil?
@@ -177,7 +187,10 @@ def cfn(template)
     # example: <template.rb> diff my-stack-name --parameters "Env=prod" --region eu-west-1
     # Diff the current template for an existing stack with the expansion of this template.
 
-    # We default to "output nothing if no differences are found" to make it easy to use the output of the diff call from within other scripts
+    # `diff` operation exit codes are:
+      # 0 - no differences are found. Outputs nothing to make it easy to use the output of the diff call from within other scripts.
+      # 1 - produced by any ValidationError exception (e.g. "Stack with id does not exist")
+      # 2 - there are changes to update (tags, params, template)
     # If you want output of the entire file, simply use this option with a large number, i.e., -U 10000
     # In fact, this is what Diffy does by default; we just don't want that, and we can't support passing arbitrary options to diff
     # because Diffy's "context" configuration is mutually exclusive with the configuration to pass arbitrary options to diff
@@ -246,7 +259,11 @@ def cfn(template)
       puts
     end
 
-    exit(true)
+    if tags_diff.empty? && params_diff.empty? && template_diff.empty?
+      exit(true)
+    else
+      exit(2)
+    end
 
   when 'validate'
     begin
@@ -400,32 +417,58 @@ def cfn(template)
       old_stack = old_stack[0]
     end
 
-    # If updating a stack and some parameters are marked as immutable, fail if the new parameters don't match the old ones.
+    # If updating a stack and some parameters or tags are marked as immutable, set the variable to true.
+    immutables_exist = nil 
+
     if not immutable_parameters.empty?
       old_parameters = Hash[old_stack.parameters.map { |p| [p.parameter_key, p.parameter_value]}]
       new_parameters = template.parameters
-
       immutable_parameters.sort.each do |param|
-        if old_parameters[param].to_s != new_parameters[param].to_s
+        if old_parameters[param].to_s != new_parameters[param].to_s && old_parameters.key?(param)
           $stderr.puts "Error: unable to update immutable parameter " +
                            "'#{param}=#{old_parameters[param]}' to '#{param}=#{new_parameters[param]}'."
-          exit(false)
+          immutables_exist = true
         end
       end
     end
 
-    # Tags are immutable in CloudFormation.  Validate against the existing stack to ensure tags haven't changed.
-    # Compare the sorted arrays for an exact match
-    old_cfn_tags = old_stack.tags.map { |p| [p.key.to_sym, p.value]}.sort
-    cfn_tags_ary = cfn_tags.to_a.sort
-    if cfn_tags_ary != old_cfn_tags
-      $stderr.puts "CloudFormation stack tags do not match and cannot be updated. You must either use the same tags or create a new stack." +
-                      "\n" + (old_cfn_tags - cfn_tags_ary).map {|tag| "< #{tag}" }.join("\n") +
-                      "\n" + "---" +
-                      "\n" + (cfn_tags_ary - old_cfn_tags).map {|tag| "> #{tag}"}.join("\n")
+    if not immutable_tags.empty?
+      old_cfn_tags = Hash[old_stack.tags.map { |t| [t.key, t.value]}]
+      cfn_tags_ary = Hash[cfn_tags.map { |k,v| [k, v]}]
+      immutable_tags.sort.each do |tag|
+        if old_cfn_tags[tag].to_s != cfn_tags_ary[tag].to_s && old_cfn_tags.key?(tag)
+          $stderr.puts "Error: unable to update immutable tag " +
+                           "'#{tag}=#{old_cfn_tags[tag]}' to '#{tag}=#{cfn_tags_ary[tag]}'."
+          immutables_exist = true
+        end
+      end
+    end
+
+    # Fail if some parameters or tags were marked as immutable.
+    if immutables_exist
       exit(false)
     end
 
+    # Compare the sorted arrays of parameters for an exact match and print difference.
+    old_parameters = old_stack.parameters.map { |p| [p.parameter_key, p.parameter_value]}.sort
+    new_parameters = template.parameters.sort
+    if new_parameters != old_parameters
+      puts "\nCloudFormation stack parameters that do not match and will be updated:" +
+               "\n" + (old_parameters - new_parameters).map {|param| "< #{param}" }.join("\n") +
+               "\n" + "---" +
+               "\n" + (new_parameters - old_parameters).map {|param| "> #{param}"}.join("\n")
+    end
+
+    # Compare the sorted arrays of tags for an exact match and print difference.
+    old_cfn_tags = old_stack.tags.map { |t| [t.key, t.value]}.sort
+    cfn_tags_ary = cfn_tags.map { |k,v| [k, v]}.sort
+    if cfn_tags_ary != old_cfn_tags
+      puts "\nCloudFormation stack tags that do not match and will be updated:" +
+               "\n" + (old_cfn_tags - cfn_tags_ary).map {|tag| "< #{tag}" }.join("\n") +
+               "\n" + "---" +
+               "\n" + (cfn_tags_ary - old_cfn_tags).map {|tag| "> #{tag}"}.join("\n")
+    end
+
     # update the stack
     begin
 
@@ -434,6 +477,7 @@ def cfn(template)
           stack_name: stack_name,
           template_body: template_string,
           parameters: template.parameters.map { |k,v| {parameter_key: k, parameter_value: v}}.to_a,
+          tags: cfn_tags.map { |k,v| {"key" => k.to_s, "value" => v.to_s} }.to_a,
           capabilities: ["CAPABILITY_IAM"],
       }
 
@@ -460,7 +504,7 @@ end
 # Example:
 #
 # desired, unknown = extract_options("arg1 --option withvalue --optionwithoutvalue", %w(--option), %w())
-# 
+#
 # puts desired => Array{"arg1", "--option", "withvalue"}
 # puts unknown => Array{}
 #
@@ -515,6 +559,6 @@ end
 
 # Main entry point
 def template(&block)
-  stack_name, parameters, aws_region, nopretty = parse_args
-  raw_template(parameters, stack_name, aws_region, nopretty, &block)
+  stack_name, parameters, aws_region, aws_profile, nopretty = parse_args
+  raw_template(parameters, stack_name, aws_region, aws_profile, nopretty, &block)
 end

data/lib/cloudformation-ruby-dsl/dsl.rb

@@ -44,8 +44,8 @@ end
 ############################# CloudFormation DSL
 
 # Main entry point
-def raw_template(parameters = {}, stack_name = nil, aws_region = default_region, nopretty = false, &block)
-  TemplateDSL.new(parameters, stack_name, aws_region, nopretty, &block)
+def raw_template(parameters = {}, stack_name = nil, aws_region = default_region, aws_profile = nil, nopretty = false, &block)
+  TemplateDSL.new(parameters, stack_name, aws_region, aws_profile, nopretty, &block)
 end
 
 def default_region
@@ -54,12 +54,13 @@ end
 
 # Core interpreter for the DSL
 class TemplateDSL < JsonObjectDSL
-  attr_reader :parameters, :aws_region, :nopretty, :stack_name
+  attr_reader :parameters, :aws_region, :nopretty, :stack_name, :aws_profile
 
-  def initialize(parameters = {}, stack_name = nil, aws_region = default_region, nopretty = false)
+  def initialize(parameters = {}, stack_name = nil, aws_region = default_region, aws_profile = nil, nopretty = false)
     @parameters = parameters
     @stack_name = stack_name
     @aws_region = aws_region
+    @aws_profile = aws_profile
     @nopretty = nopretty
     super()
   end
@@ -110,15 +111,36 @@ class TemplateDSL < JsonObjectDSL
     contents
   end
 
+  # Find tags where the specified attribute is true then remove this attribute.
+  def get_tag_attribute(tags, attribute)
+    marked_tags = []
+    tags.each do |tag, options|
+      if options.delete(attribute.to_sym) or options.delete(attribute.to_s)
+        marked_tags << tag
+      end
+    end
+    marked_tags
+  end
+
   def excise_tags!
     tags = @dict.fetch(:Tags, {})
     @dict.delete(:Tags)
     tags
   end
 
-  def tag(tag)
-    tag.each do | name, value |
-      default(:Tags, {})[name] = value
+  def tag(tag, *args)
+    if (tag.is_a?(String) || tag.is_a?(Symbol)) && !args.empty?
+      default(:Tags, {})[tag.to_s] = args[0]
+    # For backward-compatibility, transform `tag_name=>value` format to `tag_name, :Value=>value, :Immutable=>true`
+    # Tags declared this way remain immutable and won't be updated.
+    elsif tag.is_a?(Hash) && tag.size == 1 && args.empty?
+      $stderr.puts "WARNING: #{tag} tag declaration format is deprecated and will be removed in a future version. Please use resource-like style instead."
+      tag.each do |name, value|
+        default(:Tags, {})[name.to_s] = {:Value => value, :Immutable => true}
+      end
+    else
+      $stderr.puts "Error: #{tag} tag validation error. Please verify tag's declaration format."
+      exit(false)
     end
   end
 

data/lib/cloudformation-ruby-dsl/version.rb

@@ -15,7 +15,7 @@
 module Cfn
   module Ruby
     module Dsl
-      VERSION = "1.1.0"
+      VERSION = "1.2.0"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cloudformation-ruby-dsl
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Shawn Smith
@@ -15,7 +15,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-20 00:00:00.000000000 Z
+date: 2016-03-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: detabulator