Change behavior to behaviour in docs and tests (#39392)

* Change behavior to behaviour

- use existing fact to get hash setting rather than shell task
- fix code highlighting syntax in playbooks_variables.rst

* Re-wrote intro section; this entire topic needs a clean-up/rewrite.
This commit is contained in:
Sam Doran 2018-05-17 14:07:12 -04:00 committed by GitHub
parent c9d3bb59a4
commit 59e541e31a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 30 additions and 41 deletions

View file

@ -5,23 +5,15 @@ Variables
.. contents:: Topics
While automation exists to make it easier to make things repeatable, all of your systems are likely not exactly alike.
While automation exists to make it easier to make things repeatable, all systems are not exactly alike; some may require configuration that is slightly different from others. In some instances, the observed behavior or state of one system might influence how you configure other systems. For example, you might need to find out the IP address of a system and use it as a configuration value on another system.
On some systems you may want to set some behavior or configuration that is slightly different from others.
Ansible uses *variables* to help deal with differences between systems.
Also, some of the observed behavior or state
of remote systems might need to influence how you configure those systems. (Such as you might need to find out the IP
address of a system and even use it as a configuration value on another system).
You might have some templates for configuration files that are mostly the same, but slightly different based on those variables.
Variables in Ansible are how we deal with differences between systems.
To understand variables you'll also want to dig into :doc:`playbooks_conditionals` and :doc:`playbooks_loops`.
To understand variables you'll also want to read :doc:`playbooks_conditionals` and :doc:`playbooks_loops`.
Useful things like the **group_by** module
and the ``when`` conditional can also be used with variables, and to help manage differences between systems.
It's highly recommended that you consult the ansible-examples github repository to see a lot of examples of variables put to use.
The ansible-examples github repository contains many examples of how variables are used in Ansible.
For advice on best practices, refer to :ref:`best_practices_for_variables_and_vaults` in the *Best Practices* chapter.
@ -34,7 +26,7 @@ Before we start using variables, it's important to know what are valid variable
Variable names should be letters, numbers, and underscores. Variables should always start with a letter.
``foo_port`` is a great variable. ``foo5`` is fine too.
``foo_port`` is a great variable. ``foo5`` is fine too.
``foo-port``, ``foo port``, ``foo.port`` and ``12`` are not valid variable names.
@ -171,7 +163,7 @@ There are other places where variables can come from, but these are a type of va
Facts are information derived from speaking with your remote systems.
An example of this might be the IP address of the remote host, or what the operating system is.
An example of this might be the IP address of the remote host, or what the operating system is.
To see what information is available, try the following::
@ -449,7 +441,7 @@ Local Facts (Facts.d)
As discussed in the playbooks chapter, Ansible facts are a way of getting data about remote systems for use in playbook variables.
Usually these are discovered automatically by the **setup** module in Ansible. Users can also write custom facts modules, as described in the API guide. However, what if you want to have a simple way to provide system or user provided data for use in Ansible variables, without writing a fact module?
Usually these are discovered automatically by the ``setup`` module in Ansible. Users can also write custom facts modules, as described in the API guide. However, what if you want to have a simple way to provide system or user provided data for use in Ansible variables, without writing a fact module?
"Facts.d" is one mechanism for users to control some aspect of how their systems are managed.
@ -759,7 +751,7 @@ Passing Variables On The Command Line
In addition to ``vars_prompt`` and ``vars_files``, it is possible to set variables at the
command line using the ``--extra-vars`` (or ``-e``) argument. Variables can be defined using
a single quoted string (containing one or more variables) using one of the formats below
a single quoted string (containing one or more variables) using one of the formats below
key=value format::
@ -803,7 +795,7 @@ Escaping quotes and other special characters:
.. versionadded:: 1.2
Ensure you're escaping quotes appropriately for both your markup (e.g. JSON), and for
Ensure you're escaping quotes appropriately for both your markup (e.g. JSON), and for
the shell you're operating in.::
ansible-playbook arcade.yml --extra-vars "{\"name\":\"Conan O\'Brien\"}"
@ -812,7 +804,7 @@ the shell you're operating in.::
.. versionadded:: 1.3
In these cases, it's probably best to use a JSON or YAML file containing the variable
In these cases, it's probably best to use a JSON or YAML file containing the variable
definitions.
.. _ansible_variable_precedence:
@ -873,10 +865,10 @@ Basically, anything that goes into "role defaults" (the defaults folder inside t
.. note:: Within any section, redefining a var will overwrite the previous instance.
If multiple groups have the same variable, the last one loaded wins.
If you define a variable twice in a play's vars: section, the 2nd one wins.
.. note:: the previous describes the default config `hash_behavior=replace`, switch to 'merge' to only partially overwrite.
If you define a variable twice in a play's ``vars:`` section, the second one wins.
.. note:: The previous describes the default config ``hash_behaviour=replace``, switch to ``merge`` to only partially overwrite.
.. note:: Group loading follows parent/child relationships. Groups of the same 'patent/child' level are then merged following alphabetical order.
This last one can be superceeded by the user via `ansible_group_priority`, which defaults to 0 for all groups.
This last one can be superceeded by the user via ``ansible_group_priority``, which defaults to 0 for all groups.
Another important thing to consider (for all versions) is that connection variables override config, command line and play/role/task specific options and keywords. For example::
@ -952,10 +944,10 @@ Remember: Child groups override parent groups, and hosts always override their
Next up: learning about role variable precedence.
We'll pretty much assume you are using roles at this point. You should be using roles for sure. Roles are great. You are using
roles aren't you? Hint hint.
roles aren't you? Hint hint.
If you are writing a redistributable role with reasonable defaults, put those in the ``roles/x/defaults/main.yml`` file. This means
the role will bring along a default value but ANYTHING in Ansible will override it.
the role will bring along a default value but ANYTHING in Ansible will override it.
See :doc:`playbooks_reuse_roles` for more info about this::
---
@ -1005,7 +997,7 @@ This can often be used for things that might apply to some hosts multiple times.
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.
no default for ``name`` supplied at all. Ansible can warn you when variables aren't defined -- it's the default behavior in fact.
There are a few other things that go on with roles.

View file

@ -1,4 +1,4 @@
# test code for the hash variable behavior
# test code for the hash variable behaviour
# (c) 2014, James Cammarata <jcammarata@ansible.com>
# This file is part of Ansible
@ -16,26 +16,22 @@
# You should have received a copy of the GNU General Public License
# along with Ansible. If not, see <http://www.gnu.org/licenses/>.
- name: get the hash behavior env setting
shell: env | grep ^ANSIBLE_HASH_BEHAVIOUR'=' | cut -f2- -d'='
register: hash_behavior
# This only works with the local connection. The way this test is run means the
connection: local
delegate_to: localhost
- name: debug hash behaviour result
debug:
var: ansible_env.ANSIBLE_HASH_BEHAVIOUR
verbosity: 2
- name: debug hash behavior result
debug: var=hash_behavior.stdout
- name: assert hash behavior is merge or replace
- name: assert hash behaviour is merge or replace
assert:
that:
- "hash_behavior.stdout in ('merge', 'replace')"
- ansible_env.ANSIBLE_HASH_BEHAVIOUR in ('merge', 'replace')
- name: debug test_hash var
debug: var=test_hash
debug:
var: test_hash
verbosity: 2
- name: assert the dictionary values match
assert:
that:
- "hash_behavior.stdout == 'merge' and test_hash == merged_hash or hash_behavior.stdout == 'replace' and test_hash == replaced_hash"
- "ansible_env.ANSIBLE_HASH_BEHAVIOUR == 'merge' and test_hash == merged_hash or ansible_env.ANSIBLE_HASH_BEHAVIOUR == 'replace' and test_hash == replaced_hash"

View file

@ -1,4 +1,3 @@
---
- hosts: testhost
vars_files:
- vars/test_hash_vars.yml
@ -17,4 +16,6 @@
role_vars: "this is in role vars/main.yml"
vars_file: "this is in a vars_file"
roles:
- { role: test_hash_behavior, test_hash: {'role_argument':'this is a role argument variable'} }
- role: test_hash_behaviour
test_hash:
role_argument: 'this is a role argument variable'