Using reclass with Ansible


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

  1. 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__.

  2. 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
  3. 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/ --pretty-print --inventory
    $ /…/reclass/ --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
        - 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:

    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:

    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 for more information.

Table Of Contents

Previous topic

Using reclass with Salt

Next topic

Using reclass with Puppet