puppet-runner 0.0.20 → 0.0.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ef7b7a722f72764a0d2b013624442fbf1a953a78f9ccd380d718209f53acf61
-  data.tar.gz: c060b7c2a5d188de60cda6afc41f9beb6e1693aed4966d609396596cbbdf6c57
+  metadata.gz: 255f8a295029af51ad19f6b7eaedaed8d84c23443e113a71d377e2ec619e4cef
+  data.tar.gz: 21d692bf0b338f1f4e53e74a675131843e1206cdc0dc7c19c08268cc7ac77eeb
 SHA512:
-  metadata.gz: 67de10395d2f7c802a5b00e8c0a15b2149a33514b1cbda0a811cdd34d97a108b5b343b142386918e6aa957ead50fcc0ffe38bc503a56d877bfd89d85faa243af
-  data.tar.gz: 864c05e7c5b9223d01fc09e1b43ae2925904542128b5ecd81310c60167706918a1768a833679f10fb545cb27850335f803c32fa5b49c282fc71588d679153be2
+  metadata.gz: 04c85a270ffedc2ff99e77c264dbb807b22cba02d0b87cd42359323d1793b440d9d145722beb26e3129ed1c62bf2154f7a5153d3c46fcd48e8c7327e25144261
+  data.tar.gz: ebb4ab20384b64d3420721fe031a0edad4e230eeeafc22719790ab842b496e2abef9ee32218a0a18635942bb201f6638d09efb92ef85bf19c4dcf218a9f1944c

data/README.md

@@ -101,6 +101,271 @@ With this setup we define prefix -> substitution_string pair for each prefix in
 
 "hostname"_facts.yaml - must contain all prefixed custom facts to customize the setup 
 
+### Fact Metadata
+
+The defaults file contains all the facts (variables) that are needed to run the tempalte, the basic format of this is:
+```
+fact_name: 'fact_value'
+```
+
+So in this instance fact_name will have a default value of fact_value, which can be overiden by the user in their own facts file.
+
+However it is also possible to add metadata to the facts by changing the format, the current metadata is `comment` and `type`, this extened format looks like:
+
+```
+fact_name:
+    value: 'fact_value'
+    comment: 'this is an important fact'
+    type: 'string'
+```
+
+The two metadata values are:
+`comment` - This is a description for the fact to help identify what it is for, it is added above the fact in the reultant facts files written by puppet-runner
+`type` - This identifies the data type of the fact, by default if this meatadata is not set the value defaults to `string`, current valid types are:
+**string**
+**boolean**
+**nilable**
+
+### Fact Types
+
+As mentioned above it is possible to assign a "type" metadata element to each fact, the reasons is that facter delivers all its data as a string, this can cause issues so the "type" metadata allows puppet-runner to do something special for other data typs:
+
+#### string
+
+All data is passed by default as a string, setting the type to string does not do anythign special
+
+#### boolean
+
+If the type is set to boolean this tells puppet-runner that we want to pass in true boolean values, a conversion from the string value into true boolean is attempted.  If the conversions is successfull the fact reference in the final compiled hiera document (/etc/puppet/hiera/<HOSTNAME>.eyaml) would be replaced with the actual boolean value so that puppet does not recive its string representation.
+
+Example:
+
+Template
+```
+---
+  
+prefixes:
+    - yum_
+
+classes:
+    - yum
+
+dependencies:
+  - yum
+  - puppi
+
+yum::defaultrepo: "%{::yum_defaultrepo}"
+```
+
+If the defaults does not use metadata (or uses a type of string) and the facts are set as below
+```
+---
+  
+yum_defaultrepo: "true"
+```
+
+Then the value writen into /etc/puppet/hiera/<HOSTNAME>.eyaml would be 
+
+```
+yum::defaultrepo: "%{::yum_defaultrepo}"
+```
+
+Whereas if the default was set to boolean as below:
+```
+---
+  
+yum_defaultrepo: 
+  value: "true"
+  type: "boolean"
+```
+
+Then the value writen into /etc/puppet/hiera/<HOSTNAME>.eyaml would be 
+
+```
+yum::defaultrepo: true
+```
+
+#### nilable
+
+If the type is set to nilable this tells puppet-runner that we want to pass in a nil/undef (null) value instead of an empty string, if the fact value is blank '' it will be converted into a tilda (~) as this is the nil representation  in hiera.  If the conversions is successfull the fact reference in the final compiled hiera document (/etc/puppet/hiera/<HOSTNAME>.eyaml) would be replaced with a tilda.  Please note this only works for puppet variables that are defaulted in the code to undef, if they have a value passing nil to them will result in the code default still being set
+
+Example:
+
+Template
+```
+---
+classes:
+  - artifactory
+
+
+artifactory::conf:
+    tarball_location_file: "%{::artifactory_file_location}"
+    tarball_location_url:  "%{::artifactory_url_location}"
+    .........
+```
+
+If the defaults does not use metadata (or uses a type of string) and the facts are set as below
+```
+---
+  
+artifactory_file_location: '/tmp/file.zip'
+artifactory_url_location: 
+```
+
+They are therefore both mandatory fileds and puppet-runner will ask for you to give a value for both, however in reality these are mutually exclusive, one will take precident over the other so passing them both could have unforseen consequences.
+
+The other otpion is to set the facts to be empty string, however this still passed an empty string into puppet which, unless the code has been written to discount that, could still cause issues:
+```
+artifactory_file_location: '/tmp/file.zip'
+artifactory_url_location: ''
+```
+
+Then the value writen into /etc/puppet/hiera/<HOSTNAME>.eyaml would be 
+
+```
+artifactory::conf:
+    tarball_location_file: "%{::artifactory_file_location}"
+    tarball_location_url:  "%{::artifactory_url_location}"
+```
+
+Whereas if the metadata type was set to nilable and a value of '' (empty string is supplied)  in the defaults
+```
+---
+  
+artifactory_file_location:
+  value: ''
+  comment: 'blah'
+  type: 'nilable'
+artifactory_url_location: 
+  value: ''
+  comment: 'other blah'
+  type: 'nilable'
+```
+
+And the facts were set with a value for one and empty string for the other as below:
+```
+artifactory_file_location: '/tmp/file.zip'
+artifactory_url_location: ''
+```
+
+Then the value writen into /etc/puppet/hiera/<HOSTNAME>.eyaml would be 
+
+```
+artifactory::conf:
+    tarball_location_file: "%{::artifactory_file_location}"
+    tarball_location_url:  ~
+```
+
+### Inter fact references
+
+There are a number of occasions where you may want one fact to point to the value of another, either because you want it to be exactly the same or you want your fact to be a superset of the other, puppet-runner will evaluate facts that reference another fact and present the last fact reference to puppet, the resolution will recursivly resolve facts down to their base fact to a max depth of 5, after which it will stop in order to prevent infinite loops, this will cause a failure of the fact lookup.
+
+#### Example 1: Fact directly referneces another fact
+
+In this example we want our fact to reference another, in this example we will point a custom fact at a system fact (although you can point it at any fact, system or custom)
+
+**template:**
+````
+---
+  
+prefixes:
+  - vpn_snat_
+
+classes:
+  - fw
+
+dependencies:
+  - fw
+  - firewall
+  - stdlib
+
+fw::rules: &fw_rules
+  "%{::vpn_snat_description}":
+      chain: "%{::vpn_snat_chain}"
+      tosource: "%{::vpn_snat_tosource}"
+      jump: "%{::vpn_snat_jump}"
+      source: "%{::vpn_snat_source}"
+      table: "%{::vpn_snat_table}"
+      proto: "%{::vpn_snat_proto}"
+````
+
+We want the `tosource` value to be set with the IP address for the servers eth0 adapter, there is already a system fact for this `ipaddress_eth0` 
+
+We set the facts as below:
+
+````
+vpn_snat_description: '000 VPN SNAT Configuration'
+vpn_snat_chain: 'POSTROUTING'
+vpn_snat_tosource: "%{::ipaddress_eth0}"
+vpn_snat_jump: 'SNAT'
+vpn_snat_source: '172.28.254.0/23'
+vpn_snat_table: 'nat'
+vpn_snat_proto: 'all'
+````
+
+Pupet-runner will resolve the `vpn_snat_tosource` faqt down to the first fact it references, which is `ipaddress_eth0`, as a result the value writen into /etc/puppet/hiera/<HOSTNAME>.eyaml would be 
+
+````
+fw::rules: &fw_rules
+  "%{::vpn_snat_description}":
+      chain: "%{::vpn_snat_chain}"
+      tosource: "%{::ipaddress_eth0}"
+      jump: "%{::vpn_snat_jump}"
+      source: "%{::vpn_snat_source}"
+      table: "%{::vpn_snat_table}"
+      proto: "%{::vpn_snat_proto}"
+````
+
+#### Example 2: Fact includes another fact as part of its value
+
+In this example we want our fact to be a superset of another fact.
+
+**template:**
+````
+---
+
+prefixes:
+  - tripwire_
+
+classes:
+  - tripwire
+
+dependencies:
+  - tripwire
+  - stdlib
+  - concat
+
+tripwire::local_passphrase: '%{::tripwire_local_passphrase}'
+tripwire::site_passphrase: '%{::tripwire_site_passphrase}'
+tripwire::tripwire_email: '%{::tripwire_tripwire_email}'
+tripwire::tripwire_policy_file: '%{::tripwire_tripwire_policy_file}'
+````
+
+We want the `site_passphrase` value to be the same as `local_passphrase` but with _LOCAL at the end
+
+We set the facts as below:
+
+````
+tripwire_global_passphrase: 'super_secret'
+tripwire_local_passphrase: "%{::tripwire_site_passphrase}_LOCAL"
+tripwire_site_passphrase: "%{::tripwire_global_passphrase}
+tripwire_tripwire_email: 'blackhole'
+tripwire_tripwire_policy_file: 'false'
+````
+ 
+Note here we have added a custom fact that is not references in any template or default, this will still be avaliable via facter in the normal way.
+
+The fact `tripwire_site_passphrase` will resolve down to `tripwire_global_passphrase` as in the previous example, however the fact `tripwire_local_passphrase` will be resolved twice (once to `tripwire_site_passphrase` and then again down to `tripwire_global_passphrase`)
+
+As a result the value writen into /etc/puppet/hiera/<HOSTNAME>.eyaml would be 
+
+````
+tripwire::local_passphrase: '%{::tripwire_global_passphrase}_LOCAL'
+tripwire::site_passphrase: '%{::tripwire_global_passphrase}'
+tripwire::tripwire_email: '%{::tripwire_tripwire_email}'
+tripwire::tripwire_policy_file: '%{::tripwire_tripwire_policy_file}'
+````
+
 #### TEMPLATES
 Must contain 2 subdirectories.
 - templates - template yaml files
@@ -155,6 +420,7 @@ Path to output Puppetfile.
 *  -o PUPPETFILE_OUTPUT_PATH --puppetfile_output_path PUPPETFILE_OUTPUT_PATH Result Puppetfile path
 *  -e EYAML_KEY_PATH --eyaml_key_pair EYAML_KEY_PATH                         Path to eyaml encryption key pair
 *  -p PUPPET_APPLY --puppet_apply PUPPET_APPLY                               Custom puppet apply command to run
+*    -k --keep-facts                                                        Flag to keep the encrypted facts file in /tmp for analysis
 
 Commands:
 

data/bin/puppet-runner

@@ -107,12 +107,35 @@ def extract_type_from_hash(input)
            type = val["type"]
         end
       end
-      {key => type }
+      {type => key }
     }
   end
   res
 end
 
+# function to resolve inter fact references, it should return the last fact name (not value)
+def resolve_fact(fact_name, max_depth=5, current_depth=0)
+  final_val = nil
+  fact_name = fact_name.sub(/%{::/,'').sub(/}/,'')
+  if max_depth == current_depth
+    warning "Fact resolution has reached a depth of 5 facts, aborting lookup"
+  else
+    # attempt to get value
+    val = $all_facts[fact_name] || Facter.value(fact_name) || nil
+
+    if val == "%{::#{fact_name}}"
+      warning "Fact resolves to itself, skipping"
+    elsif val.instance_of?(String) and val.match(/%{::.*.}/)
+      val = resolve_fact(val,max_depth, current_depth + 1)
+    else
+      val = "%{::#{fact_name}}"
+    end
+    final_val = val
+  end
+  final_val
+end
+
+
 begin
     options = Docopt::docopt(doc)
 rescue Docopt::Exit => e
@@ -170,7 +193,8 @@ if options['all'] || options['prepare']
     prefixed_facts_comments = {}
     puppetfile_config = YAML.load_file(puppetfile_config_path) || {}
     puppetfile_dependencies = []
-    global_transform_data = []
+    global_data_types = []
+    nil_transform_present = false
       # functionalities:
       # # In honor of Henry... 
       #   1_app:
@@ -211,17 +235,7 @@ if options['all'] || options['prepare']
             fact_comments_as_string = extract_comment_from_hash(default_facts).to_s
             
             # get a list of each fields type if set (if not they will report as strings)
-            data_type = extract_type_from_hash(default_facts)
-
-            # Check to see if any of the fields are booleans, if so add an entry to the transform_data array
-            transform_data = []
-            data_type.each do | field|
-              field.each do | field_name, field_type |
-                if field_type == 'boolean'
-                  transform_data << field_name
-                end
-              end
-            end
+            data_types = extract_type_from_hash(default_facts)
             
             if to_add.is_a?(Hash)
               # if prefixes are not defined skip replacing
@@ -239,7 +253,13 @@ if options['all'] || options['prepare']
                         facts_as_string = facts_as_string.gsub(/#{prefix}/, "#{replace_prefixes_with}")
                         fact_comments_as_string = fact_comments_as_string.gsub(/#{prefix}/, "#{replace_prefixes_with}")
                         prefixed_required_facts = prefixed_required_facts.merge(required_facts.map! { |item| item.gsub(/#{prefix}/, "#{replace_prefixes_with}") })
-                        transform_data = transform_data.map {|s| s.gsub(/#{prefix}/, "#{replace_prefixes_with}")} if !transform_data.empty?
+                        if !data_types.empty?
+                          data_types.each do | transform |
+                            transform.each do|key, value|
+                              transform[key] = value.gsub(/#{prefix}/, "#{replace_prefixes_with}")
+                            end
+                          end
+                        end
                       end
                     end
                   end
@@ -252,7 +272,13 @@ if options['all'] || options['prepare']
                     facts_as_string = facts_as_string.gsub(/#{prefix}/, "#{replace_prefixes_with}")
                     fact_comments_as_string = fact_comments_as_string.gsub(/#{prefix}/, "#{replace_prefixes_with}")
                     prefixed_required_facts = prefixed_required_facts.merge(required_facts.map! { |item| item.gsub(/#{prefix}/, "#{replace_prefixes_with}") })
-                    transform_data = transform_data.map {|s| s.gsub(/#{prefix}/, "#{replace_prefixes_with}")} if !transform_data.empty?
+                    if !data_types.empty?
+                      data_types.each do | transform |
+                        transform.each do|key, value|
+                          transform[key] = value.gsub(/#{prefix}/, "#{replace_prefixes_with}")
+                        end
+                      end
+                    end
                   end
                 end
               end
@@ -267,8 +293,8 @@ if options['all'] || options['prepare']
               default_fact_comments = extract_comment_from_hash(plain_facts)  
               prefixed_required_facts = prefixed_required_facts.merge(required_facts)
             end
-            # add the "local" transformation list to the global one
-            global_transform_data.push(*transform_data)
+            # add the "local" data type list to the global one
+            global_data_types.push(*data_types)
 
             result_template.deep_merge!(template)
             # default_facts_prefixed is Array of hashes as the result of map, this will create hash from it
@@ -287,37 +313,89 @@ if options['all'] || options['prepare']
 
       File.open(output_encrypted_facts_file_path, 'w+') do |output_file|
         output_result_default_facts = result_default_facts.deep_merge!(custom_facts, {:merge_hash_arrays => true}).to_yaml
+      
+        # convert final facts to hash for inter fact resolution and also for potential transformations later
+        $all_facts = YAML.load(output_result_default_facts)
+
+        #convert result templat to string
+        result_template = result_template.to_s
+
+        # loop through facts looking for any that reference other facts
+        $all_facts.each do | fact_key, fact_val |
+          if fact_val.instance_of?(String) and fact_val.match(/%{::.*.}/)
+            debug "Fact #{fact_key} references another fact or facts"
+            # find each instance of a fact within the value (it may contain multiple facts
+            # i.e "TEST%{::fact1}TEST%{::fact2}"
+            fact_val.gsub(/}/,"}\n").scan(/%{::.*.}/).each do | fact |
+              # resolve the fact down to its last reference to another fact (not the end value)
+              resolved_fact = resolve_fact(fact)
+              # if the resolved fact name is not the same as the original fact we found referenced
+              # then replace the value in fact_val
+              if !resolved_fact.nil? and resolved_fact != fact
+                fact_val = fact_val.gsub(/#{fact}/,"#{resolved_fact}")
+              end
+            end
+            debug "Attempting to replace fact '#{fact_key}' with value '#{fact_val}' in compiled template"
+            # replace the original fact reference in the template with the resovled value
+            # this is done before global teansformation as they may change the final value again
+            result_template = result_template.gsub(/\"\%{::#{fact_key}}\"/, "\"#{fact_val}\"")
+          end
+        end
+
+        # add comments above any fact lines
         prefixed_facts_comments.each do |pattern, replacement|
           if replacement != nil
             output_result_default_facts.gsub!(/^#{pattern}/, "\##{replacement}\n#{pattern}")
           end
         end
 
+        # write the temp encrypted facts file
         output_file.write(output_result_default_facts)
 
         # now that the merged final facts are present look for any global transformations to apply 
-        # global transformations are currently just booleans that need to be expressed directly in output file
-        if !global_transform_data.empty?
-          result_template = result_template.to_s
-          all_facts = YAML.load(output_result_default_facts)
-          global_transform_data.each do | transform_value |
-            debug "Attempting to replace boolean value for fact #{transform_value}"
-            begin
-              # convert the final template to a string, replace any facts that are booleans with their actual value and then convert the result bacl to YAML
-              # convert the fact to boolean and then back to string during the replace, this allows validation that the fact is actually a boolean
-              result_template = result_template.gsub(/\"\%{::#{transform_value}}\"/, all_facts[transform_value].to_bool.to_s)
-            rescue
-              warning "Unable to convert fact #{transform_value} with value #{all_facts[transform_value]} into boolean, conversion will be skipped"
+        # global transformations are currently either booleans that need to be expressed directly in 
+        # the output file or nilable values that need to be expressed as unquoted tildas (~)
+        if !global_data_types.empty?
+          global_data_types.each do | transform |
+            transform.each do|transform_type, transform_value|
+              begin
+                if transform_type == 'boolean'
+                  debug "Attempting to replace boolean value for fact #{transform_value}"
+                  # convert the fact to boolean and then back to string during the replace, this allows validation that the fact is actually a boolean
+                  result_template = result_template.gsub(/\"\%{::#{transform_value}}\"/, $all_facts[transform_value].to_bool.to_s)
+                elsif transform_type == 'nilable'
+                  # replace fact reference with tilda if the value is nil, empty or already a tilda
+                  # due to issues with ruby hash values being unquoted we will quote it now and remove the quotes later
+                  if $all_facts[transform_value].nil? or $all_facts[transform_value].empty? or $all_facts[transform_value] == "~"
+                    debug "Attempting to replace nilable value for fact #{transform_value}"
+                    # replace value with tilda
+                    result_template = result_template.gsub(/\"\%{::#{transform_value}}\"/, '"~"')
+                    # identify that we have made at least one nil transformation 
+                    nil_transform_present = true
+                  end
+                end
+              rescue
+                warning "Unable to convert fact #{transform_value} with value #{all_facts[transform_value]} into #{transform_type}, conversion will be skipped"
+              end
             end
           end
-          result_template = eval(result_template)
         end
       end
 
+      # convert result_template back to hash
+      result_template = eval(result_template)
+
       # Write results
       File.open(output_file_path, 'w+') do |output_file|
         YAML.dump(result_template, output_file)
       end
+
+      # hack to get around the fact we have to pass tilda as quoted earlier
+      if nil_transform_present
+        compiled_hiera = File.read(output_file_path)
+        replaced_hiera = compiled_hiera.gsub('"~"', '~')
+        File.open(output_file_path, "w") {|new_hiera| new_hiera.puts replaced_hiera}
+      end
       
       # decrypt facts file because Puppet doesn't appear to be able to read encrypted facts
       require 'hiera/backend/eyaml/plugins'

data/puppet-runner.gemspec

@@ -4,7 +4,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
   spec.name          = "puppet-runner"
-  spec.version       = "0.0.20"
+  spec.version       = "0.0.21"
   spec.authors       = ["Martin Brehovsky", "Matthew Hope"]
   spec.email         = ["mbrehovsky@adaptavist.com"]
   spec.summary       = %q{Preprocessor for hiera config}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: puppet-runner
 version: !ruby/object:Gem::Version
-  version: 0.0.20
+  version: 0.0.21
 platform: ruby
 authors:
 - Martin Brehovsky
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-05 00:00:00.000000000 Z
+date: 2018-04-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler