Webpage update
diff --git a/ansible.html b/ansible.html
new file mode 100644
index 0000000..e0f7934
--- /dev/null
+++ b/ansible.html
@@ -0,0 +1,328 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Using reclass with Ansible — reclass 1.4.1 documentation</title>
+
+ <link rel="stylesheet" href="_static/default.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '1.4.1',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="reclass 1.4.1 documentation" href="index.html" />
+ <link rel="next" title="Using reclass with Puppet" href="puppet.html" />
+ <link rel="prev" title="Using reclass with Salt" href="salt.html" />
+ </head>
+ <body>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="puppet.html" title="Using reclass with Puppet"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="salt.html" title="Using reclass with Salt"
+ accesskey="P">previous</a> |</li>
+ <li><a href="index.html">reclass</a> »</li>
+ </ul>
+ </div>
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+ <div class="body">
+
+ <div class="section" id="using-reclass-with-ansible">
+<h1>Using reclass with Ansible<a class="headerlink" href="#using-reclass-with-ansible" title="Permalink to this headline">¶</a></h1>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">I was kicked out of the Ansible community, presumably for <a class="reference external" href="https://github.com/madduck/reclass/issues/6">asking the wrong
+questions</a>, and therefore I have no interest in developing this adapter
+anymore. If you use it and have changes, I will take your patch.</p>
+</div>
+<div class="section" id="quick-start-with-ansible">
+<h2>Quick start with Ansible<a class="headerlink" href="#quick-start-with-ansible" title="Permalink to this headline">¶</a></h2>
+<p>The following steps should get you up and running quickly with <strong>reclass</strong> and
+<a class="reference external" href="http://www.ansibleworks.com">Ansible</a>. Generally, we will be working in <tt class="docutils literal"><span class="pre">/etc/ansible</span></tt>. However, if you
+are using a source-code checkout of Ansible, you might also want to work
+inside the <tt class="docutils literal"><span class="pre">./hacking</span></tt> directory instead.</p>
+<p>Or you can also just look into <tt class="docutils literal"><span class="pre">./examples/ansible</span></tt> of your <strong>reclass</strong>
+checkout, where the following steps have already been prepared.</p>
+<p>/…/reclass refers to the location of your <strong>reclass</strong> checkout.</p>
+<ol class="arabic">
+<li><p class="first">Complete the installation steps described in the <a class="reference internal" href="install.html"><em>installation section</em></a>.</p>
+</li>
+<li><p class="first">Symlink <tt class="docutils literal"><span class="pre">/usr/share/reclass/reclass-ansible</span></tt> (or wherever your distro put
+that file), or <tt class="docutils literal"><span class="pre">/…/reclass/reclass/adapters/ansible.py</span></tt> (if running from
+source) to <tt class="docutils literal"><span class="pre">/etc/ansible/hosts</span></tt> (or <tt class="docutils literal"><span class="pre">./hacking/hosts</span></tt>).</p>
+</li>
+<li><p class="first">Copy the two directories <tt class="docutils literal"><span class="pre">nodes</span></tt> and <tt class="docutils literal"><span class="pre">classes</span></tt> from the example
+subdirectory in the <strong>reclass</strong> checkout to <tt class="docutils literal"><span class="pre">/etc/ansible</span></tt></p>
+<p>If you prefer to put those directories elsewhere, you can create
+<tt class="docutils literal"><span class="pre">/etc/ansible/reclass-config.yml</span></tt> with contents such as:</p>
+<div class="highlight-python"><div class="highlight"><pre>storage_type: yaml_fs
+inventory_base_uri: /srv/reclass
+</pre></div>
+</div>
+<p>Note that <tt class="docutils literal"><span class="pre">yaml_fs</span></tt> is currently the only supported <tt class="docutils literal"><span class="pre">storage_type</span></tt>, and
+it’s the default if you don’t set it.</p>
+</li>
+<li><p class="first">Check out your inventory by invoking</p>
+<div class="highlight-python"><div class="highlight"><pre>$ ./hosts --list
+</pre></div>
+</div>
+<p>which should return 5 groups in JSON format, and each group has exactly
+one member <tt class="docutils literal"><span class="pre">localhost</span></tt>.</p>
+</li>
+</ol>
+<ol class="arabic" start="4">
+<li><p class="first">See the node information for <tt class="docutils literal"><span class="pre">localhost</span></tt>:</p>
+<div class="highlight-python"><div class="highlight"><pre>$ ./hosts --host localhost
+</pre></div>
+</div>
+<p>This should print a set of keys and values, including a greeting,
+a colour, and a sub-class called <tt class="docutils literal"><span class="pre">__reclas__</span></tt>.</p>
+</li>
+<li><p class="first">Execute some ansible commands, e.g.:</p>
+<div class="highlight-python"><div class="highlight"><pre>$ 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
+</pre></div>
+</div>
+</li>
+<li><p class="first">You can also invoke <strong>reclass</strong> directly, which gives a slightly different
+view onto the same data, i.e. before it has been adapted for Ansible:</p>
+<div class="highlight-python"><div class="highlight"><pre>$ /…/reclass/reclass.py --pretty-print --inventory
+$ /…/reclass/reclass.py --pretty-print --nodeinfo localhost
+</pre></div>
+</div>
+<p>Or, if <strong>reclass</strong> is properly installed, just use the <strong>reclass</strong> command.</p>
+</li>
+</ol>
+</div>
+<div class="section" id="integration-with-ansible">
+<h2>Integration with Ansible<a class="headerlink" href="#integration-with-ansible" title="Permalink to this headline">¶</a></h2>
+<p>The integration between <strong>reclass</strong> and Ansible is performed through an adapter,
+and needs not be of our concern too much.</p>
+<p>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:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="53%" />
+<col width="47%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head"><strong>reclass</strong> concept</th>
+<th class="head">Ansible concept</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>nodes</td>
+<td>hosts</td>
+</tr>
+<tr class="row-odd"><td>classes</td>
+<td>groups</td>
+</tr>
+<tr class="row-even"><td>applications</td>
+<td>playbooks</td>
+</tr>
+<tr class="row-odd"><td>parameters</td>
+<td>host_vars</td>
+</tr>
+</tbody>
+</table>
+<p><strong>reclass</strong> does not provide any <tt class="docutils literal"><span class="pre">group_vars</span></tt> because of its node-centric
+perspective. While class definitions include parameters, those are inherited
+by the node definitions and hence become node_vars.</p>
+<p><strong>reclass</strong> also does not provide playbooks, nor does it deal with any of the
+related Ansible concepts, i.e. <tt class="docutils literal"><span class="pre">vars_files</span></tt>, vars, tasks, handlers, roles, etc..</p>
+<blockquote>
+<div>Let it be said at this point that you’ll probably want to stop using
+<tt class="docutils literal"><span class="pre">host_vars</span></tt>, <tt class="docutils literal"><span class="pre">group_vars</span></tt> and <tt class="docutils literal"><span class="pre">vars_files</span></tt> 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.</div></blockquote>
+<p><strong>reclass</strong>‘ Ansible adapter massage the <strong>reclass</strong> output into Ansible-usable data,
+namely:</p>
+<ul>
+<li><p class="first">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.:</p>
+<div class="highlight-python"><div class="highlight"><pre>$ 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
+</pre></div>
+</div>
+<p>The attentive reader might stumble over the use of singular words, whereas
+it might make more sense to address all <tt class="docutils literal"><span class="pre">mailserver*s*</span></tt> with this tool.
+This is convention and up to you. I prefer to think of my node as
+a (singular) mailserver when I add <tt class="docutils literal"><span class="pre">mailserver</span></tt> to its parent classes.</p>
+</li>
+<li><p class="first">Every entry in the list of a host’s applications might well correspond to
+an Ansible playbook. Therefore, <strong>reclass</strong> creates a (Ansible-)group for
+every application, and adds <tt class="docutils literal"><span class="pre">_hosts</span></tt> to the name. This postfix can be
+configured with a CLI option (<tt class="docutils literal"><span class="pre">--applications-postfix</span></tt>) or in the
+configuration file (<tt class="docutils literal"><span class="pre">applications_postfix</span></tt>).</p>
+<p>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:</p>
+<div class="highlight-python"><div class="highlight"><pre>- name: SSH server management
+ hosts: ssh.server_hosts ← SEE HERE
+ tasks:
+ - name: install SSH package
+ action: …
+ …
+</pre></div>
+</div>
+<p>There’s a bit of redundancy in this, but unfortunately Ansible playbooks
+hardcode the nodes to which a playbook applies.</p>
+<p>It’s now trivial to apply this playbook across your infrastructure:</p>
+<div class="highlight-python"><div class="highlight"><pre>$ ansible-playbook ssh.server.yml
+</pre></div>
+</div>
+<p>My suggested way to use Ansible site-wide is then to create a <tt class="docutils literal"><span class="pre">site.yml</span></tt>
+playbook that includes all the other playbooks (which shall hopefully be
+based on Ansible roles), and then to invoke Ansible like this:</p>
+<blockquote>
+<div><p>ansible-playbook site.yml</p>
+</div></blockquote>
+<p>or, if you prefer only to reconfigure a subset of nodes, e.g. all
+webservers:</p>
+<div class="highlight-python"><div class="highlight"><pre>$ ansible-playbook site.yml --limit webserver
+</pre></div>
+</div>
+<p>Again, if the singular word <tt class="docutils literal"><span class="pre">webserver</span></tt> puts you off, change the
+convention as you wish.</p>
+<p>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!</p>
+</li>
+<li><p class="first">Parameters corresponding to a node become <tt class="docutils literal"><span class="pre">host_vars</span></tt> for that host.</p>
+</li>
+</ul>
+</div>
+<div class="section" id="variable-interpolation">
+<h2>Variable interpolation<a class="headerlink" href="#variable-interpolation" title="Permalink to this headline">¶</a></h2>
+<p>Ansible allows you to include <a class="reference external" href="http://jinja.pocoo.org">Jinja2</a>-style variables in parameter values:</p>
+<div class="highlight-python"><div class="highlight"><pre>parameters:
+ motd:
+ greeting: Welcome to {{ ansible_fqdn }}!
+ closing: This system is part of {{ realm }}
+ dict_reference: {{ motd }}
+</pre></div>
+</div>
+<p>However, in resolving this, Ansible casts everything to a string, so in this
+example, <tt class="docutils literal"><span class="pre">dict_reference</span></tt> would be the string-representation of the
+dictionary under the <tt class="docutils literal"><span class="pre">motd</span></tt> key <a class="footnote-reference" href="#string-casts" id="id1">[1]</a>. To get at facts (such as
+<tt class="docutils literal"><span class="pre">ansible_fqdn</span></tt>), you still have to use this approach, but for pure parameter
+references, I strongly suggest to use <strong>reclass</strong> interpolation instead, as it
+supports deep references, does not clobber type information, and is more
+efficient anyway:</p>
+<div class="highlight-python"><div class="highlight"><pre>parameters:
+ motd:
+ greeting: Welcome to {{ ansible_fqdn }}!
+ closing: This system is part of ${realm}
+ dict_reference: ${motd}
+</pre></div>
+</div>
+<p>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.</p>
+<p>And as expected, <tt class="docutils literal"><span class="pre">dict_reference</span></tt> now points to a dictionary, not
+a string-representation thereof.</p>
+<table class="docutils footnote" frame="void" id="string-casts" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>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
+<a class="reference external" href="https://github.com/madduck/reclass/issues/6">https://github.com/madduck/reclass/issues/6</a> for more information.</td></tr>
+</tbody>
+</table>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ </div>
+ <div class="sphinxsidebar">
+ <div class="sphinxsidebarwrapper">
+ <h3><a href="index.html">Table Of Contents</a></h3>
+ <ul>
+<li><a class="reference internal" href="#">Using reclass with Ansible</a><ul>
+<li><a class="reference internal" href="#quick-start-with-ansible">Quick start with Ansible</a></li>
+<li><a class="reference internal" href="#integration-with-ansible">Integration with Ansible</a></li>
+<li><a class="reference internal" href="#variable-interpolation">Variable interpolation</a></li>
+</ul>
+</li>
+</ul>
+
+ <h4>Previous topic</h4>
+ <p class="topless"><a href="salt.html"
+ title="previous chapter">Using reclass with Salt</a></p>
+ <h4>Next topic</h4>
+ <p class="topless"><a href="puppet.html"
+ title="next chapter">Using reclass with Puppet</a></p>
+<div id="searchbox" style="display: none">
+ <h3>Quick search</h3>
+ <form class="search" action="search.html" method="get">
+ <input type="text" name="q" />
+ <input type="submit" value="Go" />
+ <input type="hidden" name="check_keywords" value="yes" />
+ <input type="hidden" name="area" value="default" />
+ </form>
+ <p class="searchtip" style="font-size: 90%">
+ Enter search terms or a module, class or function name.
+ </p>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="puppet.html" title="Using reclass with Puppet"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="salt.html" title="Using reclass with Salt"
+ >previous</a> |</li>
+ <li><a href="index.html">reclass</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2013, martin f. krafft.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file