Doc build warning/broken link clean-a-palooza (#37382)
* Doc build warning/broken link clean-a-palooza, WIP commit 1. * Fixed broken anchor * Fixing additional broken links; converting from doc to ref. * Fix anchor
This commit is contained in:
scottb
GitHub
parent
ff15a9e7e2
commit
381359a8f8
67 changed files with 289 additions and 230 deletions
|
|
@ -4,9 +4,13 @@ cat <<- EOF > ../docsite/rst/dev_guide/testing/sanity/index.rst
|
|||
Sanity Tests
|
||||
============
|
||||
|
||||
The following sanity tests are available as \`\`--test\`\` options for \`\`ansible-test sanity\`\`:
|
||||
|
||||
$(for test in $(../../test/runner/ansible-test sanity --list-tests); do echo "- :doc:\`${test} <${test}>\`"; done)
|
||||
|
||||
The following sanity tests are available as \`\`--test\`\` options for \`\`ansible-test sanity\`\`.
|
||||
This list is also available using \`\`ansible-test sanity --list-tests\`\`.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
$(for test in $(../../test/runner/ansible-test sanity --list-tests); do echo " ${test}"; done)
|
||||
|
||||
|
||||
EOF
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _community_committer_guidelines:
|
||||
|
||||
Committers Guidelines (for people with commit rights to Ansible on GitHub)
|
||||
``````````````````````````````````````````````````````````````````````````
|
||||
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ actually manage the GitHub permissions.
|
|||
Change Branch Permissions for Release
|
||||
-------------------------------------
|
||||
|
||||
When we make releases we make people go through a :doc:`release_manager` to push commits to that
|
||||
When we make releases we make people go through a :ref:`release_managers` to push commits to that
|
||||
branch. The GitHub admins are responsible for setting the branch so only the Release Manager can
|
||||
commit to the branch when the release process reaches that stage and later opening the branch once
|
||||
the release has been made. The Release manager will let the GitHub Admin know when this needs to be
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _ansible_community_guide:
|
||||
|
||||
***********************
|
||||
Ansible Community Guide
|
||||
***********************
|
||||
|
|
|
|||
|
|
@ -1,3 +1,6 @@
|
|||
.. _release_managers:
|
||||
|
||||
|
||||
Release Managers
|
||||
================
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _developing_api:
|
||||
|
||||
Python API
|
||||
==========
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +1,12 @@
|
|||
.. _developing_inventory:
|
||||
|
||||
Developing Dynamic Inventory Sources
|
||||
====================================
|
||||
|
||||
.. contents:: Topics
|
||||
:local:
|
||||
|
||||
As described in :doc:`../intro_dynamic_inventory`, Ansible can pull inventory information from dynamic sources, including cloud sources. You can also create a new dynamic inventory provider by creating a script or program that can output JSON in the correct format when invoked with the proper arguments. There is no restriction on the language used for creating a dynamic inventory provider.
|
||||
As described in :ref:`dynamic_inventory`, Ansible can pull inventory information from dynamic sources, including cloud sources. You can also create a new dynamic inventory provider by creating a script or program that can output JSON in the correct format when invoked with the proper arguments. There is no restriction on the language used for creating a dynamic inventory provider.
|
||||
|
||||
.. _inventory_script_conventions:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _appendix_module_utilities:
|
||||
|
||||
Appendix: Module Utilities
|
||||
``````````````````````````
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _developing_modules:
|
||||
|
||||
Developing Modules
|
||||
==================
|
||||
|
||||
|
|
@ -16,7 +18,7 @@ return information to ansible by printing a JSON string to stdout before
|
|||
exiting. They take arguments in one of several ways which we'll go into
|
||||
as we work through this tutorial.
|
||||
|
||||
See :doc:`../modules` for a list of existing modules.
|
||||
See :ref:`all_modules` for a list of existing modules.
|
||||
|
||||
Modules can be written in any language and are found in the path specified
|
||||
by :envvar:`ANSIBLE_LIBRARY` or the ``--module-path`` command line option or
|
||||
|
|
@ -31,7 +33,7 @@ develop a module. Ask the following questions:
|
|||
|
||||
1. Does a similar module already exist?
|
||||
|
||||
There are a lot of existing modules available, you should check out the list of existing modules at :doc:`../modules`
|
||||
There are a lot of existing modules available, you should check out the list of existing modules at :ref:`modules`
|
||||
|
||||
2. Has someone already worked on a similar Pull Request?
|
||||
|
||||
|
|
@ -93,7 +95,7 @@ The following topics will discuss how to develop and work with modules:
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`../modules`
|
||||
:ref:`all_modules`
|
||||
Learn about available modules
|
||||
:doc:`developing_plugins`
|
||||
Learn about developing plugins
|
||||
|
|
|
|||
|
|
@ -188,7 +188,7 @@ The following fields can be used and are all required unless specified otherwise
|
|||
:module:
|
||||
The name of the module. This must be the same as the filename, without the ``.py`` extension.
|
||||
:short_description:
|
||||
* A short description which is displayed on the :doc:`../list_of_all_modules` page and ``ansible-doc -l``.
|
||||
* A short description which is displayed on the :ref:`all_modules` page and ``ansible-doc -l``.
|
||||
* As the short description is displayed by ``ansible-doc -l`` without the category grouping it needs enough detail to explain its purpose without the context of the directory structure in which it lives.
|
||||
* Unlike ``description:`` this field should not have a trailing full stop.
|
||||
:description:
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _developing_modules_general_windows:
|
||||
|
||||
Windows Ansible Module Development Walkthrough
|
||||
==============================================
|
||||
|
||||
|
|
|
|||
|
|
@ -22,12 +22,12 @@ Although it's tempting to get straight into coding, there are a few things to be
|
|||
* For new modules going into Ansible 2.4 we are raising the bar so they must be PEP 8 compliant. See :doc:`testing_pep8` for more information.
|
||||
* Starting with Ansible version 2.4, all new modules must support Python 2.6 and Python 3.5+. If this is an issue, please contact us (see the "Speak to us" section later in this document to learn how).
|
||||
* All modules shipped with Ansible must be done so under the GPLv3 license. Files under the ``lib/ansible/module_utils/`` directory should be done so under the BSD license.
|
||||
* Have a look at the existing modules and how they've been named in the :doc:`../list_of_all_modules`, especially in the same functional area (such as cloud, networking, databases).
|
||||
* Have a look at the existing modules and how they've been named in the :ref:`all_modules`, especially in the same functional area (such as cloud, networking, databases).
|
||||
* 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/``.
|
||||
* 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>`_.
|
||||
* Starting with Ansible 2.4 all :doc:`../list_of_network_modules` MUST have unit tests.
|
||||
* Starting with Ansible 2.4 all :ref:`network_modules` MUST have unit tests.
|
||||
|
||||
|
||||
Naming Convention
|
||||
|
|
@ -37,7 +37,7 @@ As you may have noticed when looking under ``lib/ansible/modules/`` we support u
|
|||
|
||||
The directory name should represent the *product* or *OS* name, not the company name.
|
||||
|
||||
Each module should have the above (or similar) prefix; see existing :doc:`../list_of_all_modules` for existing examples.
|
||||
Each module should have the above (or similar) prefix; see existing :ref:`all_modules` for existing examples.
|
||||
|
||||
**Note:**
|
||||
|
||||
|
|
@ -61,7 +61,7 @@ Where to get support
|
|||
|
||||
Ansible has a thriving and knowledgeable community of module developers that is a great resource for getting your questions answered.
|
||||
|
||||
On :doc:`../community` you can find how to:
|
||||
In the :ref:`ansible_community_guide` you can find how to:
|
||||
|
||||
* Subscribe to the Mailing Lists - We suggest "Ansible Development List" (for codefreeze info) and "Ansible Announce list"
|
||||
* ``#ansible-devel`` - We have found that IRC ``#ansible-devel`` on FreeNode's IRC network works best for module developers so we can have an interactive dialogue.
|
||||
|
|
@ -93,7 +93,7 @@ And that's it.
|
|||
|
||||
Before pushing your PR to GitHub it's a good idea to review the :doc:`developing_modules_checklist` again.
|
||||
|
||||
After publishing your PR to https://github.com/ansible/ansible, a Shippable CI test should run within a few minutes. Check the results (at the end of the PR page) to ensure that it's passing (green). If it's not passing, inspect each of the results. Most of the errors should be self-explanatory and are often related to badly formatted documentation (see :doc:`../YAMLSyntax`) or code that isn't valid Python 2.6 or valid Python 3.5 (see :doc:`developing_python3`). If you aren't sure what a Shippable test message means, copy it into the PR along with a comment and we will review.
|
||||
After publishing your PR to https://github.com/ansible/ansible, a Shippable CI test should run within a few minutes. Check the results (at the end of the PR page) to ensure that it's passing (green). If it's not passing, inspect each of the results. Most of the errors should be self-explanatory and are often related to badly formatted documentation (see :ref:`yaml_syntax`) or code that isn't valid Python 2.6 or valid Python 3.5 (see :ref:`developing_python_3`). If you aren't sure what a Shippable test message means, copy it into the PR along with a comment and we will review.
|
||||
|
||||
If you need further advice, consider join the ``#ansible-devel`` IRC channel (see how in the "Where to get support").
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _developing_plugins:
|
||||
|
||||
Developing Plugins
|
||||
==================
|
||||
|
||||
|
|
@ -149,7 +151,7 @@ Connection plugins allow Ansible to connect to the target hosts so it can execut
|
|||
|
||||
By default, Ansible ships with several plugins. The most commonly used are the 'paramiko' SSH, native ssh (just called 'ssh'), and 'local' connection types. All of these can be used in playbooks and with /usr/bin/ansible to decide how you want to talk to remote machines.
|
||||
|
||||
The basics of these connection types are covered in the :doc:`../intro_getting_started` section.
|
||||
The basics of these connection types are covered in the :ref:`intro_getting_started` section.
|
||||
|
||||
Should you want to extend Ansible to support other transports (SNMP, Message bus, etc) it's as simple as copying the format of one of the existing modules and dropping it into the connection plugins directory.
|
||||
|
||||
|
|
@ -362,8 +364,8 @@ When shipped as part of a role, the plugin will be available as soon as the role
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`../modules`
|
||||
List of built-in modules
|
||||
:ref:`all_modules`
|
||||
List of all modules
|
||||
:doc:`developing_api`
|
||||
Learn about the Python API for task execution
|
||||
:doc:`developing_inventory`
|
||||
|
|
|
|||
|
|
@ -211,7 +211,7 @@ the managed machine.
|
|||
complications around Windows modules that must have the same names as Python
|
||||
modules, so that internal calling of modules from other Action Plugins work.)
|
||||
|
||||
Much of this functionality comes from the :class:`BaseAction` class,
|
||||
Much of this functionality comes from the `BaseAction` class,
|
||||
which lives in :file:`plugins/action/__init__.py`. It makes use of
|
||||
``Connection`` and ``Shell`` objects to do its work.
|
||||
|
||||
|
|
@ -278,18 +278,18 @@ substitutions:
|
|||
- :code:`"<<ANSIBLE_VERSION>>"` is substituted with the Ansible version. In
|
||||
:ref:`new-style Python modules <flow_python_modules>` under the
|
||||
:ref:`Ansiballz` framework the proper way is to instead instantiate an
|
||||
:class:`AnsibleModule` and then access the version from
|
||||
`AnsibleModule` and then access the version from
|
||||
:attr:``AnsibleModule.ansible_version``.
|
||||
- :code:`"<<INCLUDE_ANSIBLE_MODULE_COMPLEX_ARGS>>"` is substituted with
|
||||
a string which is the Python ``repr`` of the :term:`JSON` encoded module
|
||||
parameters. Using ``repr`` on the JSON string makes it safe to embed in
|
||||
a Python file. In new-style Python modules under the Ansiballz framework
|
||||
this is better accessed by instantiating an :class:`AnsibleModule` and
|
||||
this is better accessed by instantiating an `AnsibleModule` and
|
||||
then using :attr:`AnsibleModule.params`.
|
||||
- :code:`<<SELINUX_SPECIAL_FILESYSTEMS>>` substitutes a string which is
|
||||
a comma separated list of file systems which have a file system dependent
|
||||
security context in SELinux. In new-style Python modules, if you really
|
||||
need this you should instantiate an :class:`AnsibleModule` and then use
|
||||
need this you should instantiate an `AnsibleModule` and then use
|
||||
:attr:`AnsibleModule._selinux_special_fs`. The variable has also changed
|
||||
from a comma separated string of file system names to an actual python
|
||||
list of filesystem names.
|
||||
|
|
@ -302,7 +302,7 @@ substitutions:
|
|||
``syslog_facility`` which was named in :file:`ansible.cfg` or any
|
||||
``ansible_syslog_facility`` inventory variable that applies to this host. In
|
||||
new-style Python modules this has changed slightly. If you really need to
|
||||
access it, you should instantiate an :class:`AnsibleModule` and then use
|
||||
access it, you should instantiate an `AnsibleModule` and then use
|
||||
:attr:`AnsibleModule._syslog_facility` to access it. It is no longer the
|
||||
actual syslog facility and is now the name of the syslog facility. See
|
||||
the :ref:`documentation on internal arguments <flow_internal_arguments>`
|
||||
|
|
@ -365,7 +365,7 @@ it parses this string and places the args into
|
|||
other code.
|
||||
|
||||
.. note::
|
||||
Internally, the :class:`AnsibleModule` uses the helper function,
|
||||
Internally, the `AnsibleModule` uses the helper function,
|
||||
:py:func:`ansible.module_utils.basic._load_params`, to load the parameters
|
||||
from stdin and save them into an internal global variable. Very dynamic
|
||||
custom modules which need to parse the parameters prior to instantiating
|
||||
|
|
@ -395,7 +395,7 @@ This is a boolean. If it's True then the playbook specified ``no_log`` (in
|
|||
a task's parameters or as a play parameter). This automatically affects calls
|
||||
to :py:meth:`AnsibleModule.log`. If a module implements its own logging then
|
||||
it needs to check this value. The best way to look at this is for the module
|
||||
to instantiate an :class:`AnsibleModule` and then check the value of
|
||||
to instantiate an `AnsibleModule` and then check the value of
|
||||
:attr:`AnsibleModule.no_log`.
|
||||
|
||||
.. note::
|
||||
|
|
@ -410,7 +410,7 @@ the messages are only logged if this is True. This also turns on logging of
|
|||
external commands that the module executes. This can be changed via
|
||||
the ``debug`` setting in :file:`ansible.cfg` or the environment variable
|
||||
:envvar:`ANSIBLE_DEBUG`. If, for some reason, a module must access this, it
|
||||
should do so by instantiating an :class:`AnsibleModule` and accessing
|
||||
should do so by instantiating an `AnsibleModule` and accessing
|
||||
:attr:`AnsibleModule._debug`.
|
||||
|
||||
_ansible_diff
|
||||
|
|
@ -419,7 +419,7 @@ _ansible_diff
|
|||
This boolean is turned on via the ``--diff`` command line option. If a module
|
||||
supports it, it will tell the module to show a unified diff of changes to be
|
||||
made to templated files. The proper way for a module to access this is by
|
||||
instantiating an :class:`AnsibleModule` and accessing
|
||||
instantiating an `AnsibleModule` and accessing
|
||||
:attr:`AnsibleModule._diff`.
|
||||
|
||||
_ansible_verbosity
|
||||
|
|
@ -432,7 +432,7 @@ _ansible_selinux_special_fs
|
|||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This is a list of names of filesystems which should have a special selinux
|
||||
context. They are used by the :class:`AnsibleModule` methods which operate on
|
||||
context. They are used by the `AnsibleModule` methods which operate on
|
||||
files (changing attributes, moving, and copying). The list of names is set
|
||||
via a comma separated string of filesystem names from :file:`ansible.cfg`::
|
||||
|
||||
|
|
@ -458,7 +458,7 @@ This parameter controls which syslog facility ansible module logs to. It may
|
|||
be set by changing the ``syslog_facility`` value in :file:`ansible.cfg`. Most
|
||||
modules should just use :meth:`AnsibleModule.log` which will then make use of
|
||||
this. If a module has to use this on its own, it should instantiate an
|
||||
:class:`AnsibleModule` and then retrieve the name of the syslog facility from
|
||||
`AnsibleModule` and then retrieve the name of the syslog facility from
|
||||
:attr:`AnsibleModule._syslog_facility`. The code will look slightly different
|
||||
than it did under :ref:`module_replacer` due to how hacky the old way was
|
||||
|
||||
|
|
@ -480,7 +480,7 @@ _ansible_version
|
|||
~~~~~~~~~~~~~~~~
|
||||
|
||||
This parameter passes the version of ansible that runs the module. To access
|
||||
it, a module should instantiate an :class:`AnsibleModule` and then retrieve it
|
||||
it, a module should instantiate an `AnsibleModule` and then retrieve it
|
||||
from :attr:`AnsibleModule.ansible_version`. This replaces
|
||||
:attr:`ansible.module_utils.basic.ANSIBLE_VERSION` from
|
||||
:ref:`module_replacer`.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _developing_python_3:
|
||||
|
||||
====================
|
||||
Ansible and Python 3
|
||||
====================
|
||||
|
|
|
|||
|
|
@ -24,6 +24,6 @@ To get started, select one of the following topics.
|
|||
developing_rebasing
|
||||
testing
|
||||
repomerge
|
||||
../release_and_maintenance
|
||||
../committer_guidelines
|
||||
../reference_appendices/release_and_maintenance
|
||||
../community/committer_guidelines
|
||||
./style_guide/index
|
||||
|
|
|
|||
|
|
@ -1,4 +0,0 @@
|
|||
Compile Tests
|
||||
=============
|
||||
|
||||
See :doc:`../../testing_compile` for more information.
|
||||
|
|
@ -73,3 +73,5 @@ yamllint
|
|||
~~~~~~~~
|
||||
|
||||
Check YAML files for syntax and formatting issues.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -15,9 +15,9 @@ We believe simplicity is relevant to all sizes of environments, so we design for
|
|||
Ansible manages machines in an agent-less manner. There is never a question of how to
|
||||
upgrade remote daemons or the problem of not being able to manage systems because daemons are uninstalled. Because OpenSSH is one of the most peer-reviewed open source components, security exposure is greatly reduced. Ansible is decentralized--it relies on your existing OS credentials to control access to remote machines. If needed, Ansible can easily connect with Kerberos, LDAP, and other centralized authentication management systems.
|
||||
|
||||
This documentation covers the current released version of Ansible (2.3) and also some development version features (2.4). For recent features, we note in each section the version of Ansible where the feature was added.
|
||||
This documentation covers the current released version of Ansible (2.5) and also some development version features. For recent features, we note in each section the version of Ansible where the feature was added.
|
||||
|
||||
Ansible, Inc. releases a new major release of Ansible approximately every two months. The core application evolves somewhat conservatively, valuing simplicity in language design and setup. However, the community around new modules and plugins being developed and contributed moves very quickly, typically adding 20 or so new modules in each release.
|
||||
Ansible releases a new major release of Ansible approximately every two months. The core application evolves somewhat conservatively, valuing simplicity in language design and setup. However, the community around new modules and plugins being developed and contributed moves very quickly, adding many new modules in each release.
|
||||
|
||||
|
||||
.. toctree::
|
||||
|
|
@ -80,6 +80,7 @@ Ansible, Inc. releases a new major release of Ansible approximately every two mo
|
|||
reference_appendices/python_3_support
|
||||
reference_appendices/release_and_maintenance
|
||||
reference_appendices/test_strategies
|
||||
dev_guide/testing/sanity/index
|
||||
reference_appendices/faq
|
||||
reference_appendices/glossary
|
||||
reference_appendices/tower
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _intro_configuration:
|
||||
|
||||
*******************
|
||||
Configuring Ansible
|
||||
*******************
|
||||
|
|
@ -29,9 +31,9 @@ default settings in Ansible.
|
|||
|
||||
An `example file is available on Github <https://raw.github.com/ansible/ansible/devel/examples/ansible.cfg>`_.
|
||||
|
||||
For more details and a full listing of available configurations go to :ref:`configuration_settings`. Starting with Ansible version 2.4, you can use the :doc:`ansible-config` command line utility to list your available options and inspect the current values.
|
||||
For more details and a full listing of available configurations go to :ref:`configuration_settings`. Starting with Ansible version 2.4, you can use the :ref:`ansible-config` command line utility to list your available options and inspect the current values.
|
||||
|
||||
For in-depth details, see :doc:`_config`.
|
||||
For in-depth details, see :ref:`config`.
|
||||
|
||||
|
||||
Environmental configuration
|
||||
|
|
|
|||
|
|
@ -1,3 +1,6 @@
|
|||
.. _installation_guide:
|
||||
.. _intro_installation_guide:
|
||||
|
||||
Installation Guide
|
||||
==================
|
||||
|
||||
|
|
@ -85,7 +88,7 @@ default this uses sftp. If that's not available, you can switch to scp in
|
|||
By default, Ansible uses Python 2 in order to maintain compatibility with older distributions
|
||||
such as RHEL 6. However, some Linux distributions (Gentoo, Arch) may not have a
|
||||
Python 2.X interpreter installed by default. On those systems, you should install one, and set
|
||||
the 'ansible_python_interpreter' variable in inventory (see :doc:`intro_inventory`) to point at your 2.X Python. Distributions
|
||||
the 'ansible_python_interpreter' variable in inventory (see :ref:`inventory`) to point at your 2.X Python. Distributions
|
||||
like Red Hat Enterprise Linux, CentOS, Fedora, and Ubuntu all have a 2.X interpreter installed
|
||||
by default and this does not apply to those distributions. This is also true of nearly all
|
||||
Unix systems.
|
||||
|
|
@ -363,7 +366,7 @@ Ansible's own modules.
|
|||
$ git submodule update --init --recursive
|
||||
|
||||
Once running the env-setup script you'll be running from checkout and the default inventory file
|
||||
will be /etc/ansible/hosts. You can optionally specify an inventory file (see :doc:`intro_inventory`)
|
||||
will be /etc/ansible/hosts. You can optionally specify an inventory file (see :ref:`inventory`)
|
||||
other than /etc/ansible/hosts:
|
||||
|
||||
.. code-block:: bash
|
||||
|
|
@ -397,9 +400,9 @@ bugs and feature ideas.
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`intro_adhoc`
|
||||
:ref:`intro_adhoc`
|
||||
Examples of basic commands
|
||||
:doc:`playbooks`
|
||||
:ref:`working_with_playbooks`
|
||||
Learning ansible's configuration management language
|
||||
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
||||
Questions? Help? Ideas? Stop by the list on Google Groups
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _plugins_lookup:
|
||||
|
||||
********************
|
||||
Working With Plugins
|
||||
********************
|
||||
|
|
|
|||
|
|
@ -392,5 +392,5 @@ Connection plugins
|
|||
Porting custom scripts
|
||||
======================
|
||||
|
||||
Custom scripts that used the ``ansible.runner.Runner`` API in 1.x have to be ported in 2.x. Please refer to: :doc:`dev_guide/developing_api`
|
||||
Custom scripts that used the ``ansible.runner.Runner`` API in 1.x have to be ported in 2.x. Please refer to: :ref:`developing_api`
|
||||
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ In Ansible 2.2 (and possibly earlier) the `async:` keyword could not be used in
|
|||
**NEW** In Ansible 2.3:
|
||||
|
||||
|
||||
.. code-block:: yaml
|
||||
.. code-block:: guess
|
||||
|
||||
- name: Install nginx asynchronously
|
||||
service:
|
||||
|
|
@ -43,7 +43,7 @@ The `ansible_distribution_release` and `ansible_distribution_version` facts on O
|
|||
**OLD** In Ansible 2.2 (and earlier)
|
||||
|
||||
|
||||
.. code-block:: yaml
|
||||
.. code-block:: guess
|
||||
|
||||
"ansible_distribution": "OpenBSD"
|
||||
"ansible_distribution_release": "6.0",
|
||||
|
|
@ -52,7 +52,7 @@ The `ansible_distribution_release` and `ansible_distribution_version` facts on O
|
|||
**NEW** In Ansible 2.3:
|
||||
|
||||
|
||||
.. code-block:: yaml
|
||||
.. code-block:: guess
|
||||
|
||||
"ansible_distribution": "OpenBSD",
|
||||
"ansible_distribution_release": "release",
|
||||
|
|
@ -68,7 +68,7 @@ Blocks can now have names, this allows you to avoid the ugly `# this block is fo
|
|||
**NEW** In Ansible 2.3:
|
||||
|
||||
|
||||
.. code-block:: yaml
|
||||
.. code-block:: guess
|
||||
|
||||
- name: Block test case
|
||||
hosts: localhost
|
||||
|
|
@ -176,7 +176,7 @@ Deprecation of top-level connection arguments
|
|||
|
||||
**OLD** In Ansible 2.2:
|
||||
|
||||
.. code-block:: yaml
|
||||
.. code-block:: guess
|
||||
|
||||
- name: example of using top-level options for connection properties
|
||||
ios_command:
|
||||
|
|
@ -189,7 +189,7 @@ Deprecation of top-level connection arguments
|
|||
|
||||
Will result in:
|
||||
|
||||
.. code-block:: yaml
|
||||
.. code-block:: guess
|
||||
|
||||
[WARNING]: argument username has been deprecated and will be removed in a future version
|
||||
[WARNING]: argument host has been deprecated and will be removed in a future version
|
||||
|
|
@ -199,7 +199,7 @@ Will result in:
|
|||
**NEW** In Ansible 2.3:
|
||||
|
||||
|
||||
.. code-block:: yaml
|
||||
.. code-block:: guess
|
||||
|
||||
- name: Gather facts
|
||||
eos_facts:
|
||||
|
|
|
|||
|
|
@ -99,7 +99,7 @@ In addition to the deprecation warnings, many new tests have been introduced tha
|
|||
|
||||
when: result is successful
|
||||
|
||||
See :doc:`playbooks_tests` for more information.
|
||||
See :ref:`playbook_tests` for more information.
|
||||
|
||||
Additionally, a script was created to assist in the conversion for tests using filter syntax to proper jinja test syntax. This script has been used to convert all of the Ansible integration tests to the correct format. There are a few limitations documented, and all changes made by this script should be evaluated for correctness before executing the modified playbooks. The script can be found at `https://github.com/ansible/ansible/blob/devel/hacking/fix_test_syntax.py <https://github.com/ansible/ansible/blob/devel/hacking/fix_test_syntax.py>`_.
|
||||
|
||||
|
|
@ -271,4 +271,4 @@ NEW In Ansible 2.5
|
|||
from ansible.module_utils.network.vyos.vyos import get_config, load_config
|
||||
|
||||
|
||||
See the module utilities developer guide see :doc:`dev_guide/developing_module_utilities` for more information.
|
||||
See the module utilities developer guide see :ref:`appendix_module_utilities` for more information.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,6 @@
|
|||
.. _yaml_syntax:
|
||||
|
||||
|
||||
YAML Syntax
|
||||
===========
|
||||
|
||||
|
|
@ -8,7 +11,7 @@ We use YAML because it is easier for humans to read and write than other common
|
|||
data formats like XML or JSON. Further, there are libraries available in most
|
||||
programming languages for working with YAML.
|
||||
|
||||
You may also wish to read :doc:`playbooks` at the same time to see how this
|
||||
You may also wish to read :ref:`working_with_playbooks` at the same time to see how this
|
||||
is used in practice.
|
||||
|
||||
|
||||
|
|
@ -217,7 +220,7 @@ value::
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`playbooks`
|
||||
:ref:`working_with_playbooks`
|
||||
Learn what playbooks can do and how to write/run them.
|
||||
`YAMLLint <http://yamllint.com/>`_
|
||||
YAML Lint (online) helps you debug YAML syntax if you are having problems
|
||||
|
|
|
|||
|
|
@ -90,7 +90,7 @@ This key contains a list of dictionaries that will be presented to the user. Key
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`modules`
|
||||
:ref:`all_modules`
|
||||
Learn about available modules
|
||||
`GitHub Core modules directory <https://github.com/ansible/ansible-modules-core/tree/devel>`_
|
||||
Browse source of core modules
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _ansible_faq:
|
||||
|
||||
Frequently Asked Questions
|
||||
==========================
|
||||
|
||||
|
|
@ -23,8 +25,6 @@ How do I handle different machines needing different user accounts or ports to l
|
|||
|
||||
Setting inventory variables in the inventory file is the easiest way.
|
||||
|
||||
.. include:: ../rst_common/ansible_ssh_changes_note.rst
|
||||
|
||||
For instance, suppose these hosts have different usernames and ports:
|
||||
|
||||
.. code-block:: ini
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _ansible_galaxy:
|
||||
|
||||
Ansible Galaxy
|
||||
++++++++++++++
|
||||
|
||||
|
|
@ -54,7 +56,7 @@ The following provides an example of using *--roles-path* to install the role in
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`intro_configuration`
|
||||
:ref:`intro_configuration`
|
||||
All about configuration files
|
||||
|
||||
version
|
||||
|
|
@ -198,7 +200,7 @@ The complex form can also be used as follows:
|
|||
version: 775396299f2da1f519f0d8885022ca2d6ee80ee8
|
||||
name: composer
|
||||
|
||||
When dependencies are encountered by ``ansible-galaxy``, it will automatically install each dependency to the ``roles_path``. To understand how dependencies are handled during play execution, see :doc:`playbooks_reuse_roles`.
|
||||
When dependencies are encountered by ``ansible-galaxy``, it will automatically install each dependency to the ``roles_path``. To understand how dependencies are handled during play execution, see :ref:`playbooks_reuse_roles`.
|
||||
|
||||
.. note::
|
||||
|
||||
|
|
@ -507,7 +509,7 @@ Provide the ID of the integration to be disabled. You can find the ID by using t
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`playbooks_reuse_roles`
|
||||
:ref:`playbooks_reuse_roles`
|
||||
All about ansible roles
|
||||
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
||||
Questions? Help? Ideas? Stop by the list on Google Groups
|
||||
|
|
|
|||
|
|
@ -65,7 +65,7 @@ when a term comes up on the mailing list.
|
|||
A conditional is an expression that evaluates to true or false that
|
||||
decides whether a given task is executed on a given machine or not.
|
||||
Ansible's conditionals are powered by the 'when' statement, which are
|
||||
discussed in the :doc:`playbook documentation <playbooks>`.
|
||||
discussed in the :ref:`working_with_playbooks`.
|
||||
|
||||
Declarative
|
||||
An approach to achieving a task that uses a description of the
|
||||
|
|
@ -489,11 +489,11 @@ when a term comes up on the mailing list.
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`faq`
|
||||
:ref:`ansible_faq`
|
||||
Frequently asked questions
|
||||
:doc:`playbooks`
|
||||
:ref:`working_with_playbooks`
|
||||
An introduction to playbooks
|
||||
:doc:`playbooks_best_practices`
|
||||
:ref:`playbooks_best_practices`
|
||||
Best practices advice
|
||||
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
|
||||
Have a question? Stop by the google group!
|
||||
|
|
|
|||
|
|
@ -65,7 +65,7 @@ Testing Python 3 module support
|
|||
[py3-hosts:vars]
|
||||
ansible_python_interpreter=/usr/bin/python3
|
||||
|
||||
See :doc:`intro_inventory` for more information.
|
||||
See :ref:`intro_inventory` for more information.
|
||||
|
||||
* Run your command or playbook:
|
||||
|
||||
|
|
@ -75,7 +75,7 @@ See :doc:`intro_inventory` for more information.
|
|||
$ ansible-playbook sample-playbook.yml
|
||||
|
||||
|
||||
Note that you can also use the :option:`-e` command line option to manually
|
||||
Note that you can also use the `-e` command line option to manually
|
||||
set the python interpreter when you run a command. For example:
|
||||
|
||||
.. code-block:: shell
|
||||
|
|
@ -92,5 +92,5 @@ report on `Ansible's GitHub project
|
|||
the bug report so that the right people look at it.
|
||||
|
||||
If you would like to fix the code and submit a pull request on github, you can
|
||||
refer to :doc:`dev_guide/developing_python3` for information on how we fix
|
||||
refer to :ref:`developing_python3` for information on how we fix
|
||||
common Python3 compatibility issues in the Ansible codebase.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _release_and_maintenance:
|
||||
|
||||
Release and maintenance
|
||||
=======================
|
||||
|
||||
|
|
@ -14,7 +16,7 @@ This cycle can be extended in order to allow for larger changes to be properly
|
|||
implemented and tested before a new release is made available.
|
||||
|
||||
Ansible has a graduated support structure that extends to three major releases.
|
||||
For more information, read about the `development and stable version maintenance workflow`_ or see
|
||||
For more information, read about the :ref: `_development_and_stable_versiona_maintenance_workflow` or see
|
||||
the chart in :ref:`schedule` for the degrees to which current releases are supported.
|
||||
|
||||
.. note:: Support for three major releases began with Ansible-2.4. Ansible-2.3 and older versions
|
||||
|
|
@ -65,6 +67,7 @@ devel `2.5`_ (unreleased, trunk) In development
|
|||
.. _support_life:
|
||||
.. _methods:
|
||||
|
||||
.. _development_and_stable_versiona_maintenance_workflow:
|
||||
|
||||
Development and stable version maintenance workflow
|
||||
```````````````````````````````````````````````````
|
||||
|
|
@ -132,11 +135,11 @@ be delayed in order to allow the new release to be shipped as soon as possible.
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`committer_guidelines`
|
||||
:ref:`community_committer_guidelines`
|
||||
Guidelines for Ansible core contributors and maintainers
|
||||
:doc:`test_strategies`
|
||||
:ref:`testing_strategies`
|
||||
Testing strategies
|
||||
:doc:`community`
|
||||
:ref:`ansible_community_guide`
|
||||
Community information and contributing
|
||||
`Ansible Changelog <https://github.com/ansible/ansible/blob/devel/CHANGELOG.md>`_
|
||||
Documentation of the improvements for each version of Ansible
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _testing_strategies:
|
||||
|
||||
Testing Strategies
|
||||
==================
|
||||
|
||||
|
|
@ -142,7 +144,7 @@ a subset of the QA battery against remote nodes. This is what the next section
|
|||
Integrating Testing With Rolling Updates
|
||||
````````````````````````````````````````
|
||||
|
||||
If you have read into :doc:`playbooks_delegation` it may quickly become apparent that the rolling update pattern can be extended, and you
|
||||
If you have read into :ref:`playbooks_delegation` it may quickly become apparent that the rolling update pattern can be extended, and you
|
||||
can use the success or failure of the playbook run to decide whether to add a machine into a load balancer or not.
|
||||
|
||||
This is the great culmination of embedded tests::
|
||||
|
|
@ -260,11 +262,11 @@ system.
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`modules`
|
||||
:ref:`all_modules`
|
||||
All the documentation for Ansible modules
|
||||
:doc:`playbooks`
|
||||
:ref:`working_with_playbooks`
|
||||
An introduction to playbooks
|
||||
:doc:`playbooks_delegation`
|
||||
:ref:`playbooks_delegation`
|
||||
Delegation, useful for working with load balancers, clouds, and locally executed steps.
|
||||
`User Mailing List <http://groups.google.com/group/ansible-project>`_
|
||||
Have a question? Stop by the google group!
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _ansible_tower:
|
||||
|
||||
Ansible Tower
|
||||
=============
|
||||
|
||||
|
|
|
|||
|
|
@ -141,11 +141,11 @@ Host Inventory
|
|||
``````````````
|
||||
|
||||
Once your nodes are spun up, you'll probably want to talk to them again. With a cloud setup, it's best to not maintain a static list of cloud hostnames
|
||||
in text files. Rather, the best way to handle this is to use the ec2 dynamic inventory script. See :doc:`intro_dynamic_inventory`.
|
||||
in text files. Rather, the best way to handle this is to use the ec2 dynamic inventory script. See :ref:`dynamic_inventory`.
|
||||
|
||||
This will also dynamically select nodes that were even created outside of Ansible, and allow Ansible to manage them.
|
||||
|
||||
See :doc:`intro_dynamic_inventory` for how to use this, then flip back over to this chapter.
|
||||
See :ref:`dynamic_inventory` for how to use this, then return to this chapter.
|
||||
|
||||
.. _aws_tags_and_groups:
|
||||
|
||||
|
|
@ -190,7 +190,7 @@ Read :ref:`ansible-pull` for more information on pull-mode playbooks.
|
|||
Autoscaling with Ansible Tower
|
||||
``````````````````````````````
|
||||
|
||||
:doc:`tower` also contains a very nice feature for auto-scaling use cases. In this mode, a simple curl script can call
|
||||
:ref:`ansible_tower` also contains a very nice feature for auto-scaling use cases. In this mode, a simple curl script can call
|
||||
a defined URL and the server will "dial out" to the requester and configure an instance that is spinning up. This can be a great way
|
||||
to reconfigure ephemeral nodes. See the Tower install and product documentation for more details.
|
||||
|
||||
|
|
@ -241,11 +241,11 @@ documentation for a full list with examples.
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`modules`
|
||||
:ref:`all_modules`
|
||||
All the documentation for Ansible modules
|
||||
:doc:`playbooks`
|
||||
:ref:`working_with_playbooks`
|
||||
An introduction to playbooks
|
||||
:doc:`playbooks_delegation`
|
||||
:ref:`playbooks_delegation`
|
||||
Delegation, useful for working with loud balancers, clouds, and locally executed steps.
|
||||
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
|
||||
Have a question? Stop by the google group!
|
||||
|
|
|
|||
|
|
@ -169,7 +169,7 @@ To use the rackspace dynamic inventory script, copy ``rax.py`` into your invento
|
|||
|
||||
.. note:: Dynamic inventory scripts (like ``rax.py``) are saved in ``/usr/share/ansible/inventory`` if Ansible has been installed globally. If installed to a virtualenv, the inventory scripts are installed to ``$VIRTUALENV/share/inventory``.
|
||||
|
||||
.. note:: Users of :doc:`tower` will note that dynamic inventory is natively supported by Tower, and all you have to do is associate a group with your Rackspace Cloud credentials, and it will easily synchronize without going through these steps::
|
||||
.. note:: Users of :ref:`ansible_tower` will note that dynamic inventory is natively supported by Tower, and all you have to do is associate a group with your Rackspace Cloud credentials, and it will easily synchronize without going through these steps::
|
||||
|
||||
$ RAX_CREDS_FILE=~/.raxpub ansible all -i rax.py -m setup
|
||||
|
||||
|
|
@ -797,7 +797,7 @@ Advanced Usage
|
|||
Autoscaling with Tower
|
||||
++++++++++++++++++++++
|
||||
|
||||
:doc:`tower` also contains a very nice feature for auto-scaling use cases.
|
||||
:ref:`ansible_tower` also contains a very nice feature for auto-scaling use cases.
|
||||
In this mode, a simple curl script can call a defined URL and the server will "dial out" to the requester
|
||||
and configure an instance that is spinning up. This can be a great way to reconfigure ephemeral nodes.
|
||||
See the Tower documentation for more details.
|
||||
|
|
|
|||
|
|
@ -77,7 +77,7 @@ as push updates to all of the servers::
|
|||
|
||||
.. note::
|
||||
|
||||
If you're not familiar with terms like playbooks and plays, you should review :doc:`playbooks`.
|
||||
If you're not familiar with terms like playbooks and plays, you should review :ref:`working_with_playbooks`.
|
||||
|
||||
In this playbook we have 5 plays. The first one targets ``all`` hosts and applies the ``common`` role to all of the hosts.
|
||||
This is for site-wide things like yum repository configuration, firewall configuration, and anything else that needs to apply to all of the servers.
|
||||
|
|
@ -100,7 +100,7 @@ your roles is up to you and your application, but most sites will have one or mo
|
|||
all systems, and then a series of application-specific roles that install and configure particular parts of the site.
|
||||
|
||||
Roles can have variables and dependencies, and you can pass in parameters to roles to modify their behavior.
|
||||
You can read more about roles in the :doc:`playbooks_reuse_roles` section.
|
||||
You can read more about roles in the :ref:`playbooks_reuse_roles` section.
|
||||
|
||||
.. _lamp_group_variables:
|
||||
|
||||
|
|
@ -185,7 +185,7 @@ This loops over all of the hosts in the group called ``monitoring``, and adds an
|
|||
each monitoring hosts' default IPv4 address to the current machine's iptables configuration, so that Nagios can monitor those hosts.
|
||||
|
||||
You can learn a lot more about Jinja2 and its capabilities `here <http://jinja.pocoo.org/docs/>`_, and you
|
||||
can read more about Ansible variables in general in the :doc:`playbooks_variables` section.
|
||||
can read more about Ansible variables in general in the :ref:`playbooks_variables` section.
|
||||
|
||||
.. _lamp_rolling_upgrade:
|
||||
|
||||
|
|
@ -269,9 +269,9 @@ Again, if you were using a Netscaler or F5 or Elastic Load Balancer, you would j
|
|||
Managing Other Load Balancers
|
||||
`````````````````````````````
|
||||
|
||||
In this example, we use the simple HAProxy load balancer to front-end the web servers. It's easy to configure and easy to manage. As we have mentioned, Ansible has built-in support for a variety of other load balancers like Citrix NetScaler, F5 BigIP, Amazon Elastic Load Balancers, and more. See the :doc:`modules` documentation for more information.
|
||||
In this example, we use the simple HAProxy load balancer to front-end the web servers. It's easy to configure and easy to manage. As we have mentioned, Ansible has built-in support for a variety of other load balancers like Citrix NetScaler, F5 BigIP, Amazon Elastic Load Balancers, and more. See the :ref:`working_with_modules` documentation for more information.
|
||||
|
||||
For other load balancers, you may need to send shell commands to them (like we do for HAProxy above), or call an API, if your load balancer exposes one. For the load balancers for which Ansible has modules, you may want to run them as a ``local_action`` if they contact an API. You can read more about local actions in the :doc:`playbooks_delegation` section. Should you develop anything interesting for some hardware where there is not a core module, it might make for a good module for core inclusion!
|
||||
For other load balancers, you may need to send shell commands to them (like we do for HAProxy above), or call an API, if your load balancer exposes one. For the load balancers for which Ansible has modules, you may want to run them as a ``local_action`` if they contact an API. You can read more about local actions in the :ref:`playbooks_delegation` section. Should you develop anything interesting for some hardware where there is not a core module, it might make for a good module for core inclusion!
|
||||
|
||||
.. _lamp_end_to_end:
|
||||
|
||||
|
|
@ -282,7 +282,7 @@ Now that you have an automated way to deploy updates to your application, how do
|
|||
|
||||
Depending on your environment, you might be deploying continuously to a test environment, running an integration test battery against that environment, and then deploying automatically into production. Or you could keep it simple and just use the rolling-update for on-demand deployment into test or production specifically. This is all up to you.
|
||||
|
||||
For integration with Continuous Integration systems, you can easily trigger playbook runs using the ``ansible-playbook`` command line tool, or, if you're using :doc:`tower`, the ``tower-cli`` or the built-in REST API. (The tower-cli command 'joblaunch' will spawn a remote job over the REST API and is pretty slick).
|
||||
For integration with Continuous Integration systems, you can easily trigger playbook runs using the ``ansible-playbook`` command line tool, or, if you're using :ref:`ansible_tower`, the ``tower-cli`` or the built-in REST API. (The tower-cli command 'joblaunch' will spawn a remote job over the REST API and is pretty slick).
|
||||
|
||||
This should give you a good idea of how to structure a multi-tier application with Ansible, and orchestrate operations upon that app, with the eventual goal of continuous delivery to your customers. You could extend the idea of the rolling upgrade to lots of different parts of the app; maybe add front-end web servers along with application servers, for instance, or replace the SQL database with something like MongoDB or Riak. Ansible gives you the capability to easily manage complicated environments and automate common operations.
|
||||
|
||||
|
|
@ -290,11 +290,11 @@ This should give you a good idea of how to structure a multi-tier application wi
|
|||
|
||||
`lamp_haproxy example <https://github.com/ansible/ansible-examples/tree/master/lamp_haproxy>`_
|
||||
The lamp_haproxy example discussed here.
|
||||
:doc:`playbooks`
|
||||
:ref:`working_with_playbooks`
|
||||
An introduction to playbooks
|
||||
:doc:`playbooks_reuse_roles`
|
||||
:ref:`playbooks_reuse_roles`
|
||||
An introduction to playbook roles
|
||||
:doc:`playbooks_variables`
|
||||
:ref:`playbooks_variables`
|
||||
An introduction to Ansible variables
|
||||
`Ansible.com: Continuous Delivery <https://www.ansible.com/ansible-continuous-delivery>`_
|
||||
An introduction to Continuous Delivery with Ansible
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ If you're not familiar with Vagrant, you should visit `the documentation
|
|||
<http://docs.vagrantup.com/v2/>`_.
|
||||
|
||||
This guide assumes that you already have Ansible installed and working.
|
||||
Running from a Git checkout is fine. Follow the :doc:`intro_installation`
|
||||
Running from a Git checkout is fine. Follow the :ref:`installation_guide`
|
||||
guide for more information.
|
||||
|
||||
.. _vagrant_setup:
|
||||
|
|
@ -149,6 +149,6 @@ The "Tips and Tricks" chapter of the `Ansible Provisioner documentation
|
|||
The Vagrant documentation for the Ansible provisioner
|
||||
`Vagrant Issue Tracker <https://github.com/mitchellh/vagrant/issues?q=is%3Aopen+is%3Aissue+label%3Aprovisioners%2Fansible>`_
|
||||
The open issues for the Ansible provisioner in the Vagrant project
|
||||
:doc:`playbooks`
|
||||
:ref:`working_with_playbooks`
|
||||
An introduction to playbooks
|
||||
|
||||
|
|
|
|||
|
|
@ -55,6 +55,6 @@ When debugging or creating a new issue, you will need information about your VMw
|
|||
The issue tracker for the pyVmomi project
|
||||
`govc <https://github.com/vmware/govmomi/tree/master/govc>`_
|
||||
govc is a vSphere CLI built on top of govmomi
|
||||
:doc:`playbooks`
|
||||
:ref:`working_with_playbooks`
|
||||
An introduction to playbooks
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _become:
|
||||
|
||||
**********************************
|
||||
Understanding Privilege Escalation
|
||||
**********************************
|
||||
|
|
@ -145,7 +147,7 @@ a potential danger.
|
|||
|
||||
Ways to resolve this include:
|
||||
|
||||
* Use :ref:`pipelining`. When pipelining is enabled, Ansible doesn't save the
|
||||
* Use `pipelining`. When pipelining is enabled, Ansible doesn't save the
|
||||
module to a temporary file on the client. Instead it pipes the module to
|
||||
the remote python interpreter's stdin. Pipelining does not work for
|
||||
non-python modules.
|
||||
|
|
@ -278,7 +280,6 @@ If a password is required to enter enable mode this can be specified by doing on
|
|||
|
||||
As a reminder passwords should never be stored in plain text. See how encrypt secrets in vault :doc:`playbooks_vault` for more information.
|
||||
|
||||
For more information about ``network_cli`` see :ref:`network-cli`.
|
||||
|
||||
.. _become-network-auth-and-auth-password:
|
||||
|
||||
|
|
@ -300,7 +301,7 @@ For network platforms that do not currently support ``connection: network_cli``
|
|||
authorize: yes
|
||||
auth_pass: " {{ secret_auth_pass }}"
|
||||
|
||||
Note that over time more platforms will move to support ``become``. Check the :doc:`list_of_network_modules` for details.
|
||||
Note that over time more platforms will move to support ``become``. Check the :ref:`network_modules` for details.
|
||||
|
||||
.. _become-windows:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _intro_adhoc:
|
||||
|
||||
Introduction To Ad-Hoc Commands
|
||||
===============================
|
||||
|
||||
|
|
@ -75,13 +77,13 @@ It is also possible to become a user other than root using
|
|||
Rarely, some users have security rules where they constrain their sudo/pbrun/doas environment to running specific command paths only.
|
||||
This does not work with ansible's no-bootstrapping philosophy and hundreds of different modules.
|
||||
If doing this, use Ansible from a special account that does not have this constraint.
|
||||
One way of doing this without sharing access to unauthorized users would be gating Ansible with :doc:`tower`, which
|
||||
One way of doing this without sharing access to unauthorized users would be gating Ansible with :ref:`ansible_tower`, which
|
||||
can hold on to an SSH credential and let members of certain organizations use it on their behalf without having direct access.
|
||||
|
||||
Ok, so those are basics. If you didn't read about patterns and groups yet, go back and read :doc:`intro_patterns`.
|
||||
Ok, so those are basics. If you didn't read about patterns and groups yet, go back and read :ref:`intro_patterns`.
|
||||
|
||||
The ``-f 10`` in the above specifies the usage of 10 simultaneous
|
||||
processes to use. You can also set this in :doc:`intro_configuration` to avoid setting it again. The default is actually 5, which
|
||||
processes to use. You can also set this in :ref:`intro_configuration` to avoid setting it again. The default is actually 5, which
|
||||
is really small and conservative. You are probably going to want to talk to a lot more simultaneous hosts so feel free
|
||||
to crank this up. If you have more hosts than the value set for the fork count, Ansible will talk to them, but it will
|
||||
take a little longer. Feel free to push this value as high as your system can handle!
|
||||
|
|
@ -94,7 +96,7 @@ run some other :doc:`modules`.
|
|||
.. note::
|
||||
The :ref:`command` module does not support extended shell syntax like piping and redirects (although
|
||||
shell variables will always work). If your command requires shell-specific syntax, use the `shell` module
|
||||
instead. Read more about the differences on the :doc:`modules` page.
|
||||
instead. Read more about the differences on the :ref:`working_with_modules` page.
|
||||
|
||||
Using the :ref:`shell` module looks like this::
|
||||
|
||||
|
|
@ -266,11 +268,11 @@ Read more about facts at :doc:`playbooks_variables` once you're ready to read up
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`intro_configuration`
|
||||
:ref:`intro_configuration`
|
||||
All about the Ansible config file
|
||||
:doc:`modules`
|
||||
:ref:`all_modules`
|
||||
A list of available modules
|
||||
:doc:`playbooks`
|
||||
:ref:`working_with_playbooks`
|
||||
Using Ansible for configuration management & deployment
|
||||
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
||||
Questions? Help? Ideas? Stop by the list on Google Groups
|
||||
|
|
|
|||
|
|
@ -86,11 +86,11 @@ Please feel free to report any issues or incompatibilities you discover with BSD
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`intro_adhoc`
|
||||
:ref:`intro_adhoc`
|
||||
Examples of basic commands
|
||||
:doc:`playbooks`
|
||||
:ref:`working_with_playbooks`
|
||||
Learning ansible's configuration management language
|
||||
:doc:`dev_guide/developing_modules`
|
||||
:ref:`developing_modules`
|
||||
How to write modules
|
||||
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
||||
Questions? Help? Ideas? Stop by the list on Google Groups
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
.. _intro_dynamic_inventory:
|
||||
.. _dynamic_inventory:
|
||||
|
||||
Working With Dynamic Inventory
|
||||
|
|
@ -7,16 +8,16 @@ Working With Dynamic Inventory
|
|||
|
||||
Often a user of a configuration management system will want to keep inventory
|
||||
in a different software system. Ansible provides a basic text-based system as described in
|
||||
:doc:`intro_inventory` but what if you want to use something else?
|
||||
:ref:`inventory` but what if you want to use something else?
|
||||
|
||||
Frequent examples include pulling inventory from a cloud provider, LDAP, `Cobbler <http://cobbler.github.com>`_,
|
||||
or a piece of expensive enterprisey CMDB software.
|
||||
|
||||
Ansible easily supports all of these options via an external inventory system. The contrib/inventory directory contains some of these already -- including options for EC2/Eucalyptus, Rackspace Cloud, and OpenStack, examples of some of which will be detailed below.
|
||||
|
||||
:doc:`tower` also provides a database to store inventory results that is both web and REST Accessible. Tower syncs with all Ansible dynamic inventory sources you might be using, and also includes a graphical inventory editor. By having a database record of all of your hosts, it's easy to correlate past event history and see which ones have had failures on their last playbook runs.
|
||||
:ref:`ansible_tower` also provides a database to store inventory results that is both web and REST Accessible. Tower syncs with all Ansible dynamic inventory sources you might be using, and also includes a graphical inventory editor. By having a database record of all of your hosts, it's easy to correlate past event history and see which ones have had failures on their last playbook runs.
|
||||
|
||||
For information about writing your own dynamic inventory source, see :doc:`dev_guide/developing_inventory`.
|
||||
For information about writing your own dynamic inventory source, see :ref:`developing_inventory`.
|
||||
|
||||
|
||||
.. _cobbler_example:
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _intro_getting_started:
|
||||
|
||||
Getting Started
|
||||
===============
|
||||
|
||||
|
|
@ -8,7 +10,7 @@ Getting Started
|
|||
Foreword
|
||||
````````
|
||||
|
||||
Now that you've read :doc:`../installation_guide/intro_installation` and installed Ansible, it's time to get
|
||||
Now that you've read :ref:`intro_installation` and installed Ansible, it's time to get
|
||||
started with some ad-hoc commands.
|
||||
|
||||
What we are showing first are not the powerful configuration/deployment/orchestration features of Ansible.
|
||||
|
|
@ -28,7 +30,7 @@ By default, Ansible will try to use native
|
|||
OpenSSH for remote communication when possible. This enables ControlPersist (a performance feature), Kerberos, and options in ``~/.ssh/config`` such as Jump Host setup. However, when using Enterprise Linux 6 operating systems as the control machine (Red Hat Enterprise Linux and derivatives such as CentOS), the version of OpenSSH may be too old to support ControlPersist. On these operating systems, Ansible will fallback into using a high-quality Python implementation of
|
||||
OpenSSH called 'paramiko'. If you wish to use features like Kerberized SSH and more, consider using Fedora, OS X, or Ubuntu as your control machine until a newer version of OpenSSH is available for your platform.
|
||||
|
||||
Occasionally you'll encounter a device that doesn't support SFTP. This is rare, but should it occur, you can switch to SCP mode in :doc:`intro_configuration`.
|
||||
Occasionally you'll encounter a device that doesn't support SFTP. This is rare, but should it occur, you can switch to SCP mode in :ref:`intro_configuration`.
|
||||
|
||||
When speaking with remote machines, Ansible by default assumes you are using SSH keys. SSH keys are encouraged but password authentication can also be used where needed by supplying the option ``--ask-pass``. If using sudo features and when sudo requires a password, also supply ``--ask-become-pass`` (previously ``--ask-sudo-pass`` which has been deprecated).
|
||||
|
||||
|
|
@ -145,15 +147,15 @@ Also note that host key checking in paramiko mode is reasonably slow, therefore
|
|||
|
||||
Ansible will log some information about module arguments on the remote system in the remote syslog, unless a task or play is marked with a "no_log: True" attribute. This is explained later.
|
||||
|
||||
To enable basic logging on the control machine see :doc:`intro_configuration` document and set the 'log_path' configuration file setting. Enterprise users may also be interested in :doc:`tower`. Tower provides a very robust database logging feature where it is possible to drill down and see history based on hosts, projects, and particular inventories over time -- explorable both graphically and through a REST API.
|
||||
To enable basic logging on the control machine see :ref:`intro_configuration` document and set the 'log_path' configuration file setting. Enterprise users may also be interested in :ref:`ansible_tower`. Tower provides a very robust database logging feature where it is possible to drill down and see history based on hosts, projects, and particular inventories over time -- explorable both graphically and through a REST API.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`intro_inventory`
|
||||
:ref:`intro_inventory`
|
||||
More information about inventory
|
||||
:doc:`intro_adhoc`
|
||||
:ref:`intro_adhoc`
|
||||
Examples of basic commands
|
||||
:doc:`playbooks`
|
||||
:ref:`working_with_playbooks`
|
||||
Learning Ansible's configuration management language
|
||||
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
||||
Questions? Help? Ideas? Stop by the list on Google Groups
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
.. _intro_inventory:
|
||||
.. _inventory:
|
||||
|
||||
|
||||
Working with Inventory
|
||||
======================
|
||||
|
||||
|
|
@ -11,7 +13,7 @@ which defaults to being saved in the location ``/etc/ansible/hosts``.
|
|||
You can specify a different inventory file using the ``-i <path>`` option on the command line.
|
||||
|
||||
Not only is this inventory configurable, but you can also use multiple inventory files at the same time and
|
||||
pull inventory from dynamic or cloud sources or different formats (YAML, ini, etc), as described in :doc:`intro_dynamic_inventory`.
|
||||
pull inventory from dynamic or cloud sources or different formats (YAML, ini, etc), as described in :ref:`intro_dynamic_inventory`.
|
||||
Introduced in version 2.4, Ansible has inventory plugins to make this flexible and customizable.
|
||||
|
||||
.. _inventoryformat:
|
||||
|
|
@ -22,7 +24,7 @@ Hosts and Groups
|
|||
The inventory file can be in one of many formats, depending on the inventory plugins you have.
|
||||
For this example, the format for ``/etc/ansible/hosts`` is an INI-like (one of Ansible's defaults) and looks like this:
|
||||
|
||||
.. code-block:: ini
|
||||
.. code-block:: guess
|
||||
|
||||
mail.example.com
|
||||
|
||||
|
|
@ -65,7 +67,7 @@ Ports listed in your SSH config file won't be used with the `paramiko` connectio
|
|||
|
||||
To make things explicit, it is suggested that you set them if things are not running on the default port:
|
||||
|
||||
.. code-block:: ini
|
||||
.. code-block:: guess
|
||||
|
||||
badwolf.example.com:5309
|
||||
|
||||
|
|
@ -74,7 +76,7 @@ You can also describe hosts via variables:
|
|||
|
||||
In INI:
|
||||
|
||||
.. code-block:: ini
|
||||
.. code-block:: guess
|
||||
|
||||
jumper ansible_port=5555 ansible_host=192.0.2.50
|
||||
|
||||
|
|
@ -98,24 +100,21 @@ Generally speaking, this is not the best way to define variables that describe y
|
|||
|
||||
If you are adding a lot of hosts following similar patterns, you can do this rather than listing each hostname:
|
||||
|
||||
.. code-block:: ini
|
||||
.. code-block:: guess
|
||||
|
||||
[webservers]
|
||||
www[01:50].example.com
|
||||
|
||||
For numeric patterns, leading zeros can be included or removed, as desired. Ranges are inclusive. You can also define alphabetic ranges:
|
||||
|
||||
.. code-block:: ini
|
||||
.. code-block:: guess
|
||||
|
||||
[databases]
|
||||
db-[a:f].example.com
|
||||
|
||||
|
||||
.. include:: ../rst_common/ansible_ssh_changes_note.rst
|
||||
|
||||
You can also select the connection type and user on a per host basis:
|
||||
|
||||
.. code-block:: ini
|
||||
.. code-block:: guess
|
||||
|
||||
[targets]
|
||||
|
||||
|
|
@ -132,7 +131,7 @@ Host Variables
|
|||
|
||||
As described above, it is easy to assign variables to hosts that will be used later in playbooks:
|
||||
|
||||
.. code-block:: ini
|
||||
.. code-block:: guess
|
||||
|
||||
[atlanta]
|
||||
host1 http_port=80 maxRequestsPerChild=808
|
||||
|
|
@ -147,7 +146,7 @@ Variables can also be applied to an entire group at once:
|
|||
|
||||
The INI way:
|
||||
|
||||
.. code-block:: ini
|
||||
.. code-block:: guess
|
||||
|
||||
[atlanta]
|
||||
host1
|
||||
|
|
@ -180,7 +179,7 @@ It is also possible to make groups of groups using the ``:children`` suffix in I
|
|||
You can apply variables using ``:vars`` or ``vars:``:
|
||||
|
||||
|
||||
.. code-block:: ini
|
||||
.. code-block:: guess
|
||||
|
||||
[atlanta]
|
||||
host1
|
||||
|
|
@ -259,7 +258,7 @@ The preferred practice in Ansible is to not store variables in the main inventor
|
|||
In addition to storing variables directly in the inventory file, host and group variables can be stored in individual files relative to the inventory file (not directory, it is always the file).
|
||||
|
||||
These variable files are in YAML format. Valid file extensions include '.yml', '.yaml', '.json', or no file extension.
|
||||
See :doc:`YAMLSyntax` if you are new to YAML.
|
||||
See :ref:`yaml_syntax` if you are new to YAML.
|
||||
|
||||
Assuming the inventory file path is::
|
||||
|
||||
|
|
@ -340,9 +339,6 @@ Host connection:
|
|||
ansible_connection
|
||||
Connection type to the host. This can be the name of any of ansible's connection plugins. SSH protocol types are ``smart``, ``ssh`` or ``paramiko``. The default is smart. Non-SSH based types are described in the next section.
|
||||
|
||||
|
||||
.. include:: ../rst_common/ansible_ssh_changes_note.rst
|
||||
|
||||
General for all connections:
|
||||
|
||||
ansible_host
|
||||
|
|
@ -473,11 +469,11 @@ Here is an example of how to instantly deploy to created containers::
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`intro_dynamic_inventory`
|
||||
:ref:`intro_dynamic_inventory`
|
||||
Pulling inventory from dynamic sources, such as cloud providers
|
||||
:doc:`intro_adhoc`
|
||||
:ref:`intro_adhoc`
|
||||
Examples of basic commands
|
||||
:doc:`playbooks`
|
||||
:ref:`working_with_playbooks`
|
||||
Learning Ansible's configuration, deployment, and orchestration language.
|
||||
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
||||
Questions? Help? Ideas? Stop by the list on Google Groups
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _intro_patterns:
|
||||
|
||||
Working with Patterns
|
||||
=====================
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _working_with_modules:
|
||||
|
||||
Working With Modules
|
||||
====================
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _intro_modules:
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
|
|
@ -49,13 +51,13 @@ For a list of all available modules, see :doc:`modules_by_category`, or run the
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`intro_adhoc`
|
||||
:ref:`intro_adhoc`
|
||||
Examples of using modules in /usr/bin/ansible
|
||||
:doc:`playbooks`
|
||||
:ref:`working_with_playbooks`
|
||||
Examples of using modules with /usr/bin/ansible-playbook
|
||||
:doc:`dev_guide/developing_modules`
|
||||
:ref:`developing_modules`
|
||||
How to write your own modules
|
||||
:doc:`dev_guide/developing_api`
|
||||
:ref:`developing_api`
|
||||
Examples of using modules with the Python API
|
||||
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
||||
Questions? Help? Ideas? Stop by the list on Google Groups
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _working_with_playbooks:
|
||||
|
||||
Working With Playbooks
|
||||
======================
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _playbooks_best_practices:
|
||||
|
||||
Best Practices
|
||||
==============
|
||||
|
||||
|
|
@ -491,15 +493,15 @@ This best practice has no limit on the amount of variable and vault files or the
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`YAMLSyntax`
|
||||
:ref:`yaml_syntax`
|
||||
Learn about YAML syntax
|
||||
:doc:`playbooks`
|
||||
:ref:`working_with_playbooks`
|
||||
Review the basic playbook features
|
||||
:doc:`modules`
|
||||
:ref:`all_modules`
|
||||
Learn about available modules
|
||||
:doc:`dev_guide/developing_modules`
|
||||
:ref:`developing_modules`
|
||||
Learn how to extend Ansible by writing your own modules
|
||||
:doc:`intro_patterns`
|
||||
:ref:`intro_patterns`
|
||||
Learn about how to select hosts
|
||||
`GitHub examples directory <https://github.com/ansible/ansible-examples>`_
|
||||
Complete playbook files from the github project source
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _playbooks_conditionals:
|
||||
|
||||
Conditionals
|
||||
============
|
||||
|
||||
|
|
@ -140,7 +142,7 @@ If using a dict in a loop::
|
|||
Loading in Custom Facts
|
||||
```````````````````````
|
||||
|
||||
It's also easy to provide your own facts if you want, which is covered in :doc:`dev_guide/developing_modules`. To run them, just
|
||||
It's also easy to provide your own facts if you want, which is covered in :ref:`developing_modules`. To run them, just
|
||||
make a call to your own custom fact gathering module at the top of your list of tasks, and variables returned
|
||||
there will be accessible to future tasks::
|
||||
|
||||
|
|
@ -318,7 +320,7 @@ You may check the registered variable's string contents for emptiness::
|
|||
Commonly Used Facts
|
||||
```````````````````
|
||||
|
||||
The following Facts (see :ref:`_vars_and_facts`) are frequently used in Conditionals - see above for examples.
|
||||
The following Facts are frequently used in Conditionals - see above for examples.
|
||||
|
||||
.. _ansible_distribution:
|
||||
|
||||
|
|
@ -381,13 +383,13 @@ Possible values::
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`playbooks`
|
||||
:ref:`working_with_playbooks`
|
||||
An introduction to playbooks
|
||||
:doc:`playbooks_reuse_roles`
|
||||
:ref:`playbooks_reuse_roles`
|
||||
Playbook organization by roles
|
||||
:doc:`playbooks_best_practices`
|
||||
:ref:`playbooks_best_practices`
|
||||
Best practices in playbooks
|
||||
:doc:`playbooks_variables`
|
||||
:ref:`playbooks_variables`
|
||||
All about variables
|
||||
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
|
||||
Have a question? Stop by the google group!
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _playbooks_delegation:
|
||||
|
||||
Delegation, Rolling Updates, and Local Actions
|
||||
==============================================
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _playbooks_filters:
|
||||
|
||||
Filters
|
||||
-------
|
||||
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@ index after you're done with this section.
|
|||
Playbook Language Example
|
||||
`````````````````````````
|
||||
|
||||
Playbooks are expressed in YAML format (see :doc:`YAMLSyntax`) and have a minimum of syntax, which intentionally
|
||||
Playbooks are expressed in YAML format (see :ref:`yaml_syntax`) and have a minimum of syntax, which intentionally
|
||||
tries to not be a programming language or script, but rather a model of a configuration or a process.
|
||||
|
||||
Each playbook is composed of one or more 'plays' in a list.
|
||||
|
|
@ -525,17 +525,15 @@ can do this::
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`YAMLSyntax`
|
||||
:ref:`yaml_syntax`
|
||||
Learn about YAML syntax
|
||||
:doc:`playbooks_best_practices`
|
||||
:ref:`playbooks_best_practices`
|
||||
Various tips about managing playbooks in the real world
|
||||
:doc:`index`
|
||||
Hop back to the documentation index for a lot of special topics about playbooks
|
||||
:doc:`modules`
|
||||
:ref:`all_modules`
|
||||
Learn about available modules
|
||||
:doc:`dev_guide/developing_modules`
|
||||
:ref:`developing_modules`
|
||||
Learn how to extend Ansible by writing your own modules
|
||||
:doc:`intro_patterns`
|
||||
:ref:`intro_patterns`
|
||||
Learn about how to select hosts
|
||||
`Github examples directory <https://github.com/ansible/ansible-examples>`_
|
||||
Complete end-to-end playbook examples
|
||||
|
|
|
|||
|
|
@ -36,17 +36,17 @@ One way of using lookups is to populate variables. These macros are evaluated ea
|
|||
- debug:
|
||||
msg: "motd value is {{ motd_value }}"
|
||||
|
||||
For more details and a complete list of lookup plugins available, please see :doc:`plugins/lookup`.
|
||||
For more details and a complete list of lookup plugins available, please see :ref:`plugins_lookup`.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`playbooks`
|
||||
:ref:`working_with_playbooks`
|
||||
An introduction to playbooks
|
||||
:doc:`playbooks_conditionals`
|
||||
:ref:`playbooks_conditionals`
|
||||
Conditional statements in playbooks
|
||||
:doc:`playbooks_variables`
|
||||
:ref:`playbooks_variables`
|
||||
All about variables
|
||||
:doc:`playbooks_loops`
|
||||
:ref:`playbooks_loops`
|
||||
Looping in playbooks
|
||||
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
|
||||
Have a question? Stop by the google group!
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _playbooks_loops:
|
||||
|
||||
Loops
|
||||
=====
|
||||
|
||||
|
|
@ -90,10 +92,6 @@ For example, using the 'nested' lookup, you can combine lists::
|
|||
password: "foo"
|
||||
loop: "{{ lookup('nested', [ 'alice', 'bob' ], [ 'clientdb', 'employeedb', 'providerdb' ]) }}"
|
||||
|
||||
|
||||
:doc:`Jinja2 lookups playbooks_lookups`, :doc:`filters playbooks_filters` and :doc:`tests playbooks_tests`
|
||||
make for some powerful data generation and manipulation.
|
||||
|
||||
.. note:: ``with_`` loops are actually a combination of things ``with_`` + ``lookup()``, even ``items`` is a lookup. ``loop`` can be used in the same way as shown above.
|
||||
|
||||
.. _do_until_loops:
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _playbooks_reuse:
|
||||
|
||||
Creating Reusable Playbooks
|
||||
===========================
|
||||
|
||||
|
|
@ -67,17 +69,17 @@ Using ``import*`` can also have some limitations when compared to dynamic includ
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`playbooks`
|
||||
:ref:`working_with_playbooks`
|
||||
Review the basic Playbook language features
|
||||
:doc:`playbooks_variables`
|
||||
:ref:`playbooks_variables`
|
||||
All about variables in playbooks
|
||||
:doc:`playbooks_conditionals`
|
||||
:ref:`playbooks_conditionals`
|
||||
Conditionals in playbooks
|
||||
:doc:`playbooks_loops`
|
||||
:ref:`playbooks_loops`
|
||||
Loops in playbooks
|
||||
:doc:`playbooks_best_practices`
|
||||
:ref:`playbooks_best_practices`
|
||||
Various tips about managing playbooks in the real world
|
||||
:doc:`galaxy`
|
||||
:ref:`ansible_galaxy`
|
||||
How to share roles on galaxy, role management
|
||||
`GitHub Ansible examples <https://github.com/ansible/ansible-examples>`_
|
||||
Complete playbook files from the GitHub project source
|
||||
|
|
|
|||
|
|
@ -108,21 +108,21 @@ Please refer to :doc:`playbooks_reuse_roles` for details on including and import
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`YAMLSyntax`
|
||||
:ref:`yaml_syntax`
|
||||
Learn about YAML syntax
|
||||
:doc:`playbooks`
|
||||
:ref:`working_with_playbooks`
|
||||
Review the basic Playbook language features
|
||||
:doc:`playbooks_best_practices`
|
||||
:ref:`playbooks_best_practices`
|
||||
Various tips about managing playbooks in the real world
|
||||
:doc:`playbooks_variables`
|
||||
:ref:`playbooks_variables`
|
||||
All about variables in playbooks
|
||||
:doc:`playbooks_conditionals`
|
||||
:ref:`playbooks_conditionals`
|
||||
Conditionals in playbooks
|
||||
:doc:`playbooks_loops`
|
||||
:ref:`playbooks_loops`
|
||||
Loops in playbooks
|
||||
:doc:`modules`
|
||||
:ref:`all_modules`
|
||||
Learn about available modules
|
||||
:doc:`dev_guide/developing_modules`
|
||||
:red:`developing_modules`
|
||||
Learn how to extend Ansible by writing your own modules
|
||||
`GitHub Ansible examples <https://github.com/ansible/ansible-examples>`_
|
||||
Complete playbook files from the GitHub project source
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _playbooks_reuse_roles:
|
||||
|
||||
Roles
|
||||
=====
|
||||
|
||||
|
|
@ -298,7 +300,7 @@ Embedding Modules and Plugins In Roles
|
|||
|
||||
This is an advanced topic that should not be relevant for most users.
|
||||
|
||||
If you write a custom module (see :doc:`dev_guide/developing_modules`) or a plugin (see :doc:`dev_guide/developing_plugins`), you may wish to distribute it as part of a role.
|
||||
If you write a custom module (see :ref:`developing_modules`) or a plugin (see :ref:`developing_plugins`), you may wish to distribute it as part of a role.
|
||||
Generally speaking, Ansible as a project is very interested in taking high-quality modules into ansible core for inclusion, so this shouldn't be the norm, but it's quite easy to do.
|
||||
|
||||
A good example for this is if you worked at a company called AcmeWidgets, and wrote an internal module that helped configure your internal software, and you wanted other
|
||||
|
|
@ -345,7 +347,7 @@ Ansible will search for roles in the following way:
|
|||
- A ``roles/`` directory, relative to the playbook file.
|
||||
- By default, in ``/etc/ansible/roles``
|
||||
|
||||
In Ansible 1.4 and later you can configure an additional roles_path to search for roles. Use this to check all of your common roles out to one location, and share them easily between multiple playbook projects. See :doc:`intro_configuration` for details about how to set this up in ansible.cfg.
|
||||
In Ansible 1.4 and later you can configure an additional roles_path to search for roles. Use this to check all of your common roles out to one location, and share them easily between multiple playbook projects. See :ref:`intro_configuration` for details about how to set this up in ansible.cfg.
|
||||
|
||||
Ansible Galaxy
|
||||
``````````````
|
||||
|
|
@ -358,23 +360,23 @@ Read the "About" page on the Galaxy site for more information.
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`galaxy`
|
||||
:ref:`ansible_galaxy`
|
||||
How to share roles on galaxy, role management
|
||||
:doc:`YAMLSyntax`
|
||||
:ref:`yaml_syntax`
|
||||
Learn about YAML syntax
|
||||
:doc:`playbooks`
|
||||
:ref:`working_with_playbooks`
|
||||
Review the basic Playbook language features
|
||||
:doc:`playbooks_best_practices`
|
||||
:ref:`playbooks_best_practices`
|
||||
Various tips about managing playbooks in the real world
|
||||
:doc:`playbooks_variables`
|
||||
:ref:`playbooks_variables`
|
||||
All about variables in playbooks
|
||||
:doc:`playbooks_conditionals`
|
||||
:ref:`playbooks_conditionals`
|
||||
Conditionals in playbooks
|
||||
:doc:`playbooks_loops`
|
||||
:ref:`playbooks_loops`
|
||||
Loops in playbooks
|
||||
:doc:`modules`
|
||||
:ref:`all_modules`
|
||||
Learn about available modules
|
||||
:doc:`dev_guide/developing_modules`
|
||||
:ref:`developing_modules`
|
||||
Learn how to extend Ansible by writing your own modules
|
||||
`GitHub Ansible examples <https://github.com/ansible/ansible-examples>`_
|
||||
Complete playbook files from the GitHub project source
|
||||
|
|
|
|||
|
|
@ -8,10 +8,10 @@ The documentation regarding roles and includes for playbooks have moved. Their n
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`galaxy`
|
||||
:ref:`ansible_galaxy`
|
||||
How to share roles on galaxy, role management
|
||||
:doc:`playbooks`
|
||||
:ref:`working_with_playbooks`
|
||||
Review the basic Playbook language features
|
||||
:doc:`playbooks_reuse`
|
||||
:ref:`playbooks_reuse`
|
||||
Creating reusable Playbooks.
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,6 @@ and adopt these only if they seem relevant or useful to your environment.
|
|||
:maxdepth: 1
|
||||
|
||||
become
|
||||
playbooks_acceleration
|
||||
playbooks_async
|
||||
playbooks_checkmode
|
||||
playbooks_debugger
|
||||
|
|
@ -17,10 +16,10 @@ and adopt these only if they seem relevant or useful to your environment.
|
|||
playbooks_environment
|
||||
playbooks_error_handling
|
||||
playbooks_advanced_syntax
|
||||
plugins
|
||||
../plugins/plugins
|
||||
playbooks_prompts
|
||||
playbooks_tags
|
||||
playbooks_vault
|
||||
playbooks_startnstep
|
||||
playbooks_keywords
|
||||
../reference_appendices/playbooks_keywords
|
||||
playbooks_lookups
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _playbook_tests:
|
||||
|
||||
Tests
|
||||
-----
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _playbooks_variables:
|
||||
|
||||
Variables
|
||||
=========
|
||||
|
||||
|
|
@ -148,7 +150,7 @@ Hey Wait, A YAML Gotcha
|
|||
```````````````````````
|
||||
|
||||
YAML syntax requires that if you start a value with ``{{ foo }}`` you quote the whole line, since it wants to be
|
||||
sure you aren't trying to start a YAML dictionary. This is covered on the :doc:`YAMLSyntax` page.
|
||||
sure you aren't trying to start a YAML dictionary. This is covered on the :ref:`yaml_syntax` documentation.
|
||||
|
||||
This won't work::
|
||||
|
||||
|
|
@ -839,8 +841,6 @@ a use for it.
|
|||
|
||||
If multiple variables of the same name are defined in different places, they get overwritten in a certain order.
|
||||
|
||||
.. include:: ../rst_common/ansible_ssh_changes_note.rst
|
||||
|
||||
In 1.x, the precedence is as follows (with the last listed variables winning prioritization):
|
||||
|
||||
* "role defaults", which lose in priority to everything and are the most easily overridden
|
||||
|
|
@ -942,7 +942,7 @@ First off, group variables are powerful.
|
|||
|
||||
Site wide defaults should be defined as a ``group_vars/all`` setting. Group variables are generally placed alongside
|
||||
your inventory file. They can also be returned by a dynamic inventory script (see :doc:`intro_dynamic_inventory`) or defined
|
||||
in things like :doc:`tower` from the UI or API::
|
||||
in things like :ref:`ansible_tower` from the UI or API::
|
||||
|
||||
---
|
||||
# file: /etc/ansible/group_vars/all
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ requirement. You can use the `Upgrade-PowerShell.ps1 <https://github.com/jborean
|
|||
|
||||
This is an example of how to run this script from PowerShell:
|
||||
|
||||
.. code-block:: powershell
|
||||
.. code-block:: guess
|
||||
|
||||
$url = "https://raw.githubusercontent.com/jborean93/ansible-windows/master/scripts/Upgrade-PowerShell.ps1"
|
||||
$file = "$env:TEMP\Upgrade-PowerShell.ps1"
|
||||
|
|
@ -49,7 +49,7 @@ Once completed, you will need to remove auto logon
|
|||
and set the execution policy back to the default of ``Restricted``. You can
|
||||
do this with the following PowerShell commands:
|
||||
|
||||
.. code-block:: powershell
|
||||
.. code-block:: guess
|
||||
|
||||
# this isn't needed but is a good security practice to complete
|
||||
Set-ExecutionPolicy -ExecutionPolicy Restricted -Force
|
||||
|
|
@ -90,7 +90,7 @@ imaging process. The script `Install-WMF3Hotfix.ps1 <https://github.com/jborean9
|
|||
|
||||
The following PowerShell command will install the hotfix:
|
||||
|
||||
.. code-block:: powershell
|
||||
.. code-block:: guess
|
||||
|
||||
$url = "https://raw.githubusercontent.com/jborean93/ansible-windows/master/scripts/Install-WMF3Hotfix.ps1"
|
||||
$file = "$env:SystemDrive\temp\Install-WMF3Hotfix.ps1"
|
||||
|
|
@ -113,7 +113,7 @@ authentication option on the service.
|
|||
|
||||
To use this script, run the following in PowerShell:
|
||||
|
||||
.. code-block:: powershell
|
||||
.. code-block:: guess
|
||||
|
||||
$url = "https://raw.githubusercontent.com/ansible/ansible/devel/examples/scripts/ConfigureRemotingForAnsible.ps1"
|
||||
$file = "$env:SystemDrive\temp\ConfigureRemotingForAnsible.ps1"
|
||||
|
|
@ -186,7 +186,7 @@ the key options that are useful to understand are:
|
|||
in the connection. To get the details of the certificate itself, run this
|
||||
command with the relevant certificate thumbprint in PowerShell:
|
||||
|
||||
.. code-block:: powershell
|
||||
.. code-block:: guess
|
||||
|
||||
$thumbprint = "E6CDAA82EEAF2ECE8546E05DB7F3E01AA47D76CE"
|
||||
Get-ChildItem -Path cert:\LocalMachine\My -Recurse | Where-Object { $_.Thumbprint -eq $thumbprint } | Select-Object *
|
||||
|
|
@ -209,7 +209,7 @@ There are three ways to set up a WinRM listener:
|
|||
* Using PowerShell to create the listener with a specific configuration. This
|
||||
can be done by running the following PowerShell commands:
|
||||
|
||||
.. code-block:: powershell
|
||||
.. code-block:: guess
|
||||
|
||||
$selector_set = @{
|
||||
Address = "*"
|
||||
|
|
@ -232,7 +232,7 @@ Delete WinRM Listener
|
|||
+++++++++++++++++++++
|
||||
To remove a WinRM listener:
|
||||
|
||||
.. code-block:: powershell
|
||||
.. code-block:: guess
|
||||
|
||||
# remove all listeners
|
||||
Remove-Item -Path WSMan:\localhost\Listener\* -Recurse -Force
|
||||
|
|
@ -326,7 +326,7 @@ options are:
|
|||
To modify a setting under the ``Service`` key in PowerShell, the following
|
||||
command can be used:
|
||||
|
||||
.. code-block:: powershell
|
||||
.. code-block:: guess
|
||||
|
||||
# substitute {path} with the path to the option after winrm/config/Service
|
||||
Set-Item -Path WSMan:\localhost\Service\{path} -Value "value here"
|
||||
|
|
@ -337,7 +337,7 @@ command can be used:
|
|||
To modify a setting under the ``Winrs`` key in PowerShell, the following
|
||||
command can be used:
|
||||
|
||||
.. code-block:: powershell
|
||||
.. code-block:: guess
|
||||
|
||||
# substitute {path} with the path to the option after winrm/config/Winrs
|
||||
Set-Item -Path WSMan:\localhost\Shell\{path} -Value "value here"
|
||||
|
|
|
|||
|
|
@ -473,7 +473,7 @@ Developing Windows Modules
|
|||
``````````````````````````
|
||||
Because Ansible modules for Windows are written in PowerShell, the development
|
||||
guides for Windows modules differ substantially from those for standard standard modules. Please see
|
||||
:doc:`dev_guide/developing_modules_general_windows` for more information.
|
||||
:ref:`developing_modules_general_windows` for more information.
|
||||
|
||||
.. seealso::
|
||||
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@ The following example shows host vars configured for basic authentication::
|
|||
Basic authentication is not enabled by default on a Windows host but can be
|
||||
enabled by running the following in PowerShell:
|
||||
|
||||
.. code-block:: powershell
|
||||
.. code-block:: guess
|
||||
|
||||
Set-Item -Path WSMan:\localhost\Service\Auth\Basic -Value $true
|
||||
|
||||
|
|
@ -80,7 +80,7 @@ The following example shows host vars configured for certificate authentication:
|
|||
Certificate authentication is not enabled by default on a Windows host but can
|
||||
be enabled by running the following in PowerShell:
|
||||
|
||||
.. code-block:: powershell
|
||||
.. code-block:: guess
|
||||
|
||||
Set-Item -Path WSMan:\localhost\Service\Auth\Certificate -Value $true
|
||||
|
||||
|
|
@ -128,7 +128,7 @@ To generate a certificate with ``OpenSSL``:
|
|||
|
||||
To generate a certificate with ``New-SelfSignedCertificate``:
|
||||
|
||||
.. code-block:: powershell
|
||||
.. code-block:: guess
|
||||
|
||||
# set the name of the local user that will have the key mapped
|
||||
$username = "username"
|
||||
|
|
@ -168,7 +168,7 @@ both the issuing certificate and public key are the same.
|
|||
|
||||
Following example shows how to import the issuing certificate:
|
||||
|
||||
.. code-block:: powershell
|
||||
.. code-block:: guess
|
||||
|
||||
$cert = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Certificate2
|
||||
$cert.Import("cert.pem")
|
||||
|
|
@ -186,7 +186,7 @@ Following example shows how to import the issuing certificate:
|
|||
|
||||
The code to import the client certificate public key is:
|
||||
|
||||
.. code-block:: powershell
|
||||
.. code-block:: guess
|
||||
|
||||
$cert = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Certificate2
|
||||
$cert.Import("cert.pem")
|
||||
|
|
@ -205,7 +205,7 @@ Once the certificate has been imported, it needs to be mapped to the local user
|
|||
|
||||
This can be done with the following PowerShell command:
|
||||
|
||||
.. code-block:: powershell
|
||||
.. code-block:: guess
|
||||
|
||||
$username = "username"
|
||||
$password = ConvertTo-SecureString -String "password" -AsPlainText -Force
|
||||
|
|
@ -454,7 +454,7 @@ There are some extra host variables that can be set as shown below::
|
|||
CredSSP authentication is not enabled by default on a Windows host, but can
|
||||
be enabled by running the following in PowerShell:
|
||||
|
||||
.. code-block:: powershell
|
||||
.. code-block:: guess
|
||||
|
||||
Enable-WSManCredSSP -Role Server -Force
|
||||
|
||||
|
|
@ -489,7 +489,7 @@ needs to be installed.
|
|||
Once the update has been applied and the Windows host rebooted, run the following
|
||||
PowerShell commands to enable TLS 1.2:
|
||||
|
||||
.. code-block:: powershell
|
||||
.. code-block:: guess
|
||||
|
||||
$reg_path = "HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProvider\SCHANNEL\Protocols\TLS 1.2"
|
||||
New-Item -Path $reg_path
|
||||
|
|
@ -512,7 +512,7 @@ another certificate.
|
|||
|
||||
To explicitly set the certificate to use for CredSSP:
|
||||
|
||||
.. code-block:: powershell
|
||||
.. code-block:: guess
|
||||
|
||||
# note the value $certificate_thumbprint will be different in each
|
||||
# situation, this needs to be set based on the cert that is used.
|
||||
|
|
@ -526,7 +526,7 @@ Non-Administrator Accounts
|
|||
WinRM is configured by default to only allow connections from accounts in the local
|
||||
``Administrators`` group. This can be changed by running:
|
||||
|
||||
.. code-block:: powershell
|
||||
.. code-block:: guess
|
||||
|
||||
winrm configSDDL default
|
||||
|
||||
|
|
@ -562,7 +562,7 @@ should only be used for development and debugging purposes, as anything sent
|
|||
from Ansible can viewed by anyone on the network. To disable the encryption
|
||||
requirement, run the following from PowerShell on the target host:
|
||||
|
||||
.. code-block:: powershell
|
||||
.. code-block:: guess
|
||||
|
||||
Set-Item -Path WSMan:\localhost\Service\AllowUnencrypted -Value $true
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +0,0 @@
|
|||
.. note::
|
||||
|
||||
Ansible 2.0 has deprecated the "ssh" from ``ansible_ssh_user``, ``ansible_ssh_host``, and ``ansible_ssh_port`` to become ``ansible_user``, ``ansible_host``, and ``ansible_port``. If you are using a version of Ansible prior to 2.0, you should continue using the older style variables (``ansible_ssh_*``). These shorter variables are ignored, without warning, in older versions of Ansible.
|
||||
Loading…
Reference in a new issue