Gitiles
Code Review Sign In
gerrit.mcp.mirantis.com / packaging / sources / reclass / refs/heads/gh-pages / . / operations.html
blob: 0d9d710f69a6d61a761e6aad286983a906b4fee8 [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 operations &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="Using reclass" href="usage.html" />
28 <link rel="prev" title="reclass concepts" href="concepts.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="usage.html" title="Using reclass"
39 accesskey="N">next</a> |</li>
40 <li class="right" >
41 <a href="concepts.html" title="reclass concepts"
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-operations">
53<h1>reclass operations<a class="headerlink" href="#reclass-operations" title="Permalink to this headline"></a></h1>
54<div class="section" id="yaml-fs-storage">
55<h2>YAML FS storage<a class="headerlink" href="#yaml-fs-storage" title="Permalink to this headline"></a></h2>
56<p>While <strong>reclass</strong> has been built to support different storage backends through
57plugins, currently only the <tt class="docutils literal"><span class="pre">yaml_fs</span></tt> storage backend exists. This is a very
58simple, yet powerful, YAML-based backend, using flat files on the filesystem
59(as suggested by the <tt class="docutils literal"><span class="pre">_fs</span></tt> postfix).</p>
60<p><tt class="docutils literal"><span class="pre">yaml_fs</span></tt> works with two directories, one for node definitions, and another
61for class definitions. The two directories must not be the same, nor can one
62be a parent of the other.</p>
63<p>Files in those directories are YAML-files, specifying key-value pairs. The
64following three keys are read by <strong>reclass</strong>:</p>
65<table border="1" class="docutils">
66<colgroup>
67<col width="16%" />
68<col width="84%" />
69</colgroup>
70<thead valign="bottom">
71<tr class="row-odd"><th class="head">Key</th>
72<th class="head">Description</th>
73</tr>
74</thead>
75<tbody valign="top">
76<tr class="row-even"><td>classes</td>
77<td>a list of parent classes</td>
78</tr>
79<tr class="row-odd"><td>appliations</td>
80<td>a list of applications to append to the applications defined by
81ancestors. If an application name starts with <tt class="docutils literal"><span class="pre">~</span></tt>, it would
82remove this application from the list, if it had already been
83added — but it does not prevent a future addition.
84E.g. <tt class="docutils literal"><span class="pre">~firewalled</span></tt></td>
85</tr>
86<tr class="row-even"><td>parameters</td>
87<td><p class="first">key-value pairs to set defaults in class definitions, override
88existing data, or provide node-specific information in node
89specifications.
90By convention, parameters corresponding to an application
91should be provided as subkey-value pairs, keyed by the name of
92the application, e.g.:</p>
93<div class="last highlight-python"><div class="highlight"><pre>applications:
94- ssh.server
95parameters:
96 ssh.server:
97 permit_root_login: no
98</pre></div>
99</div>
100</td>
101</tr>
102<tr class="row-odd"><td>environment</td>
103<td>only relevant for nodes, this allows to specify an &#8220;environment&#8221;
104into which the node definition is supposed to be place.</td>
105</tr>
106</tbody>
107</table>
108<p>Classes files may reside in subdirectories, which act as namespaces. For
109instance, a class <tt class="docutils literal"><span class="pre">ssh.server</span></tt> will result in the class definition to be
110read from <tt class="docutils literal"><span class="pre">ssh/server.yml</span></tt>. Specifying just <tt class="docutils literal"><span class="pre">ssh</span></tt> will cause the class
111data to be read from <tt class="docutils literal"><span class="pre">ssh/init.yml</span></tt> or <tt class="docutils literal"><span class="pre">ssh.yml</span></tt>. Note, however, that only
112one of those two may be present.</p>
113<p>Nodes may also be defined in subdirectories. However, node names (filename)
114must be unique across all subdirectories, and <strong>reclass</strong> will exit with an
115error if a node is defined multiple times. Subdirectories therefore really
116only exist for the administrator&#8217;s local data structuring. They may be used in
117mappings (see below) to tag additional classes onto nodes.</p>
118</div>
119<div class="section" id="data-merging">
120<h2>Data merging<a class="headerlink" href="#data-merging" title="Permalink to this headline"></a></h2>
121<p><strong>reclass</strong> has two modes of operation: node information retrieval and inventory
122listing. The second is really just a loop of the first across all defined
123nodes, and needs not be further described.</p>
124<p>When retrieving information about a node, <strong>reclass</strong> first obtains the node
125definition from the storage backend. Then, it iterates the list of classes
126defined for the node and recursively asks the storage backend for each class
127definition (unless already cached).</p>
128<p>Next, <strong>reclass</strong> recursively descends each class, looking at the classes it
129defines, and so on, until a leaf node is reached, i.e. a class that references
130no other classes.</p>
131<p>Now, the merging starts. At every step, the list of applications and the set
132of parameters at each level is merged into what has been accumulated so far.</p>
133<p>Merging of parameters is done &#8220;deeply&#8221;, meaning that lists and dictionaries
134are extended (recursively), rather than replaced. However, a scalar value
135<em>does</em> overwrite a dictionary or list value. While the scalar could be
136appended to an existing list, there is no sane default assumption in the
137context of a dictionary, so this behaviour seems the most logical. Plus, it
138allows for a dictionary to be erased by overwriting it with the null value.</p>
139<p>After all classes (and the classes they reference) have been visited,
140<strong>reclass</strong> finally merges the applications list and parameters defined for the
141node into what has been accumulated during the processing of the classes, and
142returns the final result.</p>
143</div>
144<div class="section" id="wildcard-regexp-mappings">
145<h2>Wildcard/Regexp mappings<a class="headerlink" href="#wildcard-regexp-mappings" title="Permalink to this headline"></a></h2>
146<p>Using the <a class="reference internal" href="configfile.html"><em>configuration file</em></a>, it is also possible to
147provide a list mappings between node names and classes. For instance:</p>
148<div class="highlight-python"><div class="highlight"><pre>class_mappings:
149 - \* default
150 - /^www\d+/ webserver
151 - \*.ch hosted@switzerland another_class_to_show_that_it_can_take_lists
152</pre></div>
153</div>
154<p>This will assign the <tt class="docutils literal"><span class="pre">default</span></tt> class to all nodes (make sure to escape
155a leading asterisk (*) to keep YAML happy), <tt class="docutils literal"><span class="pre">webserver</span></tt> to all nodes named
156<tt class="docutils literal"><span class="pre">www1</span></tt> or <tt class="docutils literal"><span class="pre">www999</span></tt>, and <tt class="docutils literal"><span class="pre">hosted-in-switzerland</span></tt> to all nodes whose names
157end with <tt class="docutils literal"><span class="pre">.ch</span></tt> (again, note the escaped leading asterisk). Multiple classes
158can be assigned to each mapping by providing a space-separated list (class
159names cannot contain spaces anyway).</p>
160<div class="admonition warning">
161<p class="first admonition-title">Warning</p>
162<p class="last">The class mappings do not really belong in the configuration file, as they
163are data, not configuration inmformation. Therefore, they are likely going
164to move elsewhere, but I have not quite figured out to where. Most likely,
165there will be an additional file, specified in the configuration file, which
166then lists the mappings.</p>
167</div>
168<p>Note that mappings are not designed to replace node definitions. Mappings can
169be used to pre-populate the classes of existing nodes, but you still need to
170define all nodes (and if only to allow them to be enumerated for the
171inventory).</p>
172<p>The mapped classes can also contain backreferences when regular expressions
173are used, although they need to be escaped, e.g.:</p>
174<div class="highlight-python"><div class="highlight"><pre>class_mappings:
175 - /\.(\S+)$/ tld-\\1
176</pre></div>
177</div>
178<p>Furthermore, since the outer slashes (&#8216;/&#8217;) are used to &#8220;quote&#8221; the regular
179expression, <em>any</em> slashes within the regular expression must be escaped. For
180instance, the following class mapping assigns a <tt class="docutils literal"><span class="pre">subdir-X</span></tt> class to all
181nodes that are defined in a subdirectory (using yaml_fs):</p>
182<div class="highlight-python"><div class="highlight"><pre>class_mappings:
183 - /^([^\/]+)\// subdir-\\1
184</pre></div>
185</div>
186</div>
187<div class="section" id="parameter-interpolation">
188<h2>Parameter interpolation<a class="headerlink" href="#parameter-interpolation" title="Permalink to this headline"></a></h2>
189<p>Parameters may reference each other, including deep references, e.g.:</p>
190<div class="highlight-python"><div class="highlight"><pre>parameters:
191 location: Munich, Germany
192 motd:
193 header: This node sits in ${location}
194 for_demonstration: ${motd:header}
195 dict_reference: ${motd}
196</pre></div>
197</div>
198<p>After merging and interpolation, which happens automatically inside the
199storage modules, the <tt class="docutils literal"><span class="pre">for_demonstration</span></tt> parameter will have a value of
200&#8220;This node sits in Munich, Germany&#8221;.</p>
201<p>Types are preserved if the value contains nothing but a reference. Hence, the
202value of <tt class="docutils literal"><span class="pre">dict_reference</span></tt> will actually be a dictionary.</p>
203<p>You should now be ready to <a class="reference internal" href="usage.html"><em>use reclass</em></a>!</p>
204</div>
205</div>
206
207
208 </div>
209 </div>
210 </div>
211 <div class="sphinxsidebar">
212 <div class="sphinxsidebarwrapper">
213 <h3><a href="index.html">Table Of Contents</a></h3>
214 <ul>
215<li><a class="reference internal" href="#">reclass operations</a><ul>
216<li><a class="reference internal" href="#yaml-fs-storage">YAML FS storage</a></li>
217<li><a class="reference internal" href="#data-merging">Data merging</a></li>
218<li><a class="reference internal" href="#wildcard-regexp-mappings">Wildcard/Regexp mappings</a></li>
219<li><a class="reference internal" href="#parameter-interpolation">Parameter interpolation</a></li>
220</ul>
221</li>
222</ul>
223
224 <h4>Previous topic</h4>
225 <p class="topless"><a href="concepts.html"
226 title="previous chapter">reclass concepts</a></p>
227 <h4>Next topic</h4>
228 <p class="topless"><a href="usage.html"
229 title="next chapter">Using reclass</a></p>
230<div id="searchbox" style="display: none">
231 <h3>Quick search</h3>
232 <form class="search" action="search.html" method="get">
233 <input type="text" name="q" />
234 <input type="submit" value="Go" />
235 <input type="hidden" name="check_keywords" value="yes" />
236 <input type="hidden" name="area" value="default" />
237 </form>
238 <p class="searchtip" style="font-size: 90%">
239 Enter search terms or a module, class or function name.
240 </p>
241</div>
242<script type="text/javascript">$('#searchbox').show(0);</script>
243 </div>
244 </div>
245 <div class="clearer"></div>
246 </div>
247 <div class="related">
248 <h3>Navigation</h3>
249 <ul>
250 <li class="right" style="margin-right: 10px">
251 <a href="genindex.html" title="General Index"
252 >index</a></li>
253 <li class="right" >
254 <a href="usage.html" title="Using reclass"
255 >next</a> |</li>
256 <li class="right" >
257 <a href="concepts.html" title="reclass concepts"
258 >previous</a> |</li>
259 <li><a href="index.html">reclass</a> &raquo;</li>
260 </ul>
261 </div>
262 <div class="footer">
263 &copy; Copyright 2013, martin f. krafft.
264 Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
265 </div>
266 </body>
267</html>