kafo 0.6.12 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3d75a2516f7aad0cf5d07cd155116e94492bf682
-  data.tar.gz: 273e49a2e52be9eff3dd1ab63e75db07b8d69dd9
+  metadata.gz: 2b2cd9bfcb84fbe243ae9497b70a2507e6f22a97
+  data.tar.gz: 3754932d4a739e84c8bac944de846275c49d0cf8
 SHA512:
-  metadata.gz: 83eaf3dfdaa56ec533ce683bc1b818a94e6c12e808f8d44969ffb1f4844764dd6f867dd4096428fc96081cb3136f0d287d0878fb42270464ecddc0ad7ef3442b
-  data.tar.gz: fa3a8432b961d920bf2fd4a11f6dfc6bd87c7e9283d304d0d96c1c17885ed7d2f492ca666394ba39d7a6fa91f681ee2cee850a258764108da59848d9e3c68ddd
+  metadata.gz: e101e1d508b08dfe5df3fe967f719d4fa6a7250633e59e6a9cabefb7c8e32c7bb3ad4229d32f4c20aa5de521df6089295ed7f556c294666a0e5125b3483f41ad
+  data.tar.gz: d06b2bea38b080f2a628720120af2f9e5d9c1bb343c14ff05cabe887c911b6aba8555e4eb675edfca569bc60a302d07a005a6015a3ecd9e6916cee0168e13dde

data/README.md

@@ -16,10 +16,13 @@ your puppet infrastructure (e.g. install it to your clients) or you want to inst
 it in order to create a puppet infrastructure itself (e.g. foreman or
 foreman-proxy).
 
-With kafo you can reuse your puppet modules for creating an installer. 
+With kafo you can reuse your puppet modules for creating an installer.
 Even better: After the installation you can easily modify your configuration.
 All using the very same puppet modules.
 
+With your installer you can also provide multiple configuration files defining
+different installation scenarios.
+
 ## What does it do, how does it work?
 
 Kafo reads a config file to find out which modules it should use. Then it
@@ -62,35 +65,47 @@ Now we run ```kafofy``` script which will prepare the directory structure and
 optionally create a bin script according to the first parameter.
 
 ```bash
-kafofy -n foreman-installer
+kafofy -n foreman-installer -s foreman
 ```
 
 You can see that it created a modules directory where your puppet modules
-should live. It also created config and bin directories. If you specify the
-argument ```--name``` (or -n for short, foreman-installer in this case) a script in 
-the "bin" directory with this name will be created.
+should live. It also created config and bin directories and the default installation
+scenario config file. If you specify the argument ```--name``` (or -n for short,
+foreman-installer in this case) a script in the "bin" directory with this name will be created.
 
 It's the script you can use to run the installer. If you did not specify any
 arguments you can run your installer by `kafo-configure` which is the default.
 All configuration related files are to be found in the config directory.
 
-You can supply custom locations for you configuration- and answer- files using
-options:
+You can supply custom location for your scenario configuration and answer files
+and change configuration and answer files names using options:
 ```
 kafofy --help
 Usage: kafofy [options]
-    -a, --answer_file FILE           location of the answer file
-    -c, --config_file FILE           location of the configuration file
-    -n, --name        NAME           your installer name
+    -c, --config_dir DIR            location of the scenarios configuration directory [./config/installer-scenarios.d/]
+    -s, --scenario SCENARIO          scenario file name (without extension) [default]
+    -a, --answer_file ANSWERS        answer file file name (without extension) [default-answers]
+    -n, --name NAME                  installer name [kafo-configure]
 ```
 
-The configuration file will be created by a default template. It's the configuration
+The scenario configuration file will be created by a default template. It's the configuration
 of your installer (so you can setup the log level, path to puppet modules etc).
 On the other hand, the answer file must be created manually. Answer files define
 which modules should be used and hold all values for the puppet class parameters.
 
+To add another installation scenario just run kafofy again:
+```bash
+kafofy -n foreman-installer -s foreman-proxy
+```
+it will create new configuration template for you. You can check available scenarios with:
+```bash
+$ bin/foreman-installer --list-scenarios
+Available scenarios
+  foreman-proxy (use: --scenario foreman-proxy)
+  foreman (use: --scenario foreman)
+```
 
-So for example to install foreman you want to
+Let's see for example how to install foreman:
 ```bash
 cd foreman-installer/modules
 git clone https://github.com/theforeman/puppet-foreman/ foreman
@@ -99,7 +114,7 @@ You must also download any dependant modules.
 Then you need to tell kafo it's going to use the foreman module.
 ```bash
 cd ..
-echo "foreman: true" > config/answers.yaml
+echo "foreman: true" > config/installer-scenarios.d/foreman-answers.yaml
 ```
 
 Alternatively you can use the librarian-puppet project to manage all dependencies for you.
@@ -107,8 +122,9 @@ You just create a Puppetfile and call librarian to install your modules. See
 https://github.com/rodjek/librarian-puppet for more details.
 
 When you have your modules in-place, fire the installer with -h as argument
+and specify the foreman scenario to let installer find the right modules
 ```bash
-bin/foreman-installer -h
+bin/foreman-installer -S foreman -h
 ```
 
 This will show you all the possible arguments you can pass to kafo. Note that underscored
@@ -117,9 +133,10 @@ also see a documentation extracted from the foreman puppet module and a default
 value.
 
 Now run it without the -h argument. It will print you the puppet apply command
-to execute. This will be automatized later. Look at config/answers.yaml, it
-was populated with default values. To change those options you can use
-arguments like this
+to execute. This will be automatized later. Once the installer is run the scenario
+is remembered and it is not necessary to specify it again.
+Look at config/answers.yaml, it was populated with default values.
+To change those options you can use arguments like this
 
 ```bash
 bin/foreman-installer --foreman-enc=false --foreman-db-type=sqlite
@@ -131,8 +148,8 @@ or you can run it in interactive mode
 bin/foreman-installer --interactive
 ```
 
-Also every change made to the config/answers.yaml persists and becomes the new default
-value for the next run.
+Also every change made to the `config/installer-scenarios.d/foreman-answers.yaml` persists
+and becomes the new default value for the next run.
 
 As you may have noticed there are several ways how to specify arguments. Here's the list:
 (the lower the item is in this list the higher precedence it has):
@@ -144,14 +161,14 @@ As you may have noticed there are several ways how to specify arguments. Here's
 ## How do I report bugs or contribute?
 
 You can find our redmine issue tracker [here](http://projects.theforeman.org/projects/kafo),
-you can use your github account for logging in. When reporting new issues please 
+you can use your github account for logging in. When reporting new issues please
 don't forget to specify your:
   * puppet version
   * installation options (GEM/RPM/DEB)
   * error trace (if any) or log with debug level
   * reproducing steps
 
-Since Kafo is a side project of Foreman you can use its IRC channels to 
+Since Kafo is a side project of Foreman you can use its IRC channels to
 contact us on freenode. #theforeman is the channel for generic discussions
 and #theforeman-dev is reserved only for technical topics. Likewise you can use the Foreman
 mailing lists on googlegroups. For more information see [this page](http://theforeman.org/support.html)
@@ -181,6 +198,123 @@ can disable this behavior in config/kafo.yaml. Just enable the following option
 ```yaml
 :no_prefix: true
 ```
+## Scenarios
+
+With your installer you can provide multiple configuration files aka. scenarios.
+Every scenario has its own answer file to store the scenario settings.
+The files are kept in `installer-scenarios.d/` directory.
+
+### Using scenarios
+
+To list scenarios available on your system
+```bash
+foreman-installer --list-scenarios
+```
+
+The installer needs to know the configuration even for such a basic operation
+as printing help is because it contains basic settings and defines where
+to look for module parameters. There are multiple ways how the installer can select the scenario:
+  * from a command line argument `-S` or `--scenario`
+```bash
+  foreman-installer --scenario foreman -h
+   ...
+```
+  * by user selection in interractive mode (`-i` or `--interractive`)
+```bash
+  foreman-installer -i
+
+  Select installation scenario
+
+  Please select one of the pre-set installation scenarios. You can customize your installtion later during the installtion.
+
+  Available actions:
+  1. Foreman: Basic and most generic installation of Foreman
+  2. Foreman Proxy: Install Foreman proxy without Foreman
+  3. Cancel Installation
+  Your choice:
+```
+  * automatically if there is only one scenario available
+  * automatically if installer was ran already with scenario selected
+
+### Re-installing with different scenario
+
+Lets assume you have already completed installation with one scenario (e.g. smart-proxy).
+Now you want to reinstall or upgrade with different scenario (e.g. foreman). This is tricky
+situation and may end with unpredictable results so you should double check
+if the scenario and the puppet modules used in it support such kind of change.
+
+Installer tries to prevent unintentional change of a scenario and interrupts when such situation is detected:
+```bash
+  foreman-installer -S foreman-installer
+  ERROR: You are trying to replace existing installation with different scenario. This may lead to unpredictable states. Use --force to override. You can use --compare-scenarios to see the differences
+```
+
+To avoid losing some configuration values installer can detect differences between answer files of the two scenarios.
+To display them use either interactive mode (`-i`) or `--compare-scenarios` flag:
+```bash
+  foreman-installer --compare-scenarios --scenario foreman
+  Scenarios are being compared, that may take a while...
+
+  Values from previous installation that will be added by installer:
+    foreman_proxy::http_port: 8000 -> 8080
+
+  Values from previous installation that will be lost by scenario change:
+    foreman_proxy::plugin::abrt::enabled: true
+    ...
+```
+
+It may take some time as the installer has to evaluate default values for both scenarios. As a result it prints two lists.
+ - __Values from previous installation that will be added by installer:__ - in this list are options present in both scenarios but having different default values.
+   The only item from the example says that the default value for the new scenario is '8000' while the value for currently intalled scenario is '8080'.
+   When the new scenario is used the installer tries to keep the customized values from current installation and thus will use the `8080` value
+ - __Values from previous installation that will be lost by scenario change:__ - this list contains options that are part of current installation
+   and are missing from the new scenario. Most of the items are options from puppet modules that are disabled in the new scenario by default but were enabled
+   in the old one.
+
+If you are sure you want to proceed use `--force` to run the installation. Installer will replace
+the default values with values from the previous installation where possible as was indicated in the `--compare-scenario` output.
+
+### Adding scenario
+
+You can add new scenario using kafofy as it was explained earlier or by creating
+config and answer file in the `installer-scenarios.d/` directory.
+[Template](https://github.com/theforeman/kafo/blob/master/config/kafo.yaml.example)
+provided by Kafo can be used and customized to satisfy your needs
+```bash
+  cp `gem content kafo|grep "kafo.yaml.example"` <config>/installer-scenarios.d/new-scenario.yaml
+  touch <config>/installer-scenarios.d/new-scenario-answers.yaml
+```
+
+### Scenario as an installer plugin
+
+Scenarios were designed to make it possible to package them separately as optional installer extension.  
+Config files are located in separate directory which makes packaging of additional scenarios easy.
+Configuration of paths to modules, checks and hooks accepts multiple directories
+so it is possible to bundle your scenario with additional modules, hooks and checks.
+
+### Updating scenarios
+
+As your project grows you may need to change your installer modules or add new ones. To make upgrades of existing installations easier
+Kafo has support for scenario migrations. Migrations are ruby scripts similar to hooks and are located
+in `<config>/installer-scenarios.d/your-scenario.migrations/` so each scenario has its own set of independent migrations.
+During its initialization the installer checks for migrations that were not applied yet. It happens exactly between execution of `pre-migrations` and `boot` hooks.
+The installer stores names of applied migrations in `<config>/installer-scenarios.d/your-scenario.migrations/.applied` to avoid runnig the migrations multiple times.  
+It is recommended to prefix the migration names with `date +%y%m%d%H%M%S` to avoid migration ordering issues.
+
+In a migration you can modify the scenario configuration as well as the answer file. The changed configs are stored immediately after all the migrations were applied.
+Note that `--noop` and `--dont-save-answers` has no effect on migrations.
+
+Sample migration adding new module could look like as follows:
+
+```bash
+  cat <<EOF > "/etc/foreman/installer-scenarios.d/foreman-installer.migrations/`date +%y%m%d%H%M%S`-gutterball.rb"
+  scenario[:mapping]['katello::plugin::gutterball'] = {
+      :dir_name => 'katello',
+      :manifest_name => 'plugin/gutterball'
+  }
+  answers['katello::plugin::gutterball'] = true
+  EOF
+```
 
 ## Documentation
 
@@ -270,7 +404,7 @@ Kafo supports password arguments. It's adding some level of protection for your
 passwords. Usually people generate random strings for passwords. However all
 values are stored in config/answers.yaml which may introduce a security risk.
 
-If this is something to consider for you, you can use the password type (see 
+If this is something to consider for you, you can use the password type (see
 Argument types for more info how to define parameter type). It will
 generate a secure (random) password with a length of 32 chars and encrypts
 it using AES 256 in CBC mode. It uses a passphrase that is stored in
@@ -365,7 +499,7 @@ example:
 
 When you enter the Testing class module in interactive mode you can see parameters
 from the Basic group and options to configure parameters which belong to the rest
-of groups on same level, in this case Advanced and Extra parameters. 
+of groups on same level, in this case Advanced and Extra parameters.
 
 ```
 Module foreman configuration
@@ -376,11 +510,11 @@ Module foreman configuration
 5. Back to main menu
 ```
 
-When you enter Extra parameters, you see only $three and an option to get back 
-to the parent. In Advanced you can see $two and two more subgroups - Advanced A and 
+When you enter Extra parameters, you see only $three and an option to get back
+to the parent. In Advanced you can see $two and two more subgroups - Advanced A and
 Advanced B. When you enter these subgroups, you can again see their parameters.
-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 
+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 the module configuration.
 
 ```
@@ -390,9 +524,9 @@ Group Extra parameters (of module foreman)
 ```
 
 If there's no primary group a new one is created for you and it does not have
-any parameter. This means when a user enters the module configuration he or she will 
-see only subgroups in the menu (no parameters until a particular subgroup is entered). 
-If there is no group in the documentation a new primary group is created and it 
+any parameter. This means when a user enters the module configuration he or she will
+see only subgroups in the menu (no parameters until a particular subgroup is entered).
+If there is no group in the documentation a new primary group is created and it
 holds all module parameters (there are no subgroups in the module configuration).
 
 ## Conditional parameters in interactive mode
@@ -518,6 +652,7 @@ You may need to add new features to the installer. Kafo provides a simple hook
 mechanism that allows you to run custom code at 6 different occasions.
 We currently support the following hooks.
 
+* pre_migrations - just after kafo reads its configuration - useful for config file updates. Only in this stage it is posible to request config reload (`Kafo.request_config_reload`) to get in our changes
 * boot - before kafo is ready to work, useful for adding new installer arguments, but logger won't work yet
 * init - just after hooking is initialized and kafo is configured, parameters have no values yet
 * pre_values - just before value from CLI is set to parameters (they already have default values)
@@ -571,7 +706,7 @@ Last but not least you have access to logger. For more details, see
 If you don't want to modify your installer script you can place your hooks into the
 hooks directory. By default the hooks dir is searched for ruby files in subdirectories
 based on hook type. For example pre hooks are searched for in ```$installer_dir/hooks/pre/*.rb```
-The hooks from the previous example would look like this. The only change to the code is 
+The hooks from the previous example would look like this. The only change to the code is
 that you don't explicitely register hooks, it's done automatically for you.
 
 ```ruby
@@ -606,20 +741,20 @@ in the installer configuration file.
 - /my/plugin/hooks
 ```
 
-You can register as many hooks as you need. The order of execution for a particular hook type 
+You can register as many hooks as you need. The order of execution for a particular hook type
 is based on hook file name.
 
 If you want to cancel the installation you can use the ```exit``` method and specify an exit code.
 
 ## Colors
 
-Everybody loves colors right? In case you don't you can disable them using the ```--no-colors``` 
+Everybody loves colors right? In case you don't you can disable them using the ```--no-colors```
 argument or disallow them in the installer config file (search for ```colors:``` key and set
 it to false). If you don't touch this setting, kafo will try to detect whether colors
 are supported and will enable/disable it accordingly.
 
 Kafo supports two sets of colors, one for terminals with bright and one for dark backround.
-You can specify your installer default scheme in installer config file (```color_of_background``` 
+You can specify your installer default scheme in installer config file (```color_of_background```
 key). Alternatively the user can override this default setting with the ```--color-of-background``` argument.
 Possible values are ```dark``` and ```bright```.
 
@@ -646,7 +781,7 @@ end
 As you can see you can use HighLine helpers (e.g. say) with colors. Look at kafo/color_schema.rb for
 supported color identifiers. We can guarantee that there will always be at least :good, :bad, :info.
 
-Methods like module_enabled? and get_param are just helpers defined in the same file. If you find 
+Methods like module_enabled? and get_param are just helpers defined in the same file. If you find
 them useful, here's the definition
 
 ```ruby
@@ -668,13 +803,16 @@ paths. In order to do that you can use following configuration options:
 
 * :answer_file: /etc/kafo/kafo.yaml
 * :installer_dir: /usr/share/kafo/
-* :modules_dir: /usr/share/foreman-installer/modules
+* :module_dirs: /usr/share/foreman-installer/modules
+* :hook_dirs: /user/share/foreman-installer/hooks
+* :check_dirs: /user/share/foreman-installer/checks
 * :kafo_modules_dir: /usr/share/kafo/modules
 
-Answer file is obvious. The "installer_dir" is the place where your installer is 
-located. E.g. system checks will be loaded from here (under checks 
-subdirectory). You can optionally change foreman-installer modules dir
-using modules_dir option.
+Answer file is obvious. The "installer_dir" is the place where your installer is
+located. E.g. system checks will be loaded from here (under checks
+subdirectory) if not set elsewhere by `check_dirs`. You can optionally change foreman-installer modules dir
+using `module_dirs` option and hooks dir using `hook_dirs` option. `module_dirs`, `hook_dirs` and `check_dirs`
+can hold multiple directories where to look for the resources.
 
 On debian systems you may want to specify kafo modules dir
 independent on your installer location. If you specify this option kafo's
@@ -737,7 +875,7 @@ but you want the logs to be readable by specific users.
 When you want to make sure that a user has a certain software installed or has the
 right version you can write a simple script and put it into the checks directory.
 All files found there will be executed and if any of these exits with an non-zero
-exit code, kafo won't execute puppet but only print an error message 
+exit code, kafo won't execute puppet but only print an error message
 `Your system does not meet configuration criteria.`
 
 Everything on STDOUT and STDERR is logged in error level.
@@ -773,6 +911,8 @@ Other exit codes that can be returned:
 * '23' means that you have no answer file
 * '24' means that your answer file asks for puppet module that you did not provide
 * '25' means that kafo could not get default values from puppet
+* '26' means that kafo could not find the specified scenario
+* '27' means that kafo found previous installation that has different scenario than is the specified scenario  
 * '130' user interrupt (^C)
 
 ## Running Puppet Profiling

data/bin/kafo-export-params

@@ -33,7 +33,7 @@ module Kafo
       c                         = Configuration.new(config, false)
       KafoConfigure.config      = c
       KafoConfigure.root_dir    = File.expand_path(c.app[:installer_dir])
-      KafoConfigure.modules_dir = File.expand_path(c.app[:modules_dir])
+      KafoConfigure.module_dirs = File.expand_path(c.app[:module_dirs])
       KafoConfigure.logger      = Logger.new(STDOUT)
 
       exporter = self.class.const_get(format.capitalize).new(c)

data/bin/kafofy

@@ -12,25 +12,30 @@ require 'kafo/configuration'
 options = {}
 OptionParser.new do |opts|
   opts.banner = "Usage: kafofy"
-  options[:answer_file] = './config/answers.yaml'
-  opts.on("-a", "--answer_file FILE", "location of the answer file") do |answer_file|
-    options[:answer_file] = answer_file
+  options[:config_dir] = './config/installer-scenarios.d/'
+  opts.on("-c", "--config_dir DIR", "location of the scenarios configuration directory [./config/installer-scenarios.d/]") do |config_dir|
+    options[:config_dir] = config_dir
   end
-  opts.on("-c", "--config_file FILE", "location of the configuration file") do |config_file|
-    options[:config_file] = config_file
+  opts.on("-s", "--scenario SCENARIO", "scenario file name (without extension) [default]") do |scenario|
+    options[:scenario] = scenario
   end
-  opts.on("-n", "--name NAME", "installer name") do |name|
+  opts.on("-a", "--answer_file ANSWERS", "answer file file name (without extension) [default-answers]") do |answer_file|
+    options[:answer_file] = File.join(options[:config_dir], answer_file + '.yaml')
+  end
+  opts.on("-n", "--name NAME", "installer name [kafo-configure]") do |name|
     options[:name] = name
   end
 end.parse!
 
 config = Kafo::Configuration::DEFAULT
-options[:answer_file] ||= config[:answer_file]
+options[:scenario] ||= 'default'
+options[:answer_file] ||= File.join(options[:config_dir],  options[:scenario] + '-answers.yaml')
 options[:name] ||= "kafo-configure"
-options[:config_file] ||= "./config/#{options[:name]}.yaml"
+options[:config_file] ||= File.join(options[:config_dir], options[:scenario] + '.yaml')
 
 # Create directory structure
-%w(bin config modules hooks).each do |dir|
+dirs = %w(bin config modules hooks) << options[:config_dir]
+dirs.each do |dir|
   FileUtils.mkdir_p dir
 end
 
@@ -41,7 +46,7 @@ src = File.expand_path(File.join(File.dirname(__FILE__), '..'))
 end
 
 # Create default config file
-puts "using #{options[:config_file]} as default config file"
+puts "creating #{options[:config_file]} as a default scenario file"
 if !File.exists?(options[:config_file])
   puts "... creating config file #{options[:config_file]}"
   FileUtils.touch options[:config_file]
@@ -49,23 +54,35 @@ if !File.exists?(options[:config_file])
   FileUtils.cp('config/kafo.yaml.example', options[:config_file])
   if options[:answer_file]
     `sed -i 's/^# :answer_file.*$/:answer_file: #{options[:answer_file].gsub('/', '\/')}/' #{options[:config_file]}`
-    `sed -i 's/^# :name.*$/:name: #{options[:name]}/' #{options[:config_file]}`
+    `sed -i 's/^# :name.*$/:name: #{options[:scenario]}/' #{options[:config_file]}`
   end
 end
 
-# Installer script 
+# Installer script
 script_name = "bin/#{options[:name]}"
 puts "... creating #{script_name}"
-content = <<EOS
+if !File.exists?(script_name)
+  content = <<EOS
 #!/usr/bin/env ruby
 require 'rubygems'
-CONFIG_FILE = '#{options[:config_file]}'
 require 'kafo'
-result = Kafo::KafoConfigure.run
-exit result.nil? ? 0 : result.exit_code
+
+# where to find scenarios
+CONFIG_DIR = '#{options[:config_dir]}'
+
+# Run the install
+@result = Kafo::KafoConfigure.run
+
+# handle exit code when help was invoked or installer ended with '2' (success in puppet)
+if @result.nil? || (!@result.config.app[:detailed_exitcodes] && @result.exit_code == 2)
+  exit(0)
+else
+  exit(@result.exit_code)
+end
 EOS
-File.open(script_name, 'w') { |file| file.write(content) }
-FileUtils.chmod 0755, script_name
+  File.open(script_name, 'w') { |file| file.write(content) }
+  FileUtils.chmod 0755, script_name
+end
 
 puts "Your directory was kafofied"
 
@@ -73,3 +90,4 @@ puts "Now you should:"
 puts "  1. upload your puppet modules to modules directory (you can use librarian-puppet project)"
 puts "  2. create default #{options[:answer_file]} or modify #{options[:config_file]} to load another answer file"
 puts "  3. run #{script_name} to install your modules"
+puts "  Note: You can add more scenarios by running kafofy multiple times"