Gitiles
Code Review Sign In
gerrit.mcp.mirantis.com / packaging / sources / reclass / refs/heads/gh-pages / . / concepts.html
blob: 59fac80fbdf887259ddfc1465579a20b6b4286bf [file] [log] [blame]
martin f. krafft3cd2a332014-10-28 15:58:23 +0100[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
4
5<html xmlns="http://www.w3.org/1999/xhtml">
6 <head>
7 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
8
9 <title>reclass concepts &mdash; reclass 1.4.1 documentation</title>
10
11 <link rel="stylesheet" href="_static/default.css" type="text/css" />
12 <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
13
14 <script type="text/javascript">
15 var DOCUMENTATION_OPTIONS = {
16 URL_ROOT: './',
17 VERSION: '1.4.1',
18 COLLAPSE_INDEX: false,
19 FILE_SUFFIX: '.html',
20 HAS_SOURCE: true
21 };
22 </script>
23 <script type="text/javascript" src="_static/jquery.js"></script>
24 <script type="text/javascript" src="_static/underscore.js"></script>
25 <script type="text/javascript" src="_static/doctools.js"></script>
26 <link rel="top" title="reclass 1.4.1 documentation" href="index.html" />
27 <link rel="next" title="reclass operations" href="operations.html" />
28 <link rel="prev" title="Installation" href="install.html" />
29 </head>
30 <body>
31 <div class="related">
32 <h3>Navigation</h3>
33 <ul>
34 <li class="right" style="margin-right: 10px">
35 <a href="genindex.html" title="General Index"
36 accesskey="I">index</a></li>
37 <li class="right" >
38 <a href="operations.html" title="reclass operations"
39 accesskey="N">next</a> |</li>
40 <li class="right" >
41 <a href="install.html" title="Installation"
42 accesskey="P">previous</a> |</li>
43 <li><a href="index.html">reclass</a> &raquo;</li>
44 </ul>
45 </div>
46
47 <div class="document">
48 <div class="documentwrapper">
49 <div class="bodywrapper">
50 <div class="body">
51
52 <div class="section" id="reclass-concepts">
53<h1>reclass concepts<a class="headerlink" href="#reclass-concepts" title="Permalink to this headline"></a></h1>
54<p><strong>reclass</strong> assumes a node-centric perspective into your inventory. This is
55obvious when you query <strong>reclass</strong> for node-specific information, but it might not
56be clear when you ask <strong>reclass</strong> to provide you with a list of groups. In that
57case, <strong>reclass</strong> loops over all nodes it can find in its database, reads all
58information it can find about the nodes, and finally reorders the result to
59provide a list of groups with the nodes they contain.</p>
60<p>Since the term &#8220;groups&#8221; is somewhat ambiguous, it helps to start off with
61a short glossary of <strong>reclass</strong>-specific terminology:</p>
62<table border="1" class="docutils">
63<colgroup>
64<col width="16%" />
65<col width="84%" />
66</colgroup>
67<thead valign="bottom">
68<tr class="row-odd"><th class="head">Concept</th>
69<th class="head">Description</th>
70</tr>
71</thead>
72<tbody valign="top">
73<tr class="row-even"><td>node</td>
74<td>A node, usually a computer in your infrastructure</td>
75</tr>
76<tr class="row-odd"><td>class</td>
77<td>A category, tag, feature, or role that applies to a node
78Classes may be nested, i.e. there can be a class hierarchy</td>
79</tr>
80<tr class="row-even"><td>application</td>
81<td>A specific set of behaviour to apply</td>
82</tr>
83<tr class="row-odd"><td>parameter</td>
84<td>Node-specific variables, with inheritance throughout the class
85hierarchy.</td>
86</tr>
87</tbody>
88</table>
89<p>A class consists of zero or more parent classes, zero or more applications,
90and any number of parameters.</p>
91<p>A class name must not contain spaces.</p>
92<p>A node is almost equivalent to a class, except that it usually does not (but
93can) specify applications.</p>
94<p>When <strong>reclass</strong> parses a node (or class) definition and encounters a parent
95class, it recurses to this parent class first before reading any data of the
96node (or class). When <strong>reclass</strong> returns from the recursive, depth first walk, it
97then merges all information of the current node (or class) into the
98information it obtained during the recursion.</p>
99<p>Furthermore, a node (or class) may define a list of classes it derives from,
100in which case classes defined further down the list will be able to override
101classes further up the list.</p>
102<p>Information in this context is essentially one of a list of applications or
103a list of parameters.</p>
104<p>The interaction between the depth-first walk and the delayed merging of data
105means that the node (and any class) may override any of the data defined by
106any of the parent classes (ancestors). This is in line with the assumption
107that more specific definitions (&#8220;this specific host&#8221;) should have a higher
108precedence than more general definitions (&#8220;all webservers&#8221;, which includes all
109webservers in Munich, which includes &#8220;this specific host&#8221;, for example).</p>
110<p>Here&#8217;s a quick example, showing how parameters accumulate and can get
111replaced.</p>
112<blockquote>
113<div><p>All &#8220;unixnodes&#8221; (i.e. nodes who have the <tt class="docutils literal"><span class="pre">unixnode</span></tt> class in their
114ancestry) have <tt class="docutils literal"><span class="pre">/etc/motd</span></tt> centrally-managed (through the <tt class="docutils literal"><span class="pre">motd</span></tt>
115application), and the <cite>unixnode</cite> class definition provides a generic
116message-of-the-day to be put into this file.</p>
117<p>All descendants of the class <tt class="docutils literal"><span class="pre">debiannode</span></tt>, a descendant of <tt class="docutils literal"><span class="pre">unixnode</span></tt>,
118should include the Debian codename in this message, so the
119message-of-the-day is overwritten in the <tt class="docutils literal"><span class="pre">debiannodes</span></tt> class.</p>
120<p>The node <tt class="docutils literal"><span class="pre">quantum.example.org</span></tt> (a <cite>debiannode</cite>) will have a scheduled
121downtime this weekend, so until Monday, an appropriate message-of-the-day is
122added to the node definition.</p>
123<p>When the <tt class="docutils literal"><span class="pre">motd</span></tt> application runs, it receives the appropriate
124message-of-the-day (from <tt class="docutils literal"><span class="pre">quantum.example.org</span></tt> when run on that node) and
125writes it into <tt class="docutils literal"><span class="pre">/etc/motd</span></tt>.</p>
126</div></blockquote>
127<p>At this point it should be noted that parameters whose values are lists or
128key-value pairs don&#8217;t get overwritten by children classes or node definitions,
129but the information gets merged (recursively) instead.</p>
130<p>Similarly to parameters, applications also accumulate during the recursive
131walk through the class ancestry. It is possible for a node or child class to
132<em>remove</em> an application added by a parent class, by prefixing the application
133with <cite>~</cite>.</p>
134<p>Finally, <strong>reclass</strong> happily lets you use multiple inheritance, and ensures that
135the resolution of parameters is still well-defined. Here&#8217;s another example
136building upon the one about <tt class="docutils literal"><span class="pre">/etc/motd</span></tt> above:</p>
137<blockquote>
138<div><p><tt class="docutils literal"><span class="pre">quantum.example.org</span></tt> (which is back up and therefore its node definition
139no longer contains a message-of-the-day) is at a site in Munich. Therefore,
140it is a child of the class <tt class="docutils literal"><span class="pre">hosted&#64;munich</span></tt>. This class is independent of
141the <tt class="docutils literal"><span class="pre">unixnode</span></tt> hierarchy, <tt class="docutils literal"><span class="pre">quantum.example.org</span></tt> derives from both.</p>
142<p>In this example infrastructure, <tt class="docutils literal"><span class="pre">hosted&#64;munich</span></tt> is more specific than
143<tt class="docutils literal"><span class="pre">debiannode</span></tt> because there are plenty of Debian nodes at other sites (and
144some non-Debian nodes in Munich). Therefore, <tt class="docutils literal"><span class="pre">quantum.example.org</span></tt> derives
145from <tt class="docutils literal"><span class="pre">hosted&#64;munich</span></tt> _after_ <tt class="docutils literal"><span class="pre">debiannodes</span></tt>.</p>
146<p>When an electricity outage is expected over the weekend in Munich, the admin
147can change the message-of-the-day in the <tt class="docutils literal"><span class="pre">hosted&#64;munich</span></tt> class, and it
148will apply to all hosts in Munich.</p>
149<p>However, not all hosts in Munich have <tt class="docutils literal"><span class="pre">/etc/motd</span></tt>, because some of them
150are of class <tt class="docutils literal"><span class="pre">windowsnode</span></tt>. Since the <tt class="docutils literal"><span class="pre">windowsnode</span></tt> ancestry does not
151specify the <tt class="docutils literal"><span class="pre">motd</span></tt> application, those hosts have access to the
152message-of-the-day in the node variables, but the message won&#8217;t get used…</p>
153<p>… unless, of course, <tt class="docutils literal"><span class="pre">windowsnode</span></tt> specified a Windows-specific
154application to bring such notices to the attention of the user.</p>
155</div></blockquote>
156<p>It&#8217;s also trivial to ensure a certain order of class evaluation. Here&#8217;s
157another example:</p>
158<blockquote>
159<div><p>The <tt class="docutils literal"><span class="pre">ssh.server</span></tt> class defines the <tt class="docutils literal"><span class="pre">permit_root_login</span></tt> parameter to <tt class="docutils literal"><span class="pre">no</span></tt>.</p>
160<p>The <tt class="docutils literal"><span class="pre">backuppc.client</span></tt> class defines the parameter to <tt class="docutils literal"><span class="pre">without-password</span></tt>,
161because the BackupPC server might need to log in to the host as root.</p>
162<p>Now, what happens if the admin accidentally provides the following two
163classes?</p>
164<ul class="simple">
165<li><tt class="docutils literal"><span class="pre">backuppc.client</span></tt></li>
166<li><tt class="docutils literal"><span class="pre">ssh.server</span></tt></li>
167</ul>
168<p>Theoretically, this would mean <tt class="docutils literal"><span class="pre">permit_root_login</span></tt> gets set to <tt class="docutils literal"><span class="pre">no</span></tt>.</p>
169<p>However, since all <tt class="docutils literal"><span class="pre">backuppc.client</span></tt> nodes need <tt class="docutils literal"><span class="pre">ssh.server</span></tt> (at least
170in most setups), the class <tt class="docutils literal"><span class="pre">backuppc.client</span></tt> itself derives from
171<tt class="docutils literal"><span class="pre">ssh.server</span></tt>, ensuring that it gets parsed before <tt class="docutils literal"><span class="pre">backuppc.client</span></tt>.</p>
172<p>When <strong>reclass</strong> returns to the node and encounters the <tt class="docutils literal"><span class="pre">ssh.server</span></tt> class
173defined there, it simply skips it, as it&#8217;s already been processed.</p>
174</div></blockquote>
175<p>Now read about <a class="reference internal" href="operations.html"><em>reclass operations</em></a>!</p>
176</div>
177
178
179 </div>
180 </div>
181 </div>
182 <div class="sphinxsidebar">
183 <div class="sphinxsidebarwrapper">
184 <h4>Previous topic</h4>
185 <p class="topless"><a href="install.html"
186 title="previous chapter">Installation</a></p>
187 <h4>Next topic</h4>
188 <p class="topless"><a href="operations.html"
189 title="next chapter">reclass operations</a></p>
190<div id="searchbox" style="display: none">
191 <h3>Quick search</h3>
192 <form class="search" action="search.html" method="get">
193 <input type="text" name="q" />
194 <input type="submit" value="Go" />
195 <input type="hidden" name="check_keywords" value="yes" />
196 <input type="hidden" name="area" value="default" />
197 </form>
198 <p class="searchtip" style="font-size: 90%">
199 Enter search terms or a module, class or function name.
200 </p>
201</div>
202<script type="text/javascript">$('#searchbox').show(0);</script>
203 </div>
204 </div>
205 <div class="clearer"></div>
206 </div>
207 <div class="related">
208 <h3>Navigation</h3>
209 <ul>
210 <li class="right" style="margin-right: 10px">
211 <a href="genindex.html" title="General Index"
212 >index</a></li>
213 <li class="right" >
214 <a href="operations.html" title="reclass operations"
215 >next</a> |</li>
216 <li class="right" >
217 <a href="install.html" title="Installation"
218 >previous</a> |</li>
219 <li><a href="index.html">reclass</a> &raquo;</li>
220 </ul>
221 </div>
222 <div class="footer">
223 &copy; Copyright 2013, martin f. krafft.
224 Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
225 </div>
226 </body>
227</html>