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/README.md

156 lines
5.2 KiB
Markdown

13 years ago
Ansible
=======
Ansible is a extra-simple Python API for doing 'remote things' over SSH.
13 years ago
While [Func](http://fedorahosted.org/func), which I co-wrote, 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.
13 years ago
13 years ago
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.
13 years ago
Principles
==========
13 years ago
* Dead simple setup
* Super fast & parallel by default
13 years ago
* No server or client daemons, uses existing SSHd
* No additional software required on client boxes
* Everything is self updating on the clients. "Modules" are remotely transferred to target boxes and exec'd, and do not stay active or consume resources.
13 years ago
* Only SSH keys are allowed for authentication
* usage of ssh-agent is more or less required (no passwords)
13 years ago
* plugins can be written in ANY language
* as with Func, API usage is an equal citizen to CLI usage
* use Python's multiprocessing capabilities to emulate Func's forkbomb logic
* all file paths can be specified as command line options easily allowing non-root usage
13 years ago
Requirements
============
13 years ago
For the server the tool is running from, *only*:
* python 2.6 -- or the 2.4/2.5 backport of the multiprocessing module
13 years ago
* paramiko
13 years ago
Inventory file
==============
The inventory file is a required list of hostnames that can be potentially managed by
ansible. Eventually this file may be editable via the CLI, but for now, is
edited with your favorite text editor.
13 years ago
The default inventory file (-H) is ~/.ansible_hosts and is a list
13 years ago
of all hostnames to target with ansible, one per line. These
can be hostnames or IPs
13 years ago
Example:
abc.example.com
def.example.com
192.168.10.50
192.168.10.51
13 years ago
This list is further filtered by the pattern wildcard (-P) to target
specific hosts. This is covered below.
13 years ago
13 years ago
You can organize groups of systems by having multiple inventory
files (i.e. keeping webservers different from dbservers, etc)
Command line usage example
13 years ago
==========================
Run a module by name with arguments
* ssh-agent bash
* ssh-add ~/.ssh/id_rsa.pub
* ansible -p "*.example.com" -n modName -a "arg1 arg2"
13 years ago
API Example
===========
The API is simple and returns basic datastructures.
import ansible
13 years ago
runner = ansible.Runner(
pattern='*',
module_name='inventory',
host_list=['xyz.example.com', '...']
)
data = runner.run()
13 years ago
{
'xyz.example.com' : [ 'any kind of datastructure is returnable' ],
'foo.example.com' : None, # failed to connect,
...
}
13 years ago
13 years ago
Additional options to Runner include the number of forks, hostname
exclusion pattern, library path, arguments, and so on. Read the source, it's not
13 years ago
complicated.
13 years ago
Patterns
========
To target only hosts starting with "rtp", for example:
* ansible "rtp*" -n command -a "yum update apache"
13 years ago
Parallelism
===========
Specify the number of forks to use, to run things in greater parallelism.
* ansible -f 10 "*.example.com" -n command -a "yum update apache"
13 years ago
13 years ago
10 forks. The default is 3. 5 is right out.
File Transfer
=============
13 years ago
Ansible can SCP lots of files to lots of places in parallel.
13 years ago
* ansible -f 10 -n copy -a "/etc/hosts /tmp/hosts"
13 years ago
Bundled Modules
===============
See the example library for modules, they can be written in any language
and simply return JSON to stdout. The path to your ansible library is
specified with the "-L" flag should you wish to use a different location
13 years ago
than "~/ansible". There is potential for a sizeable community to build
up around the library scripts.
13 years ago
13 years ago
Existing library modules
========================
* command -- runs commands, giving output, return codes, and run time info
* ping - just returns if the system is up or not
* facter - retrieves facts about the host OS
* copy - add files to remote systems
13 years ago
13 years ago
Future plans
============
* modules for users, groups, and files, using puppet style ensure mechanics
* ansible-inventory -- gathering fact/hw info, storing in git, adding RSS
* ansible-slurp ------ recursively rsync file trees for each host
13 years ago
* very simple option constructing/parsing for modules
* Dead-simple declarative configuration management engine using
a runbook style recipe file, written in JSON or YAML
13 years ago
* maybe it's own fact engine, not required, that also feeds from facter
* add/remove/list hosts from the command line
* list available modules from command line
13 years ago
* filter exclusion (run this only if fact is true/false)
License
=======
* MIT
13 years ago
Author
======
13 years ago
Michael DeHaan -- michael.dehaan@gmail.com
13 years ago
13 years ago
[http://michaeldehaan.net](http://michaeldehaan.net/)
13 years ago