diff --git a/api.html b/api.html index 20d4dbbad49..41e5f0f00f1 100644 --- a/api.html +++ b/api.html @@ -263,7 +263,7 @@ command line tools ansible

Often a user of a configuration management system will want to keep inventory in a different system. Frequent examples include LDAP, Cobbler, or a piece of expensive enterprisey CMDB software. Ansible easily supports all -of these options via an external interventory system.

+of these options via an external inventory system.

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 Cobbler example 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.

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.

@@ -325,7 +325,7 @@ override any that have the same name.

ansible webserver -m shell -a "echo {{ a }}"

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.

+a conf.d file appropriately or something similar. Who knows?

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.

See also

diff --git a/examples.html b/examples.html index 5a5780f7eb0..b5619762e16 100644 --- a/examples.html +++ b/examples.html @@ -201,8 +201,8 @@ ssh-add ~/.ssh/id_rsa.pub 
ansible atlanta -a "/usr/bin/foo" -u yourname

If you want to run commands through sudo:

-
-
ansible atlanta -a “/usr/bin/foo” -u yourname –sudo [–ask-sudo-pass]
+
ansible atlanta -a "/usr/bin/foo" -u yourname --sudo [--ask-sudo-pass]
+

Use –ask-sudo-pass (-K) if you are not using passwordless sudo.

Ok, so those are basics. If you didn’t read about patterns and groups yet, go back and read The Inventory File, Patterns, and Groups.

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:

ansible raleigh -m shell -a 'echo $TERM'

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 -using double vs single quotes would evaluate the variable on the box you were on.

+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 in the above example would evaluate the variable on the box you were on.

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 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.

+However, we also recognize that running ad-hoc commands is equally important, so Ansible easily supports both.

File Transfer & Templating

Here’s another use case for the /usr/bin/ansible command line.

Ansible can SCP lots of files to multiple machines in parallel, and optionally use them as template sources.

-

To just transfer a file directly to many different servers:

+

To transfer a file directly to many different servers:

ansible atlanta -m copy -a "src=/etc/hosts dest=/tmp/hosts"

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 template module to write the files using those templates.

-

Templates are written in Jinja2 format. Playbooks (covered elsewhere in the +

Templates are written in Jinja2 format. +Playbooks (covered elsewhere in the documentation) will run the setup module for you, making this even simpler:

ansible webservers -m setup    -a "favcolor=red ntp_server=192.168.1.1"
@@ -281,7 +282,7 @@ ansible webservers -m file -a "dest=/srv/foo/b.txt mode=600 owner=mdehaan group=
 
Ensure a package is not installed:

 
ansible-webservers -m yum -a "pkg=acme state=removed"

 

-
Currently Ansible only has a module for managing packages with yum.  You can install
+
Currently Ansible only has modules for managing packages with yum and apt.  You can install
 for other packages for now using the command module or (better!) contribute a module
 for other package managers.  Stop by the mailing list for info/details.
diff --git a/gettingstarted.html b/gettingstarted.html index 6fced5ea074..5a26a60e77c 100644 --- a/gettingstarted.html +++ b/gettingstarted.html @@ -259,7 +259,7 @@ $ sudo rpm -Uvh ~/rpmbuild/RPMS/noarch/ansible-*.noarch.rpm

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 -rpm -Uvh with –force when RPM tells you the package is still at the +rpm -Uvh with --force when RPM tells you the package is still at the same version. This is perfectly safe to do.

diff --git a/index.html b/index.html index 00be249855b..d476cea8d2b 100644 --- a/index.html +++ b/index.html @@ -207,8 +207,7 @@ server and daemonless, scaling potential is unlimited, and no resources are wast

Deployment and Configuration, Unified

-

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 -or ending states.

+

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.

Ansible is also unique in other ways. Extending ansible does not require programming in any particular language – you can write Ansible Modules 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.

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 @@ -345,7 +344,7 @@ Email:   Power Tricks

diff --git a/moduledev.html b/moduledev.html index e16e40f0f9a..e0a7d01da27 100644 --- a/moduledev.html +++ b/moduledev.html @@ -186,7 +186,7 @@ s.parentNode.insertBefore(ga, s);

Ansible modules are reusable units of magic that can be used by the Ansible API, or by the ansible or ansible-playbook programs.

Modules can be written in any language and are found in the path specified -by ANSIBLE_LIBRARY_PATH or the –module-path command line option.

+by ANSIBLE_LIBRARY_PATH or the --module-path command line option.

Tutorial

Let’s build a module to get and set the system time. For starters, let’s build @@ -226,7 +226,7 @@ chmod +x ansible/hacking/test-module 

{u'time': u'2012-03-14 22:13:48.539183'}
-

If you did not, you might have a typo in your module, so recheck it and try again

+

If you did not, you might have a typo in your module, so recheck it and try again.

Reading Input

@@ -240,7 +240,7 @@ Here we’ll do some basic parsing to treat the input as key=value.

If no time parameter is set, we’ll just leave the time as is and return the current time.

Let’s look at the code. Read the comments as we’ll explain as we go. Note that this -highly verbose because it’s intended as an educational example. You can write modules +is highly verbose because it’s intended as an educational example. You can write modules a lot shorter than this:

#!/usr/bin/python
 
@@ -349,10 +349,12 @@ json isn’t in the Python standard library until 2.5.:

Because the output is supposed to be valid JSON. Except that’s not quite true, but we’ll get to that later.

-

Further, modules must not output anything on stderr, even if the JSON returned -out stdout is valid. This is due to the internals of our SSH library, more or less.

+

Modules must not output anything on standard error, because the system will merge +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.

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.

+will still be shown in Ansible, but the command will not succeed.

Always use the hacking/test-module script when developing modules and it will warn you about these kind of things.

@@ -361,7 +363,7 @@ you about these kind of things.

As a reminder from the example code above, here are some basic conventions and guidelines:

update-cache:

@@ -269,7 +269,7 @@ operations like “<”, “>”, “|”, and  paths to commands must be fully qualified.

This module does not support change hooks and returns the return code from the program as well as timing information about how long the -command was running for.

+command was running.

Example action from Ansible Playbooks:

command /sbin/shutdown -t now
@@ -334,7 +334,7 @@ All parameters available to the file module are also available when running the template modules.

dest:

state:

owner:

group:

group:

groups:

append:

shell:

createhome:

force:

remove:

Example action from Ansible Playbooks:

user name=mdehaan comment=awesome passwd=awWxVV.JvmdHw createhome=yes
diff --git a/patterns.html b/patterns.html
index 972b904d20a..fdc1ab7d176 100644
--- a/patterns.html
+++ b/patterns.html
@@ -196,7 +196,7 @@ Ansible’s inventory file, which defaults to /etc/ansible/hosts.

 three.example.com
-

The things in brackets are group names, you don’t have to have them, +

The things in brackets are group names. You don’t have to have them, but they are useful.

If you have hosts that run on non-standard SSH ports you can put the port number after the hostname with a colon. This requires Ansible 0.3 (integration branch):

@@ -285,7 +285,7 @@ style file with a YAML one.:

vars: - asdf: 1234 -

Tip: Be sure to start your YAML file with the YAML record designator “—”.

+

Tip: Be sure to start your YAML file with the YAML record designator ---.

NOTE: variables specified in playbooks will override variables specified in the host file. Further, if a host is in multiple groups, currently, the variables set by the last loaded group will win over variables set in other diff --git a/playbooks.html b/playbooks.html index de710ead19c..2d9bb580fff 100644 --- a/playbooks.html +++ b/playbooks.html @@ -157,7 +157,7 @@ s.parentNode.insertBefore(ga, s);

  • Power Tricks