From ada866be464323eb0596979113f27a452b436ea7 Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Sun, 26 Feb 2012 23:03:06 -0500 Subject: [PATCH] Further README tweaks --- README.md | 47 +++++++++++++++++++++++++---------------------- 1 file changed, 25 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 703f37ce412..fa83a4056a2 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Ansible ======= Ansible is a extra-simple tool/API for doing 'parallel remote things' over SSH -- whether -executing commands, running declarative 'modules', or executing larger 'playbooks' that +executing commands, running "modules", or executing larger 'playbooks' that can serve as a configuration management or deployment system. While [Func](http://fedorahosted.org/func), which I co-wrote, @@ -11,7 +11,8 @@ Ansible aspires to be quite different and more minimal, but still able to grow more modularly over time. This is based on talking to a lot of users of various tools and wishing to eliminate problems with connectivity and long running daemons, or not picking tool X because they preferred to -code in Y. +code in Y. Further, playbooks take things a whole step further, building the config +and deployment system I always wanted to build. Why use Ansible versus something else? (Fabric, Capistrano, mCollective, Func, SaltStack, etc?) It will have far less code, it will be more correct, @@ -25,34 +26,31 @@ Design Principles * Dead simple setup * Super fast & parallel by default - * No server or client daemons, uses existing SSHd + * No server or client daemons; use existing SSHd * No additional software required on client boxes - * Everything is self updating on the clients - * Plugins can be written in ANY language - * API usage is an equal citizen to CLI usage - * Can be controlled/installed/used as non-root + * Modules can be written in ANY language + * Awesome API for creating very powerful distributed scripts + * Be usable as non-root + * Create the easiest config management system to use, ever. Requirements ============ For the server the tool is running from, *only*: - * python 2.6 -- or the 2.4/2.5 backport of the multiprocessing module - * PyYAML (install on 'overlord' if using playbooks) * paramiko + * python 2.6 (or the 2.4/2.5 backport of the multiprocessing module) + * PyYAML (only if using playbooks) -Optional -- If you want to push templates, the nodes need: +Optional -- If you want to push templates, the nodes need a template library, +which for bonus points you can install with ansible! Easy enough. * python-jinja2 Inventory file ============== -To use ansible you must have a list of hosts somewhere. - -The default inventory file (-H) is /etc/ansible/hosts and is a list -of all hostnames to manage with ansible, one per line. These -can be hostnames or IPs +To use ansible you must have a list of hosts somewhere. The default inventory file (override with -H) is /etc/ansible/hosts and is a list of all hostnames to manage with ansible, one per line. These can be hostnames or IPs. Example: @@ -61,11 +59,8 @@ Example: 192.168.10.50 192.168.10.51 -This list is further filtered by the pattern wildcard (-P) to target -specific hosts. This is covered below. - -You can organize groups of systems by having multiple inventory -files (i.e. keeping webservers different from dbservers, etc) +This list is further filtered by the pattern wildcard (-p) to target +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) Massive Parallelism, Pattern Matching, and a Usage Example ========================================================== @@ -76,6 +71,10 @@ Reboot all web servers in Atlanta, 10 at a time: * ssh-add ~/.ssh/id_rsa.pub * 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 remote system look like you state, and run the commands neccessary to get it +there. + File Transfer ============= @@ -93,6 +92,9 @@ placed by 'setup' can be reused between ansible runs. * ansible -p "*" -n template /srv/motd.j2 /etc/motd * ansible -p "*" -n template /srv/foo.j2 /etc/foo +Very soon, templates will be able to also include facter and ohai +variables. + Git Deployments =============== @@ -104,7 +106,7 @@ Take Inventory ============== Run popular open-source data discovery tools across a wide number of hosts. -This is best used from API scripts. +This is best used from API scripts that want to learn about remote systems. * ansible -p "dbserver*" -n facter * ansible -p "dbserver"" -n ohai @@ -113,7 +115,8 @@ Other Modules ============= See the library directory for lots of extras. There's also a manpage, -ansible-modules(5). +ansible-modules(5) that covers all the options they take. You can +read the asciidoc in github in the 'docs' directory. Playbooks =========