cloudformation-tool 1.3.1 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6667d6553e4525f298bb9b2fd517a7045d50f8ed88273fe7bf43ca1e5b588ed
-  data.tar.gz: f8b8ebc3884b92222e8fe67e60f6fdea325cc60b0130eecb36b45edb83e7f209
+  metadata.gz: 5d47ec3cc3379ca6dfb0cc2f85ffade8b42e0422d4b761cf15da9ee1c97ca960
+  data.tar.gz: 4853ad5baa7f8b2322cf745f62e68603d098b53a1744562db5ec92ecd3200001
 SHA512:
-  metadata.gz: 1db7a23fd37bb5ac7f5ab7437b5a62b8fe3d57e0c26a9ac48389641f08042c683f6ecf8eea482a88e08bf68e9ed7fc1c51415db6da54feb1f434a6ab41fb0d42
-  data.tar.gz: ade2265d6bf3652212ecf11125028239494e4ce0318345a88366a2f53440e7b3efde861eb0cfdb946e262438931a5968d3a0e6354376fb17c6aded89a590dfc8
+  metadata.gz: e37177758d4c82350f8af6e842ecfbfc1e336230a50a11e946c87a325f8a27ec8cfe6b07a3b7ee7d8ba3c1682bb74a235c3cfceb7627394d27f173a1598ba368
+  data.tar.gz: af3e5b0a4dac828b3b846c0b5242b2661aec5d221b4fde8b3612756b9048009404ab1f2d64bd45c5fc7339c4b126eef0bfc07ecefa0afea834a171a6b62275e2

data/README.md

@@ -103,27 +103,30 @@ multiple sub-templates, this is an error that would cause the tool to abort.
 
 ### Loading user data files
 
-When specifying a user-data block for a `LaunchConfiguration` resource or an `Instance`
-resource, the user-data can be loaded from an external YAML file (only YAML formatted user-data
-is currently supported, sorry) by specifying the `UserData` element as a map with the single
-field `File` that is set with the relative path to the user-data file. The user-data file is
-expected to be a cloud-init configuration file with the default extension `.init`.
-
-Alternatively, the field `FileTemplate` can be used under `UserData` to load an external cloud-init configuration file that includes variable place holders for the
-(CloudFormation intrinsic function Sub)[http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-sub.html]. The `FileTemplate` mode supports all
-the features described above as well as it performs the parsing detailed below, except
-compression and S3 offloading - as doing so prevents CloudFormation from performing the
-substitution operation. As a result, if the resulting cloud-init file is larger than 16KB
-you should expect that the template will fail to create the server.
+When specifying a user-data block for a `LaunchConfiguration` resource, `Instance`
+resource, or a `LaunchTemplate` resource, the user-data can be loaded from an external
+YAML file (only YAML formatted user-data is currently supported, sorry) by specifying the
+`UserData` element as a map with the single field `File` that is set with the relative
+path to the user-data file. The user-data file is expected to be a cloud-init configuration
+file with the default extension `.init` (but there really aren't any filename requirements).
+
+Alternatively, the field `FileTemplate` can be used under `UserData` to load an external
+cloud-init configuration file that includes variable place holders for the
+(CloudFormation intrinsic function Sub)[http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-sub.html].
+The `FileTemplate` mode supports all the features described above as well as it performs
+the parsing detailed below, except compression and S3 offloading - as doing so prevents
+CloudFormation from performing the substitution operation. As a result, if the resulting
+cloud-init file is larger than 16KB you should expect that the template will fail to create
+the stack.
 
 #### User data file parsing
 
 The reference file will be loaded and parsed as a ("Cloud Config data" file)[http://cloudinit.readthedocs.io/en/latest/topics/format.html#cloud-config-data]
-with the special `write_files` and `write_directories` enhancement (see below). The result is then checked that it
-does not exceed the user-data size limitation. If the file is bigger than can fit in the AWS
-user-data block, it will first be compressed using gzip and if it is still too large, it will
-be uploaded to S3 and the user-data block will be set with a cloud-init download reference to
-the S3 object.
+with the special `write_files` and `write_directories` enhancement (see below). 
+The result is then checked that it does not exceed the user-data size limitation.
+If the file is bigger than can fit in the AWS user-data block, it will first be compressed
+using gzip and if it is still too large, it will be uploaded to S3 and the user-data block
+will be set with a cloud-init download reference to the S3 object.
 
 ##### Enhanced `write_files`
 
@@ -344,7 +347,12 @@ The following commands are supported:
  - `status` - Check if the names stack exists or not
  - `delete` - Delete the specified stack. After issuing the delete command, the tool will
    immediately start `monitor` mode until the operation has completed. 
- - `servers` - List EC2 instances created and managed by this stack.
+ - `servers` - List EC2 instances created and managed by this stack, per autoscaling group, including servers in nested stacks.
+ - `groups` - list autoscaling groups managed by the stack, including groups in nested stacks.
+ - `recycle` - recycle servers in an autoscaling group in a stack by scaling the group up and down.
+ - `scale` - set the scale of an autoscaling group managed by a stack to a specific desired value.
+ - `invalidate` - send an invalidation request to a CloudFront distribution managed by a stack.
+ - `output` - retrieve output values from a stack.
 
 Please see the specific help for each command by running `cftool <command> --help` for
 more details and specific options.
@@ -356,3 +364,100 @@ The AWS region to be used can be select by specifying top level option (i.e. bef
 ### Credentials Selection
 
 The tool will use the standard AWS credentials selection process, except when you want to use AWS CLI configured credential profiles, you may select to use a profile other than "default" by specifying the top level option (i.e. before the command name) `-p <profile>`, by providing the standard environment variable `AWS_DEFAULT_PROFILE` or by having a file called `.awsprofile` - whose content is the name of a valid AWS REGION - in a parent directory (at any level up to the root directory).
+
+## Library API
+
+The cloudformatin tool can also be consumed as a library by other applications - for example an application that needs to perform high-level business-logic oriented
+operations for a specific application deployed in a stack, using the cloudformation tool abstraction of CloudFormation templates and stacks.
+
+### Usage as a library
+
+To use the cloudformatin tool as a library, require `cloud_formation_tool`.
+
+### CloudFormation templates
+
+The cloudformation pre-compiler can be used to manipulate pre-compiled templates.
+
+To access the pre-compiler, initialize a `CloudFormationTool::CloudFormation` with the path to the local template resource (either a file or a directory that can be
+parsed by the pre-compiler).
+
+The initial template resource will be loaded but will not be fully parsed - and included elements will not be read - until the `compile` method is called.
+
+The following method calls are available on the `CloudFormation` instance:
+
+#### `compile(parameters = nil)`
+
+Pre-compiles the template, with the provided parameter `Hash`, if provided. Returns a `Hash` repsenting the compiled template.
+
+#### `to_yaml`
+
+Pre-compiles the template and returns a YAML rendering of the CloudFormation template, suitable for deploying to AWS CloudFormation.
+
+#### `each`
+
+Yields a tuple for each defined template parameter, that includes the parameter's name and its default value (if set, `nil` otherwise).
+
+### CloudFormation stacks
+
+The cloudformation tool's abstraction of a CloudFormation stack can be used to manipulate stack resouces, such as autoscaling groups or instances in a stack context.
+
+To access the stack API, initialize a `CloudFormationTool::CloudFormation::Stack` with the name of the stack. You can then access the following methods:
+
+#### `exist?`
+
+Check if a stack exists.
+
+#### `create(template, params = {})`
+
+Create or update a stack by deploying the specified template. The template can be any local file or directory resource that can be parsed by the cloudformation pre-compiler.
+
+#### `delete`
+
+Deletes the stack
+
+#### `stack_id`
+
+Return the AWS CloudFormation stack identifier for the stack, which is the ARN of the stack.
+
+#### `output`
+
+Returns the output values of the stack
+
+#### `resources`
+
+Return a list of resources in the stack and all of its nested stacks
+
+#### `asgroups`
+
+Return a list of autoscaling groups in the stack and all of its nested stacks. The returned values are AWS SDK CloudFormation resources, extended with a set of methods
+to help manage autoscaling groups:
+
+##### `group`
+
+Returns the AWS SDK `Aws::AutoScaling::AutoScalingGroup` object for the autoscaling group.
+
+#### `cdns`
+
+Return a list of CloudFront CDN distributions in the stack and all of its nested stacks. The returnd values are AWS SDK CloudFormation resources, extended with a set of
+methods to help manage CloudFront distributions:
+
+##### `distribution`
+
+Returns the AWS SDK `Aws::CloudFront::Types::Distribution` object for the CloudFront distribution.
+
+##### `domain_names`
+
+Returns the comma delimited list of the distribution aliases domain names
+
+##### `invalidate(path)`
+
+Creates a new invalidation in the CloudFront distribution with the specified path expression
+
+#### `each`
+
+Yields CloudFormation stack events, in the order they were created. Subsequent calls to `each` will not repeat events previously yielded and will only yield additional
+events created since the last call to `each`.
+
+#### `see_event`
+
+Mark all events since the last call to `each` (or from stack creation, if `each` was not previously called) as "seen" so they will not be yielded in future calls to `each`.

data/lib/cloud_formation_tool/cli/compile.rb

@@ -4,11 +4,16 @@ module CloudFormationTool
     class Compile < Clamp::Command
       include ParamSupport
       
+      option "--user-data-size", "SIZE", "Maximum size of VM user data", default: $MAX_USER_DATA_SIZE do |s|
+        Integer(s)
+      end
+      
       parameter 'FILE', 'Template main file'
       
       add_param_options
       
       def execute
+      	$MAX_USER_DATA_SIZE = user_data_size
         if file.end_with? '.init'
           puts CloudInit.new(file).encode(false) # make sure cloud-init files obey AWS user-data restrictions, but are also printable
         else

data/lib/cloud_formation_tool/cli/main.rb

@@ -1,6 +1,7 @@
 require 'clamp'
 require 'io/console'
 
+$MAX_USER_DATA_SIZE = 16384
 
 module CloudFormationTool
   module CLI

data/lib/cloud_formation_tool/cloud_formation.rb

@@ -23,7 +23,7 @@ module CloudFormationTool
       begin
         text = File.read(@path)
         # remove comments because white space seen between comments can seriously psych Psych
-        text.gsub!(/^#.*\n/s,'')
+        text.gsub!(/^#.*\n/,'')
         text = fixShorthand(text)
         @data = YAML.load(text).to_h
       rescue Psych::SyntaxError => e
@@ -167,7 +167,7 @@ module CloudFormationTool
         restype = data['Type'] if restype.nil? and data.key?('Type')
         data.inject({}) do |dict, (key, val)|
           dict[key] = case restype
-            when 'AWS::AutoScaling::LaunchConfiguration'
+            when 'AWS::AutoScaling::LaunchConfiguration', 'AWS::EC2::LaunchTemplate'
               if (key == "UserData") and (val["File"]) 
                 # Support LaunchConfiguration UserData from file
                 CloudInit.new("#{@basedir}/#{val["File"]}").to_base64

data/lib/cloud_formation_tool/cloud_formation/stack.rb

@@ -96,7 +96,14 @@ module CloudFormationTool
       def resources
         begin
           awscf.list_stack_resources(stack_name: @name).each do |resp|
-            resp.stack_resource_summaries.each { |res| yield res }
+            resp.stack_resource_summaries.each do |res|
+              yield res
+              if res.resource_type == 'AWS::CloudFormation::Stack'
+                Stack.new(res.physical_resource_id).resources do |nested_res|
+                  yield nested_res
+                end
+              end
+            end
           end
         rescue Aws::CloudFormation::Errors::ValidationError => e
           raise CloudFormationTool::Errors::AppError, "Failed to get resources: #{e.message}"

data/lib/cloud_formation_tool/cloud_init.rb

@@ -45,11 +45,11 @@ module CloudFormationTool
     def encode(allow_gzip = true)
       yamlout = compile
       usegzip = false
-      if allow_gzip and yamlout.size > 16384 # max AWS EC2 user data size - try compressing it
+      if allow_gzip and yamlout.size > $MAX_USER_DATA_SIZE # max AWS EC2 user data size - try compressing it
         yamlout = Zlib::Deflate.new(nil, 31).deflate(yamlout, Zlib::FINISH) # 31 is the magic word to have deflate create a gzip compatible header
         usegzip = true
       end
-      if yamlout.size > 16384 # still to big, we should upload to S3 and create an include file
+      if yamlout.size > $MAX_USER_DATA_SIZE # still to big, we should upload to S3 and create an include file
         url = upload  make_filename('init'),
                       yamlout, mime_type: 'text/cloud-config', gzip: usegzip
         log "Wrote cloud config to #{url}"

data/lib/cloud_formation_tool/version.rb

@@ -1,3 +1,3 @@
 module CloudFormationTool
-  VERSION = '1.3.1'
+  VERSION = '1.4.1'
 end

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: cloudformation-tool
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.4.1
 platform: ruby
 authors:
 - Oded Arbel
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-03 00:00:00.000000000 Z
+date: 2021-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '12'
+        version: 12.3.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '12'
+        version: 12.3.3
 - !ruby/object:Gem::Dependency
   name: clamp
   requirement: !ruby/object:Gem::Requirement
@@ -193,7 +193,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.2
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: A pre-compiler tool for CloudFormation YAML templates