| <!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> |