From defb91ae4dae1fde45b48d8d107e5b07db03ee09 Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Sat, 3 Mar 2012 14:06:15 -0500 Subject: [PATCH] README updates --- README.md | 46 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 34 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 14cd2917ac6..fb47acfb703 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,17 @@ The -f 10 specifies the usage of 10 simultaneous processes. 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. -[Read the ansible manpage](https://github.com/mpdehaan/ansible/blob/master/docs/man/man1/ansible.1.asciidoc) +Example: Time-limited Background Operations +=========================================== + +Long running operations can be backgrounded, and their status can be checked on later. The same +job ID is given to the same task on all hosts, so you won't lose track. Polling support +is pending in the command line. + + > ansible all -B 3600 -a "/usr/bin/long_running_operation --do-stuff" + > ansible all -n job_status -a jid=123456789 + +Any module other than 'copy' or 'template' can be backgrounded. Example: File Transfer and Templating ===================================== @@ -125,14 +135,18 @@ Deploy your webapp straight from git > ansible webservers -m git -a "repo=git://foo dest=/srv/myapp version=HEAD" +Since ansible modules can notify change handlers (see 'Playbooks') it is possible +to tell ansible to run specific tasks when the code is updated, such as deploying +Perl/Python/PHP/Ruby directly from git and then restarting apache. + + Other Modules ============= -Ansible has lots of other modules. +Ansible has lots of other modules and they are growing. -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 -read the asciidoc in github in the 'docs' directory. +See the library directory in the source checkout or the manpage: +[ansible-modules(5)](https://github.com/mpdehaan/ansible/blob/master/docs/man/man5/ansible-modules.5.asciidoc) that covers what's there and all the options they take. Playbooks ========= @@ -146,20 +160,27 @@ multi-machine applications. An example showing a small playbook: --- - - hosts: 'web*.example.com' - comment: webserver setup steps + - hosts: all + user: root tasks: + - include: base.yml - name: configure template & module variables for future template calls action: setup http_port=80 max_clients=200 - name: write the apache config file - action: template src=/srv/templates/httpd.j2 dest=/etc/httpd.conf + action: template src=/srv/httpd.j2 dest=/etc/httpd.conf notify: - restart apache - name: ensure apache is running action: service name=httpd state=started handlers: - - name: restart apache - - action: service name=httpd state=restarted + - include: handlers.yml + +Some key concepts here include: + + * Everything is expressed in simple YAML + * Steps can be run as non-root + * Modules can notify 'handlers' when changes occur. + * Tasks and handlers can be 'included' to faciliate sharing and 'class' like behavior To run a playbook: @@ -171,7 +192,8 @@ See the playbook format manpage -- [ansible-playbook(5)](https://github.com/mpde API === -The Python API is very powerful: +The Python API is very powerful, and is how the ansible CLI and ansible-playbook +are implemented. import ansible.runner @@ -196,7 +218,7 @@ expressed in the 'ansible-modules' manpage. } } -Since a module can return any type of JSON data it wants, so Ansible can +A module can return any type of JSON data it wants, so Ansible can be used as a framework to rapidly build powerful applications and scripts. License