Clarify stderr behavior of modules

pull/1256/head
Michael DeHaan 13 years ago
parent aed5414cb6
commit d049d425e6

@ -247,7 +247,7 @@ languages:
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Apr 25, 2012.<br/>
Last updated on Apr 27, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

@ -331,7 +331,7 @@ a conf.d file appropriately or something similar. Who knows.</p>
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Apr 25, 2012.<br/>
Last updated on Apr 27, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

@ -346,7 +346,7 @@ a simplified syntax for this.</p>
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Apr 25, 2012.<br/>
Last updated on Apr 27, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

@ -353,7 +353,7 @@ tasks &#8211; whether for a QA sytem, build system, or anything you can think of
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Apr 25, 2012.<br/>
Last updated on Apr 27, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

@ -162,7 +162,7 @@ s.parentNode.insertBefore(ga, s);
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Apr 25, 2012.<br/>
Last updated on Apr 27, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

@ -315,7 +315,7 @@ explore, but you already have a fully working infrastructure!</p>
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Apr 25, 2012.<br/>
Last updated on Apr 27, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

@ -401,7 +401,7 @@ Puppet Labs, and rPath. Reach Michael by email <a class="reference external" hr
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Apr 25, 2012.<br/>
Last updated on Apr 27, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

@ -176,9 +176,9 @@ a module that just outputs the current time.</p>
<p>We are going to use Python here but any language is possible. Only File I/O and outputing to standard
out are required. So, bash, C++, clojure, Python, Ruby, whatever you want
is fine.</p>
<p>It&#8217;s obvious that you would never really need to build a module to set the system time,
the &#8216;command&#8217; module could already be used to do this. However, it makes for a decent example.
Reading the modules that come with ansible (linked above) is a great way to learn how to write
<p>So, here&#8217;s an example. You would never really need to build a module to set the system time,
the &#8216;command&#8217; module could already be used to do this. Though we&#8217;re going to make one.</p>
<p>Reading the modules that come with ansible (linked above) is a great way to learn how to write
modules. Keep in mind, though, that some modules in ansible&#8217;s source tree are internalisms,
so look at <cite>service</cite> or <cite>yum</cite>, and don&#8217;t stare too close into things like <cite>async_wrapper</cite> or
you&#8217;ll turn to stone. Nobody ever executes async_wrapper directly.</p>
@ -331,6 +331,12 @@ json isn&#8217;t in the Python standard library until 2.5.:</p>
</div>
<p>Because the output is supposed to be valid JSON. Except that&#8217;s not quite true,
but we&#8217;ll get to that later.</p>
<p>Further, modules must not output anything on stderr, even if the JSON returned
out stdout is valid. This is due to the internals of our SSH library, more or less.</p>
<p>If a module returns stderr or otherwise fails to produce valid JSON, the actual output
will still be shown in Ansible, however, but the command will not succeed.</p>
<p>Always use the hacking/test-module script when developing modules and it will warn
you about these kind of things.</p>
</div>
<div class="section" id="conventions">
<h2>Conventions<a class="headerlink" href="#conventions" title="Permalink to this headline"></a></h2>
@ -396,7 +402,7 @@ Stop by the mailing list to inquire about requirements.</p>
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Apr 25, 2012.<br/>
Last updated on Apr 27, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

@ -724,7 +724,7 @@ yum pkg=httpd state=installed</pre>
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Apr 25, 2012.<br/>
Last updated on Apr 27, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

@ -268,6 +268,10 @@ style file with a YAML one.:</p>
- asdf: 1234</pre>
</div>
<p>Tip: Be sure to start your YAML file with the YAML record designator &#8220;&#8212;&#8221;.</p>
<p>NOTE: variables specified in playbooks will override variables specified
in the host file. Further, if a host is in multiple groups, currently, the
variables set by the last loaded group will win over variables set in other
groups. This behavior may be refined in future releases.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
@ -291,7 +295,7 @@ style file with a YAML one.:</p>
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Apr 25, 2012.<br/>
Last updated on Apr 27, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

@ -684,7 +684,7 @@ Let&#8217;s run a playbook using a parallelism level of 10:</p>
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Apr 25, 2012.<br/>
Last updated on Apr 27, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

@ -17,8 +17,9 @@ We are going to use Python here but any language is possible. Only File I/O and
out are required. So, bash, C++, clojure, Python, Ruby, whatever you want
is fine.
It's obvious that you would never really need to build a module to set the system time,
the 'command' module could already be used to do this. However, it makes for a decent example.
So, here's an example. You would never really need to build a module to set the system time,
the 'command' module could already be used to do this. Though we're going to make one.
Reading the modules that come with ansible (linked above) is a great way to learn how to write
modules. Keep in mind, though, that some modules in ansible's source tree are internalisms,
so look at `service` or `yum`, and don't stare too close into things like `async_wrapper` or
@ -187,6 +188,15 @@ You should also never do this in a module::
Because the output is supposed to be valid JSON. Except that's not quite true,
but we'll get to that later.
Further, modules must not output anything on stderr, even if the JSON returned
out stdout is valid. This is due to the internals of our SSH library, more or less.
If a module returns stderr or otherwise fails to produce valid JSON, the actual output
will still be shown in Ansible, however, but the command will not succeed.
Always use the hacking/test-module script when developing modules and it will warn
you about these kind of things.
Conventions
```````````

@ -179,7 +179,7 @@ s.parentNode.insertBefore(ga, s);
<p class="pull-right"><a href="#">Back to top</a></p>
<p>
&copy; Copyright 2012 Michael DeHaan.<br/>
Last updated on Apr 25, 2012.<br/>
Last updated on Apr 27, 2012.<br/>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
</p>
</div>

File diff suppressed because one or more lines are too long
Loading…
Cancel
Save