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

Update role doc examples (#37844)

Browse source 
* fix role examples

- also fixed issue with overload of 'name', fixes #37836
- attempted to clarify tag inheritance/application

* Typo fix
This commit is contained in:
Brian Coca 2018-04-05 14:41:26 -04:00 committed by scottb
parent dca61cc397
commit c62551c1b0
4 changed files with 88 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
docs/docsite/rst/user_guide/playbooks_conditionals.rst
View file

@ -169,7 +169,8 @@ Or with a role::
- hosts: webservers
roles:
- { role: debian_stock_config, when: ansible_os_family == 'Debian' }
- role: debian_stock_config
when: ansible_os_family == 'Debian'
You will note a lot of 'skipped' output by default in Ansible when using this approach on systems that don't match the criteria.
Read up on the 'group_by' module in the :doc:`modules` docs for a more streamlined way to accomplish the same thing.

77
docs/docsite/rst/user_guide/playbooks_reuse_roles.rst
View file

@ -124,17 +124,23 @@ The name used for the role can be a simple name (see :ref:`role_search_path` bel
- hosts: webservers
roles:
- { role: '/path/to/my/roles/common' }
- role: '/path/to/my/roles/common'
Roles can accept parameters::
Roles can accept other keywords::
---
- hosts: webservers
roles:
- common
- { role: foo_app_instance, dir: '/opt/a', app_port: 5000 }
- { role: foo_app_instance, dir: '/opt/b', app_port: 5001 }
- role: foo_app_instance
vars:
dir: '/opt/a'
app_port: 5000
- role: foo_app_instance
vars:
dir: '/opt/b'
app_port: 5001
Or, using the newer syntax::
@ -149,7 +155,7 @@ Or, using the newer syntax::
app_port: 5000
...
You can conditionally execute a role. This is not generally recommended with the classic syntax, but is common when using ``import_role`` or ``include_role``::
You can conditionally import a role and execute it's tasks::
---
@ -159,12 +165,17 @@ You can conditionally execute a role. This is not generally recommended with the
name: some_role
when: "ansible_os_family == 'RedHat'"
Finally, you may wish to assign tags to the roles you specify. You can do so inline::
Finally, you may wish to assign tags to the tasks inside the roles you specify. You can do::
---
- hosts: webservers
roles:
- role: bar
tags: ["foo"]
# using YAML shorthand, this is equivalent to the above
- { role: foo, tags: ["bar", "baz"] }
Or, again, using the newer syntax::
@ -180,7 +191,20 @@ Or, again, using the newer syntax::
- baz
.. note::
This *tags all of the tasks in that role with the tags specified*, appending to any tags that are specified inside the role. The tags in this example will *not* be added to tasks inside an ``include_role``. Tag the ``include_role`` task directly in order to apply tags to tasks in included roles. If you find yourself building a role with lots of tags and you want to call subsets of the role at different times, you should consider just splitting that role into multiple roles.
This *tags all of the tasks in that role with the tags specified*, appending to any tags that are specified inside the role.
On the other hand you might just want to tag the import of the role itself::
- hosts: webservers
tasks:
- include_role:
name: bar
tags:
- foo
.. note:: The tags in this example will *not* be added to tasks inside an ``include_role``, you can use a surrounding ``block`` directive to do both.
.. note:: There is no facility to import a role while specifying a subset of tags to execute. If you find yourself building a role with lots of tags and you want to call subsets of the role at different times, you should consider just splitting that role into multiple roles.
Role Duplication and Execution
``````````````````````````````
@ -205,8 +229,10 @@ Example 1 - passing different parameters::
---
- hosts: webservers
roles:
- { role: foo, message: "first" }
- { role: foo, message: "second" }
- role: foo
vars:
message: "first"
- { role: foo, vars: { message: "second" } }
In this example, because each role definition has different parameters, ``foo`` will run twice.
@ -243,9 +269,16 @@ Role dependencies allow you to automatically pull in other roles when using a ro
---
dependencies:
- { role: common, some_parameter: 3 }
- { role: apache, apache_port: 80 }
- { role: postgres, dbname: blarg, other_parameter: 12 }
- role: common
vars:
some_parameter: 3
- role: apache
vars:
apache_port: 80
- role: postgres
vars:
dbname: blarg
other_parameter: 12
.. note::
Role dependencies must use the classic role definition style.
@ -259,17 +292,25 @@ For example, a role named ``car`` depends on a role named ``wheel`` as follows::
---
dependencies:
- { role: wheel, n: 1 }
- { role: wheel, n: 2 }
- { role: wheel, n: 3 }
- { role: wheel, n: 4 }
- role: wheel
vars:
n: 1
- role: wheel
vars:
n: 2
- role: wheel
vars:
n: 3
- role: wheel
vars:
n: 4
And the ``wheel`` role depends on two roles: ``tire`` and ``brake``. The ``meta/main.yml`` for wheel would then contain the following::
---
dependencies:
- { role: tire }
- { role: brake }
- role: tire
- role: brake
And the ``meta/main.yml`` for ``tire`` and ``brake`` would contain the following::

9
docs/docsite/rst/user_guide/playbooks_tags.rst
View file

@ -86,10 +86,13 @@ You can apply tags to more than tasks, but they ONLY affect the tasks themselves
tasks:
...
You may also apply tags to roles::
You may also apply tags to the tasks imported by roles::
roles:
- { role: webserver, port: 5000, tags: [ 'web', 'foo' ] }
- role: webserver
vars:
port: 5000
tags: [ 'web', 'foo' ]
And import statements::
@ -100,6 +103,8 @@ All of these apply the specified tags to EACH task inside the play, imported
file, or role, so that these tasks can be selectively run when the playbook
is invoked with the corresponding tags.
There is no way to 'import only these tags'; you probably want to split into smaller roles/includes if you find yourself looking for such a feature.
The above information does not apply to `include_tasks` or other dynamic includes,
as the attributes applied to an include, only affect the include itself.

28
docs/docsite/rst/user_guide/playbooks_variables.rst
View file

@ -987,7 +987,9 @@ Parameterized roles are useful.
If you are using a role and want to override a default, pass it as a parameter to the role like so::
roles:
- { role: apache, http_port: 8080 }
- role: apache
vars:
http_port: 8080
This makes it clear to the playbook reader that you've made a conscious choice to override some default in the role, or pass in some
configuration that the role can't assume by itself. It also allows you to pass something site-specific that isn't really part of the
@ -996,10 +998,18 @@ role you are sharing with others.
This can often be used for things that might apply to some hosts multiple times. For example::
roles:
- { role: app_user, name: Ian }
- { role: app_user, name: Terry }
- { role: app_user, name: Graham }
- { role: app_user, name: John }
- role: app_user
vars:
myname: Ian
- role: app_user
vars:
myname: Terry
- role: app_user
vars:
myname: Graham
- role: app_user
vars:
myname: John
In this example, the same role was invoked multiple times. It's quite likely there was
no default for 'name' supplied at all. Ansible can warn you when variables aren't defined -- it's the default behavior in fact.
@ -1010,9 +1020,11 @@ Generally speaking, variables set in one role are available to others. This mea
can set variables in there and make use of them in other roles and elsewhere in your playbook::
roles:
- { role: common_settings }
- { role: something, foo: 12 }
- { role: something_else }
- role: common_settings
- role: something
vars:
foo: 12
- role: something_else
.. note:: There are some protections in place to avoid the need to namespace variables.
In the above, variables defined in common_settings are most definitely available to 'something' and 'something_else' tasks, but if