Massive refactoring
This commit does some massive refactoring of the Salt source:
- reclass and all adapters have been changed to support the distribute
(setuptools) entry-points interface, while they are also runnable
directly (using `/usr/bin/env python`);
- reclass and all adapters now use exactly the same approach to
configuration (sensible defaults + config file + command-line
options), but inventory/nodeinfo is properly parametrised (e.g.
top/pillar for Salt);
- the documentation has been updated accordingly;
- defaults and constants were factored out into common modules.
Signed-off-by: martin f. krafft <madduck@madduck.net>
diff --git a/README b/README
index 35e7478..3bea51b 100644
--- a/README
+++ b/README
@@ -16,12 +16,12 @@
ext_pillar/master_tops for Salt, or /etc/ansible/hosts).
reclass allows you to define your nodes through class inheritance, while
-always able to override details of classes further up the tree. Think of
-classes as feature sets, as commonalities between nodes, or as tags. Add to
-that the ability to nest classes (multiple inheritance is allowed,
-well-defined, and encouraged), and piece together your infrastructure from
-smaller bits, eliminating redundancy and exposing all important parameters to
-a single location, logically organised.
+always able to override details further up the tree (i.e. in more specific
+nodes). Think of classes as feature sets, as commonalities between nodes, or
+as tags. Add to that the ability to nest classes (multiple inheritance is
+allowed, well-defined, and encouraged), and piece together your infrastructure
+from smaller bits, eliminating redundancy and exposing all important
+parameters to a single location, logically organised.
In general, the ENC fulfills two jobs:
@@ -36,40 +36,41 @@
~~~~~~~~~~~~
Before you can use reclass, you need to install it into a place where Python
can find it. Unless you installed a package from your distribution, the
-following step:
+following step should install the package to /usr/local:
- python setup.py install
-
-This will install the package to /usr/local, which is likely in your Python
-path. You can check this using
-
- python -c 'import sys; print sys.path'
+ $ python setup.py install
If you want to install to a different location, use --prefix like so:
- python setup.py install --prefix=/opt/local
+ $ python setup.py install --prefix=/opt/local
+
+Just make sure that the destination is in the Python module search path, which
+you can check like this:
+
+ $ python -c 'import sys; print sys.path'
More options can be found in the output of
- python setup.py install --help
- python setup.py --help
- python setup.py --help-commands
- python setup.py --help [cmd]
+ $ python setup.py install --help
+ $ python setup.py --help
+ $ python setup.py --help-commands
+ $ python setup.py --help [cmd]
If you just want to run reclass from source, e.g. because you are going to be
making and testing changes, install it in "development mode":
- python setup.py develop
+ $ python setup.py develop
-To uninstall:
+To uninstall (the rm call is necessary due to http://bugs.debian.org/714960):
- python setup.py develop --uninstall
+ $ python setup.py develop --uninstall
+ $ rm /usr/local/bin/reclass*
Uninstallation currently isn't possible for packages installed to /usr/local
as per the above method, unfortunately: http://bugs.python.org/issue4673.
The following should do:
- rm -r /usr/local/lib/python*/dist-packages/reclass* /usr/local/bin/reclass
+ $ rm -r /usr/local/lib/python*/dist-packages/reclass* /usr/local/bin/reclass*
reclass concepts
~~~~~~~~~~~~~~~~
@@ -86,7 +87,7 @@
node: A node, usually a computer in your infrastructure
class: A category, tag, feature, or role that applies to a node
Classes may be nested, i.e. there can be a class hierarchy
- application: A specific set of behaviour to apply to members of a class
+ application: A specific set of behaviour to apply
parameter: Node-specific variables, with inheritance throughout the class
hierarchy.
@@ -229,8 +230,12 @@
reclass starts out reading a node definition file, obtains the list of
classes, then reads the files corresponding to these classes, recursively
-reading parent classes, and finally merges the applications list (append
-unless
+reading parent classes, and finally merges the applications list and the
+parameters.
+
+Merging of parameters is done recursively, meaning that lists and dictionaries
+are extended, rather than replaced. There is currently no way to remove or
+overwrite an existing value.
Version control
~~~~~~~~~~~~~~~
@@ -239,8 +244,8 @@
Usage
~~~~~
-For information on how to use reclass directly, invoke reclass.py with --help
-and study the output.
+For information on how to use reclass directly, invoke reclass with --help and
+study the output.
The three options --inventory-base-uri, --nodes-uri, and --classes-uri
together specify the location of the inventory. If the base URI is specified,
@@ -248,13 +253,13 @@
these two URIs are not specified, they default to 'nodes' and 'classes'.
Therefore, if your inventory is in '/etc/reclass/nodes' and
'/etc/reclass/classes', all you need to specify is the base URI as
-'/etc/reclass'.
+'/etc/reclass' — which is actually the default (see reclass/defaults.py).
If you've installed reclass as per the above instructions, try to run it from
the source directory like this:
- reclass -b examples/ --inventory
- reclass -b examples/ --node localhost
+ $ reclass -b examples/ --inventory
+ $ reclass -b examples/ --node localhost
Those data come from examples/nodes and examples/classes, and you can surely
make your own way from here.
@@ -263,7 +268,8 @@
so-called adapters, e.g. /…/reclass/adapters/salt. The job of an adapter is to
translate between different invocation paradigms, provide a sane set of
default options, and massage the data from reclass into the format expected by
-the automation tool in use.
+the automation tool in use. Please have a look at the respective README files
+for these adapters.
Configuration file
~~~~~~~~~~~~~~~~~~
@@ -282,7 +288,15 @@
nodes_uri: ../nodes
reclass first looks in the current directory for the file called
-'reclass-config.yml' and if no such file is found, it looks "next to" the
-reclass script itself. Adapters implement their own lookup logic.
+'reclass-config.yml' (see reclass/defaults.py) and if no such file is found,
+it looks in $HOME, then in /etc/reclass, and then "next to" the reclass script
+itself, i.e. if the script is symlinked to /srv/provisioning/reclass, then the
+the script will try to access /srv/provisioning/reclass-config.yml.
- -- martin f. krafft <madduck@madduck.net> Fri, 03 Jul 2013 19:57:05 +0200
+Note that yaml_fs is currently the only supported storage_type, and it's the
+default if you don't set it.
+
+Adapters may implement their own lookup logic, of course, so make sure to read
+their READMEs.
+
+ -- martin f. krafft <madduck@madduck.net> Thu, 04 Jul 2013 22:20:20 +0200