<p>Often a user of a configuration management system will want to keep inventory
<p>Often a user of a configuration management system will want to keep inventory
in a different system. Frequent examples include LDAP, <aclass="reference external"href="http://cobbler.github.com">Cobbler</a>,
in a different system. Frequent examples include LDAP, <aclass="reference external"href="http://cobbler.github.com">Cobbler</a>,
or a piece of expensive enterprisey CMDB software. Ansible easily supports all
or a piece of expensive enterprisey CMDB software. Ansible easily supports all
of these options via an external interventory system.</p>
of these options via an external inventory system.</p>
<p>If you have a data store system where an Ansible external inventory script doesn’t already exist, this may require a little coding, but we have a <aclass="reference external"href="https://github.com/ansible/ansible/blob/master/examples/scripts/cobbler_external_inventory.py">Cobbler example</a> in the main source tree – but it’s pretty simple, as we’ll explain below – that would provide a good starting point. Like with modules, it’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’t already exist, this may require a little coding, but we have a <aclass="reference external"href="https://github.com/ansible/ansible/blob/master/examples/scripts/cobbler_external_inventory.py">Cobbler example</a> in the main source tree – but it’s pretty simple, as we’ll explain below – that would provide a good starting point. Like with modules, it’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 ‘external nodes’, with the slight difference that it also defines which hosts are managed.</p>
<p>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.</p>
<divclass="section"id="script-conventions">
<divclass="section"id="script-conventions">
...
@@ -325,7 +325,7 @@ override any that have the same name.</p>
...
@@ -325,7 +325,7 @@ override any that have the same name.</p>
<divclass="highlight-python"><pre>ansible webserver -m shell -a "echo {{ a }}"</pre>
<divclass="highlight-python"><pre>ansible webserver -m shell -a "echo {{ a }}"</pre>
</div>
</div>
<p>So in other words, you can use those variables in arguments/actions as well. You might use this to name
<p>So in other words, you can use those variables in arguments/actions as well. You might use this to name
a conf.d file appropriately or something similar. Who knows.</p>
a conf.d file appropriately or something similar. Who knows?</p>
<p>So that’s the Cobbler integration support – using the cobbler script as an example, it should be trivial to adapt Ansible to pull inventory, as well as variable information, from any data source. If you create anything interesting, please share with the mailing list, and we can keep it in the source code tree for others to use.</p>
<p>So that’s the Cobbler integration support – using the cobbler script as an example, it should be trivial to adapt Ansible to pull inventory, as well as variable information, from any data source. If you create anything interesting, please share with the mailing list, and we can keep it in the source code tree for others to use.</p>
<divclass="highlight-python"><pre>ansible atlanta -a "/usr/bin/foo" -u yourname</pre>
<divclass="highlight-python"><pre>ansible atlanta -a "/usr/bin/foo" -u yourname</pre>
</div>
</div>
<p>If you want to run commands through sudo:</p>
<p>If you want to run commands through sudo:</p>
<blockquote>
<divclass="highlight-python"><pre>ansible atlanta -a "/usr/bin/foo" -u yourname --sudo [--ask-sudo-pass]</pre>
<div>ansible atlanta -a “/usr/bin/foo” -u yourname –sudo [–ask-sudo-pass]</div></blockquote>
</div>
<p>Use –ask-sudo-pass (-K) if you are not using passwordless sudo.</p>
<p>Use –ask-sudo-pass (-K) if you are not using passwordless sudo.</p>
<p>Ok, so those are basics. If you didn’t read about patterns and groups yet, go back and read <aclass="reference internal"href="patterns.html"><em>The Inventory File, Patterns, and Groups</em></a>.</p>
<p>Ok, so those are basics. If you didn’t read about patterns and groups yet, go back and read <aclass="reference internal"href="patterns.html"><em>The Inventory File, Patterns, and Groups</em></a>.</p>
<p>The -f 10 in the above specifies the usage of 10 simultaneous processes. Normally commands also take
<p>The -f 10 in the above specifies the usage of 10 simultaneous processes. Normally commands also take
...
@@ -215,25 +215,26 @@ module looks like this:</p>
...
@@ -215,25 +215,26 @@ module looks like this:</p>
<divclass="highlight-python"><pre>ansible raleigh -m shell -a 'echo $TERM'</pre>
<divclass="highlight-python"><pre>ansible raleigh -m shell -a 'echo $TERM'</pre>
</div>
</div>
<p>When running any command with the ansible “ad hoc” CLI (as opposed to playbooks), pay particular attention
<p>When running any command with the ansible “ad hoc” CLI (as opposed to playbooks), pay particular attention
to shell quoting rules, so the shell doesn’t eat a variable before it gets passed to Ansible. For example, u
to shell quoting rules, so the shell doesn’t eat a variable before it gets passed to Ansible. For example,
using double vs single quotes would evaluate the variable on the box you were on.</p>
using double vs single quotes in the above example would evaluate the variable on the box you were on.</p>
<p>So far we’ve been demoing simple command execution, but most ansible modules usually do not work like
<p>So far we’ve been demoing simple command execution, but most ansible modules usually do not work like
simple scripts. They make the remote system look like you state, and run the commands necessary to
simple scripts. They make the remote system look like you state, and run the commands necessary to
get it there. This is commonly referred to as ‘idempotence’, and is a core design goal of ansible.
get it there. This is commonly referred to as ‘idempotence’, and is a core design goal of ansible.
However, we also recognize that running ad-hoc commands is equally imporant, so Ansible easily supports both.</p>
However, we also recognize that running ad-hoc commands is equally important, so Ansible easily supports both.</p>
</div>
</div>
<divclass="section"id="file-transfer-templating">
<divclass="section"id="file-transfer-templating">
<h2>File Transfer & Templating<aclass="headerlink"href="#file-transfer-templating"title="Permalink to this headline">¶</a></h2>
<h2>File Transfer & Templating<aclass="headerlink"href="#file-transfer-templating"title="Permalink to this headline">¶</a></h2>
<p>Here’s another use case for the <cite>/usr/bin/ansible</cite> command line.</p>
<p>Here’s another use case for the <cite>/usr/bin/ansible</cite> command line.</p>
<p>Ansible can SCP lots of files to multiple machines in parallel, and
<p>Ansible can SCP lots of files to multiple machines in parallel, and
optionally use them as template sources.</p>
optionally use them as template sources.</p>
<p>To just transfer a file directly to many different servers:</p>
<p>To transfer a file directly to many different servers:</p>
<divclass="highlight-python"><pre>ansible atlanta -m copy -a "src=/etc/hosts dest=/tmp/hosts"</pre>
<divclass="highlight-python"><pre>ansible atlanta -m copy -a "src=/etc/hosts dest=/tmp/hosts"</pre>
</div>
</div>
<p>To use templating, first run the setup module to put the template
<p>To use templating, first run the setup module to put the template
variables you would like to use on the remote host. Then use the
variables you would like to use on the remote host. Then use the
template module to write the files using those templates.</p>
template module to write the files using those templates.</p>
<p>Templates are written in Jinja2 format. Playbooks (covered elsewhere in the
<p>Templates are written in <aclass="reference external"href="http://jinja.pocoo.org/docs/">Jinja2</a> format.
Playbooks (covered elsewhere in the
documentation) will run the setup module for you, making this even
documentation) will run the setup module for you, making this even
simpler:</p>
simpler:</p>
<divclass="highlight-python"><pre>ansible webservers -m setup -a "favcolor=red ntp_server=192.168.1.1"
<divclass="highlight-python"><pre>ansible webservers -m setup -a "favcolor=red ntp_server=192.168.1.1"
<p>Note that if you are tracking the upstream source (i.e. git), the RPM revision will not be
<p>Note that if you are tracking the upstream source (i.e. git), the RPM revision will not be
bumped with every source code change. To get around this, you can use
bumped with every source code change. To get around this, you can use
rpm <cite>-Uvh</cite> with <cite>–force</cite> when RPM tells you the package is still at the
<ttclass="docutils literal"><spanclass="pre">rpm</span><spanclass="pre">-Uvh</span></tt> with <ttclass="docutils literal"><spanclass="pre">--force</span></tt> when RPM tells you the package is still at the
<h1>Deployment and Configuration, Unified<aclass="headerlink"href="#deployment-and-configuration-unified"title="Permalink to this headline">¶</a></h1>
<h1>Deployment and Configuration, Unified<aclass="headerlink"href="#deployment-and-configuration-unified"title="Permalink to this headline">¶</a></h1>
<p>Other deployment (compared to config) oriented frameworks similarly cover deployment well but lack a strongly defined resource model and devolve into glorified remote scripts. Ansible playbooks – having been designed with this problem in mind – are good at both deployment & idempotent configuration, meaning you don’t have to spread your infrastructure management out between different tools (Puppet+Capistrano, Chef+Fabric, etc), and performing ordered steps between different classes of machines is no problem, yet our modules affect system state only when required – while avoiding the problem of fragile scripting that assumes certain starting
<p>Other deployment (compared to config) oriented frameworks similarly cover deployment well but lack a strongly defined resource model and devolve into glorified remote scripts. Ansible playbooks – having been designed with this problem in mind – are good at both deployment & idempotent configuration, meaning you don’t have to spread your infrastructure management out between different tools (Puppet+Capistrano, Chef+Fabric, etc). Performing ordered steps between different classes of machines is no problem, yet our modules affect system state only when required – while avoiding the problem of fragile scripting that assumes certain starting or ending states.</p>
or ending states.</p>
<p>Ansible is also unique in other ways. Extending ansible does not require programming in any particular language – you can write <aclass="reference internal"href="modules.html"><em>Ansible Modules</em></a> as idempotent scripts or programs that return simple JSON. Ansible is also pragmatic, so when you need to, it’s also trivially easy to just execute useful shell commands.</p>
<p>Ansible is also unique in other ways. Extending ansible does not require programming in any particular language – you can write <aclass="reference internal"href="modules.html"><em>Ansible Modules</em></a> as idempotent scripts or programs that return simple JSON. Ansible is also pragmatic, so when you need to, it’s also trivially easy to just execute useful shell commands.</p>
<p>Why use Ansible versus other configuration management tools? (Puppet, Chef, etc?) Ansible will have far
<p>Why use Ansible versus other configuration management tools? (Puppet, Chef, etc?) Ansible will have far
less code, it will be (by extension) more correct, and it will be the
less code, it will be (by extension) more correct, and it will be the
<liclass="toctree-l3"><aclass="reference internal"href="playbooks.html#variables-from-other-hosts">Variables From Other Hosts</a></li>
<liclass="toctree-l3"><aclass="reference internal"href="playbooks.html#variables-from-other-hosts">Variables From Other Hosts</a></li>
<liclass="toctree-l3"><aclass="reference internal"href="playbooks.html#external-variables-and-prompted-or-sensitive-data">External Variables And Prompted or Sensitive Data</a></li>
<liclass="toctree-l3"><aclass="reference internal"href="playbooks.html#external-variables-and-prompted-or-sensitive-data">External Variables and Prompted or Sensitive Data</a></li>
<liclass="toctree-l3"><aclass="reference internal"href="playbooks.html#include-files-and-reuse">Include Files And Reuse</a></li>
<liclass="toctree-l3"><aclass="reference internal"href="playbooks.html#include-files-and-reuse">Include Files And Reuse</a></li>
...
@@ -412,7 +411,7 @@ internet infrastructure, finance, chip design, and more. Michael also
...
@@ -412,7 +411,7 @@ internet infrastructure, finance, chip design, and more. Michael also
helped co-author <aclass="reference external"href="http://fedorahosted.org/func/">Func</a>, a precursor to Ansible, which is used to
helped co-author <aclass="reference external"href="http://fedorahosted.org/func/">Func</a>, a precursor to Ansible, which is used to
orchestrate systems in lots of diverse places. He’s worked on systems
orchestrate systems in lots of diverse places. He’s worked on systems
software for IBM, Motorola, Red Hat’s Emerging Technologies Group,
software for IBM, Motorola, Red Hat’s Emerging Technologies Group,
Puppet Labs, and is now with <aclass="reference external"href="http://rpath.com">rPath</a> Reach Michael by email <aclass="reference external"href="mailto:michael.dehaan%40gmail.com">here</a>.</p>
Puppet Labs, and is now with <aclass="reference external"href="http://rpath.com">rPath</a>. Reach Michael by email <aclass="reference external"href="mailto:michael.dehaan%40gmail.com">here</a>.</p>
@@ -349,10 +349,12 @@ json isn’t in the Python standard library until 2.5.:</p>
...
@@ -349,10 +349,12 @@ json isn’t in the Python standard library until 2.5.:</p>
</div>
</div>
<p>Because the output is supposed to be valid JSON. Except that’s not quite true,
<p>Because the output is supposed to be valid JSON. Except that’s not quite true,
but we’ll get to that later.</p>
but we’ll get to that later.</p>
<p>Further, modules must not output anything on stderr, even if the JSON returned
<p>Modules must not output anything on standard error, because the system will merge
out stdout is valid. This is due to the internals of our SSH library, more or less.</p>
standard out with standard error and prevent the JSON from parsing. Capturing standard
error and returning it as a variable in the JSON on standard out is fine, and is, in fact,
how the command module is implemented.</p>
<p>If a module returns stderr or otherwise fails to produce valid JSON, the actual output
<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>
will still be shown in Ansible, but the command will not succeed.</p>
<p>Always use the hacking/test-module script when developing modules and it will warn
<p>Always use the hacking/test-module script when developing modules and it will warn
you about these kind of things.</p>
you about these kind of things.</p>
</div>
</div>
...
@@ -361,7 +363,7 @@ you about these kind of things.</p>
...
@@ -361,7 +363,7 @@ you about these kind of things.</p>
<p>As a reminder from the example code above, here are some basic conventions
<p>As a reminder from the example code above, here are some basic conventions
and guidelines:</p>
and guidelines:</p>
<ulclass="simple">
<ulclass="simple">
<li>Include a minimum of dependencies if possible. If there are dependencies, document them at the top of the module file</li>
<li>Include a minimum of dependencies if possible. If there are dependencies, document them at the top of the module file.</li>
<li>Modules must be self contained in one file to be auto-transferred by ansible</li>
<li>Modules must be self contained in one file to be auto-transferred by ansible</li>
<li>If packaging modules in an RPM, they only need to be installed on the control machine and should be dropped into /usr/share/ansible. This is entirely optional.</li>
<li>If packaging modules in an RPM, they only need to be installed on the control machine and should be dropped into /usr/share/ansible. This is entirely optional.</li>
<li>Modules should return JSON or key=value results all on one line. JSON is best if you can do JSON. All return types must be hashes (dictionaries) although they can be nested.</li>
<li>Modules should return JSON or key=value results all on one line. JSON is best if you can do JSON. All return types must be hashes (dictionaries) although they can be nested.</li>
<li><aclass="reference internal"href="#include-files-and-reuse">Include Files And Reuse</a></li>
<li><aclass="reference internal"href="#include-files-and-reuse">Include Files And Reuse</a></li>
...
@@ -261,7 +261,7 @@ documentation. The <cite>user</cite> is just the name of the user account:</p>
...
@@ -261,7 +261,7 @@ documentation. The <cite>user</cite> is just the name of the user account:</p>
user: yourname
user: yourname
sudo: True</pre>
sudo: True</pre>
</div>
</div>
<p>If you need to specify a password to sudo, run <cite>ansible-playbook</cite> with <cite>–ask-sudo-pass</cite> (<cite>-K</cite>).
<p>If you need to specify a password to sudo, run <cite>ansible-playbook</cite> with <ttclass="docutils literal"><spanclass="pre">--ask-sudo-pass</span></tt> (<cite>-K</cite>).
If you run a sudo playbook and the playbook seems to hang, it’s probably stuck at the sudo prompt.
If you run a sudo playbook and the playbook seems to hang, it’s probably stuck at the sudo prompt.
Just <cite>Control-C</cite> to kill it and run it again with <cite>-K</cite>.</p>
Just <cite>Control-C</cite> to kill it and run it again with <cite>-K</cite>.</p>
</div>
</div>
...
@@ -308,12 +308,12 @@ before moving on to the next task.</p>
...
@@ -308,12 +308,12 @@ before moving on to the next task.</p>
playbook. If things fail, simply correct the playbook file and rerun.</p>
playbook. If things fail, simply correct the playbook file and rerun.</p>
<p>The goal of each task is to execute a module, with very specific arguments.
<p>The goal of each task is to execute a module, with very specific arguments.
Variables, as mentioned above, can be used in arguments to modules.</p>
Variables, as mentioned above, can be used in arguments to modules.</p>
<p>Modules other than <cite>command</cite> are ‘idempotent’, meaning if you run them
<p>Modules other than <cite>command</cite> and <cite>shell</cite> are ‘idempotent’, meaning if you run them
again, they will make the changes they are told to make to bring the
again, they will make the changes they are told to make to bring the
system to the desired state. This makes it very safe to rerun
system to the desired state. This makes it very safe to rerun
the same playbook multiple times. They won’t change things
the same playbook multiple times. They won’t change things
unless they have to change things.</p>
unless they have to change things.</p>
<p>Command will actually rerun the same command again,
<p>The <cite>command</cite> and <cite>shell</cite> modules will actually rerun the same command again,
which is totally ok if the command is something like
which is totally ok if the command is something like
‘chmod’ or ‘setsebool’, etc.</p>
‘chmod’ or ‘setsebool’, etc.</p>
<p>Every task must have a name, which is included in the output from
<p>Every task must have a name, which is included in the output from
...
@@ -325,9 +325,9 @@ the service module takes key=value arguments:</p>
...
@@ -325,9 +325,9 @@ the service module takes key=value arguments:</p>
- name: make sure apache is running
- name: make sure apache is running
action: service name=httpd state=running</pre>
action: service name=httpd state=running</pre>
</div>
</div>
<p>The command module is the one module that just takes a list
<p>The <cite>command</cite> and <cite>shell</cite> modules are the one modules that just takes a list
of arguments, and doesn’t use the key=value form. This makes
of arguments, and don’t use the key=value form. This makes
it work just like you would expect. Simple:</p>
them work just like you would expect. Simple:</p>
<divclass="highlight-python"><pre>tasks:
<divclass="highlight-python"><pre>tasks:
- name: disable selinux
- name: disable selinux
action: command /sbin/setenforce 0</pre>
action: command /sbin/setenforce 0</pre>
...
@@ -335,7 +335,7 @@ it work just like you would expect. Simple:</p>
...
@@ -335,7 +335,7 @@ it work just like you would expect. Simple:</p>
<p>Variables can be used in action lines. Suppose you defined
<p>Variables can be used in action lines. Suppose you defined
a variable called ‘vhost’ in the ‘vars’ section, you could do this:</p>
a variable called ‘vhost’ in the ‘vars’ section, you could do this:</p>
<h3>External Variables And Prompted or Sensitive Data<aclass="headerlink"href="#external-variables-and-prompted-or-sensitive-data"title="Permalink to this headline">¶</a></h3>
<h3>External Variables and Prompted or Sensitive Data<aclass="headerlink"href="#external-variables-and-prompted-or-sensitive-data"title="Permalink to this headline">¶</a></h3>
<p>It’s a great idea to keep your playbooks under source control, but
<p>It’s a great idea to keep your playbooks under source control, but
you may wish to make the playbook source public while keeping certain
you may wish to make the playbook source public while keeping certain
important variables private. Similarly, sometimes you may just
important variables private. Similarly, sometimes you may just
...
@@ -492,6 +492,8 @@ but it is easily handled with a minimum of syntax in an Ansible Playbook:</p>
...
@@ -492,6 +492,8 @@ but it is easily handled with a minimum of syntax in an Ansible Playbook:</p>
- name: make sure apache is running
- name: make sure apache is running
action: service name=$apache state=running</pre>
action: service name=$apache state=running</pre>
</div>
</div>
<p>Note that a variable (<cite>$facter_operatingsystem</cite>) is being interpolated into the list of
filenames being defined for vars_files.</p>
<p>As a reminder, the various YAML files contain just keys and values:</p>
<p>As a reminder, the various YAML files contain just keys and values:</p>
<divclass="highlight-python"><pre>---
<divclass="highlight-python"><pre>---
# for vars/CentOS.yml
# for vars/CentOS.yml
...
@@ -558,7 +560,7 @@ includes. This may be implemented in a later release.</p>
...
@@ -558,7 +560,7 @@ includes. This may be implemented in a later release.</p>
</div>
</div>
<p>Includes can also be used in the ‘handlers’ section, for instance, if you
<p>Includes can also be used in the ‘handlers’ section, for instance, if you
want to define how to restart apache, you only have to do that once for all
want to define how to restart apache, you only have to do that once for all
of your playbooks. You might make a notifiers.yaml that looked like:</p>
of your playbooks. You might make a handlers.yml that looks like:</p>
<divclass="highlight-python"><pre>----
<divclass="highlight-python"><pre>----
# this might be in a file like handlers/handlers.yml
# this might be in a file like handlers/handlers.yml
- name: restart apache
- name: restart apache
...
@@ -618,12 +620,18 @@ actually one of the things playbooks were invented to do.</p>
...
@@ -618,12 +620,18 @@ actually one of the things playbooks were invented to do.</p>
- testuser1
- testuser1
- testuser2</pre>
- testuser2</pre>
</div>
</div>
<p>The above would be the equivalent of:</p>
<divclass="highlight-python"><pre>- name: add user testuser1
action: user name=testuser1 state=present groups=wheel
- name: add user testuser2
action: user name=testuser2 state=present groups=wheel</pre>
* Arbitrary variable names, which must be a mix of alphanumeric characters and
* Arbitrary variable names, which must be a mix of alphanumeric characters and underscores, can also be defined. Setting a variable creates a ``key=value`` pair in the JSON file for use in templating.
underscores, can also be defined. Setting a variable creates a
``key=value`` pair in the JSON file for use in templating.
