Using reclass with Ansible

Warning

I was kicked out of the Ansible community, presumably for asking the wrong questions, and therefore I have no interest in developing this adapter anymore. If you use it and have changes, I will take your patch.

Quick start with Ansible

The following steps should get you up and running quickly with reclass and Ansible. 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. Complete the installation steps described in the installation section.

2. Symlink /usr/share/reclass/reclass-ansible (or wherever your distro put that file), or /…/reclass/reclass/adapters/ansible.py (if running from source) to /etc/ansible/hosts (or ./hacking/hosts).

3. 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
   inventory_base_uri: /srv/reclass
   

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

4. 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 __reclas__.

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

   Or, if reclass is properly installed, just use the reclass command.

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:

reclass concept	Ansible concept
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.yml 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.

Variable interpolation

Ansible allows you to include Jinja2-style variables in parameter values:

parameters:
  motd:
    greeting: Welcome to {{ ansible_fqdn }}!
    closing: This system is part of {{ realm }}
  dict_reference: {{ motd }}

However, in resolving this, Ansible casts everything to a string, so in this example, dict_reference would be the string-representation of the dictionary under the motd key 1. To get at facts (such as ansible_fqdn), you still have to use this approach, but for pure parameter references, I strongly suggest to use reclass interpolation instead, as it supports deep references, does not clobber type information, and is more efficient anyway:

parameters:
  motd:
    greeting: Welcome to {{ ansible_fqdn }}!
    closing: This system is part of ${realm}
  dict_reference: ${motd}

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

And as expected, dict_reference now points to a dictionary, not a string-representation thereof.

1

I pointed this out to Michael Dehaan, Ansible’s chief developer, but he denied this behaviour. When I tried to provide further insights, I found myself banned from the mailing list, apparently because I dared to point out flaws. If you care, you may look at https://github.com/madduck/reclass/issues/6 for more information.