@ -47,76 +47,82 @@ which for bonus points you can install with ansible! Easy enough.
* python-jinja2
* python-jinja2
Inventory file
Patterns and Groups
==============
===================
To use ansible you must have a list of hosts somewhere. The default inventory host list (override with -l) is /etc/ansible/hosts and is a list of all hostnames to manage with ansible, one per line. These can be hostnames or IPs.
Ansible works off an inventory file (/etc/ansible/hosts or overrideable with -i). Hosts can
be listed by IP or hostname, and groups are supported with square brackets:
Example:
Example:
abc.example.com
abc.example.com
def.example.com
def.example.com
[atlanta]
192.168.10.50
192.168.10.50
192.168.10.51
192.168.10.51
This list is further filtered by the pattern wildcard (-p) to target
[raleigh]
specific hosts. This is covered below. You can also organize groups of systems by having multiple inventory files (i.e. keeping webservers different from dbservers, etc)
192.168.10.52
When running ansible commands, specific hosts are addressed by wildcard or group name.
The default pattern is '*', meaning all ansible hosts.
-p '*.example.com'
-p 'atlanta;raleigh'
-p 'database*;appserver*'
-p '192.168.10.50;192.168.10.52'
Massive Parallelism, Pattern Matching, and a Usage Example
Example: Massive Parallelism and Running Shell Commands
ansible -p "atlanta-web*" -f 10 -n command -a "/sbin/reboot"
ansible -p "atlanta-web*" -f 10 -n command -a "/sbin/reboot"
Other than the comamnd module, though, ansible modules are not scripts. They make
The -f 10 specifies the usage of 10 simultaneous processes.
the remote system look like you state, and run the commands neccessary to get it
there.
[Read the manpage](https://github.com/mpdehaan/ansible/blob/master/docs/man/man1/ansible.1.asciidoc)
Note that other than the command module, ansible modules do not work like simple scripts. They make
the remote system look like you state, and run the commands neccessary to get it there.
File Transfer
[Read the ansible manpage](https://github.com/mpdehaan/ansible/blob/master/docs/man/man1/ansible.1.asciidoc)
=============
Example: File Transfer and Templating
=====================================
Ansible can SCP lots of files to lots of places in parallel.
Ansible can SCP lots of files to multiple machines in parallel, and optionally use
them as template sources.
ansible -p "web-*.acme.net" -f 10 -n copy -a "/etc/hosts /tmp/hosts"
To just transfer a file directly to many different servers:
Templating
ansible -n copy -a "/etc/hosts /tmp/hosts"
==========
JSON files can be placed for template metadata using Jinja2. Variables
To use templating, first run the setup module to put the template variables you would
placed by 'setup' can be reused between ansible runs.
like to use on the remote host. Then use the template module to write the
files using the templates. Templates are written in Jinja2 format.
ansible -p "*" -n setup -a "favcolor=red ntp_server=192.168.1.1"
ansible -p webservers -n setup -a "favcolor=red ntp_server=192.168.1.1"
ansible -p "*" -n template -a "src=/srv/motd.j2 dest=/etc/motd"
ansible -p webservers -n template -a "src=/srv/motd.j2 dest=/etc/motd"
ansible -p "*" -n template -a "src=/srv/ntp.j2 dest=/etc/ntp.conf"
ansible -p webservers -n template -a "src=/srv/ntp.j2 dest=/etc/ntp.conf"
Need something like the fqdn in a template? If facter or ohai are installed, data from these projects
Need something like the fqdn in a template? If facter or ohai are installed, data from these projects
will also be made available to the template engine, using 'facter_' and 'ohai_'
will also be made available to the template engine, using 'facter_' and 'ohai_' prefixes for each.
prefixes for each.
Git Deployments
Example: Software Deployment From Source Control
===============
================================================
Deploy your webapp straight from git
Deploy your webapp straight from git
ansible -p "web*" -n git -a "repo=git://foo dest=/srv/myapp version=HEAD"
ansible -p webservers -n git -a "repo=git://foo dest=/srv/myapp version=HEAD"
Take Inventory
==============
Run popular open-source data discovery tools across a wide number of hosts.
This is best used from API scripts that want to learn about remote systems.
ansible -p "dbserver*" -n facter
ansible -p "dbserver"" -n ohai
Other Modules
Other Modules
=============
=============
Ansible has lots of other modules.
See the library directory for lots of extras. There's also a manpage,
See the library directory for lots of extras. There's also a manpage,
[ansible-modules(5)](https://github.com/mpdehaan/ansible/blob/master/docs/man/man5/ansible-modules.5.asciidoc) that covers all the options they take. You can
[ansible-modules(5)](https://github.com/mpdehaan/ansible/blob/master/docs/man/man5/ansible-modules.5.asciidoc) that covers all the options they take. You can
read the asciidoc in github in the 'docs' directory.
read the asciidoc in github in the 'docs' directory.
@ -124,15 +130,13 @@ read the asciidoc in github in the 'docs' directory.
Playbooks
Playbooks
=========
=========
Playbooks are particularly awesome. Playbooks can batch ansible commands
Playbooks are a completely different way to use ansible and are particularly awesome.
together, and can even fire off triggers when certain commands report changes.
They are the basis for a really simple configuration management system, unlike
They are the basis for a really simple configuration management system, unlike
any that already exist, and one that is very well suited to deploying complex
any that already exist, and one that is very well suited to deploying complex
multi-machine applications.
multi-machine applications.
An example showing just once pattern in a playbook is below. Playbooks can contain
An example showing a small playbook:
multple patterns in a single file.
---
---
- pattern: 'webservers*'
- pattern: 'webservers*'
@ -151,16 +155,17 @@ multple patterns in a single file.
- name: restart apache
- name: restart apache
- action: service name=httpd state=restarted
- action: service name=httpd state=restarted
See the playbook format manpage -- [ansible-playbook(5)](https://github.com/mpdehaan/ansible/blob/master/docs/man/man5/ansible-playbook.5.asciidoc) for more details.
To run a playbook:
To run a playbook:
ansible-playbook playbook.yml
ansible-playbook playbook.yml
See the playbook format manpage -- [ansible-playbook(5)](https://github.com/mpdehaan/ansible/blob/master/docs/man/man5/ansible-playbook.5.asciidoc) for more details.
API
API
===
===
The Python API is pretty powerful.
The Python API is very powerful:
import ansible.runner
import ansible.runner
@ -172,8 +177,9 @@ The Python API is pretty powerful.
)
)
datastructure = runner.run()
datastructure = runner.run()
And returns results per host, for hosts we could contact
The run method returns results per host, grouped by whether they
and also ones that we failed to contact.
could be contacted or not. Return types are module specific, as
expressed in the 'ansible-modules' manpage.
{
{
"dark" : {
"dark" : {
@ -182,33 +188,21 @@ and also ones that we failed to contact.
"contacted" : {
"contacted" : {
"web2.example.com" : 1
"web2.example.com" : 1
}
}
}
}
A module can return any type of JSON data it wants, so Ansible can
Since a module can return any type of JSON data it wants, so Ansible can
be used as a framework to build arbitrary applications and very powerful
be used as a framework to rapidly build powerful applications and scripts.
scripts.
Future plans
============
See github's issue tracker for what we're thinking about
Michael DeHaan
13 years ago