Merge 03537ca into 3a125d8

README.md

@@ -9,34 +9,65 @@
 [![Issue Count](https://codeclimate.com/github/yast/yast-configuration-management/badges/issue_count.svg)](
   https://codeclimate.com/github/yast/yast-configuration-management/issues)
 
-This module allows AutoYaST2 to delegate part of the configuration to a
-[Software Configuration Management](https://en.wikipedia.org/wiki/Software_configuration_management)
-system. Salt and Puppet are supported.
+This module allows AutoYaST2 and Firstboot to delegate part of the configuration to a [Software
+Configuration Management](https://en.wikipedia.org/wiki/Software_configuration_management) system.
+Salt and Puppet are supported.
 
-## How it works
+## How It Works
 
-The module will take care of:
+Basically, this module takes care of setting up the selected configuration management system (Salt
+or Puppet) and running it in order to update the system's configuration. It supports working on
+client/master or masterless modes and it can be combined with AutoYaST and Yast Firstboot. Even a
+standalone mode is available.
 
-* Installing needed packages.
-* Retrieving authentication keys.
-* Updating configuration if needed.
-* Applying configuration during AutoYaST 2nd stage.
+Depending on the module's configuration, it will take care of:
 
-## Example
+* Installing the required packages.
+* Retrieving authentication keys (when running in client/server mode).
+* Fetching any additional data which may be needed (Salt states, pillars or formulas or Puppet
+  modules).
+* Updating Salt/Puppet configuration and running them.
 
-### Client/master
+## Supported Systems
+
+### Salt
+
+In this case, `salt-minion` package will be installed. If a `master` is set, `/etc/salt/minion` will
+be updated. Finally, `salt-call` will be used to apply the configuration.
+
+### Puppet
+
+In this case, `puppet` package will be installed. If a `master` is set, `/etc/puppet/puppet.conf`
+will be updated. Finally, `puppet agent` will be used to apply the configuration.
+
+## Module Configuration
+
+YaST Configuration Management needs some configuration in order to know how to proceed. The snippets
+below can be embedded into an AutoYaST profile or in the Firstboot configuration
+(`/etc/YaST2/firstboot.xml`).
+
+### Client/Server
+
+When running in client/server mode, the configuration management system will need to connect to a
+master server. For authentication, the client must use a pair of public/private keys which can be
+stored on a server, a hard drive or even on an USB stick. Alternatively, the user might prefer to
+let the client generate a new pair of keys and authorize them on the fly.
 
 ```xml
 <configuration_management>
-  <type>salt</type> <!-- you can use "puppet" -->
+  <type>salt</type> <!-- you can use "puppet" too -->
   <master>my-salt-server.example.net</master>
   <auth_attempts config:type="integer">5</auth_attempts>
   <auth_time_out config:type="integer">10</auth_time_out>
   <keys_url>usb:/</keys_url> <!-- you can use HTTP, FTP... -->
 </configuration_management>
 ```
 
-### Masterless mode
+### Masterless Mode
+
+The good thing about running on masterless mode is that you do not need to set up a master server.
+In that case, you can instruct YaST Configuration Management to retrieve the required data from
+elsewhere.
 
 ```xml
 <configuration_management>
@@ -46,21 +77,81 @@ The module will take care of:
 </configuration_management>
 ```
 
-## Supported systems
+## Firstboot Integration
 
-### Salt
+The Firstboot module offers integration with YaST Configuration Management through a client called
+`firstboot_configuration_management`. So in order to use this module in firstboot you need to write
+a `<configuration_management/>` section containing the configuration options and add the client to
+the required workflow. In the example below, only the relevant parts are shown:
 
-In this case, `salt-minion` package will be installed. If a `master`
-is set in the AutoYaST profile, `/etc/salt/minion` will be
-updated. Finally, `salt-call` will be used to apply the configuration.
+**WARNING: Only Salt is supported by Firstboot.**
 
-### Puppet
-
-In this case, `puppet` package will be installed. If a `master`
-is set in the AutoYaST profile, `/etc/puppet/puppet.conf` will be
-updated. Finally, `puppet agent` will be used to apply the configuration.
-
-## Advanced options
+```xml
+<?xml version="1.0"?>
+<productDefines xmlns="http://www.suse.com/1.0/yast2ns" 
+  xmlns:config="http://www.suse.com/1.0/configns">
+
+  <configuration_management>
+      <type>salt</type>
+      <!-- Default Salt Formulas root directories -->
+      <formulas_roots config:type="list">
+        <formula_root>/usr/share/susemanager/formulas/metadata</formula_root>
+        <formula_root>/srv/formula_metadata</formula_root>
+      </formulas_roots>
+      <!-- Default Salt Formulas state directories -->
+      <states_roots config:type="list">
+        <state_root>/usr/share/susemanager/formulas/states</state_root>
+      </states_roots>
+      <!-- Default Salt Formulas pillar data directory  -->
+      <pillar_root>/srv/susemanager/formula_data</pillar_root>
+  </configuration_management>
+
+  <!-- more stuff -->
+
+  <workflows  config:type="list">
+    <workflow>
+      <stage>firstboot</stage>
+      <label>Configuration</label>
+      <mode>installation</mode>
+      <modules  config:type="list">
+        <!-- other modules -->
+        <module>
+          <label>Finish Setup</label>
+          <name>firstboot_configuration_management</name>
+        </module>
+      </modules>
+      <!-- and more modules -->
+    </workflow>
+  </workflows>
+</productDefines>
+```
 
-To set up advanced options you can use the
-[AutoYaST file element](https://www.suse.com/documentation/sles-12/singlehtml/book_autoyast/book_autoyast.html#createprofile.completeconf).
+## Salt Formulas Forms Support
+
+**WARNING: Under development.**
+
+The support for Salt Formulas Forms is still under development. Currently, the module is able to
+render the corresponding UI to get user's input, store the information and run Salt accordingly.
+However, some stuff is still missing:
+
+* Some basic widgets are not implemented yet (passwords, numbers, etc.).
+* Support for nested collections, although simple collections are already working.
+* Better integration with Firstboot (supporting stuff like going back or running Salt at the end).
+* Good documentation.
+
+## Options Reference
+
+Name            | Type         | Mode       | Description
+---             | ---          | ---        | ---
+type            | string       | all        | Configuration Management System (`salt` or `puppet`)
+master          | string       | client     | Master server
+auth_attempts   | integer      | client     | Number of attempts when connecting to the master server
+auth_time_out   | integer      | client     | Time between attempts to connect to the master server
+enable_services | boolean      | client     | Enable the configuration management service at the end
+formulas_roots  | list(string) | all        | List of directories to search for Salt formulas
+states_roots    | list(string) | all        | List of directories to search for Salt states
+pillar_root     | string       | all        | Path to write the Salt Pillar content
+pillar_url      | string       | masterless | URL to get Pillar content from
+keys_url        | string       | masterless | URL to get authentication keys from
+states_url      | string       | masterless | URL to get the Salt states from
+enabled_states  | list(string) | masterless | List of states/formulas to apply

src/lib/configuration_management/configurations/base.rb

@@ -11,8 +11,6 @@ module ConfigurationManagement
     module Configurations
       # This class inteprets the module configuration
       class Base
-        # Default location of the module configuration
-        DEFAULT_PATH = Pathname.new("/var/adm/autoinstall/configuration_management.yml")
         # Default value for auth_attempts
         DEFAULT_AUTH_ATTEMPTS = 3
         # Defaull value for auth_time_out
@@ -67,6 +65,11 @@ def initialize(options)
           post_initialize(symbolized_opts)
         end
 
+        # Hook to run after initializing the instance
+        #
+        # This method is supposed to be overwritten by configuration classes if needed.
+        #
+        # @param _options [Hash] Configuration options
         def post_initialize(_options)
           nil
         end

src/lib/configuration_management/configurators/base.rb

@@ -12,7 +12,10 @@
 module Yast
   module ConfigurationManagement
     module Configurators
-      # This class handles the general bit of configuring/running CM systems.
+      # This class handles the general bits of configuring/running CM systems.
+      #
+      # Configurators are responsible for setting up a given configuration management system.
+      # They usually take care of downloading assets and/or adjusting the configuration files.
       class Base
         include Yast::Logger
 
@@ -38,9 +41,7 @@ def mode(mode, &block)
           def command(name, *args)
             Yast::ConfigurationManagement::Commands::Base.find(name).run(*args)
           end
-        end
 
-        class << self
           # Current configurator
           #
           # @return [Yast::ConfigurationManagement::Configurators::Base] Current configurator

src/lib/configuration_management/configurators/puppet.rb

@@ -12,6 +12,16 @@ module Configurators
       # Puppet configurator
       #
       # This class is responsible for configuring Pupppet before running it.
+      #
+      # ### Masterless Mode
+      #
+      # * Updates Puppet agent configuration (see {#update_configuration}).
+      # * Retrieves Puppet modules.
+      #
+      # ### Client/Server Mode
+      #
+      # * Updates Puppet agent configuration (see {#update_configuration}).
+      # * Fetches keys for authentication from a given URL
       class Puppet < Base
         include Yast::Logger
 

src/lib/configuration_management/configurators/salt.rb

@@ -11,6 +11,17 @@ module Configurators
       # Salt configurator
       #
       # This class is responsible for configuring Salt before running it.
+      #
+      # ### Masterless Mode
+      #
+      # * Retrieves remote states and pillars if needed
+      # * Searches for formulas and configures them if needed (writing data into pillars).
+      # * Updates the minion configuration (see {#update_configuration})
+      #
+      # ### Client/Server Mode
+      #
+      # * Fetches keys for authentication from a given URL
+      # * Updates the minion configuration (see {#update_configuration})
       class Salt < Base
         PRIVATE_KEY_PATH = "/etc/salt/pki/minion/minion.pem".freeze
         PUBLIC_KEY_PATH = "/etc/salt/pki/minion/minion.pub".freeze

test/lib/configurations/base_spec.rb

@@ -21,10 +21,6 @@
     }
   end
 
-  before do
-    stub_const("Yast::ConfigurationManagement::Configurations::Base::DEFAULT_PATH", default_path)
-  end
-
   describe "#mode" do
     context "when a master server is not specified" do
       let(:master) { nil }