You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
ansible/rst/examples.rst

181 lines
6.5 KiB
ReStructuredText

13 years ago
Command Line Examples
=====================
The following examples show how to use `/usr/bin/ansible` for running ad-hoc tasks.
Start here. For configuration management and deployments, you'll want to pick up on
using `/usr/bin/ansible-playbook` -- the concepts port over directly.
13 years ago
Parallelism and Shell Commands
``````````````````````````````
13 years ago
Let's use ansible's command line tool to reboot all web servers in Atlanta, 10 at a time::
13 years ago
ssh-agent bash
ssh-add ~/.ssh/id_rsa.pub
ansible atlanta -a "/sbin/reboot" -f 10
The -f 10 specifies the usage of 10 simultaneous processes.
.. note::
-m does not always have to be specified to /usr/bin/ansible because 'command' is the default ansible module
If we want to execute a module using the shell, we can avoid using absolute paths, and can also include
pipe and redirection operators. Read more about the differences on the :doc:`modules` page. The shell
module looks like this::
ansible raleigh -m shell -a "echo \\$TERM"
.. note::
When using ansible to run commands, and in particular the shell module, be careful of shell quoting rules.
.. note::
Note that other than the command :doc:`modules`, 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.
13 years ago
13 years ago
File Transfer & Templating
``````````````````````````
13 years ago
Ansible can SCP lots of files to multiple machines in parallel, and
optionally use them as template sources.
13 years ago
To just transfer a file directly to many different servers::
ansible atlanta -m copy -a "src=/etc/hosts dest=/tmp/hosts"
13 years ago
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
documentation) will run the setup module for you, making this even
simpler::
13 years ago
ansible webservers -m setup -a "favcolor=red ntp_server=192.168.1.1"
ansible webservers -m template -a "src=/srv/motd.j2 dest=/etc/motd"
ansible webservers -m template -a "src=/srv/ntp.j2 dest=/etc/ntp.conf"
Ansible variables are used in templates by using the name surrounded by double
curly-braces. If facter or ohai were installed on the remote machine, variables
from those programs can be accessed too, which the appropriate prefix::
This is an Ansible variable: {{ favcolor }}
This is a facter variable: {{ facter_hostname }}
This is an ohai variable: {{ ohai_foo }}
The `file` module allows changing ownership and permissions on files. These
same options can be passed directly to the `copy` or `template` modules as well::
ansible webservers -m file -a "dest=/srv/foo/a.txt mode=600"
ansible webservers -m file -a "dest=/srv/foo/b.txt mode=600 owner=mdehaan group=mdehaan"
The `file` module can also create directories, similar to `mkdir -p`::
ansible webservers -m file -a "dest=/path/to/c mode=644 owner=mdehaan group=mdehaan state=directory"
As well as delete directories (recursively) and delete files::
ansible webservers -m file -a "dest=/path/to/c state=absent"
The mode, owner, and group arguments can also be used on the copy or template lines.
13 years ago
Managing Packages
`````````````````
Ensure a package is installed, but don't update it::
ansible webservers -m yum -a "pkg=acme state=installed"
Ensure a package is installed to a specific version::
ansible-webservers -m yum -a "pkg=acme-1.5 state=installed"
Ensure a package is at the latest version::
ansible webservers -m yum -a "pkg=acme state=latest"
13 years ago
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
for other package manages using the command module or contribute a module
for other package managers. Stop by the mailing list for info/details.
13 years ago
Deploying From Source Control
`````````````````````````````
13 years ago
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
:doc:`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.
13 years ago
13 years ago
Managing Services
`````````````````
Ensure a service is started on all webservers::
ansible webservers -m service -a "name=httpd state=started"
13 years ago
Alternatively, restart a service on all webservers::
ansible webservers -m service -a "name=httpd state=restarted"
Ensure a service is stopped::
ansible webservers -m service -a "name=httpd state=stopped"
13 years ago
13 years ago
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. If you kick hosts and don't want
to poll, it looks like this::
13 years ago
ansible all -B 3600 -a "/usr/bin/long_running_operation --do-stuff"
If you do decide you want to check on the job status later, you can::
ansible all -m async_status -a "jid=123456789"
13 years ago
Polling is built-in and looks like this::
ansible all -B 3600 -P 60 -a "/usr/bin/long_running_operation --do-stuff"
The above example says "run for 60 minutes max (60*60=3600), poll for status every 60 seconds".
Poll mode is smart so all jobs will be started before polling will begin on any machine.
Be sure to use a high enough `--forks` value if you want to get all of your jobs started
13 years ago
very quickly. After the time limit (in seconds) runs out (``-B``), the process on
the remote nodes will be terminated.
Any module other than `copy` or `template` can be
backgrounded. Typically you'll be backgrounding long-running
shell commands or software upgrades only. :doc:`playbooks` also support polling, and have
a simplified syntax for this.
13 years ago
.. seealso::
:doc:`modules`
A list of available modules
:doc:`playbooks`
Using ansible for configuration management & deployment
`Mailing List <http://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel
13 years ago
13 years ago