More exciting anchor tags, document more loop features!

This commit is contained in:
Michael DeHaan 2013-10-04 18:34:39 -04:00
parent b0d5033386
commit 41909d7fd5
7 changed files with 127 additions and 3 deletions

View file

@ -4,6 +4,8 @@ Ansible Modules
.. contents:: .. contents::
:depth: 3 :depth: 3
.. _modules_intro:
Introduction Introduction
```````````` ````````````
@ -55,6 +57,7 @@ Let's see what's available in the Ansible module library, out of the box:
.. include:: modules/_list.rst .. include:: modules/_list.rst
.. _writing_modules:
Writing your own modules Writing your own modules
```````````````````````` ````````````````````````

View file

@ -54,7 +54,7 @@ As noted above, accelerated mode also supports running tasks via sudo, however t
* You must remove requiretty from your sudoers options. * You must remove requiretty from your sudoers options.
* Prompting for the sudo password is not yet supported, so the NOPASSWD option is required for commands. * Prompting for the sudo password is not yet supported, so the NOPASSWD option is required for commands.
.. _fireball_mode:
Fireball Mode Fireball Mode
````````````` `````````````

View file

@ -8,6 +8,8 @@ You can find some example playbooks illustrating these best practices in our `an
.. contents:: .. contents::
:depth: 2 :depth: 2
.. _content_organization:
Content Organization Content Organization
++++++++++++++++++++++ ++++++++++++++++++++++
@ -17,6 +19,8 @@ so feel free to modify this approach and organize as you see fit.
(One thing you will definitely want to do though, is use the "roles" organization feature, which is documented as part (One thing you will definitely want to do though, is use the "roles" organization feature, which is documented as part
of the main playbooks page) of the main playbooks page)
.. _directory_layout:
Directory Layout Directory Layout
```````````````` ````````````````
@ -54,6 +58,8 @@ The top level of the directory would contain files and directories like so::
monitoring/ # "" monitoring/ # ""
fooapp/ # "" fooapp/ # ""
.. _stage_vs_prod:
How to Arrange Inventory, Stage vs Production How to Arrange Inventory, Stage vs Production
````````````````````````````````````````````` `````````````````````````````````````````````
@ -97,6 +103,8 @@ data source as well, but this is just a basic example. Define groups based on p
boston-webservers boston-webservers
boston-dbservers boston-dbservers
.. _groups_and_hosts:
Group And Host Variables Group And Host Variables
```````````````````````` ````````````````````````
@ -130,6 +138,8 @@ We can define specific hardware variance in systems in a host_vars file, but avo
foo_agent_port: 86 foo_agent_port: 86
bar_agent_port: 99 bar_agent_port: 99
.. _role_vars:
Role Variables Role Variables
`````````````` ``````````````
@ -140,6 +150,8 @@ Variables that are associated with a given role can be defined in a main.yml fil
python_version: "2.7.5" python_version: "2.7.5"
pip_version: "1.3.1" pip_version: "1.3.1"
.. _split_by_role:
Top Level Playbooks Are Separated By Role Top Level Playbooks Are Separated By Role
````````````````````````````````````````` `````````````````````````````````````````
@ -160,6 +172,8 @@ In a file like webservers.yml (also at the top level), we simply map the configu
- common - common
- webtier - webtier
.. _role_organization:
Task And Handler Organization For A Role Task And Handler Organization For A Role
```````````````````````````````````````` ````````````````````````````````````````
@ -190,6 +204,8 @@ of each play::
- name: restart ntpd - name: restart ntpd
service: name=ntpd state=restarted service: name=ntpd state=restarted
.. _organization_examples:
What This Organization Enables (Examples) What This Organization Enables (Examples)
````````````````````````````````````````` `````````````````````````````````````````
@ -229,6 +245,8 @@ And there are some useful commands to know (at least in 1.1 and higher)::
# confirm what hostnames might be communicated with if I said "limit to boston" # confirm what hostnames might be communicated with if I said "limit to boston"
ansible-playbook -i production webservers.yml --limit boston --list-hosts ansible-playbook -i production webservers.yml --limit boston --list-hosts
.. _dep_vs_config:
Deployment vs Configuration Organization Deployment vs Configuration Organization
```````````````````````````````````````` ````````````````````````````````````````
@ -239,6 +257,8 @@ may be augmented by playbooks like 'deploy_exampledotcom.yml' but the general co
Ansible allows you to deploy and configure using the same tool, so you would likely reuse groups and just Ansible allows you to deploy and configure using the same tool, so you would likely reuse groups and just
keep the OS configuration in separate playbooks from the app deployment. keep the OS configuration in separate playbooks from the app deployment.
.. _stage_vs_prod:
Stage vs Production Stage vs Production
+++++++++++++++++++ +++++++++++++++++++
@ -247,18 +267,24 @@ As also mentioned above, a good way to keep your stage (or testing) and producti
Testing things in a stage environment before trying in production is always a great idea. Your environments need not be the same Testing things in a stage environment before trying in production is always a great idea. Your environments need not be the same
size and you can use group variables to control the differences between those environments. size and you can use group variables to control the differences between those environments.
.. _rolling_update:
Rolling Updates Rolling Updates
+++++++++++++++ +++++++++++++++
Understand the 'serial' keyword. If updating a webserver farm you really want to use it to control how many machines you are Understand the 'serial' keyword. If updating a webserver farm you really want to use it to control how many machines you are
updating at once in the batch. updating at once in the batch.
.. _mention_the_state:
Always Mention The State Always Mention The State
++++++++++++++++++++++++ ++++++++++++++++++++++++
The 'state' parameter is optional to a lot of modules. Whether 'state=present' or 'state=absent', it's always best to leave that The 'state' parameter is optional to a lot of modules. Whether 'state=present' or 'state=absent', it's always best to leave that
parameter in your playbooks to make it clear, especially as some modules support additional states. parameter in your playbooks to make it clear, especially as some modules support additional states.
.. _group_by_roles:
Group By Roles Group By Roles
++++++++++++++ ++++++++++++++
@ -268,6 +294,8 @@ A system can be in multiple groups. See :doc:`intro_inventory` and :doc:`intro_
This allows playbooks to target machines based on role, as well as to assign role specific variables This allows playbooks to target machines based on role, as well as to assign role specific variables
using the group variable system. using the group variable system.
.. _os_variance:
Operating System and Distribution Variance Operating System and Distribution Variance
++++++++++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++
@ -303,6 +331,7 @@ If group-specific settings are needed, this can also be done. For example::
In the above example, CentOS machines get the value of '42' for asdf, but other machines get '10'. In the above example, CentOS machines get the value of '42' for asdf, but other machines get '10'.
.. _ship_modules_with_playbooks:
Bundling Ansible Modules With Playbooks Bundling Ansible Modules With Playbooks
+++++++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++
@ -312,17 +341,23 @@ Bundling Ansible Modules With Playbooks
If a playbook has a "./library" directory relative to its YAML file, this directory can be used to add ansible modules that will If a playbook has a "./library" directory relative to its YAML file, this directory can be used to add ansible modules that will
automatically be in the ansible module path. This is a great way to keep modules that go with a playbook together. automatically be in the ansible module path. This is a great way to keep modules that go with a playbook together.
.. _whitespace:
Whitespace and Comments Whitespace and Comments
+++++++++++++++++++++++ +++++++++++++++++++++++
Generous use of whitespace to break things up, and use of comments (which start with '#'), is encouraged. Generous use of whitespace to break things up, and use of comments (which start with '#'), is encouraged.
.. _name_tasks:
Always Name Tasks Always Name Tasks
+++++++++++++++++ +++++++++++++++++
It is possible to leave off the 'name' for a given task, though it is recommended to provide a description It is possible to leave off the 'name' for a given task, though it is recommended to provide a description
about why something is being done instead. This name is shown when the playbook is run. about why something is being done instead. This name is shown when the playbook is run.
.. _keep_it_simple:
Keep It Simple Keep It Simple
++++++++++++++ ++++++++++++++
@ -332,6 +367,8 @@ for you. For example, you will probably not need 'vars',
'vars_files', 'vars_prompt' and '--extra-vars' all at once, 'vars_files', 'vars_prompt' and '--extra-vars' all at once,
while also using an external inventory file. while also using an external inventory file.
.. _version_control:
Version Control Version Control
+++++++++++++++ +++++++++++++++

View file

@ -15,6 +15,8 @@ Example::
ansible-playbook foo.yml --check ansible-playbook foo.yml --check
.. _forcing_to_run_in_check_mode:
Running a task in check mode Running a task in check mode
```````````````````````````` ````````````````````````````
@ -37,6 +39,7 @@ As a reminder, a task with a `when` clause evaluated to false, will
still be skipped even if it has a `always_run` clause evaluated to still be skipped even if it has a `always_run` clause evaluated to
true. true.
.. _diff_mode:
Showing Differences with --diff Showing Differences with --diff
``````````````````````````````` ```````````````````````````````

View file

@ -13,6 +13,8 @@ at once during a rolling update.
This section covers all fo these features. For examples of these items in use, please see the 'ansible-examples' repository in This section covers all fo these features. For examples of these items in use, please see the 'ansible-examples' repository in
the 'ansible' github organization. the 'ansible' github organization.
.. _rolling_update_batch_size:
Rolling Update Batch Size Rolling Update Batch Size
````````````````````````` `````````````````````````
@ -29,6 +31,8 @@ use case, you can define how many hosts Ansible should manage at a single time b
In the above example, if we had 100 hosts, 3 hosts in the group 'webservers' In the above example, if we had 100 hosts, 3 hosts in the group 'webservers'
would complete the play completely before moving on to the next 3 hosts. would complete the play completely before moving on to the next 3 hosts.
.. _maximum_failure_percentage:
Maximum Failure Percentage Maximum Failure Percentage
`````````````````````````` ``````````````````````````
@ -50,6 +54,8 @@ In the above example, if more than 3 of the 10 servers in the group were to fail
The percentage set must be exceeded, not equaled. For example, if serial were set to 4 and you wanted the task to abort The percentage set must be exceeded, not equaled. For example, if serial were set to 4 and you wanted the task to abort
when 2 of the systems failed, the percentage should be set at 49 rather than 50. when 2 of the systems failed, the percentage should be set at 49 rather than 50.
.. _delegation:
Delegation Delegation
`````````` ``````````
@ -106,6 +112,8 @@ Here is an example::
Note that you must have passphrase-less SSH keys or an ssh-agent configured for this to work, otherwise rsync Note that you must have passphrase-less SSH keys or an ssh-agent configured for this to work, otherwise rsync
will need to ask for a passphrase. will need to ask for a passphrase.
.. _local_playbooks:
Local Playbooks Local Playbooks
``````````````` ```````````````

View file

@ -9,6 +9,8 @@ need to report that it 'changed' the remote system. This section describes how
the default behavior of Ansible for certain tasks so output and error handling behavior is the default behavior of Ansible for certain tasks so output and error handling behavior is
as desired. as desired.
.. _ignoring_failed_commands:
Ignoring Failed Commands Ignoring Failed Commands
```````````````````````` ````````````````````````
@ -22,6 +24,8 @@ write a task that looks like this::
command: /bin/false command: /bin/false
ignore_errors: yes ignore_errors: yes
.. _override_the_changed_result:
Overriding The Changed Result Overriding The Changed Result
````````````````````````````` `````````````````````````````

View file

@ -3,6 +3,7 @@ Loops
All about how to use loops in playbooks. All about how to use loops in playbooks.
.. _standard_loops:
Standard Loops Standard Loops
`````````````` ``````````````
@ -37,6 +38,8 @@ If you have a list of hashes, you can reference subkeys using things like::
- { name: 'testuser1', groups: 'wheel' } - { name: 'testuser1', groups: 'wheel' }
- { name: 'testuser2', groups: 'root' } - { name: 'testuser2', groups: 'root' }
.. _nested_loops:
Nested Loops Nested Loops
```````````` ````````````
@ -56,6 +59,8 @@ As with the case of 'with_items' above, you can use previously defined variables
- users - users
- [ 'clientdb', 'employeedb', 'providerdb' ] - [ 'clientdb', 'employeedb', 'providerdb' ]
.. _looping_over_fileglobs:
Looping over Fileglobs Looping over Fileglobs
`````````````````````` ``````````````````````
@ -78,13 +83,56 @@ be used like this::
Looping over Parallel Sets of Data Looping over Parallel Sets of Data
`````````````````````````````````` ``````````````````````````````````
Documentation for this feature is coming soon. .. note:: This is an uncommon thing to want to do, but we're documenting it for completeness. You won't be reaching for this one often.
Suppose you have the following variable data was loaded in via somewhere::
---
alpha: [ 'a', 'b', 'c', 'd' ]
numbers: [ 1, 2, 3, 4 ]
And you want the set of '(a, 1)' and '(b, 2)' and so on. Use 'with_together' to get this::
tasks:
- debug: msg="{{ item.0 }} and {{ item.1 }}"
with_together:
- alpha
- numbers
Looping over Subelements Looping over Subelements
```````````````````````` ````````````````````````
Documentation for this feature is coming soon. Suppose you want to do something like loop over a list of users, creating them, and allowing them to login by a certain set of
SSH keys.
How might that be accomplished? Let's assume you had the following defined and loaded in via "vars_files" or maybe a "group_vars/all" file::
---
users:
- name: alice
authorized:
- /tmp/alice/onekey.pub
- /tmp/alice/twokey.pub
- name: bob
authorized:
- /tmp/bob/id_rsa.pub
It might happen like so::
- user: name={{ item.name }} state=present generate_ssh_key=yes
with_items: users
- authorized_key: user={{ item.0.name }} key={{ lookup('file', item.1) }}
with_subelements:
- users
- authorized
Subelements walks a list of hashes (aka dictionaries) and then traverses a list with a given key inside of those
records.
The authorized_key pattern is exactly where it comes up most.
.. _looping_over_integer_sequences:
Looping over Integer Sequences Looping over Integer Sequences
`````````````````````````````` ``````````````````````````````
@ -119,6 +167,27 @@ Negative numbers are not supported. This works as follows::
- group: name=group{{ item }} state=present - group: name=group{{ item }} state=present
with_sequence: count=4 with_sequence: count=4
.. _random_choice:
Random Choices
``````````````
The 'random_choice' feature can be used to pick something at random. While it's not a load balancer, it can
somewhat be used as a poor man's loadbalancer in a MacGyver like situation::
- debug: msg={{ item }}
with_random_choice:
- "go through the door"
- "drink from the goblet"
- "press the red button"
- "do nothing"
One of the provided strings will be selected at random.
At a more basic level, they can be used to add chaos and excitement to otherwise predictable automation environments.
.. _do_until_loops:
Do-Until Loops Do-Until Loops
`````````````` ``````````````