Gitiles
Code Review Sign In
gerrit.mcp.mirantis.com / packaging / sources / reclass / 3cd2a337f02038c1cd0885b4b893ee8cdc4f60bc / . / salt.html
blob: 385ce546230945b1d811bfe2223f3bda0b129d51 [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>Using reclass with Salt &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 with Ansible" href="ansible.html" />
28 <link rel="prev" title="reclass configuration file" href="configfile.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="ansible.html" title="Using reclass with Ansible"
39 accesskey="N">next</a> |</li>
40 <li class="right" >
41 <a href="configfile.html" title="reclass configuration file"
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="using-reclass-with-salt">
53<h1>Using reclass with Salt<a class="headerlink" href="#using-reclass-with-salt" title="Permalink to this headline"></a></h1>
54<div class="admonition warning">
55<p class="first admonition-title">Warning</p>
56<p class="last">You need Salt 0.17 to use <cite>reclass</cite>, as older versions do not include the
57<cite>reclass</cite> adapter. You could use the <tt class="docutils literal"><span class="pre">cmd_yaml</span></tt> adapters, but at least for
58<tt class="docutils literal"><span class="pre">ext_pillar</span></tt>, they are currently not useable, as they <a class="reference external" href="https://github.com/saltstack/salt/issues/2276">do not export the
59minion ID to the command they run</a>.</p>
60</div>
61<div class="section" id="quick-start">
62<h2>Quick start<a class="headerlink" href="#quick-start" title="Permalink to this headline"></a></h2>
63<p>The following steps should get you up and running quickly with <strong>reclass</strong> and
64<a class="reference external" href="http://saltstack.com/community">Salt</a>. You will need to decide for yourself where to put your <strong>reclass</strong>
65inventory. This can be your first <tt class="docutils literal"><span class="pre">base</span></tt> <tt class="docutils literal"><span class="pre">file_root</span></tt> (the default), or it
66could be <tt class="docutils literal"><span class="pre">/etc/reclass</span></tt>, or <tt class="docutils literal"><span class="pre">/srv/salt</span></tt>. The following shall assume the
67latter.</p>
68<p>Or you can also just look into <tt class="docutils literal"><span class="pre">./examples/salt</span></tt> of your <strong>reclass</strong>
69checkout (<tt class="docutils literal"><span class="pre">/usr/share/doc/examples/salt</span></tt> on Debian-systems), where the
70following steps have already been prepared.</p>
71<p>/…/reclass refers to the location of your <strong>reclass</strong> checkout.</p>
72<ol class="arabic">
73<li><p class="first">Complete the installation steps described in the <a class="reference internal" href="install.html"><em>installation section</em></a>.</p>
74<p>Alternatively, you can also tell Salt via the master config file where to
75look for <strong>reclass</strong>, but then you won&#8217;t be able to interact with
76<strong>reclass</strong> through the command line.</p>
77</li>
78<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
79subdirectory in the <strong>reclass</strong> checkout to e.g. <tt class="docutils literal"><span class="pre">/srv/salt</span></tt>.</p>
80<p>It&#8217;s handy to symlink <strong>reclass</strong>&#8216; Salt adapter itself to that directory:</p>
81<div class="highlight-python"><div class="highlight"><pre>$ ln -s /usr/share/reclass/reclass-salt /srv/salt/states/reclass
82</pre></div>
83</div>
84<p>As you can now just inspect the data right there from the command line:</p>
85<div class="highlight-python"><div class="highlight"><pre>$ ./reclass --top
86</pre></div>
87</div>
88<p>If you don&#8217;t want to do this, you can also let <strong>reclass</strong> know where to
89look for the inventory with the following contents in
90<tt class="docutils literal"><span class="pre">$HOME/reclass-config.yml</span></tt>:</p>
91<div class="highlight-python"><div class="highlight"><pre>storage_type: yaml_fs
92base_inventory_uri: /srv/reclass
93</pre></div>
94</div>
95<p>Or you can reuse the first entry of <tt class="docutils literal"><span class="pre">file_roots</span></tt> under <tt class="docutils literal"><span class="pre">base</span></tt> in the Salt
96master config.</p>
97<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
98it&#8217;s the default if you don&#8217;t set it.</p>
99</li>
100<li><p class="first">Check out your inventory by invoking</p>
101<div class="highlight-python"><div class="highlight"><pre>$ reclass-salt --top
102</pre></div>
103</div>
104<p>which should return all the information about all defined nodes, which is
105only <tt class="docutils literal"><span class="pre">localhost</span></tt> in the example. This is essentially the same information
106that you would keep in your <tt class="docutils literal"><span class="pre">top.sls</span></tt> file.</p>
107<p>If you symlinked the script to your inventory base directory, use</p>
108<div class="highlight-python"><div class="highlight"><pre>$ ./reclass --top
109</pre></div>
110</div>
111</li>
112<li><p class="first">See the pillar information for <tt class="docutils literal"><span class="pre">localhost</span></tt>:</p>
113<div class="highlight-python"><div class="highlight"><pre>$ reclass-salt --pillar localhost
114</pre></div>
115</div>
116</li>
117<li><p class="first">Now add <strong>reclass</strong> to <tt class="docutils literal"><span class="pre">/etc/salt/master</span></tt>, like so:</p>
118<div class="highlight-python"><div class="highlight"><pre>reclass: &amp;reclass
119 inventory_base_uri: /srv/salt
120 reclass_source_path: ~/code/reclass
121
122master_tops:
123 […]
124 reclass: *reclass
125
126ext_pillar:
127 - reclass: *reclass
128</pre></div>
129</div>
130<div class="admonition warning">
131<p class="first admonition-title">Warning</p>
132<p class="last">When using <tt class="docutils literal"><span class="pre">ext_pillar</span></tt> and/or <tt class="docutils literal"><span class="pre">master_tops</span></tt>, you should make sure
133that your <tt class="docutils literal"><span class="pre">file_roots</span></tt> paths do not contain a <tt class="docutils literal"><span class="pre">top.sls</span></tt> file. Even
134though they ought to be able to coexist, there are a few sharp edges
135around at the moment, so beware!</p>
136</div>
137<p>If you did not install <strong>reclass</strong> (but you are running it from source),
138you can either specify the source path like above, or you can add it to
139<tt class="docutils literal"><span class="pre">PYTHONPATH</span></tt> before invoking the Salt master, to ensure that Python can
140find it:</p>
141<div class="highlight-python"><div class="highlight"><pre>PYTHONPATH=/…/reclass /etc/init.d/salt-master restart
142</pre></div>
143</div>
144</li>
145<li><p class="first">Provided that you have set up <tt class="docutils literal"><span class="pre">localhost</span></tt> as a Salt minion, the following
146commands should now return the same data as above, but processed through
147salt:</p>
148<div class="highlight-python"><div class="highlight"><pre>$ salt localhost pillar.items # shows just the parameters
149$ salt localhost state.show_top # shows only the states (applications)
150</pre></div>
151</div>
152<p>Alternatively, if you don&#8217;t have the Salt minion running yet:</p>
153<div class="highlight-python"><div class="highlight"><pre>$ salt-call pillar.items # shows just the parameters
154$ salt-call state.show_top # shows only the states (applications)
155</pre></div>
156</div>
157</li>
158<li><p class="first">You can also invoke <strong>reclass</strong> directly, which gives a slightly different
159view onto the same data, i.e. before it has been adapted for Salt:</p>
160<div class="highlight-python"><div class="highlight"><pre>$ reclass --inventory
161$ reclass --nodeinfo localhost
162</pre></div>
163</div>
164</li>
165</ol>
166</div>
167<div class="section" id="configuration-file-and-master-configuration">
168<h2>Configuration file and master configuration<a class="headerlink" href="#configuration-file-and-master-configuration" title="Permalink to this headline"></a></h2>
169<p>Even though the Salt adapter of <strong>reclass</strong> looks for and reads the
170<a class="reference internal" href="configfile.html"><em>configuration file</em></a>, a better means to pass information to
171the adapter is via Salt&#8217;s master configuration file, as shown above. Not all
172configuration options can be passed this way (e.g. <tt class="docutils literal"><span class="pre">output</span></tt> is hardcoded to
173YAML, which Salt uses), but it <em>is</em> possible to specify <a class="reference internal" href="operations.html"><em>class mappings</em></a> next to all the storage-specific options.</p>
174<div class="admonition warning">
175<p class="first admonition-title">Warning</p>
176<p class="last">The Salt CLI adapter does <em>not</em> read Salt&#8217;s master configuration, so if you
177are calling <tt class="docutils literal"><span class="pre">reclass-salt</span></tt> from the command-line (the CLI exists for
178debugging purposes, mainly), be aware that it will be run in a different
179environment than when Salt queries reclass directly.</p>
180</div>
181</div>
182<div class="section" id="integration-with-salt">
183<h2>Integration with Salt<a class="headerlink" href="#integration-with-salt" title="Permalink to this headline"></a></h2>
184<p><strong>reclass</strong> hooks into Salt at two different points: <tt class="docutils literal"><span class="pre">master_tops</span></tt> and
185<tt class="docutils literal"><span class="pre">ext_pillar</span></tt>. For both, Salt provides plugins. These plugins need to know
186where to find <strong>reclass</strong>, so if <strong>reclass</strong> is not properly installed (but
187you are running it from source), make sure to export <tt class="docutils literal"><span class="pre">PYTHONPATH</span></tt>
188accordingly before you start your Salt master, or specify the path in the
189master configuration file, as show above.</p>
190<p>Salt has no concept of &#8220;nodes&#8221;, &#8220;applications&#8221;, &#8220;parameters&#8221;, and &#8220;classes&#8221;.
191Therefore it is necessary to explain how those correspond to Salt. Crudely,
192the following mapping exists:</p>
193<table border="1" class="docutils">
194<colgroup>
195<col width="45%" />
196<col width="55%" />
197</colgroup>
198<thead valign="bottom">
199<tr class="row-odd"><th class="head"><strong>reclass</strong> concept</th>
200<th class="head">Salt terminology</th>
201</tr>
202</thead>
203<tbody valign="top">
204<tr class="row-even"><td>nodes</td>
205<td>hosts</td>
206</tr>
207<tr class="row-odd"><td>classes</td>
208<td>(none) <a class="footnote-reference" href="#nodegroups" id="id1">[1]</a></td>
209</tr>
210<tr class="row-even"><td>applications</td>
211<td>states</td>
212</tr>
213<tr class="row-odd"><td>parameters</td>
214<td>pillar</td>
215</tr>
216<tr class="row-even"><td>environment</td>
217<td>environment</td>
218</tr>
219</tbody>
220</table>
221<table class="docutils footnote" frame="void" id="nodegroups" rules="none">
222<colgroup><col class="label" /><col /></colgroup>
223<tbody valign="top">
224<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>See <a class="reference external" href="https://github.com/saltstack/salt/issues/5787">Salt issue #5787</a> for steps into the direction of letting
225<strong>reclass</strong> provide nodegroup information.</td></tr>
226</tbody>
227</table>
228<p>Whatever applications you define for a node will become states applicable to
229a host. If those applications are added via ancestor classes, then that&#8217;s
230fine, but currently, Salt does not do anything with the classes ancestry.</p>
231<p>Similarly, all parameters that are collected and merged eventually end up in
232the pillar data of a specific node.</p>
233<p>The pillar data of a node include all the information about classes and
234applications, so you could theoretically use them to target your Salt calls at
235groups of nodes defined in the <strong>reclass</strong> inventory, e.g.</p>
236<div class="highlight-python"><div class="highlight"><pre>salt -I __reclass__:classes:salt_minion test.ping
237</pre></div>
238</div>
239<p>Unfortunately, this does not work yet, please stay tuned, and let me know
240if you figure out a way. <a class="reference external" href="https://github.com/saltstack/salt/issues/5787">Salt issue #5787</a> is also of relevance.</p>
241<p>Optionally, data from pillars that run before the <strong>reclass</strong> <tt class="docutils literal"><span class="pre">ext_pillar</span></tt>
242(i.e. Salt&#8217;s builtin <tt class="docutils literal"><span class="pre">pillar_roots</span></tt>, as well as other <tt class="docutils literal"><span class="pre">ext_pillar</span></tt> modules
243listed before the <tt class="docutils literal"><span class="pre">reclass_adapter</span></tt>) can be made available to <strong>reclass</strong>.
244Please use this with caution as referencing data from Salt in the inventory
245will make it harder or impossible to run <strong>reclass</strong> in other environments. This
246feature is therefore turned off by default and must be explicitly enabled in
247the Salt master configuration file, like this:</p>
248<div class="highlight-python"><div class="highlight"><pre>ext_pillar:
249 - reclass:
250 […]
251 propagate_pillar_data_to_reclass: True
252</pre></div>
253</div>
254<p>Unfortunately, to use this, currently you cannot use YAML references (i.e.
255<tt class="docutils literal"><span class="pre">*reclass</span></tt>) as shown above, as the <tt class="docutils literal"><span class="pre">master_tops</span></tt> subsystem does not accept
256this configuration parameter, and there seems to be no way to extend an alias.
257Specifically, the following is not possible — let me know if it is!:</p>
258<div class="highlight-python"><div class="highlight"><pre>ext_pillar:
259 - reclass: *reclass # WARNING: this does not work!
260 propagate_pillar_data_to_reclass: True
261</pre></div>
262</div>
263</div>
264</div>
265
266
267 </div>
268 </div>
269 </div>
270 <div class="sphinxsidebar">
271 <div class="sphinxsidebarwrapper">
272 <h3><a href="index.html">Table Of Contents</a></h3>
273 <ul>
274<li><a class="reference internal" href="#">Using reclass with Salt</a><ul>
275<li><a class="reference internal" href="#quick-start">Quick start</a></li>
276<li><a class="reference internal" href="#configuration-file-and-master-configuration">Configuration file and master configuration</a></li>
277<li><a class="reference internal" href="#integration-with-salt">Integration with Salt</a></li>
278</ul>
279</li>
280</ul>
281
282 <h4>Previous topic</h4>
283 <p class="topless"><a href="configfile.html"
284 title="previous chapter">reclass configuration file</a></p>
285 <h4>Next topic</h4>
286 <p class="topless"><a href="ansible.html"
287 title="next chapter">Using reclass with Ansible</a></p>
288<div id="searchbox" style="display: none">
289 <h3>Quick search</h3>
290 <form class="search" action="search.html" method="get">
291 <input type="text" name="q" />
292 <input type="submit" value="Go" />
293 <input type="hidden" name="check_keywords" value="yes" />
294 <input type="hidden" name="area" value="default" />
295 </form>
296 <p class="searchtip" style="font-size: 90%">
297 Enter search terms or a module, class or function name.
298 </p>
299</div>
300<script type="text/javascript">$('#searchbox').show(0);</script>
301 </div>
302 </div>
303 <div class="clearer"></div>
304 </div>
305 <div class="related">
306 <h3>Navigation</h3>
307 <ul>
308 <li class="right" style="margin-right: 10px">
309 <a href="genindex.html" title="General Index"
310 >index</a></li>
311 <li class="right" >
312 <a href="ansible.html" title="Using reclass with Ansible"
313 >next</a> |</li>
314 <li class="right" >
315 <a href="configfile.html" title="reclass configuration file"
316 >previous</a> |</li>
317 <li><a href="index.html">reclass</a> &raquo;</li>
318 </ul>
319 </div>
320 <div class="footer">
321 &copy; Copyright 2013, martin f. krafft.
322 Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
323 </div>
324 </body>
325</html>