mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
Update README.md
This commit is contained in:
Michael DeHaan
parent
742258a078
commit
56de2e112a
1 changed files with 5 additions and 223 deletions
228
README.md
228
README.md
|
|
@ -1,25 +1,10 @@
|
||||||
Ansible
|
Ansible
|
||||||
=======
|
=======
|
||||||
|
|
||||||
Ansible is a extra-simple tool/API for doing 'parallel remote things' over SSH -- whether
|
Ansible is a radically simple configuration-management, deployment, task-execution, and
|
||||||
executing commands, running "modules", or executing larger 'playbooks' that
|
multinode orchestration framework.
|
||||||
can serve as a configuration management or deployment system.
|
|
||||||
|
|
||||||
While [Func](http://fedorahosted.org/func), which I co-wrote,
|
Read all about at it at (http://ansible.github.com)
|
||||||
aspired to avoid using SSH and have it's own daemon infrastructure,
|
|
||||||
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. 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,
|
|
||||||
and it will be the easiest thing to hack on and use you'll ever see --
|
|
||||||
regardless of your favorite language of choice. Want to only code plugins
|
|
||||||
in bash or clojure? Ansible doesn't care. The docs will fit on one page
|
|
||||||
and the source will be blindingly obvious.
|
|
||||||
|
|
||||||
Design Principles
|
Design Principles
|
||||||
=================
|
=================
|
||||||
|
|
@ -31,214 +16,11 @@ Design Principles
|
||||||
* Modules can be written in ANY language
|
* Modules can be written in ANY language
|
||||||
* Awesome API for creating very powerful distributed scripts
|
* Awesome API for creating very powerful distributed scripts
|
||||||
* Be usable as non-root
|
* Be usable as non-root
|
||||||
* Create the easiest config management system to use, ever.
|
* The easiest config management system to use, ever.
|
||||||
|
|
||||||
Requirements
|
Get Involved
|
||||||
============
|
============
|
||||||
|
|
||||||
Requirements are extremely minimal.
|
|
||||||
|
|
||||||
If you are running python 2.6 on the 'overlord' machine, you will need:
|
|
||||||
|
|
||||||
* paramiko
|
|
||||||
* python-jinja2
|
|
||||||
* PyYAML (if using playbooks)
|
|
||||||
|
|
||||||
If you are running less than Python 2.6, you will also need
|
|
||||||
|
|
||||||
* the Python 2.4 or 2.5 backport of the multiprocessing module
|
|
||||||
* simplejson
|
|
||||||
|
|
||||||
On the managed nodes, to use templating, you will need:
|
|
||||||
|
|
||||||
* python-jinja2 (you can install this with ansible)
|
|
||||||
|
|
||||||
Patterns and Groups
|
|
||||||
===================
|
|
||||||
|
|
||||||
Ansible works off an inventory file (/etc/ansible/hosts or overrideable with -i). Hosts can
|
|
||||||
be listed by IP or hostname, and groups are denoted with square brackets:
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
abc.example.com
|
|
||||||
def.example.com
|
|
||||||
|
|
||||||
[atlanta]
|
|
||||||
192.168.10.50
|
|
||||||
192.168.10.51
|
|
||||||
|
|
||||||
[raleigh]
|
|
||||||
192.168.10.52
|
|
||||||
|
|
||||||
When running ansible commands, hosts are addressed by name, wildcard, or group name.
|
|
||||||
This specifier is used in all ansible commands. 'all' is a built-in group name that matches all
|
|
||||||
hosts. Group names and host wildcards can be mixed as needed:
|
|
||||||
|
|
||||||
all
|
|
||||||
'web*.example.com'
|
|
||||||
'appservers;dbservers'
|
|
||||||
'atlanta;raleigh'
|
|
||||||
'192.168.10.50'
|
|
||||||
|
|
||||||
Example: Massive Parallelism and Running Shell Commands
|
|
||||||
=======================================================
|
|
||||||
|
|
||||||
Reboot all web servers in Atlanta, 10 at a time:
|
|
||||||
|
|
||||||
> 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 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.
|
|
||||||
|
|
||||||
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
|
|
||||||
=====================================
|
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
> ansible atlanta copy -a "/etc/hosts /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 the templates. Templates are written in Jinja2 format. Playbooks
|
|
||||||
(covered below) will run the setup module for you, making this even simpler.
|
|
||||||
|
|
||||||
> 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"
|
|
||||||
|
|
||||||
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_' prefixes for each.
|
|
||||||
|
|
||||||
Example: Software Deployment From Source Control
|
|
||||||
================================================
|
|
||||||
|
|
||||||
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 and they are growing.
|
|
||||||
|
|
||||||
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
|
|
||||||
=========
|
|
||||||
|
|
||||||
Playbooks are a completely different way to use ansible and are particularly awesome.
|
|
||||||
|
|
||||||
They are the basis for a really simple configuration management and deployment system, unlike
|
|
||||||
any that already exist, and one that is very well suited to deploying complex
|
|
||||||
multi-machine applications. While you might run the main ansible program for ad-hoc tasks,
|
|
||||||
playbooks are more likely to be kept in source control and used to push out your configuration
|
|
||||||
or assure the configurations of your remote systems are in spec.
|
|
||||||
|
|
||||||
An example showing a small playbook:
|
|
||||||
|
|
||||||
---
|
|
||||||
- hosts: all
|
|
||||||
vars:
|
|
||||||
http_port: 80
|
|
||||||
max_clients: 200
|
|
||||||
user: root
|
|
||||||
tasks:
|
|
||||||
- include: base.yml somevar=3 othervar=4
|
|
||||||
- name: write the apache config file
|
|
||||||
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:
|
|
||||||
- include: handlers.yml
|
|
||||||
|
|
||||||
Some key concepts here include:
|
|
||||||
|
|
||||||
* Everything is expressed in a simple YAML data format, not a custom language, not code.
|
|
||||||
* Playooks can have many steps
|
|
||||||
* Any step can run as any user
|
|
||||||
* Conditional handlers fire on 'notify'. Ex: restart apache only once, at the end, only if needed
|
|
||||||
* Tasks and handlers can be 'included' to faciliate sharing and reuse
|
|
||||||
* Include statements can take parameters for customization, and be used more than once per file
|
|
||||||
* Variables from the host system (from facter, ohai, etc) bubble-up for use in templates
|
|
||||||
* Variables can be deferenced like {{ varname }} in both include directives & templates
|
|
||||||
* Templates are powered by Jinja2: http://jinja.pocoo.org/docs/templates/#synopsis
|
|
||||||
|
|
||||||
To run a playbook:
|
|
||||||
|
|
||||||
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
|
|
||||||
===
|
|
||||||
|
|
||||||
The Python API is very powerful, and is how the ansible CLI and ansible-playbook
|
|
||||||
are implemented.
|
|
||||||
|
|
||||||
import ansible.runner
|
|
||||||
|
|
||||||
runner = ansible.runner.Runner(
|
|
||||||
module_name='ping',
|
|
||||||
module_args='',
|
|
||||||
pattern='web*',
|
|
||||||
forks=10
|
|
||||||
)
|
|
||||||
datastructure = runner.run()
|
|
||||||
|
|
||||||
The run method returns results per host, grouped by whether they
|
|
||||||
could be contacted or not. Return types are module specific, as
|
|
||||||
expressed in the 'ansible-modules' manpage.
|
|
||||||
|
|
||||||
{
|
|
||||||
"dark" : {
|
|
||||||
"web1.example.com" : "failure message"
|
|
||||||
}
|
|
||||||
"contacted" : {
|
|
||||||
"web2.example.com" : 1
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
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
|
|
||||||
=======
|
|
||||||
|
|
||||||
GPLv3
|
|
||||||
|
|
||||||
Communicate
|
|
||||||
===========
|
|
||||||
|
|
||||||
* [ansible-project mailing list](http://groups.google.com/group/ansible-project)
|
* [ansible-project mailing list](http://groups.google.com/group/ansible-project)
|
||||||
* irc.freenode.net: #ansible
|
* irc.freenode.net: #ansible
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue