stack_master 2.3.0 → 2.14.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b2fd9ecb9882d2a0b00adee84d08975f5ae51b72297a449c5bd5218efbf8a17
-  data.tar.gz: c2eb23ba0ae38e6db17cc296a4a151aaaf7785bbff222d75ec671251ac398f1f
+  metadata.gz: bacf542a4b317cf98eb9e39a70740e393ddea1eb9363e65340975e568d3191e1
+  data.tar.gz: 4582583ac6fa9681edf9f3a8bf4ed478e728b09e0aaebce244234ab50ff0376c
 SHA512:
-  metadata.gz: e5832578334d932b9750b9aa2914c6c0fc9d2b391606c3ab8fc60868b151c5b9fa996d2b89636d14515aff3b9892c8a913c1e0531ac57262a67072931a2a8f1c
-  data.tar.gz: 87dd2728b566b6d775a0b8cb7137acc856f1ee854436e35789578c1c129798594375bc9ad06018be2285605878918cf89d872c3df72fe20a3260380407e32b25
+  metadata.gz: bce540f043c5010594155cfd41fab249b531e80febb96cc46cebce7b957e8de2f7aca20f8b0dc09cf13050338e0455d3438ec36341d49d838002ab9fa8b21905
+  data.tar.gz: 61dae834acf176052b3fe8c2bb53443fc44dc0b68dbf33f7b053365088624b664aa6ba504697e839a18a63c5192a961e80d1736ce7efbdc82351616faf9bb8d7

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Steve Hodgkiss
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -2,7 +2,7 @@
 
 [![License MIT](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://github.com/envato/stack_master/blob/master/LICENSE.md)
 [![Gem Version](https://badge.fury.io/rb/stack_master.svg)](https://badge.fury.io/rb/stack_master)
-[![Build Status](https://travis-ci.org/envato/stack_master.svg?branch=master)](https://travis-ci.org/envato/stack_master)
+[![Build Status](https://github.com/envato/stack_master/workflows/tests/badge.svg?branch=master)](https://github.com/envato/stack_master/actions?query=workflow%3Atests+branch%3Amaster)
 
 StackMaster is a CLI tool to manage [CloudFormation](https://aws.amazon.com/cloudformation/) stacks, with the following features:
 
@@ -53,7 +53,7 @@ Stacks are defined inside a `stack_master.yml` YAML file. When running
 directory, or that the file is passed in with `--config
 /path/to/stack_master.yml`.  Here's an example configuration file:
 
-```
+```yaml
 region_aliases:
   production: us-east-1
   staging: ap-southeast-2
@@ -123,6 +123,7 @@ stack_defaults:
 ```
 
 Additional files can be configured to be uploaded to S3 alongside the templates:
+
 ```yaml
 stacks:
   production:
@@ -131,6 +132,7 @@ stacks:
       files:
         - userdata.sh
 ```
+
 ## Directories
 
 - `templates` - CloudFormation, SparkleFormation or CfnDsl templates.
@@ -141,7 +143,8 @@ stacks:
 ## Templates
 
 StackMaster supports CloudFormation templates in plain JSON or YAML. Any `.yml` or `.yaml` file will be processed as
-YAML, while any `.json` file will be processed as JSON.
+YAML, while any `.json` file will be processed as JSON. Additionally, YAML files can be pre-processed using ERB and
+compile-time parameters.
 
 ### Ruby DSLs
 By default, any template ending with `.rb` will be processed as a [SparkleFormation](https://github.com/sparkleformation/sparkle_formation)
@@ -155,7 +158,8 @@ template_compilers:
 
 ## Parameters
 
-Parameters are loaded from multiple YAML files, merged from the following lookup paths from bottom to top:
+By default, parameters are loaded from multiple YAML files, merged from the
+following lookup paths from bottom to top:
 
 - parameters/[stack_name].yaml
 - parameters/[stack_name].yml
@@ -166,18 +170,43 @@ Parameters are loaded from multiple YAML files, merged from the following lookup
 
 A simple parameter file could look like this:
 
-```
+```yaml
 key_name: myapp-us-east-1
 ```
 
-### Compile Time Parameters
+Alternatively, a `parameter_files` array can be defined to explicitly list
+parameter files that will be loaded. If `parameter_files` are defined, the
+automatic search locations will not be used.
 
-Compile time parameters can be used for [SparkleFormation](http://www.sparkleformation.io) templates. It conforms and
-allows you to use the [Compile Time Parameters](http://www.sparkleformation.io/docs/sparkle_formation/compile-time-parameters.html) feature.
+```yaml
+parameters_dir: parameters # the default
+stacks:
+  us-east-1:
+    my-app:
+      parameter_files:
+        - my-app.yml # parameters/my-app.yml
+```
 
-A simple example looks like this
+Parameters can also be defined inline with stack definitions:
 
+```yaml
+stacks:
+  us-east-1:
+    my-app:
+      parameters:
+        VpcId:
+          stack_output: my-vpc/VpcId
 ```
+
+### Compile Time Parameters
+
+Compile time parameters can be defined in a stack's parameters file, using the key `compile_time_parameters`. Keys in
+parameter files are automatically converted to camel case.
+
+As an example:
+
+```yaml
+# parameters/some_stack.yml
 vpc_cidr: 10.0.0.0/16
 compile_time_parameters:
   subnet_cidrs:
@@ -185,7 +214,37 @@ compile_time_parameters:
     - 10.0.2.0/28
 ```
 
-Keys in parameter files are automatically converted to camel case.
+#### SparkleFormation
+
+Compile time parameters can be used for [SparkleFormation](http://www.sparkleformation.io) templates. It conforms and
+allows you to use the [Compile Time Parameters](http://www.sparkleformation.io/docs/sparkle_formation/compile-time-parameters.html) feature.
+
+#### CloudFormation YAML ERB
+
+Compile time parameters can be used to pre-process YAML CloudFormation templates. An example template:
+
+```yaml
+# templates/some_stack_template.yml.erb
+Parameters:
+  VpcCidr:
+    Type: String
+Resources:
+  Vpc:
+    Type: AWS::EC2::VPC
+    Properties:
+      CidrBlock: !Ref VpcCidr
+  # Given the two subnet_cidrs parameters, this creates two resources:
+  # SubnetPrivate0 with a CidrBlock of 10.0.0.0/28, and
+  # SubnetPrivate1 with a CidrBlock of 10.0.2.0/28
+  <% params["SubnetCidrs"].each_with_index do |cidr, index| %>
+  SubnetPrivate<%= index %>:
+    Type: AWS::EC2::Subnet
+    Properties:
+      VpcId: !Ref Vpc
+      AvailabilityZone: ap-southeast-2
+      CidrBlock: <%= cidr %>
+  <% end %>
+```
 
 ## Parameter Resolvers
 
@@ -286,8 +345,8 @@ db_password:
 An alternative to the secrets store is accessing 1password secrets using the 1password cli (`op`).
 You declare a 1password lookup with the following parameters in your parameters file:
 
-```
-parameters/database.yml
+```yaml
+# parameters/database.yml
 database_password:
   one_password:
     title: production database
@@ -477,7 +536,7 @@ name of the original resolver.
 
 When creating a new resolver, one can automatically create the array resolver by adding a `array_resolver` statement
 in the class definition, with an optional class name if different from the default one.
-```
+```ruby
 module StackMaster
   module ParameterResolvers
     class MyResolver < Resolver
@@ -488,7 +547,7 @@ module StackMaster
 end
 ```
 In that example, using the array resolver would look like:
-```
+```yaml
 my_parameter:
   my_custom_array_resolver:
     - value1
@@ -498,13 +557,13 @@ my_parameter:
 Array parameter values can include nested parameter resolvers.
 
 For example, given the following parameter definition:
-```
+```yaml
 my_parameter:
   - stack_output: my-stack/output # value resolves to 'value1'
   - value2
 ```
 The parameter value will resolve to:
-```
+```yaml
 my_parameter: 'value1,value2'
 ```
 
@@ -520,7 +579,7 @@ ROLE=<%= role %>
 
 And used like this in SparkleFormation templates:
 
-```
+```ruby
 # templates/app.rb
   user_data user_data_file!('app.erb', role: :worker)
 ```
@@ -533,7 +592,7 @@ my_variable=<%= ref!(:foo) %>
 my_other_variable=<%= account_id! %>
 ```
 
-```
+```ruby
 # templates/ecs_task.rb
 container_definitions array!(
   -> {
@@ -565,7 +624,7 @@ project-root
 
 Your env-1/stack_master.yml files can reference common templates by setting:
 
-```
+```yaml
 template_dir: ../../sparkle/templates
 stack_defaults:
   compiler_options:
@@ -625,7 +684,7 @@ stacks:
 
 ## Allowed accounts
 
-The AWS account the command is executing in can be restricted to a specific list of allowed accounts. This is useful in reducing the possibility of applying non-production changes in a production account. Each stack definition can specify the `allowed_accounts` property with an array of AWS account IDs the stack is allowed to work with.
+The AWS account the command is executing in can be restricted to a specific list of allowed accounts. This is useful in reducing the possibility of applying non-production changes in a production account. Each stack definition can specify the `allowed_accounts` property with an array of AWS account IDs or aliases the stack is allowed to work with.
 
 This is an opt-in feature which is enabled by specifying at least one account to allow.
 
@@ -644,7 +703,7 @@ stacks:
       template: myapp_db.rb
       allowed_accounts: # only allow these accounts (overrides the stack defaults)
         - '1234567890'
-        - '9876543210'
+        - my-account-alias
       tags:
         purpose: back-end
     myapp-web:
@@ -659,7 +718,8 @@ stacks:
         purpose: back-end
 ```
 
-In the cases where you want to bypass the account check, there is StackMaster flag `--skip-account-check` that can be used.
+In the cases where you want to bypass the account check, there is the StackMaster flag `--skip-account-check` that can be used.
+
 
 ## Commands
 
@@ -674,15 +734,20 @@ stack_master apply # Create or update all stacks
 stack_master --changed apply # Create or update all stacks that have changed
 stack_master --yes apply [region-or-alias] [stack-name] # Create or update a stack non-interactively (forcing yes)
 stack_master diff [region-or-alias] [stack-name] # Display a stack template and parameter diff
+stack_master drift [region-or-alias] [stack-name] # Detects and displays stack drift using the CloudFormation Drift API
 stack_master delete [region-or-alias] [stack-name] # Delete a stack
 stack_master events [region-or-alias] [stack-name] # Display events for a stack
 stack_master outputs [region-or-alias] [stack-name] # Display outputs for a stack
 stack_master resources [region-or-alias] [stack-name] # Display outputs for a stack
 stack_master status # Displays the status of each stack
 stack_master tidy # Find missing or extra templates or parameter files
+stack_master compile # Print the compiled version of a given stack
+stack_master validate # Validate a template
+stack_master lint # Check the stack definition locally using cfn-lint
+stack_master nag # Check the stack template with cfn_nag
 ```
 
-## Applying updates
+## Applying updates - `stack_master apply`
 
 The apply command does the following:
 
@@ -699,6 +764,18 @@ Demo:
 
 ![Apply Demo](/apply_demo.gif?raw=true)
 
+## Drift Detection - `stack_master drift`
+
+`stack_master drift us-east-1 mystack` uses the CloudFormation APIs to trigger drift detection and display resources
+that have changed outside of the CloudFormation stack. This can happen if a resource has been updated via the console or
+CLI directly rather than via a stack update.
+
+## Diff - `stack_master diff`
+
+`stack_master diff us-east-1 mystack` displays whether the computed parameters or template differ to what was last
+applied in CloudFormation. This can happen if the template or computed parameters have changed in code and the change
+hasn't been applied to this stack.
+
 ## Maintainers
 
 - [Steve Hodgkiss](https://github.com/stevehodgkiss)

data/lib/stack_master/aws_driver/cloud_formation.rb

@@ -28,12 +28,15 @@ module StackMaster
                           :update_stack,
                           :create_stack,
                           :validate_template,
-                          :describe_stacks
+                          :describe_stacks,
+                          :detect_stack_drift,
+                          :describe_stack_drift_detection_status,
+                          :describe_stack_resource_drifts
 
       private
 
       def cf
-        @cf ||= Aws::CloudFormation::Client.new(region: region, retry_limit: 10)
+        @cf ||= Aws::CloudFormation::Client.new({ region: region, retry_limit: 10 })
       end
 
     end

data/lib/stack_master/aws_driver/s3.rb

@@ -17,10 +17,10 @@ module StackMaster
 
         s3 = new_s3_client(region: region)
 
-        current_objects = s3.list_objects(
+        current_objects = s3.list_objects({
           prefix: prefix,
           bucket: bucket
-        ).map(&:contents).flatten.inject({}){|h,obj|
+        }).map(&:contents).flatten.inject({}){|h,obj|
           h.merge(obj.key => obj)
         }
 
@@ -38,12 +38,12 @@ module StackMaster
           s3_uri = "s3://#{bucket}/#{object_key}"
           StackMaster.stdout.print "- #{File.basename(path)} => #{s3_uri} "
 
-          s3.put_object(
+          s3.put_object({
             bucket: bucket,
             key: object_key,
             body: body,
             metadata: { md5: compiled_template_md5 }
-          )
+          })
           StackMaster.stdout.puts "done."
         end
       end
@@ -61,7 +61,7 @@ module StackMaster
       private
 
       def new_s3_client(region: nil)
-        Aws::S3::Client.new(region: region || @region)
+        Aws::S3::Client.new({ region: region || @region })
       end
     end
   end

data/lib/stack_master/change_set.rb

@@ -25,12 +25,12 @@ module StackMaster
     end
 
     def self.delete(id)
-      cf.delete_change_set(change_set_name: id)
+      cf.delete_change_set({ change_set_name: id })
     end
 
     def self.execute(id, stack_name)
-      cf.execute_change_set(change_set_name: id,
-                            stack_name: stack_name)
+      cf.execute_change_set({ change_set_name: id,
+                              stack_name: stack_name })
     end
 
     def self.cf
@@ -75,7 +75,7 @@ io.puts "========================================"
                     end
       message = "#{action_name} #{resource_change.resource_type} #{resource_change.logical_resource_id}"
       color = action_color(action_name)
-      io.puts message.colorize(color)
+      io.puts Rainbow(message).color(color)
       resource_change.details.each do |detail|
         display_resource_change_detail(io, action_name, color, detail)
       end
@@ -92,7 +92,7 @@ io.puts "========================================"
         triggered_by << "(#{detail.evaluation})"
       end
       detail_messages << "Triggered by: #{triggered_by}"
-      io.puts "- #{detail_messages.join('. ')}. ".colorize(color)
+      io.puts Rainbow("- #{detail_messages.join('. ')}. ").color(color)
     end
 
     def action_color(action_name)

data/lib/stack_master/cli.rb

@@ -7,7 +7,7 @@ module StackMaster
 
     def initialize(argv, stdin=STDIN, stdout=STDOUT, stderr=STDERR, kernel=Kernel)
       @argv, @stdin, @stdout, @stderr, @kernel = argv, stdin, stdout, stderr, kernel
-      Commander::Runner.instance_variable_set('@singleton', Commander::Runner.new(argv))
+      Commander::Runner.instance_variable_set('@instance', Commander::Runner.new(argv))
       StackMaster.stdout = @stdout
       StackMaster.stderr = @stderr
       TablePrint::Config.io = StackMaster.stdout
@@ -46,7 +46,7 @@ module StackMaster
         c.option '--on-failure ACTION', String, "Action to take on CREATE_FAILURE. Valid Values: [ DO_NOTHING | ROLLBACK | DELETE ]. Default: ROLLBACK\nNote: You cannot use this option with Serverless Application Model (SAM) templates."
         c.option '--yes-param PARAM_NAME', String, "Auto-approve stack updates when only parameter PARAM_NAME changes"
         c.action do |args, options|
-          options.defaults config: default_config_file
+          options.default config: default_config_file
           execute_stacks_command(StackMaster::Commands::Apply, args, options)
         end
       end
@@ -56,7 +56,7 @@ module StackMaster
         c.summary = 'Displays outputs for a stack'
         c.description = "Displays outputs for a stack"
         c.action do |args, options|
-          options.defaults config: default_config_file
+          options.default config: default_config_file
           execute_stacks_command(StackMaster::Commands::Outputs, args, options)
         end
       end
@@ -67,7 +67,7 @@ module StackMaster
         c.description = 'Initialises the expected directory structure and stack_master.yml file'
         c.option('--overwrite', 'Overwrite existing files')
         c.action do |args, options|
-          options.defaults config: default_config_file
+          options.default config: default_config_file
           unless args.size == 2
             say "Invalid arguments. stack_master init [region] [stack_name]"
           else
@@ -82,7 +82,7 @@ module StackMaster
         c.description = "Shows a diff of the proposed stack's template and parameters"
         c.example 'diff a stack named myapp-vpc in us-east-1', 'stack_master diff us-east-1 myapp-vpc'
         c.action do |args, options|
-          options.defaults config: default_config_file
+          options.default config: default_config_file
           execute_stacks_command(StackMaster::Commands::Diff, args, options)
         end
       end
@@ -96,7 +96,7 @@ module StackMaster
         c.option '--all', 'Show all events'
         c.option '--tail', 'Tail events'
         c.action do |args, options|
-          options.defaults config: default_config_file
+          options.default config: default_config_file
           execute_stacks_command(StackMaster::Commands::Events, args, options)
         end
       end
@@ -106,7 +106,7 @@ module StackMaster
         c.summary = "Shows stack resources"
         c.description = "Shows stack resources"
         c.action do |args, options|
-          options.defaults config: default_config_file
+          options.default config: default_config_file
           execute_stacks_command(StackMaster::Commands::Resources, args, options)
         end
       end
@@ -116,7 +116,7 @@ module StackMaster
         c.summary = 'List stack definitions'
         c.description = 'List stack definitions'
         c.action do |args, options|
-          options.defaults config: default_config_file
+          options.default config: default_config_file
           say "Invalid arguments." if args.size > 0
           config = load_config(options.config)
           StackMaster::Commands::ListStacks.perform(config, nil, options)
@@ -128,8 +128,9 @@ module StackMaster
         c.summary = 'Validate a template'
         c.description = 'Validate a template'
         c.example 'validate a stack named myapp-vpc in us-east-1', 'stack_master validate us-east-1 myapp-vpc'
+        c.option '--[no-]validate-template-parameters', 'Validate template parameters. Default: validate'
         c.action do |args, options|
-          options.defaults config: default_config_file
+          options.default config: default_config_file, validate_template_parameters: true
           execute_stacks_command(StackMaster::Commands::Validate, args, options)
         end
       end
@@ -140,18 +141,29 @@ module StackMaster
         c.description = "Runs cfn-lint on the template which would be sent to AWS on apply"
         c.example 'run cfn-lint on stack myapp-vpc with us-east-1 settings', 'stack_master lint us-east-1 myapp-vpc'
         c.action do |args, options|
-          options.defaults config: default_config_file
+          options.default config: default_config_file
           execute_stacks_command(StackMaster::Commands::Lint, args, options)
         end
       end
 
+      command :nag do |c|
+        c.syntax = 'stack_master nag [region_or_alias] [stack_name]'
+        c.summary = "Check this stack's template with cfn_nag"
+        c.description = "Runs SAST scan cfn_nag on the template"
+        c.example 'run cfn_nag on stack myapp-vpc with us-east-1 settings', 'stack_master nag us-east-1 myapp-vpc'
+        c.action do |args, options|
+          options.default config: default_config_file
+          execute_stacks_command(StackMaster::Commands::Nag, args, options)
+        end
+      end
+
       command :compile do |c|
         c.syntax = 'stack_master compile [region_or_alias] [stack_name]'
         c.summary = "Print the compiled version of a given stack"
         c.description = "Processes the stack and prints out a compiled version - same we'd send to AWS"
         c.example 'print compiled stack myapp-vpc with us-east-1 settings', 'stack_master compile us-east-1 myapp-vpc'
         c.action do |args, options|
-          options.defaults config: default_config_file
+          options.default config: default_config_file
           execute_stacks_command(StackMaster::Commands::Compile, args, options)
         end
       end
@@ -162,7 +174,7 @@ module StackMaster
         c.description = 'Checks the status of all stacks defined in the stack_master.yml file. Warning this operation can be somewhat slow.'
         c.example 'description', 'Check the status of all stack definitions'
         c.action do |args, options|
-          options.defaults config: default_config_file
+          options.default config: default_config_file
           say "Invalid arguments. stack_master status" and return unless args.size == 0
           config = load_config(options.config)
           StackMaster::Commands::Status.perform(config, nil, options)
@@ -175,7 +187,7 @@ module StackMaster
         c.description = 'Cross references stack_master.yml with the template and parameter directories to identify extra or missing files.'
         c.example 'description', 'Check for missing or extra files'
         c.action do |args, options|
-          options.defaults config: default_config_file
+          options.default config: default_config_file
           say "Invalid arguments. stack_master tidy" and return unless args.size == 0
           config = load_config(options.config)
           StackMaster::Commands::Tidy.perform(config, nil, options)
@@ -214,6 +226,18 @@ module StackMaster
         end
       end
 
+      command :drift do |c|
+        c.syntax = 'stack_master drift [region_or_alias] [stack_name]'
+        c.summary = 'Detects and displays stack drift using the CloudFormation Drift API'
+        c.description = 'Detects and displays stack drift'
+        c.option '--timeout SECONDS', Integer, "The number of seconds to wait for drift detection to complete"
+        c.example 'view stack drift for a stack named myapp-vpc in us-east-1', 'stack_master drift us-east-1 myapp-vpc'
+        c.action do |args, options|
+          options.default config: default_config_file, timeout: 120
+          execute_stacks_command(StackMaster::Commands::Drift, args, options)
+        end
+      end
+
       run!
     end
 
@@ -241,6 +265,7 @@ module StackMaster
         stack_definitions = config.filter(region, stack_name)
         if stack_definitions.empty?
           StackMaster.stdout.puts "Could not find stack definition #{stack_name} in region #{region}"
+          show_other_region_candidates(config, stack_name)
           success = false
         end
         stack_definitions = stack_definitions.select do |stack_definition|
@@ -257,18 +282,27 @@ module StackMaster
       @kernel.exit false unless success
     end
 
+    def show_other_region_candidates(config, stack_name)
+      candidates = config.filter(region="", stack_name=stack_name)
+      return if candidates.empty?
+
+      StackMaster.stdout.puts "Stack name #{stack_name} exists in regions: #{candidates.map(&:region).join(', ')}"
+    end
+
     def execute_if_allowed_account(allowed_accounts, &block)
       raise ArgumentError, "Block required to execute this method" unless block_given?
       if running_in_allowed_account?(allowed_accounts)
         block.call
       else
-        StackMaster.stdout.puts "Account '#{identity.account}' is not an allowed account. Allowed accounts are #{allowed_accounts}."
+        account_text = "'#{identity.account}'"
+        account_text << " (#{identity.account_aliases.join(', ')})" if identity.account_aliases.any?
+        StackMaster.stdout.puts "Account #{account_text} is not an allowed account. Allowed accounts are #{allowed_accounts}."
         false
       end
     end
 
     def running_in_allowed_account?(allowed_accounts)
-      StackMaster.skip_account_check? || identity.running_in_allowed_account?(allowed_accounts)
+      StackMaster.skip_account_check? || identity.running_in_account?(allowed_accounts)
     end
 
     def identity

data/lib/stack_master/cloudformation_interpolating_eruby.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'erubis'
+
+module StackMaster
+  #  This class is a modified version of `Erubis::Eruby`. It allows using
+  # `<%= %>` ERB expressions to interpolate values into a source string. We use
+  # this capability to enrich user data scripts with data and parameters pulled
+  # from the AWS CloudFormation service. The evaluation produces an array of
+  # objects ready for use in a CloudFormation `Fn::Join` intrinsic function.
+  class CloudFormationInterpolatingEruby < Erubis::Eruby
+    include Erubis::ArrayEnhancer
+
+    # Load a template from a file at the specified path and evaluate it.
+    def self.evaluate_file(source_path, context = Erubis::Context.new)
+      template_contents = File.read(source_path)
+      eruby = new(template_contents)
+      eruby.filename = source_path
+      eruby.evaluate(context)
+    end
+
+    # @return [Array] The result of evaluating the source: an array of strings
+    #         from the source intermindled with Hash objects from the ERB
+    #         expressions. To be included in a CloudFormation template, this
+    #         value needs to be used in a CloudFormation `Fn::Join` intrinsic
+    #         function.
+    # @see Erubis::Eruby#evaluate
+    # @example
+    #   CloudFormationInterpolatingEruby.new("my_variable=<%= { 'Ref' => 'Param1' } %>;").evaluate
+    #     #=> ['my_variable=', { 'Ref' => 'Param1' }, ';']
+    def evaluate(_context = Erubis::Context.new)
+      format_lines_for_cloudformation(super)
+    end
+
+    # @see Erubis::Eruby#add_expr
+    def add_expr(src, code, indicator)
+      if indicator == '='
+        src << " #{@bufvar} << (" << code << ');'
+      else
+        super
+      end
+    end
+
+    private
+
+    # Split up long strings containing multiple lines. One string per line in the
+    # CloudFormation array makes the compiled template and diffs more readable.
+    def format_lines_for_cloudformation(source)
+      source.flat_map do |lines|
+        lines = lines.to_s if lines.is_a?(Symbol)
+        next(lines) unless lines.is_a?(String)
+
+        lines.scan(/[^\n]*\n?/).reject { |x| x == '' }
+      end
+    end
+  end
+end

data/lib/stack_master/cloudformation_template_eruby.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'erubis'
+require 'json'
+
+module StackMaster
+  # This class is a modified version of `Erubis::Eruby`. It provides extra
+  # helper methods to ease the dynamic creation of CloudFormation templates
+  # with ERB. These helper methods are available within `<%= %>` expressions.
+  class CloudFormationTemplateEruby < Erubis::Eruby
+    # Adds the contents of an EC2 userdata script to the CloudFormation
+    # template. Allows using the ERB `<%= %>` expressions within the user data
+    # script to interpolate CloudFormation values.
+    def user_data_file(filepath)
+      JSON.pretty_generate({ 'Fn::Base64' => { 'Fn::Join' => ['', user_data_file_as_lines(filepath)] } })
+    end
+
+    # Evaluate the ERB template at the specified filepath and return the result
+    # as an array of lines. Allows using ERB `<%= %>` expressions to interpolate
+    # CloudFormation objects into the result.
+    def user_data_file_as_lines(filepath)
+      StackMaster::CloudFormationInterpolatingEruby.evaluate_file(filepath, self)
+    end
+
+    # Add the contents of another file into the CloudFormation template as a
+    # string. ERB `<%= %>` expressions within the referenced file are not
+    # evaluated.
+    def include_file(filepath)
+      JSON.pretty_generate(File.read(filepath))
+    end
+  end
+end