cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

API docs update + fix -u reference

Browse source
This commit is contained in:
Michael DeHaan 2012-08-30 23:55:31 -04:00
parent edd2a3c6ed
commit 566f220d16
5 changed files with 78 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

50
api.html
View file

@ -156,12 +156,16 @@ s.parentNode.insertBefore(ga, s);
<li><a class="reference internal" href="#detailed-api-example">Detailed API Example</a></li>
</ul>
</li>
<li><a class="reference internal" href="#external-inventory">External Inventory</a><ul>
<li><a class="reference internal" href="#plugins-repository">Plugins Repository</a></li>
<li><a class="reference internal" href="#external-inventory-scripts">External Inventory Scripts</a><ul>
<li><a class="reference internal" href="#script-conventions">Script Conventions</a></li>
<li><a class="reference internal" href="#example-the-cobbler-external-inventory-script">Example: The Cobbler External Inventory Script</a></li>
<li><a class="reference internal" href="#example-aws-ec2-external-inventory-script">Example: AWS EC2 External Inventory Script</a></li>
<li><a class="reference internal" href="#example-openstack">Example: OpenStack</a></li>
</ul>
</li>
<li><a class="reference internal" href="#callback-plugins">Callback Plugins</a></li>
<li><a class="reference internal" href="#connection-type-plugins">Connection Type Plugins</a></li>
</ul>
</li>
</ul>
@ -191,18 +195,19 @@ s.parentNode.insertBefore(ga, s);
<div class="section" id="api-integrations">
<h1><a class="toc-backref" href="#table-of-contents">API &amp; Integrations</a><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 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
external sources. We&#8217;ll start with the Python API.</p>
<p>There are several interesting ways to use Ansible from an API perspective. You can use
the Ansible python API to control nodes, you can extend Ansible to respond to various python events,
and you can plug in inventory data from external data sources. Ansible is written in its own
API so you have a considerable amount of power across the board.</p>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><cite>Table of contents</cite></p>
<ul class="simple">
<li><a class="reference internal" href="#api-integrations" id="id2">API &amp; Integrations</a><ul>
<li><a class="reference internal" href="#python-api" id="id3">Python API</a></li>
<li><a class="reference internal" href="#external-inventory" id="id4">External Inventory</a></li>
<li><a class="reference internal" href="#plugins-repository" id="id4">Plugins Repository</a></li>
<li><a class="reference internal" href="#external-inventory-scripts" id="id5">External Inventory Scripts</a></li>
<li><a class="reference internal" href="#callback-plugins" id="id6">Callback Plugins</a></li>
<li><a class="reference internal" href="#connection-type-plugins" id="id7">Connection Type Plugins</a></li>
</ul>
</li>
</ul>
@ -275,12 +280,16 @@ 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 class="section" id="external-inventory">
<h2><a class="toc-backref" href="#table-of-contents">External Inventory</a><a class="headerlink" href="#external-inventory" title="Permalink to this headline"></a></h2>
<div class="section" id="plugins-repository">
<h2><a class="toc-backref" href="#table-of-contents">Plugins Repository</a><a class="headerlink" href="#plugins-repository" title="Permalink to this headline"></a></h2>
<p>The remainder of features in the API docs have components available in the <a class="reference external" href="http://github.com/ansible/ansible-plugins">ansible-plugins</a> repository. Please consult this repository for more information. Send us a github pull request if you develop any interesting features.</p>
</div>
<div class="section" id="external-inventory-scripts">
<h2><a class="toc-backref" href="#table-of-contents">External Inventory Scripts</a><a class="headerlink" href="#external-inventory-scripts" title="Permalink to this headline"></a></h2>
<p>Often a user of a configuration management system will want to keep inventory
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 inventory system. The <a class="reference external" href="http://github.com/ansible/ansible-plugins">ansible-plugins</a> repo contains some of these already.</p>
of these options via an external inventory system. The ansible-plugins repo contains some of these already &#8211; including options for EC2/Eucalyptus and OpenStack, which will be detailed below.</p>
<p>It&#8217;s possible to write an external inventory script in any language. 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>
@ -438,6 +447,24 @@ e.g.
<div class="highlight-python"><pre>cd examples/scripts
./ec2_external_inventory.py --host ec2-12-12-12-12.compute-1.amazonaws.com</pre>
</div>
</div>
<div class="section" id="example-openstack">
<h3>Example: OpenStack<a class="headerlink" href="#example-openstack" title="Permalink to this headline"></a></h3>
<p>Though not detailed here in as much depth as the EC2 module, there&#8217;s also a OpenStack Nova external inventory source in the ansible-plugins repository. See the inline comments in the module source.</p>
</div>
</div>
<div class="section" id="callback-plugins">
<h2><a class="toc-backref" href="#table-of-contents">Callback Plugins</a><a class="headerlink" href="#callback-plugins" title="Permalink to this headline"></a></h2>
<p>Ansible can be configured via code to respond to external events. This can include enhancing logging, signalling an external software
system, or even (yes, really) making sound effects. Some examples are contained in the ansible-plugins repository.</p>
</div>
<div class="section" id="connection-type-plugins">
<h2><a class="toc-backref" href="#table-of-contents">Connection Type Plugins</a><a class="headerlink" href="#connection-type-plugins" title="Permalink to this headline"></a></h2>
<p>By default, ansible ships with a &#8216;paramiko&#8217; SSH, native ssh (just called &#8216;ssh&#8217;), and &#8216;local&#8217; connection type, which can be used
in playbooks and with /usr/bin/ansible to decide how you want to talk to remote machines. The basics of these connection types
are covered in the &#8216;getting started&#8217; section. Should you want to extend Ansible to support other transports (SNMP? Message bus?
Carrier Pigeon?) it&#8217;s as simple as copying the format of one of the existing modules and dropping it into the connection plugins
directory.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
@ -451,7 +478,6 @@ e.g.
</div>
</div>
</div>
</div>
<br/>

7
gettingstarted.html
View file

@ -361,9 +361,10 @@ bserver.example.org</pre>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible all -m ping
</pre></div>
</div>
<p>If you want to access machines remotely as a different user than root,
you will want to specify the &#8216;-u&#8217; option to ansible. If you would
like to access sudo mode, there are also flags to do that:</p>
<p>In Ansible 0.7 and later, ansible will attempt to remote connect to the machines using your current
user name, just like SSH would. In 0.6 and before, this actually defaults to &#8216;root&#8217; (we liked the current
user behavior better). To override the remote user name, just use the &#8216;-u&#8217; parameter.</p>
<p>If you would like to access sudo mode, there are also flags to do that:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="c"># as bruce</span>
<span class="nv">$ </span>ansible all -m ping -u bruce
<span class="c"># as bruce, sudoing to root</span>

39
rst/api.rst
View file

@ -1,13 +1,10 @@
API & Integrations
==================
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 its own
API so you have a considerable amount of power there.
Also covered here, Ansible's
list of hosts, groups, and variables assigned to each host can be driven from
external sources. We'll start with the Python API.
There are several interesting ways to use Ansible from an API perspective. You can use
the Ansible python API to control nodes, you can extend Ansible to respond to various python events,
and you can plug in inventory data from external data sources. Ansible is written in its own
API so you have a considerable amount of power across the board.
.. contents:: `Table of contents`
:depth: 2
@ -85,13 +82,18 @@ 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 ``ansible`` and ``ansible-playbook``.
External Inventory
Plugins Repository
------------------
The remainder of features in the API docs have components available in the `ansible-plugins <http://github.com/ansible/ansible-plugins>`_ repository. Please consult this repository for more information. Send us a github pull request if you develop any interesting features.
External Inventory Scripts
--------------------------
Often a user of a configuration management system will want to keep inventory
in a different system. Frequent examples include LDAP, `Cobbler <http://cobbler.github.com>`_,
or a piece of expensive enterprisey CMDB software. Ansible easily supports all
of these options via an external inventory system. The `ansible-plugins <http://github.com/ansible/ansible-plugins>`_ repo contains some of these already.
of these options via an external inventory system. The ansible-plugins repo contains some of these already -- including options for EC2/Eucalyptus and OpenStack, which will be detailed below.
It's possible to write an external inventory script in any language. If you are familiar with Puppet terminology, this concept is basically the same as 'external nodes', with the slight difference that it also defines which hosts are managed.
@ -277,6 +279,25 @@ To see the complete list of variables available for an instance, run the script
cd examples/scripts
./ec2_external_inventory.py --host ec2-12-12-12-12.compute-1.amazonaws.com
Example: OpenStack
``````````````````
Though not detailed here in as much depth as the EC2 module, there's also a OpenStack Nova external inventory source in the ansible-plugins repository. See the inline comments in the module source.
Callback Plugins
----------------
Ansible can be configured via code to respond to external events. This can include enhancing logging, signalling an external software
system, or even (yes, really) making sound effects. Some examples are contained in the ansible-plugins repository.
Connection Type Plugins
-----------------------
By default, ansible ships with a 'paramiko' SSH, native ssh (just called 'ssh'), and 'local' connection type, which can be used
in playbooks and with /usr/bin/ansible to decide how you want to talk to remote machines. The basics of these connection types
are covered in the 'getting started' section. Should you want to extend Ansible to support other transports (SNMP? Message bus?
Carrier Pigeon?) it's as simple as copying the format of one of the existing modules and dropping it into the connection plugins
directory.
.. seealso::

8
rst/gettingstarted.rst
View file

@ -205,9 +205,11 @@ Now ping all your nodes:
$ ansible all -m ping
If you want to access machines remotely as a different user than root,
you will want to specify the '-u' option to ansible. If you would
like to access sudo mode, there are also flags to do that:
In Ansible 0.7 and later, ansible will attempt to remote connect to the machines using your current
user name, just like SSH would. In 0.6 and before, this actually defaults to 'root' (we liked the current
user behavior better). To override the remote user name, just use the '-u' parameter.
If you would like to access sudo mode, there are also flags to do that:
.. code-block:: bash

2
searchindex.js
View file

File diff suppressed because one or more lines are too long