From 173f27531cdc69ddde86bc7baee9f47efb5aab8f Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Fri, 17 Jul 2015 13:53:13 -0400 Subject: [PATCH] moar docs added docs for new v2 features restructures modules bar and core/extras info into their own pages changed templates to refer to the new pages added some missing ansible.cfg options more info on gathering setting --- docsite/rst/become.rst | 2 +- docsite/rst/developing_plugins.rst | 2 +- docsite/rst/guides.rst | 1 - docsite/rst/intro_configuration.rst | 44 +++++++++++++++-- docsite/rst/modules.rst | 43 +++-------------- docsite/rst/modules_core.rst | 13 +++++ docsite/rst/modules_extra.rst | 23 +++++++++ docsite/rst/modules_intro.rst | 64 +++++++++++++++++++++++++ docsite/rst/playbooks.rst | 2 + docsite/rst/playbooks_blocks.rst | 72 ++++++++++++++++++++++++++++ docsite/rst/playbooks_strategies.rst | 39 +++++++++++++++ hacking/templates/rst.j2 | 21 +------- 12 files changed, 265 insertions(+), 61 deletions(-) create mode 100644 docsite/rst/modules_core.rst create mode 100644 docsite/rst/modules_extra.rst create mode 100644 docsite/rst/modules_intro.rst create mode 100644 docsite/rst/playbooks_blocks.rst create mode 100644 docsite/rst/playbooks_strategies.rst diff --git a/docsite/rst/become.rst b/docsite/rst/become.rst index ca639c01f0d..0d09e4116ed 100644 --- a/docsite/rst/become.rst +++ b/docsite/rst/become.rst @@ -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 diff --git a/docsite/rst/developing_plugins.rst b/docsite/rst/developing_plugins.rst index 4f459a6ef05..97be451b545 100644 --- a/docsite/rst/developing_plugins.rst +++ b/docsite/rst/developing_plugins.rst @@ -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 `_ and figure things out pretty easily. .. _developing_lookup_plugins: diff --git a/docsite/rst/guides.rst b/docsite/rst/guides.rst index bcaefc83da2..c9b7c03ccec 100644 --- a/docsite/rst/guides.rst +++ b/docsite/rst/guides.rst @@ -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. diff --git a/docsite/rst/intro_configuration.rst b/docsite/rst/intro_configuration.rst index f8671fb5f1f..0a37590f9a2 100644 --- a/docsite/rst/intro_configuration.rst +++ b/docsite/rst/intro_configuration.rst @@ -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 @@ -286,9 +307,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, meaning facts will be gathered per play unless 'gather_facts: False' is set in the play and fact caching will be ignored. +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 ============== @@ -802,3 +824,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 copyc 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 diff --git a/docsite/rst/modules.rst b/docsite/rst/modules.rst index aa9ca0f40a1..6988fac8dce 100644 --- a/docsite/rst/modules.rst +++ b/docsite/rst/modules.rst @@ -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 `. -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 `_ #ansible IRC chat channel - diff --git a/docsite/rst/modules_core.rst b/docsite/rst/modules_core.rst new file mode 100644 index 00000000000..808f9839a9d --- /dev/null +++ b/docsite/rst/modules_core.rst @@ -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 `_ 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 `_ 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 `_ or on Ansible's "#ansible" channel, located on irc.freenode.net. Development oriented topics should instead use the similar `ansible-devel google group `_. + +Documentation updates for these modules 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. diff --git a/docsite/rst/modules_extra.rst b/docsite/rst/modules_extra.rst new file mode 100644 index 00000000000..0e0718cb69b --- /dev/null +++ b/docsite/rst/modules_extra.rst @@ -0,0 +1,23 @@ +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 of this module is hosted on GitHub in the `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 `_ +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 `_ +or on Ansible's "#ansible" channel, located on irc.freenode.net. +Development oriented topics should instead use the similar `ansible-devel google group `_. + +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. + +For help in developing on modules, should you be so inclined, please read :doc:`community`, :doc:`developing_test_pr` and :doc:`developing_modules`. + diff --git a/docsite/rst/modules_intro.rst b/docsite/rst/modules_intro.rst new file mode 100644 index 00000000000..bcbde9713f6 --- /dev/null +++ b/docsite/rst/modules_intro.rst @@ -0,0 +1,64 @@ +Introduction +============ + +Modules (also reffered 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 `_ + Questions? Help? Ideas? Stop by the list on Google Groups + `irc.freenode.net `_ + #ansible IRC chat channel + diff --git a/docsite/rst/playbooks.rst b/docsite/rst/playbooks.rst index cda4e9bdb7f..5e1c1b98695 100644 --- a/docsite/rst/playbooks.rst +++ b/docsite/rst/playbooks.rst @@ -24,6 +24,8 @@ It is recommended to look at `Example Playbooks `_ + Have a question? Stop by the google group! + `irc.freenode.net `_ + #ansible IRC chat channel + + + + diff --git a/docsite/rst/playbooks_strategies.rst b/docsite/rst/playbooks_strategies.rst new file mode 100644 index 00000000000..43f522df628 --- /dev/null +++ b/docsite/rst/playbooks_strategies.rst @@ -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 befor any host starts the next task, using the number of forks (default 5) to paralelize. + +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: + +Stratergy Plugins +````````````````` + +The strategies are implelented via a new type of plugin, this means that in the future new +execution types can be added in the future, 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 `_ + Have a question? Stop by the google group! + `irc.freenode.net `_ + #ansible IRC chat channel + diff --git a/hacking/templates/rst.j2 b/hacking/templates/rst.j2 index fbf50f4922b..eccae4cb777 100644 --- a/hacking/templates/rst.j2 +++ b/hacking/templates/rst.j2 @@ -175,31 +175,14 @@ Notes This is a Core Module --------------------- -The source of this module is hosted on GitHub in the `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 `_ 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 `_ or on Ansible's "#ansible" channel, located on irc.freenode.net. Development oriented topics should instead use the similar `ansible-devel google group `_. - -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 `_ 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 `_ 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 `_ or on Ansible's "#ansible" channel, located on irc.freenode.net. Development oriented topics should instead use the similar `ansible-devel google group `_. - -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 %}