Added stub for ansible-playbook (format) docs. Docs on ansible-playbook script TBD once

written.
This commit is contained in:
Michael DeHaan 2012-02-26 20:47:22 -05:00
parent fc4ba46d1a
commit 2262705ea3
4 changed files with 352 additions and 13 deletions

View file

@ -2,7 +2,7 @@
ASCII2MAN = a2x -D $(dir $@) -d manpage -f manpage $<
ASCII2HTMLMAN = a2x -D docs/html/man/ -d manpage -f xhtml
MANPAGES := docs/man/man1/ansible.1 docs/man/man5/ansible-modules.1
MANPAGES := docs/man/man1/ansible.1 docs/man/man5/ansible-modules.1 docs/man/man5/ansible-playbook.1
SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()")
docs: manuals

View file

@ -38,7 +38,7 @@ This module does not support change hooks\&.
.sp
Returns the return code from the program as well as timing information\&.
.sp
Async command running and command execution time limits are in plan\&.
Async command running and command execution time limits are in plan\&. These will probably be special keyvalue parameters expressed on the end of the command line, like ANSTIMEOUT=1 and ANS_ASYNC=1 or similar\&.
.SH "COPY"
.sp
The copy module takes a list of source files
@ -56,11 +56,18 @@ Remote absolute path where the file should end up
This module also returns md5sum information about the resultant file\&.
.SH "FACTER"
.sp
Runs the discovery program \fIfacter\fR on the remote system, returning JSON data that can be useful for inventory purposes\&. It makes no changes on the remote system\&.
Runs the discovery program \fIfacter\fR on the remote system, returning JSON data that can be useful for inventory purposes\&.
.sp
Requires that \fIfacter\fR and \fIruby\-json\fR be installed on the remote end\&.
.sp
This module takes no parameters & does not support change hooks\&.
This module is information only \- it takes no parameters & does not support change hooks, nor does it make any changes on the system\&.
.SH "FILE"
.sp
Ensures the ownership and permissions of files are as desired\&.
.sp
Use copy or template first if you need to make sure a file is on the box\&.
.sp
In plan\&.
.SH "GIT"
.sp
Deploys software from git checkouts\&.
@ -68,16 +75,18 @@ Deploys software from git checkouts\&.
This module is in plan\&.
.SH "OHAI"
.sp
Similar to the facter module, this returns JSON inventory data but makes no changes on the remote system\&.
Similar to the facter module, this returns JSON inventory data\&. Ohai data is a bit more verbose and nested than facter\&.
.sp
Requires that \fIohai\fR be installed on the remote end\&.
.sp
This module takes no parameters & does not support change hooks\&.
This module is information only \- it takes no parameters & does not support change hooks, nor does it make any changes on the system\&.
.SH "PING"
.sp
A trivial test module, this module always returns the integer \fI1\fR on successful contact\&. It makes no changes on the remote system\&.
A trivial test module, this module always returns the integer \fI1\fR on successful contact\&.
.sp
This module does not support change hooks\&.
.sp
This module is information only \- it takes no parameters & does not support change hooks, nor does it make any changes on the system\&.
.SH "SERVICE"
.sp
Controls services on remote machines\&.
@ -103,10 +112,8 @@ Writes a JSON file containing key/value data, for use in templating\&. Call this
\fBmetadata=\fR
.RS 4
Optionally overrides the default JSON file location of /etc/ansible/setup\&. If used, also supply the metadata parameter to
\fItemplate\fR\&.
\fItemplate\fR\&. Change if running as a non\-root remote user who does not have permissions on /etc/ansible\&.
.RE
.sp
Does not support change hooks yet, but in plan\&.
.SH "TEMPLATE"
.sp
Templates a file out to a remote server\&. Call the setup module prior to usage\&.
@ -123,9 +130,7 @@ location to render the template on the remote server
.PP
\fBmetadata\fR
.RS 4
location of a JSON file to use to supply template data\&. Default is /etc/ansible/setup which can be easily created using the
\fIsetup\fR
module\&.
location of a JSON file to use to supply template data\&. Default is /etc/ansible/setup which is the same as the default for the setup module\&. Change if running as a non\-root remote user who does not have permissions on /etc/ansible\&.
.RE
.sp
This module also returns md5sum information about the resultant file\&.

View file

@ -0,0 +1,113 @@
ansible-modules(5)
=================
:doctype:manpage
:man source: Ansible-playbook
:man version: 0.0.1
:man manual: System administration commands
NAME
----
ansible-playbook - format and function of an ansible playbook file
DESCRIPTION
-----------
Ansible ships with a ansible-playbook tool for running playbooks. Playbooks can represent
frequent tasks, desired system configurations, or deployment processes.
FORMAT
------
Playbooks are currently writeable in YAML. Other formats (JSON?) may be supported in the future.
EXAMPLE
-------
- pattern: '*'
hosts: '/etc/ansible/hosts'
tasks:
- do:
- configure template & module variables for future template calls
- setup http_port=80 max_clients=200
- do:
- write the apache config file
- template src=/srv/mytemplates/httpd.j2 dest=/etc/httpd/conf
notify:
- restart apache
- do
- ensure apache is running
- service name=httpd ensure=started
handlers:
- do:
- restart apache
- service name=httpd ensure=restarted
WHAT THE EXAMPLE MEANS
-----------------------
Here's what the above example will do.
For all hosts in /etc/ansible/hosts (one host per line) that are named 'webserver-anything', first
write a JSON file into /etc/ansible/setup on each remote system with the values
max_clients and http_port.
Next, use a Jinja2 template locally residing
at /srv/mytemplates/httpd.j2 to write the Apache config file on each host
to the path /etc/httpd/conf, using the previous values.
Ensure that apache is running if stopped.
If and only if the config file changed, note that we need to restart apache at the end of
the run, otherwise, don't bother because we already know it is running.
HIGH LEVEL EXPLANATION
----------------------
Playbooks are executed top down and can contain multiple references to patterns.
For instance, a playbook could do something to all webservers, then do something
to all database servers, then do something different to all webservers again.
For each pattern, the tasks in the 'tasks' list are executed in order for all
hosts in the host file matching the pattern.
For each task, a "do" statement describes what the task is and what ansible
module to use to accomplish the task, along with any arguments. The first
line in the "do" is the name of the task -- this will appear in any log output.
The second line in each "do" is the module name followed by module arguments.
Most modules accept key=value format arguments.
Handlers are like tasks, but are conditionally executed. If a module reports
a 'change', it can choose to notify a handler by name. If notified, it will
run only for hosts that changed.
FUTURE BEHAVIOR
---------------
What the playbook run does with a host when an error is detected is currently being refined
and is subject to change.
AUTHOR
------
Ansible was originally written by Michael DeHaan. See the AUTHORS file
for a complete list of contributors.
SEE ALSO
--------
ansible(1)
ansible-playbook(1) - pending
Ansible home page: <https://github.com/mpdehaan/ansible/>

View file

@ -0,0 +1,221 @@
'\" t
.\" Title: ansible-modules
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 02/26/2012
.\" Manual: System administration commands
.\" Source: Ansible-playbook 0.0.1
.\" Language: English
.\"
.TH "ANSIBLE\-MODULES" "5" "02/26/2012" "Ansible\-playbook 0\&.0\&.1" "System administration commands"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ansible-playbook \- format and function of an ansible playbook file
.SH "DESCRIPTION"
.sp
Ansible ships with a ansible\-playbook tool for running playbooks\&. Playbooks can represent frequent tasks, desired system configurations, or deployment processes\&.
.SH "FORMAT"
.sp
Playbooks are currently writeable in YAML\&. Other formats (JSON?) may be supported in the future\&.
.SH "EXAMPLE"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
pattern:
\fI*\fR
hosts:
\fI/etc/ansible/hosts\fR
tasks:
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
do:
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
configure template & module variables for future template calls
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
setup http_port=80 max_clients=200
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
do:
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
write the apache config file
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
template src=/srv/mytemplates/httpd\&.j2 dest=/etc/httpd/conf notify:
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
restart apache
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
do
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
ensure apache is running
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
service name=httpd ensure=started handlers:
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
do:
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
restart apache
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
service name=httpd ensure=restarted
.RE
.SH "WHAT THE EXAMPLE MEANS"
.sp
Here\(cqs what the above example will do\&.
.sp
For all hosts in /etc/ansible/hosts (one host per line) that are named \fIwebserver\-anything\fR, first write a JSON file into /etc/ansible/setup on each remote system with the values max_clients and http_port\&.
.sp
Next, use a Jinja2 template locally residing at /srv/mytemplates/httpd\&.j2 to write the Apache config file on each host to the path /etc/httpd/conf, using the previous values\&.
.sp
Ensure that apache is running if stopped\&.
.sp
If and only if the config file changed, note that we need to restart apache at the end of the run, otherwise, don\(cqt bother because we already know it is running\&.
.SH "HIGH LEVEL EXPLANATION"
.sp
Playbooks are executed top down and can contain multiple references to patterns\&. For instance, a playbook could do something to all webservers, then do something to all database servers, then do something different to all webservers again\&.
.sp
For each pattern, the tasks in the \fItasks\fR list are executed in order for all hosts in the host file matching the pattern\&.
.sp
For each task, a "do" statement describes what the task is and what ansible module to use to accomplish the task, along with any arguments\&. The first line in the "do" is the name of the task \(em this will appear in any log output\&.
.sp
The second line in each "do" is the module name followed by module arguments\&.
.sp
Most modules accept key=value format arguments\&.
.sp
Handlers are like tasks, but are conditionally executed\&. If a module reports a \fIchange\fR, it can choose to notify a handler by name\&. If notified, it will run only for hosts that changed\&.
.SH "FUTURE BEHAVIOR"
.sp
What the playbook run does with a host when an error is detected is currently being refined and is subject to change\&.
.SH "SEE ALSO"
.sp
ansible(1)
.sp
ansible\-playbook(1) \- pending
.sp
Ansible home page: https://github\&.com/mpdehaan/ansible/