cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Merge pull request #11637 from bcoca/moar_docs

Browse source 
Moar docs
This commit is contained in:
Brian Coca 2015-07-20 22:31:34 -04:00
parent 740f15cb0d 9b1babdaec
commit c40541964b
12 changed files with 264 additions and 61 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docsite/rst/become.rst
View file

@ -49,7 +49,7 @@ New command line options
--ask-become-pass
ask for privilege escalation password
-b, --become
--become,-b
run operations with become (no password implied)
--become-method=BECOME_METHOD

2
docsite/rst/developing_plugins.rst
View file

@ -21,7 +21,7 @@ Carrier Pigeon?) it's as simple as copying the format of one of the existing mod
directory. The value of 'smart' for a connection allows selection of paramiko or openssh based on system capabilities, and chooses
'ssh' if OpenSSH supports ControlPersist, in Ansible 1.2.1 an later. Previous versions did not support 'smart'.
More documentation on writing connection plugins is pending, though you can jump into `lib/ansible/plugins/connections <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/connections`_ and figure things out pretty easily.
More documentation on writing connection plugins is pending, though you can jump into `lib/ansible/plugins/connections <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/connections>`_ and figure things out pretty easily.
.. _developing_lookup_plugins:

1
docsite/rst/guides.rst
View file

@ -11,7 +11,6 @@ This section is new and evolving. The idea here is explore particular use cases
guide_gce
guide_vagrant
guide_rolling_upgrade
test_strategies
Pending topics may include: Docker, Jenkins, Google Compute Engine, Linode/DigitalOcean, Continuous Deployment, and more.

44
docsite/rst/intro_configuration.rst
View file

@ -144,6 +144,27 @@ different locations::
Most users will not need to use this feature. See :doc:`developing_plugins` for more details
.. _stdout_callback:
stdout_callback
===============
.. versionadded:: 2.0
This setting allows you to override the default stdout callback for ansible-playbook.
.. _callback_whitelist:
callback_whitelist
==================
.. versionadded:: 2.0
Now ansible ships with all included callback plugins ready to use but they are disabled by default,
this setting lets you enable a list of additional callbacks, this cannot change or override the
default stdout callback, use :ref:`stdout_callback` for that.
.. _command_warnings:
command_warnings
@ -285,9 +306,10 @@ gathering
New in 1.6, the 'gathering' setting controls the default policy of facts gathering (variables discovered about remote systems).
The value 'implicit' is the default, meaning facts will be gathered per play unless 'gather_facts: False' is set in the play. The value 'explicit' is the inverse, facts will not be gathered unless directly requested in the play.
The value 'smart' means each new host that has no facts discovered will be scanned, but if the same host is addressed in multiple plays it will not be contacted again in the playbook run. This option can be useful for those wishing to save fact gathering time.
The value 'implicit' is the default, which means that the fact cache will be ignored and facts will be gathered per play unless 'gather_facts: False' is set.
The value 'explicit' is the inverse, facts will not be gathered unless directly requested in the play.
The value 'smart' means each new host that has no facts discovered will be scanned, but if the same host is addressed in multiple plays it will not be contacted again in the playbook run.
This option can be useful for those wishing to save fact gathering time. Both 'smart' and 'explicit' will use the fact cache.
hash_behaviour
==============
@ -801,3 +823,19 @@ If enabled, this setting allows multiple private keys to be uploaded to the daem
New clients first connect to the target node over SSH to upload the key, which is done via a local socket file, so they must have the same access as the user that launched the daemon originally.
.. _selinux_settings:
Selinux Specific Settings
-------------------------
These are settings that control SELinux interactions.
special_context_filesystems
===========================
.. versionadded:: 1.9
This is a list of file systems that require special treatment when dealing with security context.
The normal behaviour is for operations to copy the existing context or use the user default, this changes it to use a file system dependent context.
The default list is: nfs,vboxsf,fuse,ramfs

43
docsite/rst/modules.rst
View file

@ -2,48 +2,20 @@ About Modules
=============
.. toctree::
:maxdepth: 4
:maxdepth: 1
.. _modules_intro:
modules_intro
modules_core
modules_extra
common_return_values
Introduction
````````````
Ansible ships with a number of modules (called the 'module library')
that can be executed directly on remote hosts or through :doc:`Playbooks <playbooks>`.
Users can also write their own modules. These modules can control system resources, like services, packages, or files (anything really), or
handle executing system commands.
Users can also write their own modules. These modules can control system resources,
like services, packages, or files (anything really), or handle executing system commands.
Let's review how we execute three different modules from the command line::
ansible webservers -m service -a "name=httpd state=started"
ansible webservers -m ping
ansible webservers -m command -a "/sbin/reboot -t now"
Each module supports taking arguments. Nearly all modules take ``key=value``
arguments, space delimited. Some modules take no arguments, and the command/shell modules simply
take the string of the command you want to run.
From playbooks, Ansible modules are executed in a very similar way::
- name: reboot the servers
action: command /sbin/reboot -t now
Which can be abbreviated to::
- name: reboot the servers
command: /sbin/reboot -t now
All modules technically return JSON format data, though if you are using the command line or playbooks, you don't really need to know much about
that. If you're writing your own module, you care, and this means you do not have to write modules in any particular language -- you get to choose.
Modules are `idempotent`, meaning they will seek to avoid changes to the system unless a change needs to be made. When using Ansible
playbooks, these modules can trigger 'change events' in the form of notifying 'handlers' to run additional tasks.
Documentation for each module can be accessed from the command line with the ansible-doc tool::
ansible-doc yum
.. seealso::
@ -59,4 +31,3 @@ Documentation for each module can be accessed from the command line with the ans
Questions? Help? Ideas? Stop by the list on Google Groups
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel

13
docsite/rst/modules_core.rst Normal file
View file

@ -0,0 +1,13 @@
Core Modules
------------
These are modules that the core ansible team maintains and will always ship with ansible itself.
They will also receive slightly higher priority for all requests than those in the "extras" repos.
The source of these modules is hosted on GitHub in the `ansible-modules-core <http://github.com/ansible/ansible-modules-core>`_ repo.
If you believe you have found a bug in a core module and are already running the latest stable or development version of Ansible, first look in the `issue tracker at github.com/ansible/ansible-modules-core <http://github.com/ansible/ansible-modules-core>`_ to see if a bug has already been filed. If not, we would be grateful if you would file one.
Should you have a question rather than a bug report, inquries are welcome on the `ansible-project google group <https://groups.google.com/forum/#!forum/ansible-project>`_ or on Ansible's "#ansible" channel, located on irc.freenode.net. Development oriented topics should instead use the similar `ansible-devel google group <https://groups.google.com/forum/#!forum/ansible-devel>`_.
Documentation updates for these modules can also be edited directly in the module itself and by submitting a pull request to the module source code, just look for the "DOCUMENTATION" block in the source tree.

22
docsite/rst/modules_extra.rst Normal file
View file

@ -0,0 +1,22 @@
Extras Modules
--------------
These modules are currently shipped with Ansible, but might be shipped separately in the future. They are also mostly maintained by the community.
Non-core modules are still fully usable, but may receive slightly lower response rates for issues and pull requests.
Popular "extras" modules may be promoted to core modules over time.
This source for these modules is hosted on GitHub in the `ansible-modules-extras <http://github.com/ansible/ansible-modules-extras>`_ repo.
If you believe you have found a bug in an extras module and are already running the latest stable or development version of Ansible,
first look in the `issue tracker at github.com/ansible/ansible-modules-extras <http://github.com/ansible/ansible-modules-extras>`_
o see if a bug has already been filed. If not, we would be grateful if you would file one.
Should you have a question rather than a bug report, inquries are welcome on the `ansible-project google group <https://groups.google.com/forum/#!forum/ansible-project>`_
or on Ansible's "#ansible" channel, located on irc.freenode.net.
Development oriented topics should instead use the similar `ansible-devel google group <https://groups.google.com/forum/#!forum/ansible-devel>`_.
Documentation updates for this module can also be edited directly in the module and by submitting a pull request to the module source code, just look for the "DOCUMENTATION" block in the source tree.
For help in developing on modules, should you be so inclined, please read :doc:`community`, :doc:`developing_test_pr` and :doc:`developing_modules`.

64
docsite/rst/modules_intro.rst Normal file
View file

@ -0,0 +1,64 @@
Introduction
============
Modules (also referred to as "task plugins" or "library plugins") are the ones that do
the actual work in ansible, they are what gets executed in each playbook task.
But you can also run a single one using the 'ansible' command.
Let's review how we execute three different modules from the command line::
ansible webservers -m service -a "name=httpd state=started"
ansible webservers -m ping
ansible webservers -m command -a "/sbin/reboot -t now"
Each module supports taking arguments. Nearly all modules take ``key=value``
arguments, space delimited. Some modules take no arguments, and the command/shell modules simply
take the string of the command you want to run.
From playbooks, Ansible modules are executed in a very similar way::
- name: reboot the servers
action: command /sbin/reboot -t now
Which can be abbreviated to::
- name: reboot the servers
command: /sbin/reboot -t now
Another way to pass arguments to a module is using yaml syntax also called 'complex args' ::
- name: restart webserver
service:
name: httpd
state: restarted
All modules technically return JSON format data, though if you are using the command line or playbooks, you don't really need to know much about
that. If you're writing your own module, you care, and this means you do not have to write modules in any particular language -- you get to choose.
Modules strive to be `idempotent`, meaning they will seek to avoid changes to the system unless a change needs to be made. When using Ansible
playbooks, these modules can trigger 'change events' in the form of notifying 'handlers' to run additional tasks.
Documentation for each module can be accessed from the command line with the ansible-doc tool::
ansible-doc yum
A list of all installed modules is also available::
ansible-doc -l
.. seealso::
:doc:`intro_adhoc`
Examples of using modules in /usr/bin/ansible
:doc:`playbooks`
Examples of using modules with /usr/bin/ansible-playbook
:doc:`developing_modules`
How to write your own modules
:doc:`developing_api`
Examples of using modules with the Python API
`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

2
docsite/rst/playbooks.rst
View file

@ -24,6 +24,8 @@ It is recommended to look at `Example Playbooks <https://github.com/ansible/ansi
playbooks_filters
playbooks_conditionals
playbooks_loops
playbooks_blocks
playbooks_strategies
playbooks_best_practices

72
docsite/rst/playbooks_blocks.rst Normal file
View file

@ -0,0 +1,72 @@
Blocks
======
In 2.0 we added a block feature to allow for logical grouping of tasks and even
in play error handling. Most of what you can apply to a single task can be applied
at the block level, which also makes it much easier to set data or directives common
to the tasks.
Example::
tasks:
- block:
- yum: name={{ item }} state=installed
with_items:
- httpd
- memcached
- template: src=templates/src.j2 dest=/etc/foo.conf
- service: name=bar state=started enabled=True
when: ansible_distribution == 'CentOS'
become: true
become_user: root
In the example above the 3 tasks will be executed only when the block's when condition is met and enables
privilege escalation for all the enclosed tasks.
.. _block_error_handling:
Error Handling
``````````````
About Blocks
Blocks also introduce the ability to handle errors in a way similar to exceptions in most programming languages.::
tasks:
- block:
- debug: msg='i execute normally'
- command: /bin/false
- debug: msg='i never execute, cause ERROR!'
rescue:
- debug: msg='I caught an error'
- command: /bin/false
- debug: msg='I also never execute :-('
always:
- debug: msg="this always executes"
The tasks in the ``block`` would execute normally, if there is any error the ``rescue`` section would get executed
with whatever you need to do to recover from the previous error. The ``always`` section runs no matter what previous
error did or did not occur in the ``block`` and ``rescue`` sections.
.. seealso::
:doc:`playbooks`
An introduction to playbooks
:doc:`playbooks_roles`
Playbook organization by roles
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel

39
docsite/rst/playbooks_strategies.rst Normal file
View file

@ -0,0 +1,39 @@
Strategies
===========
In 2.0 we added a new way to control play execution, ``strategy``, by default plays will
still run as they used to, with what we call the ``linear`` strategy. All hosts will run each
task before any host starts the next task, using the number of forks (default 5) to parallelize.
The ``serial`` directive can 'batch' this behaviour to a subset of the hosts, which then run to
completion of the play before the next 'batch' starts.
A second ``strategy`` ships with ansible ``free``, which allows each host to run until the end of
the play as fast as it can.::
- hosts: all
strategy: free
tasks:
...
.. _strategy_plugins:
Strategy Plugins
`````````````````
The strategies are implelented via a new type of plugin, this means that in the future new
execution types can be added, either locally by users or to Ansible itself by
a code contribution.
.. seealso::
:doc:`playbooks`
An introduction to playbooks
:doc:`playbooks_roles`
Playbook organization by roles
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel

21
hacking/templates/rst.j2
View file

@ -175,31 +175,14 @@ Notes
This is a Core Module
---------------------
The source of this module is hosted on GitHub in the `ansible-modules-core <http://github.com/ansible/ansible-modules-core>`_ repo.
If you believe you have found a bug in this module, and are already running the latest stable or development version of Ansible, first look in the `issue tracker at github.com/ansible/ansible-modules-core <http://github.com/ansible/ansible-modules-core>`_ to see if a bug has already been filed. If not, we would be grateful if you would file one.
Should you have a question rather than a bug report, inquries are welcome on the `ansible-project google group <https://groups.google.com/forum/#!forum/ansible-project>`_ or on Ansible's "#ansible" channel, located on irc.freenode.net. Development oriented topics should instead use the similar `ansible-devel google group <https://groups.google.com/forum/#!forum/ansible-devel>`_.
Documentation updates for this module can also be edited directly by submitting a pull request to the module source code, just look for the "DOCUMENTATION" block in the source tree.
This is a "core" ansible module, which means it will receive slightly higher priority for all requests than those in the "extras" repos.
For more information on what this means please read :doc:`modules_core`
{% else %}
This is an Extras Module
------------------------
This source of this module is hosted on GitHub in the `ansible-modules-extras <http://github.com/ansible/ansible-modules-extras>`_ repo.
If you believe you have found a bug in this module, and are already running the latest stable or development version of Ansible, first look in the `issue tracker at github.com/ansible/ansible-modules-extras <http://github.com/ansible/ansible-modules-extras>`_ to see if a bug has already been filed. If not, we would be grateful if you would file one.
Should you have a question rather than a bug report, inquries are welcome on the `ansible-project google group <https://groups.google.com/forum/#!forum/ansible-project>`_ or on Ansible's "#ansible" channel, located on irc.freenode.net. Development oriented topics should instead use the similar `ansible-devel google group <https://groups.google.com/forum/#!forum/ansible-devel>`_.
Documentation updates for this module can also be edited directly by submitting a pull request to the module source code, just look for the "DOCUMENTATION" block in the source tree.
Note that this module is designated a "extras" module. Non-core modules are still fully usable, but may receive slightly lower response rates for issues and pull requests.
Popular "extras" modules may be promoted to core modules over time.
For more information on what this means please read :doc:`modules_extra`
{% endif %}
{% endif %}