<!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 the Python API — Ansible v0.0.1 documentation</title> <link rel="stylesheet" href="_static/default.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <link rel="stylesheet" href="_static/bootstrap.css" type="text/css" /> <link rel="stylesheet" href="_static/bootstrap-sphinx.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '', VERSION: '0.0.1', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: false }; </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> <script type="text/javascript" src="_static/bootstrap-dropdown.js"></script> <script type="text/javascript" src="_static/bootstrap-scrollspy.js"></script> <link rel="top" title="Ansible v0.0.1 documentation" href="index.html" /> <link rel="next" title="Frequently Asked Questions" href="faq.html" /> <link rel="prev" title="Playbooks" href="playbooks.html" /> <script type="text/javascript"> (function () { /** * Patch TOC list. * * Will mutate the underlying span to have a correct ul for nav. * * @param $span: Span containing nested UL's to mutate. * @param minLevel: Starting level for nested lists. (1: global, 2: local). */ var patchToc = function ($span, minLevel) { var $tocList = $("<ul/>").attr('class', "dropdown-menu"), findA; // Find all a "internal" tags, traversing recursively. findA = function ($elem, level) { var level = level || 0, $items = $elem.find("> li > a.internal, > ul, > li > ul"); // Iterate everything in order. $items.each(function (index, item) { var $item = $(item), tag = item.tagName.toLowerCase(), pad = 10 + ((level - minLevel) * 10); if (tag === 'a' && level >= minLevel) { // Add to existing padding. $item.css('padding-left', pad + "px"); // Add list element. $tocList.append($("<li/>").append($item)); } else if (tag === 'ul') { // Recurse. findA($item, level + 1); } }); }; // Start construction and return. findA($span); // Wipe out old list and patch in new one. return $span.empty("ul").append($tocList); }; $(document).ready(function () { // Patch the global and local TOC's to be bootstrap-compliant. patchToc($("span.globaltoc"), 1); patchToc($("span.localtoc"), 2); // Activate. $('#topbar').dropdown(); }); }()); </script> <script type="text/javascript"> var _gaq = _gaq || []; _gaq.push(['_setAccount', 'UA-29861888-1']); _gaq.push(['_trackPageview']); (function() { var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); })(); </script> </head> <body> <div class="topbar" data-scrollspy="scrollspy" > <div class="topbar-inner"> <div class="container"> <a class="brand" href="index.html">Ansible</a> <ul class="nav"> <li class="dropdown" data-dropdown="dropdown"> <a href="index.html" class="dropdown-toggle">Site</a> <span class="globaltoc"><ul class="current"> <li class="toctree-l1"><a class="reference internal" href="gettingstarted.html">Downloads & Getting Started</a></li> <li class="toctree-l1"><a class="reference internal" href="patterns.html">The Inventory File, Patterns, and Groups</a></li> <li class="toctree-l1"><a class="reference internal" href="examples.html">Command Line Examples</a></li> <li class="toctree-l1"><a class="reference internal" href="modules.html">Ansible Modules</a></li> <li class="toctree-l1"><a class="reference internal" href="YAMLScripts.html">YAML Format</a></li> <li class="toctree-l1"><a class="reference internal" href="playbooks.html">Playbooks</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="">Using the Python API</a></li> <li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li> <li class="toctree-l1"><a class="reference internal" href="man.html">Man Pages</a></li> </ul> </span> </li> <li class="dropdown" data-dropdown="dropdown"> <a href="#" class="dropdown-toggle">Page</a> <span class="localtoc"><ul> <li><a class="reference internal" href="#">Using the Python API</a><ul> <li><a class="reference internal" href="#detailed-api-example">Detailed API Example</a></li> </ul> </li> </ul> </span> </li> <li><a href="playbooks.html" title="previous chapter">« Playbooks</a></li> <li><a href="faq.html" title="next chapter">Frequently Asked Questions »</a></li> </ul> <ul class="nav secondary-nav"> <form class="pull-left" action="search.html" method="get"> <input type="text" name="q" placeholder="Search" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </ul> </div> </div> </div> <div class="container"> <div class="section" id="using-the-python-api"> <h1>Using the Python API<a class="headerlink" href="#using-the-python-api" title="Permalink to this headline">¶</a></h1> <p>The Python API is very powerful, and is how the ansible CLI and ansible-playbook are implemented.</p> <p>It’s pretty simple:</p> <div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">ansible.runner</span> <span class="n">runner</span> <span class="o">=</span> <span class="n">ansible</span><span class="o">.</span><span class="n">runner</span><span class="o">.</span><span class="n">Runner</span><span class="p">(</span> <span class="n">module_name</span><span class="o">=</span><span class="s">'ping'</span><span class="p">,</span> <span class="n">module_args</span><span class="o">=</span><span class="s">''</span><span class="p">,</span> <span class="n">pattern</span><span class="o">=</span><span class="s">'web*'</span><span class="p">,</span> <span class="n">forks</span><span class="o">=</span><span class="mi">10</span> <span class="p">)</span> <span class="n">datastructure</span> <span class="o">=</span> <span class="n">runner</span><span class="o">.</span><span class="n">run</span><span class="p">()</span> </pre></div> </div> <p>The run method returns results per host, grouped by whether they could be contacted or not. Return types are module specific, as expressed in the ‘ansible-modules’ documentation.:</p> <div class="highlight-python"><pre>{ "dark" : { "web1.example.com" : "failure message" } "contacted" : { "web2.example.com" : 1 } }</pre> </div> <p>A module can return any type of JSON data it wants, so Ansible can be used as a framework to rapidly build powerful applications and scripts.</p> <div class="section" id="detailed-api-example"> <h2>Detailed API Example<a class="headerlink" href="#detailed-api-example" title="Permalink to this headline">¶</a></h2> <p>The following script prints out the uptime information for all hosts:</p> <div class="highlight-python"><div class="highlight"><pre><span class="c">#!/usr/bin/python</span> <span class="kn">import</span> <span class="nn">ansible.runner</span> <span class="kn">import</span> <span class="nn">sys</span> <span class="c"># construct the ansible runner and execute on all hosts</span> <span class="n">results</span> <span class="o">=</span> <span class="n">ansible</span><span class="o">.</span><span class="n">runner</span><span class="o">.</span><span class="n">Runner</span><span class="p">(</span> <span class="n">pattern</span><span class="o">=</span><span class="s">'*'</span><span class="p">,</span> <span class="n">forks</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">module_name</span><span class="o">=</span><span class="s">'command'</span><span class="p">,</span> <span class="n">module_args</span><span class="o">=</span><span class="p">[</span><span class="s">'/usr/bin/uptime'</span><span class="p">],</span> <span class="p">)</span><span class="o">.</span><span class="n">run</span><span class="p">()</span> <span class="k">if</span> <span class="n">results</span> <span class="ow">is</span> <span class="bp">None</span><span class="p">:</span> <span class="k">print</span> <span class="s">"No hosts found"</span> <span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="k">print</span> <span class="s">"UP ***********"</span> <span class="k">for</span> <span class="p">(</span><span class="n">hostname</span><span class="p">,</span> <span class="n">result</span><span class="p">)</span> <span class="ow">in</span> <span class="n">results</span><span class="p">[</span><span class="s">'contacted'</span><span class="p">]</span><span class="o">.</span><span class="n">items</span><span class="p">():</span> <span class="k">if</span> <span class="ow">not</span> <span class="s">'failed'</span> <span class="ow">in</span> <span class="n">result</span><span class="p">:</span> <span class="k">print</span> <span class="s">"</span><span class="si">%s</span><span class="s"> >>> </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">hostname</span><span class="p">,</span> <span class="n">result</span><span class="p">[</span><span class="s">'stdout'</span><span class="p">])</span> <span class="k">print</span> <span class="s">"FAILED *******"</span> <span class="k">for</span> <span class="p">(</span><span class="n">hostname</span><span class="p">,</span> <span class="n">result</span><span class="p">)</span> <span class="ow">in</span> <span class="n">results</span><span class="p">[</span><span class="s">'contacted'</span><span class="p">]</span><span class="o">.</span><span class="n">items</span><span class="p">():</span> <span class="k">if</span> <span class="s">'failed'</span> <span class="ow">in</span> <span class="n">result</span><span class="p">:</span> <span class="k">print</span> <span class="s">"</span><span class="si">%s</span><span class="s"> >>> </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">hostname</span><span class="p">,</span> <span class="n">result</span><span class="p">[</span><span class="s">'msg'</span><span class="p">])</span> <span class="k">print</span> <span class="s">"DOWN *********"</span> <span class="k">for</span> <span class="p">(</span><span class="n">hostname</span><span class="p">,</span> <span class="n">result</span><span class="p">)</span> <span class="ow">in</span> <span class="n">results</span><span class="p">[</span><span class="s">'dark'</span><span class="p">]</span><span class="o">.</span><span class="n">items</span><span class="p">():</span> <span class="k">print</span> <span class="s">"</span><span class="si">%s</span><span class="s"> >>> </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">hostname</span><span class="p">,</span> <span class="n">result</span><span class="p">)</span> </pre></div> </div> <p>Advanced programmers may also wish to read the source to ansible itself, for it uses the Runner() API (with all available options) to implement the command line tools <tt class="docutils literal"><span class="pre">ansible</span></tt> and <tt class="docutils literal"><span class="pre">ansible-playbook</span></tt>.</p> </div> </div> </div> <footer class="footer"> <div class="container"> <p class="pull-right"><a href="#">Back to top</a></p> <p> © Copyright 2012 Michael DeHaan.<br/> Last updated on Mar 09, 2012.<br/> Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/> </p> </div> </footer> </body> </html>