Added FAQ page (limited space in menu, so trimmed some topics on lesser used bits) + docs build

pull/1256/head
Michael DeHaan 13 years ago
parent e575c0639f
commit 37864337eb

@ -95,6 +95,7 @@
<a href="index.html"
class="dropdown-toggle">Site</a>
<span class="globaltoc"><ul class="current">
<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="gettingstarted.html">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>

@ -95,6 +95,7 @@
<a href="index.html"
class="dropdown-toggle">Site</a>
<span class="globaltoc"><ul class="current">
<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="gettingstarted.html">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>

@ -95,6 +95,7 @@
<a href="index.html"
class="dropdown-toggle">Site</a>
<span class="globaltoc"><ul class="current">
<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="gettingstarted.html">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 current"><a class="current reference internal" href="">Command Line Examples</a></li>

@ -93,6 +93,7 @@
<a href="index.html"
class="dropdown-toggle">Site</a>
<span class="globaltoc"><ul>
<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="gettingstarted.html">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>

@ -27,7 +27,7 @@
<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="The Inventory File, Patterns, and Groups" href="patterns.html" />
<link rel="prev" title="Introducing Ansible" href="index.html" />
<link rel="prev" title="Frequently Asked Questions" href="faq.html" />
<script type="text/javascript">
(function () {
/**
@ -95,6 +95,7 @@
<a href="index.html"
class="dropdown-toggle">Site</a>
<span class="globaltoc"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">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>
@ -127,8 +128,8 @@
<li><a href="index.html"
title="previous chapter">&laquo; Introducing Ansible</a></li>
<li><a href="faq.html"
title="previous chapter">&laquo; Frequently Asked Questions</a></li>
<li><a href="patterns.html"
title="next chapter">The Inventory File, Patterns, and Groups &raquo;</a></li>

@ -26,7 +26,7 @@
<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="#" />
<link rel="next" title="Getting Started" href="gettingstarted.html" />
<link rel="next" title="Frequently Asked Questions" href="faq.html" />
<script type="text/javascript">
(function () {
/**
@ -94,6 +94,7 @@
<a href="#"
class="dropdown-toggle">Site</a>
<span class="globaltoc"><ul>
<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="gettingstarted.html">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>
@ -124,8 +125,8 @@
<li><a href="gettingstarted.html"
title="next chapter">Getting Started &raquo;</a></li>
<li><a href="faq.html"
title="next chapter">Frequently Asked Questions &raquo;</a></li>
@ -205,6 +206,23 @@ you with questions about Ansible.</p>
<h1>Contents<a class="headerlink" href="#contents" title="Permalink to this headline"></a></h1>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="faq.html#what-inspired-ansible">What inspired Ansible?</a></li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#comparisons">Comparisons</a><ul>
<li class="toctree-l3"><a class="reference internal" href="faq.html#vs-func">vs Func?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faq.html#vs-puppet">vs Puppet?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faq.html#vs-chef">vs Chef?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faq.html#vs-capistrano-fabric">vs Capistrano/Fabric?</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#other-questions">Other Questions</a><ul>
<li class="toctree-l3"><a class="reference internal" href="faq.html#how-does-ansible-scale">How does Ansible scale?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faq.html#are-transports-other-than-ssh-supported">Are transports other than SSH supported?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faq.html#what-are-some-ideal-uses-for-ansible">What are some ideal uses for Ansible?</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="gettingstarted.html">Getting Started</a><ul>
<li class="toctree-l2"><a class="reference internal" href="gettingstarted.html#requirements">Requirements</a></li>
<li class="toctree-l2"><a class="reference internal" href="gettingstarted.html#developer-requirements">Developer Requirements</a></li>

@ -94,6 +94,7 @@
<a href="index.html"
class="dropdown-toggle">Site</a>
<span class="globaltoc"><ul class="current">
<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="gettingstarted.html">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>

@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!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>ansible-modules</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="refentry" title="ansible-modules" lang="en"><a id="id345526"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible-modules — stock modules shipped with ansible</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p>Ansible ships with a number of modules that can be executed directly on remote hosts or through
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible-modules</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="refentry" title="ansible-modules" lang="en"><a id="id327777"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible-modules — stock modules shipped with ansible</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p>Ansible ships with a number of modules that can be executed directly on remote hosts or through
ansible playbooks.</p></div><div class="refsect1" title="IDEMPOTENCE"><a id="_idempotence"></a><h2>IDEMPOTENCE</h2><p>Most modules other than command are idempotent, meaning they will seek to avoid changes
unless a change needs to be made. When using ansible playbooks, these modules can
trigger change events, as described in <span class="strong"><strong>ansible-playbooks</strong></span>(5).</p><p>Unless otherwise noted, all modules support change hooks.</p></div><div class="refsect1" title="command"><a id="_command"></a><h2>command</h2><p>The command module takes the command name followed by a list of arguments, space delimited.

@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!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>ansible-modules</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="refentry" title="ansible-modules" lang="en"><a id="id514998"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible-playbook — format and function of an ansible playbook file</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p>Ansible ships with <span class="emphasis"><em>ansible-playbook</em></span>, a tool for running playbooks.
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible-modules</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="refentry" title="ansible-modules" lang="en"><a id="id358599"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible-playbook — format and function of an ansible playbook file</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p>Ansible ships with <span class="emphasis"><em>ansible-playbook</em></span>, a tool for running playbooks.
Playbooks can represent frequent tasks, desired system configurations,
or deployment processes.</p></div><div class="refsect1" title="FORMAT"><a id="_format"></a><h2>FORMAT</h2><p>Playbooks are written in YAML.</p></div><div class="refsect1" title="EXAMPLE"><a id="_example"></a><h2>EXAMPLE</h2><p>See:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<a class="ulink" href="https://github.com/mpdehaan/ansible/blob/master/examples/playbook.yml" target="_top">https://github.com/mpdehaan/ansible/blob/master/examples/playbook.yml</a>

@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!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>ansible</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="refentry" title="ansible" lang="en"><a id="id377235"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible — run a command somewhere else</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><p>ansible &lt;host-pattern&gt; [-f forks] [-m module_name] [-a args]</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p><span class="strong"><strong>Ansible</strong></span> is an extra-simple tool/framework/API for doing 'remote things' over
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="refentry" title="ansible" lang="en"><a id="id471170"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible — run a command somewhere else</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><p>ansible &lt;host-pattern&gt; [-f forks] [-m module_name] [-a args]</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p><span class="strong"><strong>Ansible</strong></span> is an extra-simple tool/framework/API for doing 'remote things' over
SSH.</p></div><div class="refsect1" title="ARGUMENTS"><a id="_arguments"></a><h2>ARGUMENTS</h2><div class="variablelist"><dl><dt><span class="term">
<span class="strong"><strong>host-pattern</strong></span>
</span></dt><dd>

@ -95,6 +95,7 @@
<a href="index.html"
class="dropdown-toggle">Site</a>
<span class="globaltoc"><ul class="current">
<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="gettingstarted.html">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>

@ -95,6 +95,7 @@
<a href="index.html"
class="dropdown-toggle">Site</a>
<span class="globaltoc"><ul class="current">
<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="gettingstarted.html">Getting Started</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">The Inventory File, Patterns, and Groups</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Command Line Examples</a></li>

@ -95,6 +95,7 @@
<a href="index.html"
class="dropdown-toggle">Site</a>
<span class="globaltoc"><ul class="current">
<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="gettingstarted.html">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>

@ -99,6 +99,7 @@
<a href="index.html"
class="dropdown-toggle">Site</a>
<span class="globaltoc"><ul>
<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="gettingstarted.html">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>

File diff suppressed because one or more lines are too long

@ -0,0 +1,182 @@
Frequently Asked Questions
==========================
What inspired Ansible?
----------------------
Back when I worked for Red Hat and working on Cobbler, several of us identified a gap between
provisioning (Cobbler) and configuration management solutions (cfengine, Puppet, etc).
There was a need for a way to do ad-hoc tasks efficiently, and various parallel
SSH scripts were not API based enough for us. So we (Adrian Likins, Seth Vidal, and I)
created Func -- a secure distributed command framework.
I always wanted to have a configuration management system built on Func, but never
built it due to needing to spend time on Cobbler and other projects.
In the meantime, a John Eckersberg developed Taboot,
a deployment framework of sorts that sat on top of Func, using a YAML syntax very
much like what Ansible now has.
After trying to get Func running again recently at a new company, I got tired
of some SSL and DNS issues and decided to create something a bit simpler, taking
all of the good ideas from Func, and merging them with experience I learned from
working at Puppet Labs. I wanted something that was easy to pick up and was installable
without any bootstrapping, and didn't suffer from the "I don't want to learn X" mentality
that often impacted adoption of tools like Puppet and Chef among certain ops teams.
I also spent some time working with a couple of sites that needed to do large webapp deployments,
and noticed how complex various configuration management and deployment tools were to these
companies, compared with what they actually needed. Release processes were too complex
and needed something simple to straighten them out -- but I really didn't want to train
all the dev(ops) on Puppet or Chef, and they really didn't want to learn them either.
I kept thinking, is there a reason for these programs to be so large and complicated?
Well, systems management is a little complicated, but no. Not really.
Can I build something that a sysadmin can
figure out in 15 minutes and get going, and then extend in any language he knows?
That's how Ansible was born. It sheds 'best practices' for 'you know your infrastructure
best', and distills all of the ideas behind all of these other tools to the core.
Not only is Ansible very simple and easy to learn/extend, it's configuration management, deployment, and ad-hoc tasks all in one app. And I think that makes it pretty powerful. It hasn't really been done before.
I'd like to know what you think of it. Hop by the mailing list and say hi.
Comparisons
-----------
vs Func?
++++++++
Ansible uses SSH by default instead of SSL and custom daemons, and requires
no extra software to run on managed machines. You can also write modules
in any language as long as they return JSON. Ansible's API, of course, is
heavily inspired by Func. Some features, like delegation hierarchies, are
not supported, but Ansible does have an async mode. Ansible also adds
a configuration management and multinode orchestration layer that Func didn't have.
vs Puppet?
++++++++++
First off, Ansible wouldn't have happened without Puppet. Puppet took configuration
management ideas from cfengine and made them sane. However, I still think they can
be simpler.
Ansible playbooks ARE a complete configuration management system. Unlike Puppet, playbooks
are implicitly ordered (more like Chef), but still retain the ability to signal
notification events (like Puppet). This is kind of a 'best of both worlds' thing.
There is no central server to promote scaling, and Ansible is
also designed with multi-node deployment in mind from day-one -- something that is difficult
for Puppet because of the pull architecture. Ansible is push based,
so you can do things in an ordered fashion, addressing batches of servers
at one time, and you do not have to contend with the DAG. It's also extensible in any language
and the source is designed so that you don't have to be an expert programmer to submit a patch.
Ansible's resources are heavily inspired by Puppet, with the "state" keyword being a more or less
direct port of "ensure" from Puppet. Unlike Puppet, Ansible can be extended in any language,
even bash ... just return some output in JSON format. You don't need to know Ruby.
Unlike Puppet, hosts are taken out of playbooks when they have a failure. It encourages
'fail first', so you can correct the error, instead of configuring as much of the system
as it can. A system shouldn't be half correct, especially if we're planning on configuring
other systems that depend on that system.
Ansible also has a VERY short learning curve -- but it also has less language constructs and
does not create it'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
almost like cheating).
I also suspect some Ansible users will actually use Ansible to trigger Puppet -- using the git
module to checkout a Puppet module hierachy from source, and the command module to run
'puppet apply'. That's ok too, but you may find playbooks do all you need.
Ansible does support gathering variables from 'facter', if installed, and Ansible templates
in jinja2 in a way just like Puppet does with erb.
vs Chef?
++++++++
Much in the ways Ansible is different from Puppet. Chef is notoriously hard
to set up on the server, and requires that you know how to program in Ruby to
use the language. As such, it seems to have a pretty good following mainly
among Rails coders.
Like Chef (and unlike Puppet), Ansible executes configuration tasks in the order
given, rather than having to manually specify a dependency graph. Ansible extends
this though, by allowing triggered notifiers, so Apache can, be restarted if needed,
only once, at the end of a configuration run.
Unlike Chef, Ansible's playbooks are not a programming language. This means
that you can parse Ansible's playbooks and treat the instructions as data. It also
means working on your infrastructure is not a development task and testing is easier.
Ansible can be used regardless of your programming language experience. Both
Chef and Puppet are around 60k+ lines of code, while Ansible is a much simpler
program. I believe this strongly leads to more reliable software and a richer
open source community -- the code is kept simple so it is easy for anyone to
submit a patch or module.
Just like with puppet, some users may wish to use Ansible to trigger chef-solo to
avoid using the server, after checking out some chef content using Ansible's git
support.
Ansible does support gathering variables from 'ohai', if installed.
vs Capistrano/Fabric?
+++++++++++++++++++++
These tools aren't really well suited to doing idempotent configuration and are
typically about pushing software out for web deployment and automating steps.
Meanwhile Ansible is designed for other types of configuration management, and contains some
advanced scaling features.
The ansible playbook syntax is documented within a page of text and also has a MUCH lower learning curve. And because Ansible is designed for more than pushing webapps, it's more generally
useful for sysadmins (not just web developers), and can also be used for firing off ad-hoc tasks.
Other Questions
---------------
How does Ansible scale?
+++++++++++++++++++++++
Whether in single-execution mode or using ansible playbooks, ansible can
run multiple commands in seperate forks, thanks to the magic behind
Python's multiprocessing module.
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's up to you and how much power you can throw at it, but it's heritage
is about handling those kinds of use cases.
There are no daemons so it's entirely up to you. When you are aren't using
Ansible, it is not consuming any resources.
If you have 10,000 systems, running a single ansible playbook against all of
them probably isn't always appropriate, but most users shouldn't have any problems.
If you want to kick off an async task/module, it's probably fine.
If you'd like to discuss scaling, please hop on the mailing list.
Are transports other than SSH supported?
++++++++++++++++++++++++++++++++++++++++
Currently SSH is the only one, though the intent is to make this entirely
pluggable very soon so if you wanted to build a message bus or XMPP (or even
sneaker net?) adapter ansible will let you do that. Stay tuned!
What are some ideal uses for Ansible?
+++++++++++++++++++++++++++++++++++++
One of the best use cases? Complex multi-node cloud deployments using playbooks. Another good
example is for configuration management where you
are starting from a clean OS with no extra software installed, adopting systems
that are already deployed.
Ansible is also great for running ad-hoc tasks across a wide variety of Linux, Unix, and *BSDs.
Because it just uses the basic tools available on the system, it is exceptionally cross platform
without needing to install management packages on each node.
It also excels for writing distributed
scripts and ad-hoc applications that need to gather data or perform arbitrary
tasks -- whether for a QA sytem, build system, or anything you can think of.

@ -76,6 +76,7 @@ Contents
.. toctree::
:maxdepth: 3
faq
gettingstarted
patterns
examples

Loading…
Cancel
Save