=============================================================
      reclass — recursive external node classification
=============================================================
reclass is © 2007–2013 martin f. krafft <madduck@madduck.net>
and available under the terms of the Artistic Licence 2.0
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

Please make sure to read the generic information in the README file first, or
alongside this document.

Quick start with Salt
~~~~~~~~~~~~~~~~~~~~~
The following steps should get you up and running quickly. You will need to
decide for yourself where to put your reclass inventory. This can be
your first base file_root (the default), or it could be /etc/reclass, or
/srv/salt. The following shall assume the latter.

Or you can also just look into ./examples/salt of your reclass checkout,
where the following steps have already been prepared.

/…/reclass refers to the location of your reclass checkout.

  0. Complete the installation steps described in the section 'Installation'
     in the main README file.

     Alternatively, you can also tell Salt via the master config file where to
     look for reclass, but then you won't be able to interact with reclass
     through the command line.

  1. Copy the two directories 'nodes' and 'classes' from the example
     subdirectory in the reclass checkout to e.g. /srv/salt.

     It's handy to symlink reclass' Salt adapter itself to that directory.

       $ ln -s $(which salt-reclass) /srv/salt/states/reclass

     As you can now just inspect the data right there from the command line:

       $ ./reclass --top

     If you don't want to do this, you can also let reclass know where to look
     for the inventory with the following contents in
     $HOME/reclass-config.yml:

       storage_type: yaml_fs
       nodes_uri: /srv/reclass/nodes
       classes_uri: /srv/reclass/classes

     Or you can reuse the first entry of 'file_roots' under 'base' in the Salt
     master config.

     Note that yaml_fs is currently the only supported storage_type, and it's
     the default if you don't set it.

  2. Check out your inventory by invoking

       $ salt-reclass --top

     which should return all the information about all defined nodes, which is
     only 'localhost' in the example. This is essentially the same information
     that you would keep in your top.sls file.

     If you symlinked the script to your inventory base directory, use

       $ ./reclass --top

  3. See the pillar information for 'localhost':

       $ salt-reclass --pillar localhost

  4. Now add reclass to /etc/salt/master, like so:

     reclass: &reclass
         inventory_base_uri: /srv/salt
         reclass_source_path: ~/code/reclass

     master_tops:
         […]
         reclass: *reclass

     ext_pillar:
         - reclass: *reclass

     If you did not install reclass, you can either specify the source path
     like above, or you can add it to PYTHONPATH before invoking the Salt
     master, to ensure that Python can find it:

       PYTHONPATH=/…/reclass /etc/init.d/salt-master restart

  5. Provided that you have set up 'localhost' as a Salt minion, the following
     commands should now return the same data as above, but processed through
     salt:

       $ salt localhost pillar.items     # shows just the parameters
       $ salt localhost state.show_top   # shows only the states (applications)

     Alternatively, if you don't have the Salt minion running yet:

       # salt-call pillar.items     # shows just the parameters
       # salt-call state.show_top   # shows only the states (applications)

  6. You can also invoke reclass directly, which gives a slightly different
     view onto the same data, i.e. before it has been adapted for Salt:

       $ reclass --inventory
       $ reclass --nodeinfo localhost

Integration with Salt
~~~~~~~~~~~~~~~~~~~~~
reclass hooks into Salt at two different points: master_tops and ext_pillar.
For both, Salt provides plugins. These plugins need to know where to find
reclass, so if reclass is not properly installed (but you are running it from
source), make sure to export PYTHONPATH accordingly before you start your Salt
master, or specify the path in the master configuration file, as show above.

Salt has no concept of "nodes", "applications", "parameters", and "classes".
Therefore it is necessary to explain how those correspond to Salt. Crudely,
the following mapping exists:

  nodes         hosts
  classes       - [*]
  applications  states
  parameters    pillar

[*] See Salt issue #5787 for steps into the direction of letting reclass
provide nodegroup information.

Whatever applications you define for a node will become states applicable to
a host. If those applications are added via ancestor classes, then that's
fine, but currently, Salt does not do anything with the classes ancestry.

Similarly, all parameters that are collected and merged eventually end up in
the pillar data of a specific node.

However, the pillar data of a node include all the information about classes
and applications, so you can use them to target your Salt calls at groups of
nodes defined in the reclass inventory, e.g.

  salt -I __reclass__:classes:salt_minion test.ping

Unfortunately, this does not work yet, please stay tuned, and let me know
if you figure out a way. Salt issue #5787 is also of relevance.

 -- martin f. krafft <madduck@madduck.net>  Wed, 07 Aug 2013 16:21:04 +0200