* Fix refs for local_facts and various cli :option:
* Fix dev_guide/testing_pep8 refs
* remove ref to non-existing 'developing_test_pr'
* Fix ref to ansible-vault encrypt_string
* Removed hard-to-localize colloquialism.
* Rename '_ansible-pull' in playbooks_intro.
It was conflicting with rst/ansible-pull.rst. Nothing
seems to reference it.
* Add explicit targets for and update refs
Replace some ':doc:' use with ':ref:'.
Replace some :ref: to section names with explicit targets
(:doc:`Dynamic vs. Static` -> :ref:`dynamic_vs_static` etc)
* The 'YAML+Jinja' syntax lex fails here, so just use yaml
Since the yaml+jinja highlight fails, code wasnt highlighted
at all, but 'yaml' works more or less.
* just use no lexer for the < python2.6 examples
py3 will fail highlighting them, and 'python2' throws
a lexer warning, and nothing actually highlights it, so
just disable.
@ -26,7 +26,7 @@ Although it's tempting to get straight into coding, there are a few things to be
* Shared code can be placed into ``lib/ansible/module_utils/``
* Shared code can be placed into ``lib/ansible/module_utils/``
* Shared documentation (for example describing common arguments) can be placed in ``lib/ansible/utils/module_docs_fragments/``.
* Shared documentation (for example describing common arguments) can be placed in ``lib/ansible/utils/module_docs_fragments/``.
* With great power comes great responsibility: Ansible module maintainers have a duty to help keep modules up to date. As with all successful community projects, module maintainers should keep a watchful eye for reported issues and contributions.
* With great power comes great responsibility: Ansible module maintainers have a duty to help keep modules up to date. As with all successful community projects, module maintainers should keep a watchful eye for reported issues and contributions.
* Although not required, unit and/or integration tests are strongly recommended. Unit tests are especially valuable when external resources (such as cloud or network devices) are required. For more information see :doc:`testing` and the `Testing Working Group <https://github.com/ansible/community/blob/master/meetings/README.md>`_.
* Although not required, unit and/or integration tests are strongly recommended. Unit tests are especially valuable when external resources (such as cloud or network devices) are required. For more information see :doc:`dev_guide/testing` and the `Testing Working Group <https://github.com/ansible/community/blob/master/meetings/README.md>`_.
* Starting with Ansible 2.4 all :doc:`../list_of_network_modules` MUST have unit tests.
* Starting with Ansible 2.4 all :doc:`../list_of_network_modules` MUST have unit tests.
This option allows you to globally configure a custom path for :ref:`_local_facts`:: for the implied `setup` task when using implied fact gathering.
This option allows you to globally configure a custom path for :ref:`local_facts` for the implied `setup` task when using implied fact gathering.
fact_path = /home/centos/ansible_facts.d
fact_path = /home/centos/ansible_facts.d
@ -657,15 +657,15 @@ merge_multiple_cli_tags
..versionadded:: 2.3
..versionadded:: 2.3
This allows changing how multiple :option:`--tags` and :option:`--skip-tags`
This allows changing how multiple :option:`--tags <ansible-playbook --tags>` and :option:`--skip-tags <ansible-playbook --skip-tags>`
arguments are handled on the command line. Specifying :option:`--tags` more
arguments are handled on the command line. Specifying :option:`--tags <ansible-playbook --tags>` more
than once merges all of the :option:`--tags` options together. If you want
than once merges all of the :option:`--tags <ansible-playbook --tags>` options together. If you want
the pre-2.4.x behaviour where only the last value of :option:`--tags` is used,
the pre-2.4.x behaviour where only the last value of :option:`--tags <ansible-playbook --tags>` is used,
then set this to False. The same holds true for :option:`--skip-tags`.
then set this to False. The same holds true for :option:`--skip-tags <ansible-playbook --skip-tags>`.
..note:: The default value for this in 2.3 is False. In 2.4, the
..note:: The default value for this in 2.3 is False. In 2.4, the
default value is True. After 2.8, the option will be removed.
default value is True. After 2.8, the option will be removed.
Multiple :option:`--tags` and multiple :option:`--skip-tags` will always
Multiple :option:`--tags <ansible-playbook --tags>` and multiple :option:`--skip-tags <ansible-playbook --skip-tags>` will always
be merged together.
be merged together.
.._module_lang:
.._module_lang:
@ -814,26 +814,6 @@ always default to the current user if this is not defined::
remote_user = root
remote_user = root
.._restrict_facts_namespace:
restrict_facts_namespace
========================
..versionadded:: 2.4
This allows restricting facts in their own namespace (under ansible_facts) instead of pushing them into the main.
False by default. Can also be set via the environment variable :envvar:`ANSIBLE_RESTRICT_FACTS`. Using `ansible_system` as an example:
When False::
- debug: var=ansible_system
When True::
- debug: var=ansible_facts.ansible_system
.._retry_files_enabled:
.._retry_files_enabled:
retry_files_enabled
retry_files_enabled
@ -1025,7 +1005,7 @@ As of 1.7 this file can also be a script. If you are using a script instead of a
Privilege Escalation Settings
Privilege Escalation Settings
-----------------------------
-----------------------------
Ansible can use existing privilege escalation systems to allow a user to execute tasks as another. As of 1.9 ‘become’ supersedes the old sudo/su, while still being backwards compatible. Settings live under the [privilege_escalation] header.
Ansible can use existing privilege escalation systems to allow a user to execute tasks as another. As of 1.9 'become' supersedes the old sudo/su, while still being backwards compatible. Settings live under the [privilege_escalation] header.
@ -34,7 +34,7 @@ If you believe you have found a bug in a module and are already running the late
Should you have a question rather than a bug report, inquiries are welcome on the `ansible-project Google group <https://groups.google.com/forum/#%21forum/ansible-project>`_ or on Ansible’s “#ansible” channel, located on irc.freenode.net.
Should you have a question rather than a bug report, inquiries are welcome on the `ansible-project Google group <https://groups.google.com/forum/#%21forum/ansible-project>`_ or on Ansible’s “#ansible” channel, located on irc.freenode.net.
For development-oriented topics, use the `ansible-devel Google group <https://groups.google.com/forum/#%21forum/ansible-devel>`_ or Ansible’s #ansible and #ansible-devel channels, located on irc.freenode.net. You should also read :doc:`Community Information & Contributing <community>`, :doc:`Testing Ansible <testing>`, and :doc:`Developing Modules <developing_modules>`.
For development-oriented topics, use the `ansible-devel Google group <https://groups.google.com/forum/#%21forum/ansible-devel>`_ or Ansible’s #ansible and #ansible-devel channels, located on irc.freenode.net. You should also read :doc:`Community Information & Contributing <community>`, :doc:`Testing Ansible <dev_guide/testing>`, and :doc:`Developing Modules <dev_guide/developing_modules>`.
The modules are hosted on GitHub in a subdirectory of the `Ansible <https://github.com/ansible/ansible/tree/devel/lib/ansible/modules>`_ repo.
The modules are hosted on GitHub in a subdirectory of the `Ansible <https://github.com/ansible/ansible/tree/devel/lib/ansible/modules>`_ repo.
Prompts for individual ``vars_prompt`` variables will be skipped for any variable that is already defined through the command line ``--extra-vars`` option, or when running from a non-interactive session (such as cron or Ansible Tower). See :ref:`_passing_variables_on_the_command_line` in the /Variables/ chapter.
Prompts for individual ``vars_prompt`` variables will be skipped for any variable that is already defined through the command line ``--extra-vars`` option, or when running from a non-interactive session (such as cron or Ansible Tower). See :ref:`passing_variables_on_the_command_line` in the /Variables/ chapter.
If you have a variable that changes infrequently, it might make sense to
If you have a variable that changes infrequently, it might make sense to
provide a default value that can be overridden. This can be accomplished using
provide a default value that can be overridden. This can be accomplished using
@ -13,6 +13,8 @@ Includes and imports (added in 2.4) allow users to break up large playbooks into
Roles allow more than just tasks to be packaged together and can include variables, handlers, or even modules and other plugins. Unlike includes and imports, roles can also be uploaded and shared via Ansible Galaxy.
Roles allow more than just tasks to be packaged together and can include variables, handlers, or even modules and other plugins. Unlike includes and imports, roles can also be uploaded and shared via Ansible Galaxy.
@ -69,7 +69,7 @@ Variables can also be passed to include files using an alternative syntax, which
- "{{ lookup('file', 'keys/one.pub') }}"
- "{{ lookup('file', 'keys/one.pub') }}"
- "{{ lookup('file', 'keys/two.pub') }}"
- "{{ lookup('file', 'keys/two.pub') }}"
Using either syntax, variables passed in can then be used in the included files. These variables will only be available to tasks within the included file. See :doc:`variable_precedence` for more details on variable inheritance and precedence.
Using either syntax, variables passed in can then be used in the included files. These variables will only be available to tasks within the included file. See :ref:`variable_precedence` for more details on variable inheritance and precedence.
Task include statements can be used at arbitrary depth.
Task include statements can be used at arbitrary depth.
@ -33,8 +33,8 @@ Roles expect files to be in certain directory names. Roles must include at least
- ``tasks`` - contains the main list of tasks to be executed by the role.
- ``tasks`` - contains the main list of tasks to be executed by the role.
- ``handlers`` - contains handlers, which may be used by this role or even anywhere outside this role.
- ``handlers`` - contains handlers, which may be used by this role or even anywhere outside this role.
- ``defaults`` - default variables for the role (see :doc:`Variables` for more information).
- ``defaults`` - default variables for the role (see :doc:`playbooks_variables` for more information).
- ``vars`` - other variables for the role (see :doc:`Variables` for more information).
- ``vars`` - other variables for the role (see :doc:`playbooks_variables` for more information).
- ``files`` - contains files which can be deployed via this role.
- ``files`` - contains files which can be deployed via this role.
- ``templates`` - contains templates which can be deployed via this role.
- ``templates`` - contains templates which can be deployed via this role.
- ``meta`` - defines some meta data for this role. See below for more details.
- ``meta`` - defines some meta data for this role. See below for more details.
@ -58,7 +58,7 @@ Other YAML files may be included in certain directories. For example, it is comm
name: "apache2"
name: "apache2"
state: present
state: present
Roles may also include modules and other plugin types. For more information, please refer to the :doc:`Embedding Modules and Plugins In Roles` section below.
Roles may also include modules and other plugin types. For more information, please refer to the :ref:`embedding_modules_and_plugins_in_roles` section below.
Using Roles
Using Roles
```````````
```````````
@ -114,9 +114,9 @@ As of Ansible 2.4, you can now use roles inline with any other tasks using ``imp
When roles are defined in the classic manner, they are treated as static imports and processed during playbook parsing.
When roles are defined in the classic manner, they are treated as static imports and processed during playbook parsing.
..note::
..note::
The ``include_role`` option was introduced in Ansible 2.3. The usage has changed slightly as of Ansible 2.4 to match the include (dynamic) vs. import (static) usage. See :doc:`Dynamic vs. Static` for more details.
The ``include_role`` option was introduced in Ansible 2.3. The usage has changed slightly as of Ansible 2.4 to match the include (dynamic) vs. import (static) usage. See :ref:`dynamic_vs_static` for more details.
The name used for the role can be a simple name (see :doc:`Role Search Path` below), or it can be a fully qualified path::
The name used for the role can be a simple name (see :ref:`role_search_path` below), or it can be a fully qualified path::
---
---
@ -291,6 +291,8 @@ Note that we did not have to use ``allow_duplicates: true`` for ``wheel``, becau
..note::
..note::
Variable inheritance and scope are detailed in the :doc:`playbooks_variables`.
Variable inheritance and scope are detailed in the :doc:`playbooks_variables`.
.._embedding_modules_and_plugins_in_roles:
Embedding Modules and Plugins In Roles
Embedding Modules and Plugins In Roles
``````````````````````````````````````
``````````````````````````````````````
@ -333,6 +335,8 @@ The same mechanism can be used to embed and distribute plugins in a role, using
They can then be used in a template or a jinja template in any role called after 'my_custom_filter'
They can then be used in a template or a jinja template in any role called after 'my_custom_filter'
To create a vaulted variable, use the :ref:`ansible-vault encrypt_string` command. See :ref:`encrypt_string` for details.
To create a vaulted variable, use the :ref:`ansible-vault encrypt_string <ansible_vault_encrypt_string>` command. See :ref:`encrypt_string` for details.
This vaulted variable will be decrypted with the supplied vault secret and used as a normal variable. The ``ansible-vault`` command line supports stdin and stdout for encrypting data on the fly, which can be used from your favorite editor to create these vaulted variables; you just have to be sure to add the ``!vault`` tag so both Ansible and YAML are aware of the need to decrypt. The ``|`` is also required, as vault encryption results in a multi-line string.
This vaulted variable will be decrypted with the supplied vault secret and used as a normal variable. The ``ansible-vault`` command line supports stdin and stdout for encrypting data on the fly, which can be used from your favorite editor to create these vaulted variables; you just have to be sure to add the ``!vault`` tag so both Ansible and YAML are aware of the need to decrypt. The ``|`` is also required, as vault encryption results in a multi-line string.
@ -19,7 +19,7 @@ The vault feature can encrypt any structured data file used by Ansible. This ca
Ansible tasks, handlers, and so on are also data so these can be encrypted with vault as well. To hide the names of variables that you're using, you can encrypt the task files in their entirety. However, that might be a little too much and could annoy your coworkers :)
Ansible tasks, handlers, and so on are also data so these can be encrypted with vault as well. To hide the names of variables that you're using, you can encrypt the task files in their entirety. However, that might be a little too much and could annoy your coworkers :)
The vault feature can also encrypt arbitrary files, even binary files. If a vault-encrypted file is
The vault feature can also encrypt arbitrary files, even binary files. If a vault-encrypted file is
given as the :ref:`src <src>` argument to the :ref:`copy <copy>`, :ref:`template <template>`,
given as the 'src' argument to the :ref:`copy <copy>`, :ref:`template <template>`,
:ref:`unarchive <unarchive>`, :ref:`script <script>` or :ref:`assemble <assemble>` modules, the file will be placed at the destination on the target host decrypted (assuming a valid vault password is supplied when running the play).
:ref:`unarchive <unarchive>`, :ref:`script <script>` or :ref:`assemble <assemble>` modules, the file will be placed at the destination on the target host decrypted (assuming a valid vault password is supplied when running the play).
As of version 2.3, Ansible also supports encrypting single values inside a YAML file, using the `!vault` tag to let YAML and Ansible know it uses special processing. This feature is covered in more details below.
As of version 2.3, Ansible also supports encrypting single values inside a YAML file, using the `!vault` tag to let YAML and Ansible know it uses special processing. This feature is covered in more details below.
@ -277,13 +277,6 @@ To specify a vault password in a text file 'dev-password', use the :option:`--va
There is a config option (:ref:`DEFAULT_VAULT_PASSWORD_FILE`) to specify a vault password file to use
There is a config option (:ref:`DEFAULT_VAULT_PASSWORD_FILE`) to specify a vault password file to use
without requiring the :option:`--vault-password-file <ansible-playbook --vault-password-file>` cli option.
without requiring the :option:`--vault-password-file <ansible-playbook --vault-password-file>` cli option.
Adrian Likins
7 years ago
committed by