Docs rebuild

This commit is contained in:
Michael DeHaan 2012-04-12 22:47:15 -04:00
parent 449725a214
commit e030d0854c
7 changed files with 69 additions and 34 deletions

View file

@ -165,7 +165,7 @@ s.parentNode.insertBefore(ga, s);
<div class="section" id="api-integrations">
<h1>API &amp; Integrations<a class="headerlink" href="#api-integrations" title="Permalink to this headline"></a></h1>
<p>There are two major ways to use Ansible from an API perspective. The primary way
is to use the Ansible python API to control nodes. Ansible is written in it&#8217;s own
is to use the Ansible python API to control nodes. Ansible is written in its own
API so you have a considerable amount of power there.</p>
<p>Also covered here, Ansible&#8217;s
list of hosts, groups, and variables assigned to each host can be driven from
@ -244,8 +244,7 @@ command line tools <tt class="docutils literal"><span class="pre">ansible</span>
in a different system. Frequent examples include LDAP, <a class="reference external" href="http://cobbler.github.com">Cobbler</a>,
or a piece of expensive enterprisey CMDB software. Ansible easily supports all
of these options via an external interventory system.</p>
<p>If you have a data store system where an Ansible external inventory script doesn&#8217;t already exist, this may require a little coding,J
but we have a <a class="reference external" href="https://github.com/ansible/ansible/blob/master/examples/scripts/cobbler_external_inventory.py">Cobbler example</a> in the main source tree &#8211; but it&#8217;s pretty simple, as we&#8217;ll explain below &#8211; that would provide a good starting point. Like with modules, it&#8217;s possible to build an external inventory script in any language, as long as it returns JSON.</p>
<p>If you have a data store system where an Ansible external inventory script doesn&#8217;t already exist, this may require a little coding, but we have a <a class="reference external" href="https://github.com/ansible/ansible/blob/master/examples/scripts/cobbler_external_inventory.py">Cobbler example</a> in the main source tree &#8211; but it&#8217;s pretty simple, as we&#8217;ll explain below &#8211; that would provide a good starting point. Like with modules, it&#8217;s possible to build an external inventory script in any language, as long as it returns JSON.</p>
<p>If you are familiar with Puppet terminology, this concept is basically the same as &#8216;external nodes&#8217;, with the slight difference that it also defines which hosts are managed.</p>
<div class="section" id="script-conventions">
<h3>Script Conventions<a class="headerlink" href="#script-conventions" title="Permalink to this headline"></a></h3>

View file

@ -234,7 +234,7 @@ even bash ... just return some output in JSON format. You don&#8217;t need to k
as it can. A system shouldn&#8217;t be half correct, especially if we&#8217;re planning on configuring
other systems that depend on that system.</p>
<p>Ansible also has a VERY short learning curve &#8211; but it also has less language constructs and
does not create it&#8217;s own programming language. What constructs Ansible does have should be enough to cover 80% or so of the cases of most Puppet users, and it should scale equally well (not having a server is
does not create its own programming language. What constructs Ansible does have should be enough to cover 80% or so of the cases of most Puppet users, and it should scale equally well (not having a server is
almost like cheating).</p>
<p>I also suspect some Ansible users will actually use Ansible to trigger Puppet &#8211; using the git
module to checkout a Puppet module hierachy from source, and the command module to run
@ -284,7 +284,7 @@ run multiple commands in seperate forks, thanks to the magic behind
Python&#8217;s multiprocessing module.</p>
<p>If you need to address 500 machines you can decide if you want to try
to contact 5 at a time, or 50 at a time.
It&#8217;s up to you and how much power you can throw at it, but it&#8217;s heritage
It&#8217;s up to you and how much power you can throw at it, but its heritage
is about handling those kinds of use cases.</p>
<p>There are no daemons so it&#8217;s entirely up to you. When you are aren&#8217;t using
Ansible, it is not consuming any resources.</p>

View file

@ -220,6 +220,7 @@ you with questions about Ansible.</p>
<li>See the presentation on <a class="reference external" href="http://speakerdeck.com/u/mpdehaan/p/ansible">Speakerdeck</a></li>
<li>Visit the <a class="reference external" href="http://groups.google.com/group/ansible-project">Google Group</a></li>
<li>Chat on <a class="reference external" href="http://webchat.freenode.net/?channels=ansible">FreeNode</a></li>
<li>View or add to the the <a class="reference external" href="https://github.com/ansible/ansible-contrib">Contrib Repo</a> on Github</li>
</ul>
<img src="http://groups.google.com/intl/en/images/logos/groups_logo_sm.gif" height=30 width=140 alt="Google Groups">
<br/>
@ -269,6 +270,7 @@ Email: <input type=text name=email>&nbsp;&nbsp;<input type=submit name="sub" val
<li class="toctree-l2"><a class="reference internal" href="modules.html#command">command</a></li>
<li class="toctree-l2"><a class="reference internal" href="modules.html#copy">copy</a></li>
<li class="toctree-l2"><a class="reference internal" href="modules.html#facter">facter</a></li>
<li class="toctree-l2"><a class="reference internal" href="modules.html#fetch">fetch</a></li>
<li class="toctree-l2"><a class="reference internal" href="modules.html#file">file</a></li>
<li class="toctree-l2"><a class="reference internal" href="modules.html#git">git</a></li>
<li class="toctree-l2"><a class="reference internal" href="modules.html#group">group</a></li>
@ -298,6 +300,7 @@ Email: <input type=text name=email>&nbsp;&nbsp;<input type=submit name="sub" val
</li>
<li class="toctree-l2"><a class="reference internal" href="playbooks.html#running-operations-on-change">Running Operations On Change</a></li>
<li class="toctree-l2"><a class="reference internal" href="playbooks.html#power-tricks">Power Tricks</a><ul>
<li class="toctree-l3"><a class="reference internal" href="playbooks.html#local-playbooks">Local Playbooks</a></li>
<li class="toctree-l3"><a class="reference internal" href="playbooks.html#external-variables-and-prompted-or-sensitive-data">External Variables And Prompted or Sensitive Data</a></li>
<li class="toctree-l3"><a class="reference internal" href="playbooks.html#conditional-execution">Conditional Execution</a></li>
<li class="toctree-l3"><a class="reference internal" href="playbooks.html#conditional-imports">Conditional Imports</a></li>

View file

@ -212,7 +212,7 @@ chmod +x ansible/hacking/test-module</pre>
<h2>Reading Input<a class="headerlink" href="#reading-input" title="Permalink to this headline"></a></h2>
<p>Let&#8217;s modify the module to allow setting the current time. We&#8217;ll do this by seeing
if a key value pair in the form <cite>time=&lt;string&gt;</cite> is passed in to the module.</p>
<p>Ansible internally saves arguments to a arguments file. So we must read the file
<p>Ansible internally saves arguments to an arguments file. So we must read the file
and parse it. The arguments file is just a string, so any form of arguments are legal.
Here we&#8217;ll do some basic parsing to treat the input as key=value.</p>
<p>The example usage we are trying to achieve to set the time is:</p>

View file

@ -133,6 +133,7 @@ s.parentNode.insertBefore(ga, s);
<li><a class="reference internal" href="#command">command</a></li>
<li><a class="reference internal" href="#copy">copy</a></li>
<li><a class="reference internal" href="#facter">facter</a></li>
<li><a class="reference internal" href="#fetch">fetch</a></li>
<li><a class="reference internal" href="#file">file</a></li>
<li><a class="reference internal" href="#git">git</a></li>
<li><a class="reference internal" href="#group">group</a></li>
@ -208,7 +209,7 @@ noted, any given module does support change hooks.</p>
</ul>
<p><em>state</em>:</p>
<ul class="simple">
<li>Can be either &#8216;installed&#8217;, &#8216;removed&#8217;, or &#8216;latest&#8217;.</li>
<li>Can be either &#8216;installed&#8217;, &#8216;removed&#8217;, or &#8216;latest&#8217;. The default is &#8216;installed&#8217;.</li>
</ul>
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
<div class="highlight-python"><pre>apt pkg=foo ensure=removed
@ -270,8 +271,24 @@ support change hooks, nor does it make any changes on the system.
Playbooks do not actually use this module, they use the <a class="reference internal" href="#setup"><em>setup</em></a>
module behind the scenes.</p>
</div>
<div class="section" id="fetch">
<h2>fetch<a class="headerlink" href="#fetch" title="Permalink to this headline"></a></h2>
<p>This module works like &#8216;copy&#8217;, but in reverse. It is used for fetching files
from remote machines and storing them locally in a file tree, organized by hostname.</p>
<p><em>src</em>:</p>
<ul class="simple">
<li>The file on the remote system to fetch. This needs to be a file, not a directory. Recursive fetching may be supported later.</li>
</ul>
<p><em>dest</em>:</p>
<ul class="simple">
<li>A directory to save the file into. For example, if the &#8216;dest&#8217; directory is &#8216;/foo&#8217;, a src file named &#8216;/tmp/bar&#8217; on host &#8216;host.example.com&#8217;, would be saved into &#8216;/foo/host.example.com/bar&#8217;.</li>
</ul>
<p>The fetch module is a useful way to gather log files from remote systems. If you require
fetching multiple files from remote systems, you may wish to execute a tar command and
then fetch the tarball.</p>
</div>
<div class="section" id="file">
<span id="id5"></span><h2>file<a class="headerlink" href="#file" title="Permalink to this headline"></a></h2>
<h2>file<a class="headerlink" href="#file" title="Permalink to this headline"></a></h2>
<p>Sets attributes of files, symlinks, and directories, or removes files/symlinks/directories.
All parameters available to the file module are also available when running the <cite>copy</cite> or
<cite>template</cite> modules.</p>
@ -309,9 +326,10 @@ file path=/some/path owner=foo group=foo state=directory
file path=/path/to/delete state=absent
file src=/file/to/link/to dest=/path/to/symlink owner=foo group=foo state=link</pre>
</div>
<p>The file module also supports numerous SELinux attributes (documentation on this pending).</p>
</div>
<div class="section" id="git">
<span id="id6"></span><h2>git<a class="headerlink" href="#git" title="Permalink to this headline"></a></h2>
<span id="id5"></span><h2>git<a class="headerlink" href="#git" title="Permalink to this headline"></a></h2>
<p>Deploys software (or files) from git checkouts.</p>
<p><em>repo</em>:</p>
<ul class="simple">
@ -331,7 +349,7 @@ file src=/file/to/link/to dest=/path/to/symlink owner=foo group=foo state=link</
</div>
</div>
<div class="section" id="group">
<span id="id7"></span><h2>group<a class="headerlink" href="#group" title="Permalink to this headline"></a></h2>
<span id="id6"></span><h2>group<a class="headerlink" href="#group" title="Permalink to this headline"></a></h2>
<p>Adds or removes groups.</p>
<p><em>name</em>:</p>
<ul class="simple">
@ -351,7 +369,7 @@ file src=/file/to/link/to dest=/path/to/symlink owner=foo group=foo state=link</
</div>
</div>
<div class="section" id="ohai">
<span id="id8"></span><h2>ohai<a class="headerlink" href="#ohai" title="Permalink to this headline"></a></h2>
<span id="id7"></span><h2>ohai<a class="headerlink" href="#ohai" title="Permalink to this headline"></a></h2>
<p>Similar to the <a class="reference internal" href="#facter"><em>facter</em></a> module, this returns JSON inventory data.
Ohai data is a bit more verbose and nested than facter.</p>
<p>Requires that &#8216;ohai&#8217; be installed on the remote end.</p>
@ -361,7 +379,7 @@ support change hooks, nor does it make any changes on the system.</p>
<a class="reference internal" href="#setup"><em>setup</em></a> module behind the scenes instead.</p>
</div>
<div class="section" id="ping">
<span id="id9"></span><h2>ping<a class="headerlink" href="#ping" title="Permalink to this headline"></a></h2>
<span id="id8"></span><h2>ping<a class="headerlink" href="#ping" title="Permalink to this headline"></a></h2>
<p>A trivial test module, this module always returns the integer <tt class="docutils literal"><span class="pre">1</span></tt> on
successful contact.</p>
<p>This module does not support change hooks and is informative only - it
@ -369,7 +387,7 @@ takes no parameters &amp; does not support change hooks, nor does it make
any changes on the system.</p>
</div>
<div class="section" id="service">
<span id="id10"></span><h2>service<a class="headerlink" href="#service" title="Permalink to this headline"></a></h2>
<span id="id9"></span><h2>service<a class="headerlink" href="#service" title="Permalink to this headline"></a></h2>
<p>Controls services on remote machines.</p>
<p><em>state</em>:</p>
<ul class="simple">
@ -388,7 +406,7 @@ service name=httpd state=restarted</pre>
</div>
</div>
<div class="section" id="setup">
<span id="id11"></span><h2>setup<a class="headerlink" href="#setup" title="Permalink to this headline"></a></h2>
<span id="id10"></span><h2>setup<a class="headerlink" href="#setup" title="Permalink to this headline"></a></h2>
<p>Writes a JSON file containing key/value data, for use in templating.
Call this once before using the <a class="reference internal" href="#template"><em>template</em></a> module. Playbooks
will execute this module automatically as the first step in each play
@ -410,12 +428,12 @@ tell their source. All variables are then bubbled up to the caller.</p>
ntpserver: 'ntp.example.com'
xyz: 1234</pre>
</div>
<p>Example action from <cite>/usr/bin/Ansible</cite>:</p>
<div class="highlight-python"><pre>Ansible -m all setup -a "ntpserver=ntp.example.com xyz=1234"</pre>
<p>Example action from <cite>/usr/bin/ansible</cite>:</p>
<div class="highlight-python"><pre>ansible all -m setup -a "ntpserver=ntp.example.com xyz=1234"</pre>
</div>
</div>
<div class="section" id="shell">
<span id="id12"></span><h2>shell<a class="headerlink" href="#shell" title="Permalink to this headline"></a></h2>
<span id="id11"></span><h2>shell<a class="headerlink" href="#shell" title="Permalink to this headline"></a></h2>
<p>The shell module takes the command name followed by a list of
arguments, space delimited. It is almost exactly like the command module
but runs the command through the shell rather than directly.</p>
@ -433,7 +451,7 @@ command was running for.</p>
</div>
</div>
<div class="section" id="template">
<span id="id13"></span><h2>template<a class="headerlink" href="#template" title="Permalink to this headline"></a></h2>
<span id="id12"></span><h2>template<a class="headerlink" href="#template" title="Permalink to this headline"></a></h2>
<p>Templates a file out to a remote server. Call the <a class="reference internal" href="#setup"><em>setup</em></a> module
prior to usage if you are not running from a playbook. In addition to the options
listed below, the arguments available to the <cite>file</cite> module can also be passed to the copy
@ -453,7 +471,7 @@ be a relative or absolute path.</li>
</div>
</div>
<div class="section" id="user">
<span id="id14"></span><h2>user<a class="headerlink" href="#user" title="Permalink to this headline"></a></h2>
<span id="id13"></span><h2>user<a class="headerlink" href="#user" title="Permalink to this headline"></a></h2>
<p>Creates user accounts, manipulates existing user accounts, and removes user accounts.</p>
<p><em>name</em>:</p>
<ul class="simple">
@ -506,7 +524,7 @@ user name=mdehaan state=absent force=yes</pre>
</div>
</div>
<div class="section" id="virt">
<span id="id15"></span><h2>virt<a class="headerlink" href="#virt" title="Permalink to this headline"></a></h2>
<span id="id14"></span><h2>virt<a class="headerlink" href="#virt" title="Permalink to this headline"></a></h2>
<p>Manages virtual machines supported by libvirt. Requires that libvirt be installed
on the managed machine.</p>
<p><em>guest</em>:</p>
@ -535,15 +553,15 @@ ansible host -m virt -a "guest=foo command=get_xml"
ansible host -m virt -a "guest=foo command=autostart"</pre>
</div>
<p>Example host (hypervisor) management commands from /usr/bin/ansible:</p>
<div class="highlight-python"><pre>ansible host -m virt -a "freemem"
ansible host -m virt -a "list_vms"
ansible host -m virt -a "info"
ansible host -m virt -a "nodeinfo"
ansible host -m virt -a "virttype"</pre>
<div class="highlight-python"><pre>ansible host -m virt -a "command=freemem"
ansible host -m virt -a "command=list_vms"
ansible host -m virt -a "command=info"
ansible host -m virt -a "command=nodeinfo"
ansible host -m virt -a "command=virttype"</pre>
</div>
</div>
<div class="section" id="yum">
<span id="id16"></span><h2>yum<a class="headerlink" href="#yum" title="Permalink to this headline"></a></h2>
<span id="id15"></span><h2>yum<a class="headerlink" href="#yum" title="Permalink to this headline"></a></h2>
<p>Will install, upgrade, remove, and list packages with the yum package manager.</p>
<p><em>pkg</em>:</p>
<ul class="simple">
@ -551,7 +569,7 @@ ansible host -m virt -a "virttype"</pre>
</ul>
<p><em>state</em>:</p>
<ul class="simple">
<li>Can be either &#8216;installed&#8217;, &#8216;latest&#8217;, or &#8216;removed&#8217;</li>
<li>Can be either &#8216;installed&#8217;, &#8216;latest&#8217;, or &#8216;removed&#8217;. The default is &#8216;installed&#8217;.</li>
</ul>
<p><em>list</em>:</p>
<ul class="simple">
@ -572,14 +590,14 @@ yum pkg=httpd ensure=installed</pre>
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference internal" href="examples.html"><em>Command Line Examples</em></a></dt>
<dd>Examples of using modules in /usr/bin/Ansible</dd>
<dd>Examples of using modules in /usr/bin/ansible</dd>
<dt><a class="reference internal" href="playbooks.html"><em>Playbooks</em></a></dt>
<dd>Examples of using modules with /usr/bin/Ansible-playbook</dd>
<dd>Examples of using modules with /usr/bin/ansible-playbook</dd>
<dt><a class="reference internal" href="moduledev.html"><em>Module Development Guide</em></a></dt>
<dd>How to write your own modules</dd>
<dt><a class="reference internal" href="api.html"><em>API &amp; Integrations</em></a></dt>
<dd>Examples of using modules with the Python API</dd>
<dt><a class="reference external" href="http://groups.google.com/group/Ansible-project">Mailing List</a></dt>
<dt><a class="reference external" href="http://groups.google.com/group/ansible-project">Mailing List</a></dt>
<dd>Questions? Help? Ideas? Stop by the list on Google Groups</dd>
<dt><a class="reference external" href="http://irc.freenode.net">irc.freenode.net</a></dt>
<dd>#ansible IRC chat channel</dd>

View file

@ -138,6 +138,7 @@ s.parentNode.insertBefore(ga, s);
</li>
<li><a class="reference internal" href="#running-operations-on-change">Running Operations On Change</a></li>
<li><a class="reference internal" href="#power-tricks">Power Tricks</a><ul>
<li><a class="reference internal" href="#local-playbooks">Local Playbooks</a></li>
<li><a class="reference internal" href="#external-variables-and-prompted-or-sensitive-data">External Variables And Prompted or Sensitive Data</a></li>
<li><a class="reference internal" href="#conditional-execution">Conditional Execution</a></li>
<li><a class="reference internal" href="#conditional-imports">Conditional Imports</a></li>
@ -197,7 +198,7 @@ Each playbook is composed of one or more &#8216;plays&#8217; in a list.</p>
orchestrate multi-machine deployments, running certain steps on all
machines in the webservers group, then certain steps on the database
server group, then more commands back on the webservers group, etc.</p>
<p>For starters, here&#8217;s a playbook that contains just one play.:</p>
<p>For starters, here&#8217;s a playbook that contains just one play:</p>
<div class="highlight-python"><pre>---
- hosts: webservers
vars:
@ -355,6 +356,20 @@ won&#8217;t need them for much else.</p>
<h2>Power Tricks<a class="headerlink" href="#power-tricks" title="Permalink to this headline"></a></h2>
<p>Now that you have the basics down, let&#8217;s learn some more advanced
things you can do with playbooks.</p>
<div class="section" id="local-playbooks">
<h3>Local Playbooks<a class="headerlink" href="#local-playbooks" title="Permalink to this headline"></a></h3>
<p>It may be useful to use a playbook locally, rather than by connecting over SSH. This can be useful
for assuring the configuration of a system by putting a playbook on a crontab. This may also be used
to run a playbook inside a OS installer, such as an Anaconda kickstart.</p>
<p>To run an entire playbook locally, just set the &#8220;hosts:&#8221; line to &#8220;hosts:127.0.0.1&#8221; and then run the playbook like so:</p>
<div class="highlight-python"><pre>playbook playbook.yml --connection=local</pre>
</div>
<p>Alternatively, a local connection can be used in a single playbook play, even if other plays in the playbook
use the default remote connection type:</p>
<div class="highlight-python"><pre>hosts: 127.0.0.1
connection: local</pre>
</div>
</div>
<div class="section" id="external-variables-and-prompted-or-sensitive-data">
<h3>External Variables And Prompted or Sensitive Data<a class="headerlink" href="#external-variables-and-prompted-or-sensitive-data" title="Permalink to this headline"></a></h3>
<p>It&#8217;s a great idea to keep your playbooks under source control, but
@ -411,7 +426,7 @@ or it could be something like performing some cleanup steps if a filesystem is g
<p>This is easy to do in Ansible, with the <cite>only_if</cite> clause. This clause can be applied to any task,
and allows usage of variables from anywhere in ansible, either denoted with <cite>$dollar_sign_syntax</cite> or
<cite>{{ braces_syntax }}</cite> and then evaluates them with a Python expression. Don&#8217;t panic &#8211; it&#8217;s actually
pretty simple.:</p>
pretty simple:</p>
<div class="highlight-python"><pre>vars:
favcolor: blue
is_favcolor_blue: "'$favcolor' == 'blue'"
@ -569,7 +584,7 @@ running operations can go faster. The easiest way to do this is
to kick them off all at once and then poll until they are done.</p>
<p>You will also want to use asynchronous mode on very long running
operations that might be subject to timeout.</p>
<p>To launch a task asynchronously, specify it&#8217;s maximum runtime
<p>To launch a task asynchronously, specify its maximum runtime
and how frequently you would like to poll for status. The default
poll value is 10 seconds if you do not specify a value for <cite>poll</cite>:</p>
<div class="highlight-python"><pre>---

File diff suppressed because one or more lines are too long