kafo 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 172038c701a1e259a865a0315bb5d31a41797420
-  data.tar.gz: c526c08e0df34742fd03fdfc0cac5c99595eb13a
+  metadata.gz: 7361c36d1938a0cb6e0aef8e7ba478e23f8f4af0
+  data.tar.gz: 828ffbb4779539427b3b40b1cb81db900e08820c
 SHA512:
-  metadata.gz: 2a1c8d58ec05bba52eb9f190a9d6743d154b45ccc39dd33fc1aa830302c8a011e8255a4f1bce76365986b9a504c7318bbd0781015b12120fbd088f984d551adc
-  data.tar.gz: 51e160a1ee3329136b0c36ae7492384d39506b9a64db76b5e2dcd9269b4074f2a496f9b48b6b3a2a485b8da740b405fdb3c08bb11f361dd21bda8a3561aced6a
+  metadata.gz: 11cf281c119c97541a028f364681fc00f7d93b86cb53123cec742b6530412bdf417d5bfc0f9a433e1a0eaf4ecdda1f857752d913a8df40e3fb59cf4c4a9675de
+  data.tar.gz: 872579a93ddff382ce44d83973a6b0eb0971a5fd7adee80733b5b3284416246e00b17ec1907aa006557639e142f0484cac4cf4582b68df648986e02921b43e8e

data/README.md

@@ -168,6 +168,40 @@ class foreman (
 }
 ```
 
+You can separate your parameters into groups like this.
+
+Example - separating parameters into groups:
+```puppet
+# Manage your foreman server
+#
+# === Parameters:
+#
+# $foreman_url::            URL on which foreman is going to run
+#
+# === Advanced parameters:
+#
+# $foreman_port::           Foreman listens on this port
+#
+# ==== MySQL:
+#
+# $mysql_host::             MySQL server address
+```
+
+When you run the installer with ```--help``` argument it displays only
+parameters specified in ```=== Parameters:``` group. If you don't specify
+any group all parameters will be considered as Basic and will be displayed.
+
+If you run installer with ```--full-help``` you'll receive help of all
+parameters divided into groups. Note that only headers that include word
+parameters are considered as parameter groups. Other headers are ignored.
+Also note that you can nest parameter groups and the child has precedence.
+Help output does not take header level into account though.
+
+So in previous example, each parameter would be printed in one group even
+though MySQL is a child of Advanced parameter. All groups in help would be
+prefixed with second level (==). The first level is always a module to which
+particular parameter belongs.
+
 ## Argument types
 
 By default all arguments that are parsed from puppet are treated as string.
@@ -237,6 +271,125 @@ bin/foreman-installer --puppetmaster-environments=development --puppetmaster-env
 In interactive mode you'll be prompted for another value until you specify
 blank line.
 
+## Grouping in interactive mode
+
+If your module has too much parameters you may find useful grouping. Every
+block in your documentation (prefixed by header) forms a group. Unlike for
+help, all block are used in interactive mode. Suppose you have following
+example:
+
+```puppet
+# Testing class
+#
+# == Parameters:
+#
+# $one::    number one
+#
+# == Advanced parameters:
+#
+# $two::    number two
+#
+# === Advanced A:
+#
+# $two_a::  2_a
+#
+# === Advanced 2_b
+#
+# $two_b::  2_b
+#
+# == Extra parameters:
+#
+# $three::  number three
+```
+
+When you enter Testing class module in interactive mode you see parameters
+from Basic group and options to configure parameters which belongs to rest
+of groups on same level, in this case Advanced and Extra parameters. 
+
+```
+Module foreman configuration
+1. Enable/disable foreman module, current value: true
+2. Set one, current value: '1'
+3. Configure Advanced parameters
+4. Configure Extra parameters
+5. Back to main menu
+```
+
+When you enter Extra paramaters, you see only $three and option to get back 
+to parent. In Advanced you see $two and two more subgroups - Advanced A and 
+Advanced B. When you enter these subgroups, you see their parameters of 
+course. Nesting is unlimited. Also there's no naming rule. Just notice that 
+the main group must be called `Parameters` and it's parameters are always 
+displayed on first level of module configuration.
+
+```
+Group Extra parameters (of module foreman)
+1. Set two_b, current value: '2b'
+2. Back to parent menu
+```
+
+If there's no primary group a new one is created for you and it does not have
+any parameter. This mean when user enters module configuration he or she will 
+see only subgroups in menu (no parameters until a particular subgroup is entered). 
+If there is no group in documentation a new primary group is created and it 
+holds all module parameters (there are no subgroups in module configuration).
+
+## Conditional parameters in interactive mode
+
+You can also define conditions to parameter and their groups. These conditions
+are evaluated in interactive mode and based on the result they are displayed
+to the user. You can use this for example to hide mysql_* parameters when
+$db_type is not set 'mysql'. Let's look at following example
+
+```puppet
+# Testing class
+#
+# == Parameters:
+#
+# $use_db::                  use database?
+#                            type:boolean
+#
+# == Database parameters:    condition: $use_db
+#
+# $database_type::           mysql/sqlite
+#
+# === MySQL:                 condition: $database_type == 'mysql'
+#
+# $remote::                  use remote connection
+#                            type:boolean
+# $host                      server to connect to
+#                            condition: $remote
+# $socket                    server to connect to
+#                            condition: !$remote
+```
+
+Here you can see we defined several conditions on group and parameter level.
+You can write condition in ruby language. All dollar-prefixed words are be
+substituted by value of a particular puppet parameter.
+
+Note that conditions are combined using ```&&``` when you nest them. So these
+are facts based on example:
+
+* $database_type, $remote, $host, $socket are displayed only when $use_db is set to true
+* $remote, $host, $socket are displayed only when $database_type is set to 'mysql'
+* $host is displayed only if $remote is set to true, $socket is displayed otherwise
+
+Here's explanation how conditions are constructed
+
+```
+-----------------------------------------------------------------------------
+| parameter name | resulting condition                                      |
+-----------------------------------------------------------------------------
+| $use_db        | true                                                     |
+| $database_type | true && $use_db                                          |
+| $remote        | true && $use_db && $database_type == 'mysql'             |
+| $host          | true && $use_db && $database_type == 'mysql' && $remote  |
+| $socket        | true && $use_db && $database_type == 'mysql' && !$remote |
+-----------------------------------------------------------------------------
+```
+As already said you can use whatever ruby code, so you could leverage e.g.
+parentheses, &&, ||, !, and, or
+
 ## Custom modules and manifest names
 
 By default Kafo expects a common module structure. For example if you add
@@ -290,6 +443,45 @@ bin/foreman-installer --foreman-db-password=UNDEF
 
 It also works in interactive mode.
 
+## Hooks
+
+You may need to add new features to the installer. Kafo provides simple hook
+mechanism that allows you to run custom code just before and after the puppet
+is ran. Let's assume we want to add --reset-foreman-db option to our
+foreman-installer. We add following lines to generated installer script
+
+```ruby
+require 'kafo/hooking'
+
+# functions specific to foreman installer
+KafoConfigure.app_option '--reset-foreman-db',
+  :flag, 'Drop foreman database first? You will lose all data!', :default => false
+
+KafoConfigure.hooking.register_pre(:reset_db) do |kafo|
+  if kafo.config.app[:reset_foreman_db] && !kafo.config.app[:noop]
+    `which foreman-rake > /dev/null 2>&1`
+    if $?.success?
+      KafoConfigure.logger.info 'Dropping database!'
+      output = `foreman-rake db:drop 2>&1`
+      KafoConfigure.logger.debug output.to_s
+      unless $?.success?
+        KafoConfigure.logger.warn "Unable to drop DB, ignoring since it's not fatal, output was: '#{output}''"
+      end
+    else
+      KafoConfigure.logger.warn 'Foreman not installed yet, can not drop database!'
+    end
+  end
+end
+```
+
+Note that we can access other installer options using ```kafo.config.app```. Since ```kafo``` is
+KafoConfigure instance, you can even access puppet params values. Last but not least you have
+access to logger.
+
+You can register as many hooks as you need. They are executed in unspecified order. Every hook
+must have a unique name. In a very similar way you can register :post hooks that are executed
+right after puppet run is over.
+
 ## Custom paths
 
 Usually when you package your installer you want to load files from specific

data/bin/kafo-configure

@@ -1,9 +1,6 @@
 #!/usr/bin/env ruby
 
-# TODO cover with tests
-# TODO validations: "puppet master --compile <fqdn>" compiles a catalog for a given host but it uses the global manifest/modules rather than stdin.. but by specifying --manifestdir you could get it to read a site.pp that contains the "include kafo_configure"
-
 $LOAD_PATH.unshift File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'kafo'))
 require 'kafo_configure'
-result = KafoConfigure.run
+result = Kafo::KafoConfigure.run
 exit result.nil? ? 0 : result.exit_code

data/bin/kafo-export-params

@@ -1,4 +1,6 @@
 #!/usr/bin/env ruby
+require 'rubygems'
+require 'ostruct'
 require 'clamp'
 require 'logging'
 require 'kafo/string_helper'
@@ -8,97 +10,119 @@ require 'configuration'
 
 KafoConfigure = OpenStruct.new
 
-class KafoExportParams < Clamp::Command
-  TYPES = %w(md html)
+module Kafo
+  class KafoExportParams < Clamp::Command
+    TYPES = %w(md html asciidoc)
 
-  option ['-c', '--config'], 'FILE', 'Config file for which should we generate params',
-         :required => true
+    option ['-c', '--config'], 'FILE', 'Config file for which should we generate params',
+           :required => true
 
-  option ['-f', '--format'], 'FORMAT',
-         'Config file for which should we generate params', :default => 'md' do |format|
-    format = format.downcase
-    raise ArgumentError unless TYPES.include?(format)
-    format
-  end
+    option ['-f', '--format'], 'FORMAT',
+           'Config file for which should we generate params', :default => 'md' do |format|
+      format = format.downcase
+      raise ArgumentError unless TYPES.include?(format)
+      format
+    end
 
-  def execute
-    c = Configuration.new(config, false)
-    KafoConfigure.config = c
-    KafoConfigure.root_dir = File.expand_path(c.app[:installer_dir])
+    def execute
+      c                      = Configuration.new(config, false)
+      KafoConfigure.config   = c
+      KafoConfigure.root_dir = File.expand_path(c.app[:installer_dir])
 
-    exporter = self.class.const_get(format.capitalize).new(c)
-    exporter.print_out
-  end
+      exporter = self.class.const_get(format.capitalize).new(c)
+      exporter.print_out
+    end
 
-  class Html
-    include StringHelper
+    class Html
+      include StringHelper
 
-    def initialize(config)
-      @config = config
-    end
+      def initialize(config)
+        @config = config
+      end
 
-    def print_out
-      puts '<div id="installer-options">'
-      puts '  <table class="table table-bordered table-condensed">'
-      header
-      puts '    <tbody>'
-
-      @config.modules.each do |mod|
-        mod.params.each do |param|
-          puts '      <tr>'
-          puts "        <td>#{parametrize(param)}</td>"
-          puts "        <td>#{param.doc.join(' ')}</td>"
-          puts '      </tr>'
+      def print_out
+        puts '<div id="installer-options">'
+        puts '  <table class="table table-bordered table-condensed">'
+        header
+        puts '    <tbody>'
+
+        @config.modules.sort.each do |mod|
+          mod.params.sort.each do |param|
+            puts '      <tr>'
+            puts "        <td style='white-space:nowrap'>#{parametrize(param)}</td>"
+            puts "        <td>#{param.doc.join(' ')}</td>"
+            puts '      </tr>'
+          end
         end
+
+        puts '    </tbody>'
+        puts '  </table>'
+        puts '</div>'
       end
 
-      puts '    </tbody>'
-      puts '  </table>'
-      puts '</div>'
+      private
+
+      def header
+        puts '    <thead>'
+        puts '      <tr>'
+        puts '        <th>Option</th>'
+        puts '        <th>Description</th>'
+        puts '      </tr>'
+        puts '    </thead>'
+      end
     end
 
-    private
+    class Asciidoc
+      include StringHelper
+
+      def initialize(config)
+        @config = config
+      end
 
-    def header
-      puts '    <thead>'
-      puts '      <tr>'
-      puts '        <th>Option</th>'
-      puts '        <th>Description</th>'
-      puts '      </tr>'
-      puts '    </thead>'
+      def print_out
+        @config.modules.sort.each do |mod|
+          puts "Parameters for '#{mod}'\n:"
+          mod.params.sort.each do |param|
+            puts "#{parametrize(param)}::"
+            puts param.doc.join("\n")
+            puts "\n"
+          end
+          puts "\n"
+        end
+      end
     end
-  end
 
-  class Md
-    include StringHelper
+    class Md
+      include StringHelper
 
-    def initialize(config)
-      @config = config
-      @max = max_description_length
-    end
+      def initialize(config)
+        @config = config
+        @max    = max_description_length
+      end
 
-    def print_out
-      puts "| #{('Parameter name').ljust(40)} | #{'Description'.ljust(@max)} |"
-      puts "| #{'-'*40} | #{'-' * @max} |"
-      @config.modules.each do |mod|
-        mod.params.each do |param|
-          puts "| #{parametrize(param).ljust(40)} | #{param.doc.join(' ').ljust(@max)} |"
+      def print_out
+        puts "| #{('Parameter name').ljust(40)} | #{'Description'.ljust(@max)} |"
+        puts "| #{'-'*40} | #{'-' * @max} |"
+        @config.modules.sort.each do |mod|
+          mod.params.sort.each do |param|
+            puts "| #{parametrize(param).ljust(40)} | #{param.doc.join(' ').ljust(@max)} |"
+          end
         end
       end
-    end
 
-    private
+      private
 
-    def header
-      @header ||= "| #{'-'*40} | #{'-' * @max} |"
-    end
+      def header
+        @header ||= "| #{'-'*40} | #{'-' * @max} |"
+      end
 
-    def max_description_length
-      doc_lengths = @config.modules.map { |mod| mod.params.map { |param| param.doc.join(' ').length } }.flatten
-      doc_lengths << 52
-      doc_lengths.max
+      def max_description_length
+        doc_lengths = @config.modules.map { |mod| mod.params.map { |param| param.doc.join(' ').length } }.flatten
+        doc_lengths << 52
+        doc_lengths.max
+      end
     end
   end
 end
 
-KafoExportParams.run
+Kafo::KafoExportParams.run

data/bin/kafofy

@@ -24,7 +24,7 @@ if ARGV.size > 0
 require 'rubygems'
 require 'kafo'
 CONFIG_FILE = "/etc/#{name}/#{name}.yaml"
-result = KafoConfigure.run
+result = Kafo::KafoConfigure.run
 exit result.nil? ? 0 : result.exit_code
 EOS
   File.open(script_name, 'w') { |file| file.write(content) }

data/lib/kafo/condition.rb

@@ -0,0 +1,25 @@
+# encoding: UTF-8
+module Kafo
+  class Condition
+    VARIABLE_RE = /(\$\w+)/
+
+    def initialize(expression, context = [])
+      @expression = expression
+      @context = context
+    end
+
+    def evaluate
+      !!eval(substitute(@expression))
+    end
+
+    private
+
+    def substitute(expression)
+      expression.gsub(VARIABLE_RE) do |variable|
+        param = @context.detect { |p| p.name == $1.tr('$','') }
+        raise ConditionError, "can't substitute #{$1}, unknown parameter with such name" if param.nil?
+        variable.gsub!($1, param.condition_value)
+      end
+    end
+  end
+end