Split Ansible-specific stuff from README
Signed-off-by: martin f. krafft <madduck@madduck.net>
diff --git a/README b/README
index ca3de45..228486f 100644
--- a/README
+++ b/README
@@ -11,8 +11,8 @@
The purpose of an ENC is to allow a system administrator to maintain an
inventory of nodes to be managed, completely separately from the configuration
of the automation tool. Usually, the external node classifier completely
-replaces the tool-specific inventory (such as site.pp for Puppet, or
-/etc/ansible/hosts).
+replaces the tool-specific inventory (such as site.pp for Puppet,
+ext_pillar/ext_nodes 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
@@ -27,14 +27,9 @@
- it provides information about groups of nodes and group memberships
- it gives access to node-specific information, such as variables
-While reclass was born into a Puppet environment and has also been used with
-Salt, the version you have in front of you is a rewrite from scratch, which
-was targetted at Ansible. However, care was taken to make the code flexible
-enough to allow it to be used from Salt, Puppet, and maybe even other tools as
-well.
-
-In this document, you will find an overview of the concepts of reclass, the
-way it works, and how it can be tied in with Ansible.
+In this document, you will find an overview of the concepts of reclass and the
+way it works. Have a look at README.Salt and README.Ansible for information
+about integration of reclass with these tools.
Installation
~~~~~~~~~~~~
@@ -49,62 +44,6 @@
make PYTHON=/opt/local/bin/python
-Quick start — Ansible
-~~~~~~~~~~~~~~~~~~~~~
-The following steps should get you up and running quickly. Generally, we will
-be working in /etc/ansible. However, if you are using a source-code checkout
-of Ansible, you might also want to work inside the ./hacking directory
-instead.
-
-Or you can also just look into ./examples/ansible of your reclass checkout,
-where the following steps have already been prepared.
-
-/…/reclass refers to the location of your reclass checkout.
-
- 1. Symlink /…/reclass/adapters/ansible to /etc/ansible/hosts (or
- ./hacking/hosts)
-
- 2. Copy the two directories 'nodes' and 'classes' from the example
- subdirectory in the reclass checkout to /etc/ansible
-
- If you prefer to put those directories elsewhere, you can create
- /etc/ansible/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.
-
- 3. Check out your inventory by invoking
-
- ./hosts --list
-
- which should return 5 groups in JSON-format, and each group has exactly
- one member 'localhost'.
-
- 4. See the node information for 'localhost':
-
- ./hosts --host localhost
-
- This should print a set of keys and values, including a greeting,
- a colour, and a sub-class called 'RECLASS'.
-
- 5. Execute some ansible commands, e.g.
-
- ansible -i hosts \* --list-hosts
- ansible -i hosts \* -m ping
- ansible -i hosts \* -m debug -a 'msg="${greeting}"'
- ansible -i hosts \* -m setup
- ansible-playbook -i hosts test.yml
-
- 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 Ansible:
-
- /…/reclass.py --pretty-print --inventory
- /…/reclass.py --pretty-print --nodeinfo localhost
-
reclass concepts
~~~~~~~~~~~~~~~~
reclass assumes a node-centric perspective into your inventory. This is
@@ -277,8 +216,8 @@
and study the output.
More commonly, however, use of reclass will happen indirectly, and through
-so-called adapters, e.g. /…/reclass/adapters/ansible. The job of an adapter is
-to translate between different invocation paradigms, provide a sane set of
+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.
@@ -301,109 +240,6 @@
'reclass-config.yml' and if no such file is found, it looks "next to" the
reclass script itself. Adapters implement their own lookup logic.
-Integration with Ansible
-~~~~~~~~~~~~~~~~~~~~~~~~
-The integration between reclass and Ansible is performed through an adapter,
-and needs not be of our concern too much.
-
-However, Ansible has no concept of "nodes", "applications", "parameters", and
-"classes". Therefore it is necessary to explain how those correspond to
-Ansible. Crudely, the following mapping exists:
-
- nodes hosts
- classes groups
- applications playbooks
- parameters host_vars
-
-reclass does not provide any group_vars because of its node-centric
-perspective. While class definitions include parameters, those are inherited
-by the node definitions and hence become node_vars.
-
-reclass also does not provide playbooks, nor does it deal with any of the
-related Ansible concepts, i.e. vars_files, vars, tasks, handlers, roles, etc..
-
- Let it be said at this point that you'll probably want to stop using
- host_vars, group_vars and vars_files altogether, and if only because you
- should no longer need them, but also because the variable precedence rules
- of Ansible are full of surprises, at least to me.
-
-reclass' Ansible adapter massage the reclass output into Ansible-usable data,
-namely:
-
- - Every class in the ancestry of a node becomes a group to Ansible. This is
- mainly useful to be able to target nodes during interactive use of
- Ansible, e.g.
-
- ansible debiannode@wheezy -m command -a 'apt-get upgrade'
- → upgrade all Debian nodes running wheezy
-
- ansible ssh.server -m command -a 'invoke-rc.d ssh restart'
- → restart all SSH server processes
-
- ansible mailserver -m command -a 'tail -n1000 /var/log/mail.err'
- → obtain the last 1,000 lines of all mailserver error log files
-
- The attentive reader might stumble over the use of singular words, whereas
- it might make more sense to address all 'mailserver*s*' with this tool.
- This is convention and up to you. I prefer to think of my node as
- a (singular) mailserver when I add 'mailserver' to its parent classes.
-
- - Every entry in the list of a host's applications might well correspond to
- an Ansible playbook. Therefore, reclass creates a (Ansible-)group for
- every application, and adds '_hosts' to the name. This postfix can be
- configured with a CLI option (--applications-postfix) or in the
- configuration file (applications_postfix).
-
- For instance, the ssh.server class adds the ssh.server application to
- a node's application list. Now the admin might create an Ansible playbook
- like so:
-
- - name: SSH server management
- hosts: ssh.server_hosts ← SEE HERE
- tasks:
- - name: install SSH package
- action: …
- …
-
- There's a bit of redundancy in this, but unfortunately Ansible playbooks
- hardcode the nodes to which a playbook applies.
-
- It's now trivial to apply this playbook across your infrastructure:
-
- ansible-playbook ssh.server.yml
-
- My suggested way to use Ansible site-wide is then to create a 'site'
- playbook that includes all the other playbooks (which shall hopefully be
- based on Ansible roles), and then to invoke Ansible like this:
-
- ansible-playbook site.yml
-
- or, if you prefer only to reconfigure a subset of nodes, e.g. all
- webservers:
-
- ansible-playbook site.yml --limit webserver
-
- Again, if the singular word 'webserver' puts you off, change the
- convention as you wish.
-
- And if anyone comes up with a way to directly connect groups in the
- inventory with roles, thereby making it unnecessary to write playbook
- files (containing redundant information), please tell me!
-
- - Parameters corresponding to a node become host_vars for that host.
-
-It is possible to include Jinja2-style variables like you would in Ansible,
-in parameter values. This is especially powerful in combination with the
-recursive merging, e.g.
-
- parameters:
- motd:
- greeting: Welcome to {{ ansible_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.
-
Contributing to reclass
~~~~~~~~~~~~~~~~~~~~~~~
Conttributions to reclass are very welcome. Since I prefer to keep a somewhat