cfhighlander 0.2.1.alpha.43 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0076c7a6d8d8d5dcfe21a9c57601f659014cc64dadfc78c890b78ac98aaee7e
-  data.tar.gz: d9688f728ef4edd875f8603b8733c153a95270a1650b0555a706cf9d0f7f5a6b
+  metadata.gz: 2db06592f56122df80f8ad27fb1bc67f8920b47a623dbd8f6343f265998efa60
+  data.tar.gz: fcf86ec795983ec1a73d565e49685314b88dd0bc2cc22174fa1bb41841dfbaa2
 SHA512:
-  metadata.gz: 928880bc75f3bc9665ab84c7bbd8d50fe8e310d520365e065c1c036cbdc8c67195e37059e608e4340dd018943965f322361287a057a3450771905997648960ad
-  data.tar.gz: 7ba9c66b2e655044c62c7b6db12d42451e46e5c5239206b879b1951a69472c1fe883b491efbfdcd26fb38a850663abcf7e673150bdf61ec5e5ed85d383c3c490
+  metadata.gz: 6a138171e3a15cee57f1ac71a55f8c5bce7d1db15560fe5ee4c11810c0e496e81e838350754375b377f9ffca562fb75abe5b897e1a3ae4ae36af7f5ec518ecea
+  data.tar.gz: 8a2c7a47987d4500a074346835c65093b3e1dbbdcfbb1d7800ea3fe7d749c3ba0c3fb6e95d0fd4d89b8fe5b530d00fc9f6f57ded2b0fe863ff721319bd51f623

data/README.md

@@ -1,27 +1,24 @@
 [![Build Status](https://travis-ci.com/theonestack/cfhighlander.svg?branch=develop)](https://travis-ci.com/theonestack/cfhighlander)
 
-# Cfhighlander
+# Highlander
 
-Cfhighlander is DSL processor that enables composition and orchestration of Amazon CloudFormation templates 
+Highlander is DSL processor that enables composition and orchestration of Amazon CloudFormation templates 
 written using [CfnDsl](https://github.com/cfndsl/cfndsl) in an abstract way. It tries to tackle problem of merging multiple templates into master
 template in an elegant way, so higher degree of template reuse can be achieved. It does so by formalising commonly
-used cfndsl template composition patterns via DSL statements. For an example, passing output of one stack into other stack is done
-automatically if parameter and output names are the same, 
-rather than wiring them manually in 'master' cfndsl template. For this example to 
+used patterns via DSL statements. For an example, passing output of one stack into other stack is achieved using 
+`OutputParam` highlander DSL statement, rather than wiring this parameters manually in cfndsl templates. For this example to 
 work, parent component will have to pull in both component rendering output values, and component pulling them in
-as parameters. Cfhighlander allows for greater reuse of component templates by allowing references to templates
-via git urls, and s3 urls. [Theonestack](https://github.com/theonestack) has several prebuilt component templates to use,
-with repositories from this org being one of the default sources for searching component templates.
+as parameters. It also enables it's user to build component library, where components can be distributed to s3, and 
+consequentially references to them resolved. 
 
-Highlander DSL produces CloudFormation templates in 4 phases
+Highlander DSL produces CloudFormation templates in 3 phases
 
 - Processing referenced component's configuration and resolving configuration exports
-- Wiring parameters from components to their inner components
 - Producing [CfnDsl](https://github.com/cfndsl/cfndsl) templates for all components and subcomponents as intermediary
   step
 - Producing resulting CloudFormation templates using configuration and templates generated in two previous phases.
 
-Each phase (aside from parameter wiring) above is executable as stand-alone through CLI, making development of Highlander templates easier by enabling
+Each phase above is executable as stand-alone through CLI, making development of Highlander templates easier by enabling
 debugging of produced configuration and cfndsl templates. 
 
 
@@ -51,7 +48,7 @@ this file defines map used within component itself
 - Define cfndsl template used for building CloudFormation resources
 
 
-**Outer component** is component that defines other component via cfhighlander dsl `Component` statement. Defined component
+**Outer component** is component that defines other component via higlander dsl `Component` statement. Defined component
 is called **inner component**. Components defined under same outer component are **sibling components**
 
 ## Usage
@@ -61,30 +58,30 @@ For both ways, highlander is distributed as ruby gem
 
 
 ```bash
-$ gem install cfhighlander
-$ cfhighlander help
-cfhighlander commands:
-  cfhighlander cfcompile component[@version] -f, --format=FORMAT   # Compile Highlander component to CloudFormation templates
-  cfhighlander cfpublish component[@version] -f, --format=FORMAT   # Publish CloudFormation template for component, and it' referenced subcomponents
-  cfhighlander configcompile component[@version]                   # Compile Highlander components configuration
-  cfhighlander dslcompile component[@version] -f, --format=FORMAT  # Compile Highlander component configuration and create cfndsl templates
-  cfhighlander help [COMMAND]                                      # Describe available commands or one specific command
-  cfhighlander publish component[@version] [-v published_version]  # Publish CloudFormation template for component, and it' referenced subcomponents
+$ gem install highlander
+$ highlander help
+highlander commands:
+  highlander cfcompile component[@version] -f, --format=FORMAT   # Compile Highlander component to CloudFormation templates
+  highlander cfpublish component[@version] -f, --format=FORMAT   # Publish CloudFormation template for component, and it' referenced subcomponents
+  highlander configcompile component[@version]                   # Compile Highlander components configuration
+  highlander dslcompile component[@version] -f, --format=FORMAT  # Compile Highlander component configuration and create cfndsl templates
+  highlander help [COMMAND]                                      # Describe available commands or one specific command
+  highlander publish component[@version] [-v published_version]  # Publish CloudFormation template for component, and it' referenced subcomponents
 
 ```
 ### Working directory
 
 All templates and configuration generated are placed in `$WORKDIR/out` directory. Optionally, you can alter working directory
-via `CFHIGHLANDER_WORKDIR` environment variable. 
+via `HIGHLANDER_WORKDIR` environment variable. 
 
 ### Commands
 
 To get full list of options for any of cli commands use `highlander help command_name` syntax
 
 ```bash
-$ cfhighlander help publish
+$ highlander help publish
 Usage:
-  cfhighlander publish component[@version] [-v published_version]
+  highlander publish component[@version] [-v published_version]
 
 Options:
       [--dstbucket=DSTBUCKET]  # Distribution S3 bucket
@@ -98,7 +95,7 @@ Publish CloudFormation template for component,
 
 #### Silent mode
 
-Cfhighlander DSL processor has built-in support for packaging and deploying AWS Lambda functions. Some of these lambda
+Highlander DSL processor has built-in support for packaging and deploying AWS Lambda functions. Some of these lambda
 functions may require shell command to be executed (e.g. pulling library dependencies) prior their packaging in ZIP archive format.
 Such commands are potential security risk, as they allow execution of arbitrary code, so for this reason user agreement is required
 e.g:
@@ -139,11 +136,11 @@ cfndsl templates. Check component configuration section for more details.
 
 #### dslcompile
 
-*dslcompile* will produce intermediary cfndsl templates. This is useful for debugging cfhighlander components
+*dslcompile* will produce intermediary cfndsl templates. This is useful for debugging highlander components
 
 #### publish
 
-*publish* command publishes cfhighlander components source code to s3 location (compared to *cfpublish* which is publishing
+*publish* command publishes highlander components source code to s3 location (compared to *cfpublish* which is publishing
 compiled cloudformation templates). Same CLI / DSL options apply as for *cfpublish* command. Version defaults to `latest`
 
 
@@ -172,7 +169,7 @@ This configuration level overrides component's own config file.
 - Outer component explicit configuration. You can pass `config` named parameter to `Component` statement, such as
 
 ```ruby
-CfhighlanderTemplate do
+HighlanderComponent do
 
 # ...
 # some dsl code
@@ -260,7 +257,7 @@ Parameters block is used to define CloudFormation template parameters, and metad
 are wired with outer or sibling components. 
 
 ```ruby
-CfhighlanderTemplate do
+HighlanderComponent do
   Parameters do
     ##
     ##  parameter definitions here
@@ -273,117 +270,81 @@ Parameter block supports following parameters
 
 #### ComponentParam
 
-`ComponentParam` - Component parameter exposes parameter to be wired from outer component. Cfhighlander's
-autowiring mechanism will try and find any stack outputs from other components defined by outer components with name 
-matching. If there is no explicit value provided, or autowired from outputs, parameter will be propagated to outer component.
-
-Propagated parameter will be prefixed with component name **if it is not defined as global parameter**. Otherwise, 
-parameter name is kept in full. 
-
-Example below demonstrates 3 different ways of providing parameter values from outer to inner component. 
-
-- Provide value explicitly
-- Provide value explicitly as output of another component     
-- Autowire value from output of another component with the same name
-- Propagate parameter to outer component 
+`ComponentParam` - Component parameter takes name and default value. It defines component parameter
+that is not auto-wired in any way with outer component. This parameter will either use default value, or value
+explicitly passed from outer component. 
 
 ```ruby
 
-# Inner Component 1
-CfhighlanderTemplate do
+# Inner Component
+HighlanderComponent do
   Name 's3'
   Parameters do
      ComponentParam 'BucketName','highlander.example.com.au'
-     ComponentParam 'BucketName2',''
-     ComponentParam 'BucketName3',''
-     ComponentParam 'BucketName4','', isGlobal: false # default value is false
-     ComponentParam 'BucketName5','', isGlobal: true
   end
-
 end
-
 ```
 
 ```ruby
-# Inner Component 2
-CfhighlanderTemplate do
-  Name 'nameproducer'
-
-  # has output 'bucket name defined in cfdnsl
+# Outer component
+HighlanderComponent do
+  # instantiate inner component with name and template
+  Component template:'s3',
+            name:'s3', 
+            parameters:{'BucketName' => 'outer.example.com.au'}
 end
+```
 
+#### StackParam
 
-# -- contents of cfndsl 
-CloudFormation do
+`StackParam` - Stack parameter bubbles up to it's outer component. Outer component will either define top level parameter
+with same name as inner component parameter (if parameter is defined as global), or it will be prefixed with inner component name.
 
-    Condition 'AlwaysFalse', FnEquals('true','false')
-    S3_Bucket :resourcetovalidateproperly do
-      Condition 'AlwaysFalse'
-    end
 
-    Output('BucketName') do
-        Value('highlanderbucketautowired.example.com.au')
-    end
+```ruby
+# Outer component
+HighlanderComponent do
+  Component template:'s3',name:'s3' 
 end
-
-
 ```
 
 ```ruby
-# Outer component
-CfhighlanderTemplate do
-    Component 'nameproducer'
-    Component 's3' do
-      parameter name: 'BucketName2', value: 'nameproducer.BucketName'
-      parameter name: 'BucketName3', value: 'mybucket.example.cfhighlander.org'
-    end
+# Inner component
+HighlanderComponent do
+  Name 's3'
+  Parameters do
+    StackParam 'EnvironmentName','dev', isGlobal:true
+    StackParam 'BucketName','highlander.example.com.au', isGlobal:false
+  end
 end
-
 ```
 
 
-Example above translates to following wiring of parameters in cfndsl template
+Example above translates to following cfndsl template in outer component
 ```ruby
 CloudFormation do
 
-     # Parameter that was propagated
-    Parameter('s3BucketName4') do
-      Type 'String'
-      Default ''
-      NoEcho false
-    end
-    
-    Parameter('BucketName5') do
-      Type 'String'
-      Default ''
-      NoEcho false
+    Parameter('EnvironmentName') do
+    Type 'String'
+    Default ''
     end
 
-   CloudFormation_Stack('s3') do
-       TemplateURL './s3.compiled.yaml'
-       Parameters ({
-       
-          # Paramater that was auto-wired
-           'BucketName' => {"Fn::GetAtt":["nameproducer","Outputs.BucketName"]},
-       
-          # Parameter that was explicitly wired as output param from another component
-           'BucketName2' => {"Fn::GetAtt":["nameproducer","Outputs.BucketName"]},
-       
-          # Paramater that was explicitly provided
-           'BucketName3' => 'mybucket.example.cfhighlander.org',
-       
-          # Reference to parameter that was propagated. isGlobal: false when defining
-          # parameter, so parameter name is prefixed with component name 
-           'BucketName4' => {"Ref":"s3BucketName4"},
-          
-          # Reference to parameter that was propagated. isGlobal: true when defining
-          # parameter, so parameter name is not prefixed, but rather propagated as-is
-          'BucketName5' => {"Ref":"BucketName5"},
-       
-       })
-   end
+    Parameter('s3BucketName') do
+    Type 'String'
+    Default 'highlander.example.com.au'
+    end
+  
+    CloudFormation_Stack('s3') do
+      TemplateURL 'https://distributionbucket/dist/latest/s3.yaml'
+      Parameters ({
+      
+        'EnvironmentName' => Ref('EnvironmentName'),
+      
+        'BucketName' => Ref('s3BucketName'),
+      
+      })
+    end
 end
-
 ```
 
 
@@ -397,7 +358,7 @@ This DSL statements takes a full body, as Mapping name, Map key, and value key n
  
  ```ruby
 # Inner component
-CfhighlanderTemplate do
+HighlanderComponent do
   Name 's3'
   Parameters do
     MappingParam 'BucketName' do
@@ -409,13 +370,17 @@ end
  ```
 
 
+#### OutputParam
+
+TBD
+
 ### DependsOn
 
 `DependsOn` - this will include any globally exported libraries from given 
 template. E.g.
 
  ```ruby
-CfhighlanderTemplate do
+HighlanderComponent do
   Name 's3'
   DependsOn 'vpc@1.0.3'
 end
@@ -433,46 +398,7 @@ so extension methods can be consumed within cfndsl template.
 #### Referencing
 
 
-## Finding templates and creating components
-
-
-Templates are located by default in following locations
-
-- `$WD`
-- `$WD/$componentname`
-- `$WD/components/$componentname`
-- `~/.cfhighlander/components/componentname/componentversion`
-- `https://github.com/cfhighlander/theonestack/hl-component-$componentname` on `master` branch
-
-Location of component templates can be given as git/github repo:
-
-```ruby
-
-CfhighlanderTemplate do
-
-      # pulls directly from master branch of https://github.com/theonestack/hl-component-vpc
-      Component name: 'vpc0', template: 'vpc'
-    
-      # specify branch github.com: or github: work. You specify branch with hash
-      Component name: 'vpc1', template: 'github:theonestack/hl-component-vpc#master'
-    
-      # you can use git over ssh
-      # Component name: 'vpc2', template: 'git:git@github.com:theonestack/hl-component-vpc.git'
-    
-      # use git over https
-      Component name: 'vpc3', template: 'git:https://github.com/theonestack/hl-component-sns.git'
-    
-      # specify .snapshot to always clone fresh copy
-      Component name: 'vpc4', template: 'git:https://github.com/theonestack/hl-component-sns.git#master.snapshot'
-    
-      # by default, if not found locally, highlander will search for https://github.com/theonestack/component-$componentname
-      # in v${version} branch (or tag for that matter)
-      Component name: 'vpc5', template: 'vpc@1.0.4'
-
-end
-
-```
-
+## Finding and loading components
 
 ## Rendering CloudFormation templates
 
@@ -482,4 +408,4 @@ end
 
 Any extensions placed within `cfndsl_ext` folder will be 
 available in cfndsl templates of all components. Any extensions placed within `hl_ext` folder are 
-available in cfhighlander templates of all components. 
+available in highlander templates of all components. 

data/bin/cfhighlander

@@ -1,3 +1,3 @@
 #!/usr/bin/env ruby
 
-require_relative('./cfhighlander')
+require_relative('./highlander')

data/bin/{cfhighlander.rb → highlander.rb}

@@ -9,10 +9,10 @@
 
 require 'thor'
 require 'rubygems'
-require_relative '../lib/cfhighlander.compiler'
-require_relative '../lib/cfhighlander.factory'
-require_relative '../lib/cfhighlander.publisher'
-require_relative '../lib/cfhighlander.validator'
+require_relative '../lib//highlander.compiler'
+require_relative '../lib/highlander.factory'
+require_relative '../lib/highlander.publisher'
+require_relative '../lib/highlander.validator'
 
 class HighlanderCli < Thor
 
@@ -22,15 +22,15 @@ class HighlanderCli < Thor
 
   desc 'configcompile component[@version]', 'Compile Highlander components configuration'
 
-  def configcompile(template_name)
+  def configcompile(component_name)
 
     # find and load component
-    component_loader = Cfhighlander::Factory::ComponentFactory.new
-    component = component_loader.loadComponentFromTemplate(template_name)
+    component_loader = Highlander::Factory::ComponentFactory.new
+    component = component_loader.findComponent(component_name)
     component.load
 
     # compile cfndsl template
-    component_compiler = Cfhighlander::Compiler::ComponentCompiler.new(component)
+    component_compiler = Highlander::Compiler::ComponentCompiler.new(component)
     component_compiler.writeConfig(true)
   end
 
@@ -50,7 +50,7 @@ class HighlanderCli < Thor
     component = build_component(options, component_name)
 
     # compile cfndsl template
-    component_compiler = Cfhighlander::Compiler::ComponentCompiler.new(component)
+    component_compiler = Highlander::Compiler::ComponentCompiler.new(component)
     component_compiler.silent_mode = options[:quiet]
     out_format = options[:format]
     component_compiler.compileCfnDsl out_format
@@ -75,12 +75,12 @@ class HighlanderCli < Thor
     component = build_component(options, component_name)
 
     # compile cloud formation
-    component_compiler = Cfhighlander::Compiler::ComponentCompiler.new(component)
+    component_compiler = Highlander::Compiler::ComponentCompiler.new(component)
     component_compiler.silent_mode = options[:quiet]
     out_format = options[:format]
     component_compiler.compileCloudFormation out_format
     if options[:validate]
-      component_validator = Cfhighlander::Cloudformation::Validator.new(component)
+      component_validator = Highlander::Cloudformation::Validator.new(component)
       component_validator.validate(component_compiler.cfn_template_paths, out_format)
     end
     component_compiler
@@ -103,7 +103,7 @@ class HighlanderCli < Thor
 
   def cfpublish(component_name)
     compiler = cfcompile(component_name)
-    publisher = Cfhighlander::Publisher::ComponentPublisher.new(compiler.component, false)
+    publisher = Highlander::Publisher::Component.new(compiler.component, false)
     publisher.publishFiles(compiler.cfn_template_paths + compiler.lambda_src_paths)
   end
 
@@ -117,35 +117,37 @@ class HighlanderCli < Thor
   method_option :version, :type => :string, :required => false, :default => nil, :aliases => '-v',
       :desc => 'Distribution component version, defaults to latest'
 
-  def publish(template_name)
+  def publish(component_name)
     component_version = options[:version]
     distribution_bucket = options[:dstbucket]
     distribution_prefix = options[:dstprefix]
 
     # find and load component
-    component_loader = Cfhighlander::Factory::ComponentFactory.new
-    component = component_loader.loadComponentFromTemplate(template_name)
+    component_loader = Highlander::Factory::ComponentFactory.new
+    component = component_loader.findComponent(component_name)
     component.version = component_version
     component.distribution_bucket = distribution_bucket unless distribution_bucket.nil?
     component.distribution_prefix = distribution_prefix unless distribution_prefix.nil?
     component.load
 
-    publisher = Cfhighlander::Publisher::ComponentPublisher.new(component, true)
+    publisher = Highlander::Publisher::Component.new(component, true)
     publisher.publishComponent
   end
 
 end
 
 # build component from passed cli options
-def build_component(options, template_name)
-
+def build_component(options, component_name)
+  if ENV['HIGHLANDER_WORKDIR'].nil?
+    ENV['HIGHLANDER_WORKDIR'] = Dir.pwd
+  end
   component_version = options[:version]
   distribution_bucket = options[:dstbucket]
   distribution_prefix = options[:dstprefix]
 
   # find and load component
-  component_loader = Cfhighlander::Factory::ComponentFactory.new
-  component = component_loader.loadComponentFromTemplate(template_name)
+  component_loader = Highlander::Factory::ComponentFactory.new
+  component = component_loader.findComponent(component_name)
   component.version = component_version unless component_version.nil?
   component.distribution_bucket = distribution_bucket unless distribution_bucket.nil?
   component.distribution_prefix = distribution_prefix unless distribution_prefix.nil?
@@ -153,11 +155,4 @@ def build_component(options, template_name)
   component
 end
 
-if ENV['CFHIGHLANDER_WORKDIR'].nil?
-  ENV['CFHIGHLANDER_WORKDIR'] = Dir.pwd
-end
-if ENV['HIGHLANDER_WORKDIR'].nil?
-  ENV['HIGHLANDER_WORKDIR'] = Dir.pwd
-end
-
 HighlanderCli.start