mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
More exciting anchor tags, document more loop features!
This commit is contained in:
parent
b0d5033386
commit
41909d7fd5
7 changed files with 127 additions and 3 deletions
|
@ -4,6 +4,8 @@ Ansible Modules
|
|||
.. contents::
|
||||
:depth: 3
|
||||
|
||||
.. _modules_intro:
|
||||
|
||||
Introduction
|
||||
````````````
|
||||
|
||||
|
@ -55,6 +57,7 @@ Let's see what's available in the Ansible module library, out of the box:
|
|||
|
||||
.. include:: modules/_list.rst
|
||||
|
||||
.. _writing_modules:
|
||||
|
||||
Writing your own modules
|
||||
````````````````````````
|
||||
|
|
|
@ -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.
|
||||
* Prompting for the sudo password is not yet supported, so the NOPASSWD option is required for commands.
|
||||
|
||||
|
||||
.. _fireball_mode:
|
||||
|
||||
Fireball Mode
|
||||
`````````````
|
||||
|
|
|
@ -8,6 +8,8 @@ You can find some example playbooks illustrating these best practices in our `an
|
|||
.. contents::
|
||||
:depth: 2
|
||||
|
||||
.. _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
|
||||
of the main playbooks page)
|
||||
|
||||
.. _directory_layout:
|
||||
|
||||
Directory Layout
|
||||
````````````````
|
||||
|
||||
|
@ -54,6 +58,8 @@ The top level of the directory would contain files and directories like so::
|
|||
monitoring/ # ""
|
||||
fooapp/ # ""
|
||||
|
||||
.. _stage_vs_prod:
|
||||
|
||||
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-dbservers
|
||||
|
||||
.. _groups_and_hosts:
|
||||
|
||||
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
|
||||
bar_agent_port: 99
|
||||
|
||||
.. _role_vars:
|
||||
|
||||
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"
|
||||
pip_version: "1.3.1"
|
||||
|
||||
.. _split_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
|
||||
- webtier
|
||||
|
||||
.. _role_organization:
|
||||
|
||||
Task And Handler Organization For A Role
|
||||
````````````````````````````````````````
|
||||
|
||||
|
@ -190,6 +204,8 @@ of each play::
|
|||
- name: restart ntpd
|
||||
service: name=ntpd state=restarted
|
||||
|
||||
.. _organization_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"
|
||||
ansible-playbook -i production webservers.yml --limit boston --list-hosts
|
||||
|
||||
.. _dep_vs_config:
|
||||
|
||||
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
|
||||
keep the OS configuration in separate playbooks from the app deployment.
|
||||
|
||||
.. _stage_vs_prod:
|
||||
|
||||
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
|
||||
size and you can use group variables to control the differences between those environments.
|
||||
|
||||
.. _rolling_update:
|
||||
|
||||
Rolling Updates
|
||||
+++++++++++++++
|
||||
|
||||
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.
|
||||
|
||||
.. _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
|
||||
parameter in your playbooks to make it clear, especially as some modules support additional states.
|
||||
|
||||
.. _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
|
||||
using the group variable system.
|
||||
|
||||
.. _os_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'.
|
||||
|
||||
.. _ship_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
|
||||
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
|
||||
+++++++++++++++++++++++
|
||||
|
||||
Generous use of whitespace to break things up, and use of comments (which start with '#'), is encouraged.
|
||||
|
||||
.. _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
|
||||
about why something is being done instead. This name is shown when the playbook is run.
|
||||
|
||||
.. _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,
|
||||
while also using an external inventory file.
|
||||
|
||||
.. _version_control:
|
||||
|
||||
Version Control
|
||||
+++++++++++++++
|
||||
|
||||
|
|
|
@ -15,6 +15,8 @@ Example::
|
|||
|
||||
ansible-playbook foo.yml --check
|
||||
|
||||
.. _forcing_to_run_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
|
||||
true.
|
||||
|
||||
.. _diff_mode:
|
||||
|
||||
Showing Differences with --diff
|
||||
```````````````````````````````
|
||||
|
|
|
@ -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
|
||||
the 'ansible' github organization.
|
||||
|
||||
.. _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'
|
||||
would complete the play completely before moving on to the next 3 hosts.
|
||||
|
||||
.. _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
|
||||
when 2 of the systems failed, the percentage should be set at 49 rather than 50.
|
||||
|
||||
.. _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
|
||||
will need to ask for a passphrase.
|
||||
|
||||
.. _local_playbooks:
|
||||
|
||||
Local Playbooks
|
||||
```````````````
|
||||
|
||||
|
|
|
@ -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
|
||||
as desired.
|
||||
|
||||
.. _ignoring_failed_commands:
|
||||
|
||||
Ignoring Failed Commands
|
||||
````````````````````````
|
||||
|
||||
|
@ -22,6 +24,8 @@ write a task that looks like this::
|
|||
command: /bin/false
|
||||
ignore_errors: yes
|
||||
|
||||
.. _override_the_changed_result:
|
||||
|
||||
Overriding The Changed Result
|
||||
`````````````````````````````
|
||||
|
||||
|
|
|
@ -3,6 +3,7 @@ Loops
|
|||
|
||||
All about how to use loops in playbooks.
|
||||
|
||||
.. _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: 'testuser2', groups: 'root' }
|
||||
|
||||
.. _nested_loops:
|
||||
|
||||
Nested Loops
|
||||
````````````
|
||||
|
||||
|
@ -56,6 +59,8 @@ As with the case of 'with_items' above, you can use previously defined variables
|
|||
- users
|
||||
- [ 'clientdb', 'employeedb', 'providerdb' ]
|
||||
|
||||
.. _looping_over_fileglobs:
|
||||
|
||||
Looping over Fileglobs
|
||||
``````````````````````
|
||||
|
||||
|
@ -78,13 +83,56 @@ be used like this::
|
|||
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
|
||||
````````````````````````
|
||||
|
||||
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
|
||||
``````````````````````````````
|
||||
|
@ -119,6 +167,27 @@ Negative numbers are not supported. This works as follows::
|
|||
- group: name=group{{ item }} state=present
|
||||
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
|
||||
``````````````
|
||||
|
||||
|
|
Loading…
Reference in a new issue