=============================================================
      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
/etc/reclass, or it could be /srv/salt, for instance if /srv/salt/states is
where your Salt file_roots live. 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. Run 'make' in the root of the reclass checkout (see the section
     'Installation' in the README file for the reason).

  1. Symlink /…/reclass/adapters/salt to /srv/salt/states/reclass. This is not
     at all required, because Salt interfaces with reclass as a Python module,
     but it's handy to have the inventory within reach.

  2. Copy the two directories 'nodes' and 'classes' from the example
     subdirectory in the reclass checkout to /srv/salt/states

     If you prefer to put those directories elsewhere, you can create
     /srv/salt/states/reclass-config.yml with contents such as

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

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

     Again, this isn't really required, but it's good to get you started. If
     you really put your inventory into /srv/reclass or /etc/reclass, you'll
     tell the Salt master later.

  3. Check out your inventory by invoking

       ./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.

  4. See the pillar information for 'localhost':

       ./reclass --pillar localhost

     This is the so-called pillar-data for the named host.

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

     master_tops:
       […]
       reclass:
         inventory_base_uri: /srv/salt

     ext_pillar:
       reclass:
         inventory_base_uri: /srv/salt

     Currently, there is no way to unify these configuration data, but it's
     hardly much to duplicate. In the future, I may provide for a global
     'reclass' key, but for now you will have to add the data twice.

     Now restart your Salt master and make sure that reclass is in the
     PYTHONPATH, so if it's not properly installed (but you are running it
     from source), do this:

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

  6. 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)

  7. 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.py --pretty-print --inventory
       /…/reclass.py --pretty-print --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.

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.

It will also be possible to include Jinja2-style variables in parameter
values. This is especially powerful in combination with the recursive merging,
e.g.

  parameters:
    motd:
      greeting: Welcome to {{ grains.fqdn }}!
      closing: This system is part of {{ realm }}

Now you just need to specify realm somewhere. The reference can reside in
a parent class, while the variable is defined e.g. in the node.

This is also not yet working. The main reason is that the expansion cannot
happen at the YAML-file level, because that would cast most types to strings.
Instead, the interpolation needs to happen at the data structure level inside
reclass, or maybe at the adapter level, reusing the templating of Salt. This
will require some more thought, but it's on the horizon…