README.Salt - packaging/sources/reclass - Gitiles

 =============================================================
       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…
	=============================================================
	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…