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

[docs][2.10] Backportapalooza 9 (#71493)

Browse source 
* Explain duplicate checks includes tags and when (#68183)

##### SUMMARY
Per #67913, when comparing dependencies, Ansible takes into account parameters, tags and the when clause in determining whether a role is a duplicate or not.

##### ISSUE TYPE
- Docs Pull Request

+label: docsite_pr

(cherry picked from commit 3e4377300b)

* Docs: ansible_host can contain FQDN (#71186)

(cherry picked from commit 13ab73cd89)

* clarify inventory plugin user documentation (#71387)

(cherry picked from commit fb035da3b2)

* Keep caution tape for older versions (#71400)

(cherry picked from commit 156b1c5245)

* document securing editor for vault (#71404)

(cherry picked from commit 6c48c62f93)

* galaxy: Add examples for galaxy section in ansible.cfg (#70931)

Add example section for galaxy section in ansible.cfg

Fixes: #68402

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
(cherry picked from commit 3f3bcbf05e)

* docs: Remove examples using the `ec2.py` script (#69107)

This script is mostly unmaintained and relies on the deprecated and
unmaintained `boto` library. Featuring it prominently in the docs
leads to many new users using it instead of the supported `aws_ec2`
inventory plugin.

(cherry picked from commit 66e38bf499)

* Update uri.py (#67688)

Adds an example of creating workspaces in Log analytics Azure
Co-authored-by: Alicia Cozine <acozine@users.noreply.github.com>

(cherry picked from commit 4317c2c80c)

* docs: Update Kubernetes Guide (#71372)

Fixes: #61681

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
(cherry picked from commit 59b80b9146)

* fix broken links due to master -> main branch rename (#71426)

(cherry picked from commit 2b7461eb52)

* Modify wording to specify two ctl-d to end stdin input in ansible-vault (#69436)

* 51860 - Modify wording to specify two ctl-d to end stdin input in ansible-vault
* removes space to make line 160 chars

(cherry picked from commit a6537b59ab)

* user_guide: Add an example for loop (#71441)

Explain how to use complex data in loop while converting
from with_together

Fixes: #47906

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
(cherry picked from commit 5c1594916a)

* Add link to Matt's blog (#71436)

nitzmahone's blog nicely explained why Windows is not supported
as Ansible controller. Link that in documentation so users can
read about it.

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
(cherry picked from commit 3c8744f0c1)

* user_guide: Fix reuse role examples (#71440)

Fixes: #53919

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
(cherry picked from commit 0b16c0a8c7)

* service: Add a note about ignored parameters (#71455)

Some parameters for systemd are ignored, add a note about such parameters in documentation.
Fixes: #23144

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
(cherry picked from commit 1257b0a184)

* updates network plugin docs pages for 2.10 (#71467)

Co-authored-by: Alicia Cozine <acozine@users.noreply.github.com>
(cherry picked from commit f82a1e06d7)

* Remove "mode: preserve" option from documentation (#71486)

Remove "mode: preserve" option from documentation in doc fragments "FILE_COMMON_ARGUMENTS", as it was incorrectly included in the documentation for the `lineinfile`, `unarchive` and other file-related modules.
The `copy` and `templates` modules documentation remains untouched and still contain "mode: preserve", as intended.

(cherry picked from commit 7127d37466)

* quick update to changelog instructins (#71492)

(cherry picked from commit addee0699e)

* update Network Advanced Topics for FQCN (#71325)

* update Network Advanced Topics for FQCN

(cherry picked from commit b6f10b9b52)

* fix shippable error

Co-authored-by: David M. Lee <leedm777@yahoo.com>
Co-authored-by: Eric G <e+github1690@linuxw.info>
Co-authored-by: Sloane Hertel <shertel@redhat.com>
Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com>
Co-authored-by: flowerysong <paul.arthur@flowerysong.com>
Co-authored-by: Jose l. Azagra <azagramac@gmail.com>
Co-authored-by: Patrick Reader <pxeger@protonmail.com>
Co-authored-by: John Westcott IV <32551173+john-westcott-iv@users.noreply.github.com>
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
Co-authored-by: Timothy Visser <team@sacrome.com>
This commit is contained in:
Sandra McCann 2020-08-31 10:59:52 -04:00 committed by GitHub
parent 393412dc64
commit d3e0cb4320
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
32 changed files with 398 additions and 472 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
changelogs/fragments/68402_galaxy.yml Normal file
View file

@ -0,0 +1,2 @@
minor_changes:
- galaxy - add documentation about galaxy parameters in examples/ansible.cfg (https://github.com/ansible/ansible/issues/68402).

21
docs/docsite/rst/dev_guide/developing_collections.rst
View file

@ -9,7 +9,7 @@ Collections are a distribution format for Ansible content. You can use collectio
You can publish and use collections through `Ansible Galaxy <https://galaxy.ansible.com>`_.
* For details on how to *use* collections see :ref:`collections`.
* For the current development status of Collections and FAQ see `Ansible Collections Overview and FAQ <https://github.com/ansible-collections/overview/blob/master/README.rst>`_.
* For the current development status of Collections and FAQ see `Ansible Collections Overview and FAQ <https://github.com/ansible-collections/overview/blob/main/README.rst>`_.
.. contents::
:local:
@ -532,7 +532,7 @@ Collection versions use `Semantic Versioning <https://semver.org/>`_ for version
Migrating Ansible content to a different collection
====================================================
First, look at `Ansible Collection Checklist <https://github.com/ansible-collections/overview/blob/master/collection_requirements.rst>`_.
First, look at `Ansible Collection Checklist <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst>`_.
To migrate content from one collection to another, you need to create three PRs as follows:
@ -731,8 +731,6 @@ We recommend that you use the `antsibull-changelog <https://github.com/ansible-c
Ansible here refers to the Ansible 2.10 or later release that includes a curated set of collections.
If your collection is part of Ansible but you are not using this tool, your collection should include the properly formatted ``changelog.yaml`` file or your changelogs will not be part of the combined Ansible CHANGELOG.rst and Porting Guide at release. See the `changlog.yaml format <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelog.yaml-format.md>`_ for details.
Understanding antsibull-changelog
---------------------------------
@ -773,6 +771,21 @@ The following changelog fragment categories are consumed by the Ansible changelo
* ``deprecated_features``
* ``removed_features``
Including collection changelogs into Ansible
=============================================
If your collection is part of Ansible, use one of the following three options to include your changelog into the Ansible release changelog:
* Use the ``antsibull-changelog`` tool.
* If are not using this tool, include the properly formatted ``changelog.yaml`` file into your collection. See the `changlog.yaml format <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelog.yaml-format.md>`_ for details.
* Add a link to own changelogs or release notes in any format by opening an issue at https://github.com/ansible-community/ansible-build-data/ with the HTML link to that information.
.. note::
For the first two options, Ansible pulls the changelog details from Galaxy so your changelogs must be included in the collection version on Galaxy that is included in the upcoming Ansible release.
.. seealso::

2
docs/docsite/rst/installation_guide/intro_installation.rst
View file

@ -24,7 +24,7 @@ Control node requirements
Currently Ansible can be run from any machine with Python 2 (version 2.7) or Python 3 (versions 3.5 and higher) installed.
This includes Red Hat, Debian, CentOS, macOS, any of the BSDs, and so on.
Windows is not supported for the control node.
Windows is not supported for the control node, read more about this in `Matt Davis's blog post <http://blog.rolpdog.com/2020/03/why-no-ansible-controller-for-windows.html>`_.
When choosing a control node, bear in mind that any management system benefits from being run near the machines being managed. If you are running Ansible in a cloud, consider running it from a machine inside that cloud. In most cases this will work better than on the open Internet.

6
docs/docsite/rst/network/user_guide/faq.rst
View file

@ -20,7 +20,7 @@ The ``strategy`` plugin tells Ansible how to order multiple tasks on multiple ho
The default strategy is ``linear``. With strategy set to ``linear``, Ansible waits until the current task has run on all hosts before starting the next task on any host. Ansible may have forks free, but will not use them until all hosts have completed the current task. If each task in your playbook must succeed on all hosts before you run the next task, use the ``linear`` strategy.
Using the ``free`` strategy, Ansible uses available forks to execute tasks on each host as quickly as possible. Even if an earlier task is still running on one host, Ansible executes later tasks on other hosts. The ``free`` strategy uses available forks more efficiently. If your playbook stalls on each task, waiting for one slow host, consider using ``strategy: free`` to boost overall performance.
Using the ``free`` strategy, Ansible uses available forks to execute tasks on each host as quickly as possible. Even if an earlier task is still running on one host, Ansible executes later tasks on other hosts. The ``free`` strategy uses available forks more efficiently. If your playbook stalls on each task, waiting for one slow host, consider using ``strategy: free`` to boost overall performance.
.. _network_faq_limit_show_running:
@ -41,7 +41,7 @@ Network modules support the use of a :ref:`proxy or jump host<network_delegate_t
Set ``--forks`` to match your needs
---------------------------------------------------------------------------------
Every time Ansible runs a task, it forks its own process. The ``--forks`` parameter defines the number of concurrent tasks - if you retain the default setting, which is ``--forks=5``, and you are running a playbook on 10 hosts, five of those hosts will have to wait until a fork is available. Of course, the more forks you allow, the more memory and processing power Ansible will use. Since most network tasks are run on the control host, this means your laptop can quickly become cpu- or memory-bound.
Every time Ansible runs a task, it forks its own process. The ``--forks`` parameter defines the number of concurrent tasks - if you retain the default setting, which is ``--forks=5``, and you are running a playbook on 10 hosts, five of those hosts will have to wait until a fork is available. Of course, the more forks you allow, the more memory and processing power Ansible will use. Since most network tasks are run on the control host, this means your laptop can quickly become cpu- or memory-bound.
.. _network_faq_redacted_output:
@ -70,7 +70,7 @@ To avoid this problem, use long-form commands with the ``*_config`` modules:
- hosts: all
gather_facts: no
tasks:
- ios_config:
- cisco.ios.ios_config:
lines:
- shutdown
parents: interface GigabitEthernet1/0/11

2
docs/docsite/rst/network/user_guide/index.rst
View file

@ -17,8 +17,8 @@ If you're new to Ansible, or new to using Ansible for network automation, start
:caption: Advanced Topics
network_resource_modules
faq
network_best_practices_2.5
network_debug_troubleshooting
network_working_with_command_output
faq
platform_index

66
docs/docsite/rst/network/user_guide/network_best_practices_2.5.rst
View file

@ -14,7 +14,7 @@ Prerequisites
This example requires the following:
* **Ansible 2.5** (or higher) installed. See :ref:`intro_installation_guide` for more information.
* **Ansible 2.10** (or higher) installed. See :ref:`intro_installation_guide` for more information.
* One or more network devices that are compatible with Ansible.
* Basic understanding of YAML :ref:`yaml_syntax`.
* Basic understanding of Jinja2 templates. See :ref:`playbooks_templating` for more information.
@ -35,7 +35,7 @@ Because Ansible is a flexible tool, there are a number of ways to specify connec
[all:vars]
# these defaults can be overridden for any group in the [group:vars] section
ansible_connection=network_cli
ansible_connection=ansible.netcommon.network_cli
ansible_user=ansible
[switches:children]
@ -52,7 +52,7 @@ Because Ansible is a flexible tool, there are a number of ways to specify connec
[eos:vars]
ansible_become=yes
ansible_become_method=enable
ansible_network_os=eos
ansible_network_os=arista.eos.eos
ansible_user=my_eos_user
ansible_password=my_eos_password
@ -64,7 +64,7 @@ Because Ansible is a flexible tool, there are a number of ways to specify connec
[ios:vars]
ansible_become=yes
ansible_become_method=enable
ansible_network_os=ios
ansible_network_os=cisco.ios.ios
ansible_user=my_ios_user
ansible_password=my_ios_password
@ -74,7 +74,7 @@ Because Ansible is a flexible tool, there are a number of ways to specify connec
vyos03 ansible_host=vyos-03.example.net
[vyos:vars]
ansible_network_os=vyos
ansible_network_os=vyos.vyos.vyos
ansible_user=my_vyos_user
ansible_password=my_vyos_password
@ -111,9 +111,9 @@ The following variables are common for all platforms in the inventory, though th
:ansible_connection:
Ansible uses the ansible-connection setting to determine how to connect to a remote device. When working with Ansible Networking, set this to ``network_cli`` so Ansible treats the remote node as a network device with a limited execution environment. Without this setting, Ansible would attempt to use ssh to connect to the remote and execute the Python script on the network device, which would fail because Python generally isn't available on network devices.
Ansible uses the ansible-connection setting to determine how to connect to a remote device. When working with Ansible Networking, set this to an appropriate network connection option, such as``ansible.netcommon.network_cli``, so Ansible treats the remote node as a network device with a limited execution environment. Without this setting, Ansible would attempt to use ssh to connect to the remote and execute the Python script on the network device, which would fail because Python generally isn't available on network devices.
:ansible_network_os:
Informs Ansible which Network platform this hosts corresponds to. This is required when using ``network_cli`` or ``netconf``.
Informs Ansible which Network platform this hosts corresponds to. This is required when using the ``ansible.netcommon.*`` connection options.
:ansible_user: The user to connect to the remote device (switch) as. Without this the user that is running ``ansible-playbook`` would be used.
Specifies which user on the network device the connection
:ansible_password:
@ -126,13 +126,13 @@ The following variables are common for all platforms in the inventory, though th
Privilege escalation
--------------------
Certain network platforms, such as Arista EOS and Cisco IOS, have the concept of different privilege modes. Certain network modules, such as those that modify system state including users, will only work in high privilege states. Ansible supports ``become`` when using ``connection: network_cli``. This allows privileges to be raised for the specific tasks that need them. Adding ``become: yes`` and ``become_method: enable`` informs Ansible to go into privilege mode before executing the task, as shown here:
Certain network platforms, such as Arista EOS and Cisco IOS, have the concept of different privilege modes. Certain network modules, such as those that modify system state including users, will only work in high privilege states. Ansible supports ``become`` when using ``connection: ansible.netcommon.network_cli``. This allows privileges to be raised for the specific tasks that need them. Adding ``become: yes`` and ``become_method: enable`` informs Ansible to go into privilege mode before executing the task, as shown here:
.. code-block:: ini
[eos:vars]
ansible_connection=ansible.netcommon.network_cli
ansible_network_os=eos
ansible_network_os=arista.eos.eos
ansible_become=yes
ansible_become_method=enable
@ -142,16 +142,16 @@ For more information, see the :ref:`using become with network modules<become_net
Jump hosts
----------
If the Ansible Controller doesn't have a direct route to the remote device and you need to use a Jump Host, please see the :ref:`Ansible Network Proxy Command <network_delegate_to_vs_ProxyCommand>` guide for details on how to achieve this.
If the Ansible Controller does not have a direct route to the remote device and you need to use a Jump Host, please see the :ref:`Ansible Network Proxy Command <network_delegate_to_vs_ProxyCommand>` guide for details on how to achieve this.
Example 1: collecting facts and creating backup files with a playbook
=====================================================================
Ansible facts modules gather system information 'facts' that are available to the rest of your playbook.
Ansible Networking ships with a number of network-specific facts modules. In this example, we use the ``_facts`` modules :ref:`eos_facts <eos_facts_module>`, :ref:`ios_facts <ios_facts_module>` and :ref:`vyos_facts <vyos_facts_module>` to connect to the remote networking device. As the credentials are not explicitly passed via module arguments, Ansible uses the username and password from the inventory file.
Ansible Networking ships with a number of network-specific facts modules. In this example, we use the ``_facts`` modules :ref:`arista.eos.eos_facts <ansible_collections.arista.eos.eos_facts_module>`, :ref:`cisco.ios.ios_facts <ansible_collections.cisco.ios.ios_facts_module>` and :ref:`vyos.vyos.vyos_facts <ansible_collections.vyos.vyos.vyos_facts_module>` to connect to the remote networking device. As the credentials are not explicitly passed with module arguments, Ansible uses the username and password from the inventory file.
Ansible's "Network Fact modules" gather information from the system and store the results in facts prefixed with ``ansible_net_``. The data collected by these modules is documented in the `Return Values` section of the module docs, in this case :ref:`eos_facts <eos_facts_module>` and :ref:`vyos_facts <vyos_facts_module>`. We can use the facts, such as ``ansible_net_version`` late on in the "Display some facts" task.
Ansible's "Network Fact modules" gather information from the system and store the results in facts prefixed with ``ansible_net_``. The data collected by these modules is documented in the `Return Values` section of the module docs, in this case :ref:`arista.eos.eos_facts <ansible_collections.arista.eos.eos_facts_module>` and :ref:`vyos.vyos.vyos_facts <ansible_collections.vyos.vyos.vyos_facts_module>`. We can use the facts, such as ``ansible_net_version`` late on in the "Display some facts" task.
To ensure we call the correct mode (``*_facts``) the task is conditionally run based on the group defined in the inventory file, for more information on the use of conditionals in Ansible Playbooks see :ref:`the_when_statement`.
@ -196,15 +196,15 @@ Next, create a playbook file called ``facts-demo.yml`` containing the following:
#
- name: Gather facts (eos)
arista.eos.eos_facts:
when: ansible_network_os == 'eos'
when: ansible_network_os == 'arista.eos.eos'
- name: Gather facts (ios)
cisco.ios.ios_facts:
when: ansible_network_os == 'ios'
when: ansible_network_os == 'cisco.ios.ios'
- name: Gather facts (vyos)
vyos.vyos.vyos_facts:
when: ansible_network_os == 'vyos'
when: ansible_network_os == 'vyos.vyos.vyos'
###
# Demonstrate variables
@ -255,13 +255,13 @@ Next, create a playbook file called ``facts-demo.yml`` containing the following:
arista.eos.eos_config:
backup: yes
register: backup_eos_location
when: ansible_network_os == 'eos'
when: ansible_network_os == 'arista.eos.eos'
- name: backup switch (vyos)
vyos.vyos.vyos_config:
backup: yes
register: backup_vyos_location
when: ansible_network_os == 'vyos'
when: ansible_network_os == 'vyos.vyos.vyos'
- name: Create backup dir
file:
@ -273,13 +273,13 @@ Next, create a playbook file called ``facts-demo.yml`` containing the following:
copy:
src: "{{ backup_eos_location.backup_path }}"
dest: "/tmp/backups/{{ inventory_hostname }}/{{ inventory_hostname }}.bck"
when: ansible_network_os == 'eos'
when: ansible_network_os == 'arista.eos.eos'
- name: Copy backup files into /tmp/backups/ (vyos)
copy:
src: "{{ backup_vyos_location.backup_path }}"
dest: "/tmp/backups/{{ inventory_hostname }}/{{ inventory_hostname }}.bck"
when: ansible_network_os == 'vyos'
when: ansible_network_os == 'vyos.vyos.vyos'
Step 3: Running the playbook
----------------------------
@ -325,10 +325,10 @@ Example 2: simplifying playbooks with network agnostic modules
(This example originally appeared in the `Deep Dive on cli_command for Network Automation <https://www.ansible.com/blog/deep-dive-on-cli-command-for-network-automation>`_ blog post by Sean Cavanaugh -`@IPvSean <https://github.com/IPvSean>`_).
If you have two or more network platforms in your environment, you can use the network agnostic modules to simplify your playbooks. You can use network agnostic modules such as ``cli_command`` or ``cli_config`` in place of the platform-specific modules such as ``eos_config``, ``ios_config``, and ``junos_config``. This reduces the number of tasks and conditionals you need in your playbooks.
If you have two or more network platforms in your environment, you can use the network agnostic modules to simplify your playbooks. You can use network agnostic modules such as ``ansible.netcommon.cli_command`` or ``ansible.netcommon.cli_config`` in place of the platform-specific modules such as ``arista.eos.eos_config``, ``cisco.ios.ios_config``, and ``junipernetworks.junos.junos_config``. This reduces the number of tasks and conditionals you need in your playbooks.
.. note::
Network agnostic modules require the :ref:`network_cli <network_cli_connection>` connection plugin.
Network agnostic modules require the :ref:`ansible.netcommon.network_cli <ansible_collections.ansible.netcommon.network_cli_connection>` connection plugin.
Sample playbook with platform-specific modules
@ -342,29 +342,29 @@ This example assumes three platforms, Arista EOS, Cisco NXOS, and Juniper JunOS.
- name: Run Arista command
arista.eos.eos_command:
commands: show ip int br
when: ansible_network_os == 'eos'
when: ansible_network_os == 'arista.eos.eos'
- name: Run Cisco NXOS command
cisco.nxos.nxos_command:
commands: show ip int br
when: ansible_network_os == 'nxos'
when: ansible_network_os == 'cisco.nxos.nxos'
- name: Run Vyos command
vyos.vyos.vyos_command:
commands: show interface
when: ansible_network_os == 'vyos'
when: ansible_network_os == 'vyos.vyos.vyos'
Simplified playbook with ``cli_command`` network agnostic module
----------------------------------------------------------------
You can replace these platform-specific modules with the network agnostic ``cli_command`` module as follows:
You can replace these platform-specific modules with the network agnostic ``ansible.netcommon.cli_command`` module as follows:
.. code-block:: yaml
---
- hosts: network
gather_facts: false
connection: network_cli
connection: ansible.netcommon.network_cli
tasks:
- name: Run cli_command on Arista and display results
@ -377,7 +377,7 @@ You can replace these platform-specific modules with the network agnostic ``cli_
- name: Display result to terminal window
debug:
var: result.stdout_lines
when: ansible_network_os == 'eos'
when: ansible_network_os == 'arista.eos.eos'
- name: Run cli_command on Cisco IOS and display results
block:
@ -389,7 +389,7 @@ You can replace these platform-specific modules with the network agnostic ``cli_
- name: Display result to terminal window
debug:
var: result.stdout_lines
when: ansible_network_os == 'ios'
when: ansible_network_os == 'cisco.ios.ios'
- name: Run cli_command on Vyos and display results
block:
@ -401,7 +401,7 @@ You can replace these platform-specific modules with the network agnostic ``cli_
- name: Display result to terminal window
debug:
var: result.stdout_lines
when: ansible_network_os == 'vyos'
when: ansible_network_os == 'vyos.vyos.vyos'
If you use groups and group_vars by platform type, this playbook can be further simplified to :
@ -422,10 +422,10 @@ If you use groups and group_vars by platform type, this playbook can be further
You can see a full example of this using group_vars and also a configuration backup example at `Network agnostic examples <https://github.com/network-automation/agnostic_example>`_.
Using multiple prompts with the ``cli_command``
------------------------------------------------
Using multiple prompts with the ``ansible.netcommon.cli_command``
-------------------------------------------------------------------
The ``cli_command`` also supports multiple prompts.
The ``ansible.netcommon.cli_command`` also supports multiple prompts.
.. code-block:: yaml
@ -465,7 +465,7 @@ For more information, see :ref:`magic_variables_and_hostvars`.
Get running configuration
-------------------------
The :ref:`arista.eos.eos_config <eos_config_module>` and :ref:`vyos.vyos.vyos_config <vyos_config_module>` modules have a ``backup:`` option that when set will cause the module to create a full backup of the current ``running-config`` from the remote device before any changes are made. The backup file is written to the ``backup`` folder in the playbook root directory. If the directory does not exist, it is created.
The :ref:`arista.eos.eos_config <ansible_collections.arista.eos.eos_config_module>` and :ref:`vyos.vyos.vyos_config <ansible_collections.vyos.vyos.vyos_config_module>` modules have a ``backup:`` option that when set will cause the module to create a full backup of the current ``running-config`` from the remote device before any changes are made. The backup file is written to the ``backup`` folder in the playbook root directory. If the directory does not exist, it is created.
To demonstrate how we can move the backup file to a different location, we register the result and move the file to the path stored in ``backup_path``.

141
docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst
View file

@ -4,25 +4,16 @@
Network Debug and Troubleshooting Guide
***************************************
This section discusses how to debug and troubleshoot network modules in Ansible.
.. contents::
:local:
Introduction
============
Starting with Ansible version 2.1, you can now use the familiar Ansible models of playbook authoring and module development to manage heterogeneous networking devices. Ansible supports a growing number of network devices using both CLI over SSH and API (when available) transports.
This section discusses how to debug and troubleshoot network modules in Ansible 2.3.
How to troubleshoot
===================
This section covers troubleshooting issues with Network Modules.
Errors generally fall into one of the following categories:
Ansible network automation errors generally fall into one of the following categories:
:Authentication issues:
* Not correctly specifying credentials
@ -36,7 +27,7 @@ Errors generally fall into one of the following categories:
.. warning:: ``unable to open shell``
The ``unable to open shell`` message is new in Ansible 2.3, it means that the ``ansible-connection`` daemon has not been able to successfully
The ``unable to open shell`` message means that the ``ansible-connection`` daemon has not been able to successfully
talk to the remote network device. This generally means that there is an authentication issue. See the "Authentication and connection issues" section
in this document for more information.
@ -47,11 +38,11 @@ Enabling Networking logging and how to read the logfile
**Platforms:** Any
Ansible 2.3 features improved logging to help diagnose and troubleshoot issues regarding Ansible Networking modules.
Ansible includes logging to help diagnose and troubleshoot issues regarding Ansible Networking modules.
Because logging is very verbose it is disabled by default. It can be enabled via the :envvar:`ANSIBLE_LOG_PATH` and :envvar:`ANSIBLE_DEBUG` options on the ansible-controller, that is the machine running ansible-playbook.
Because logging is very verbose, it is disabled by default. It can be enabled with the :envvar:`ANSIBLE_LOG_PATH` and :envvar:`ANSIBLE_DEBUG` options on the ansible-controller, that is the machine running ``ansible-playbook``.
Before running ``ansible-playbook`` run the following commands to enable logging::
Before running ``ansible-playbook``, run the following commands to enable logging::
# Specify the location for the log file
export ANSIBLE_LOG_PATH=~/ansible.log
@ -104,19 +95,21 @@ Enabling Networking device interaction logging
**Platforms:** Any
Ansible 2.8 features added logging of device interaction in log file to help diagnose and troubleshoot
issues regarding Ansible Networking modules. The messages are logged in file pointed by ``log_path`` configuration
option in Ansible configuration file or by set :envvar:`ANSIBLE_LOG_PATH` as mentioned in above section.
Ansible includes logging of device interaction in the log file to help diagnose and troubleshoot
issues regarding Ansible Networking modules. The messages are logged in the file pointed to by the ``log_path`` configuration
option in the Ansible configuration file or by setting the :envvar:`ANSIBLE_LOG_PATH`.
.. warning::
The device interaction messages consist of command executed on target device and the returned response, as this
The device interaction messages consist of command executed on the target device and the returned response. Since this
log data can contain sensitive information including passwords in plain text it is disabled by default.
Additionally, in order to prevent accidental leakage of data, a warning will be shown on every task with this
setting enabled specifying which host has it enabled and where the data is being logged.
setting enabled, specifying which host has it enabled and where the data is being logged.
Be sure to fully understand the security implications of enabling this option. The device interaction logging can be enabled either globally by setting in configuration file or by setting environment or enabled on per task basis by passing special variable to task.
Be sure to fully understand the security implications of enabling this option. The device interaction logging can be enabled either globally by setting in configuration file or by setting environment or enabled on per task basis by passing a special variable to the task.
Before running ``ansible-playbook`` run the following commands to enable logging::
Before running ``ansible-playbook`` run the following commands to enable logging:
.. code-block:: text
# Specify the location for the log file
export ANSIBLE_LOG_PATH=~/ansible.log
@ -127,7 +120,7 @@ Enable device interaction logging for a given task
.. code-block:: yaml
- name: get version information
ios_command:
cisco.ios.ios_command:
commands:
- show version
vars:
@ -141,14 +134,15 @@ To make this a global setting, add the following to your ``ansible.cfg`` file:
[persistent_connection]
log_messages = True
or enable environment variable `ANSIBLE_PERSISTENT_LOG_MESSAGES`
or enable the environment variable `ANSIBLE_PERSISTENT_LOG_MESSAGES`:
.. code-block:: text
# Enable device interaction logging
export ANSIBLE_PERSISTENT_LOG_MESSAGES=True
If the task is failing at the time on connection initialization itself it is recommended to enable this option
globally else if an individual task is failing intermittently this option can be enabled for that task itself to
find the root cause.
If the task is failing on connection initialization itself, you should enable this option
globally. If an individual task is failing intermittently this option can be enabled for that task itself to find the root cause.
After Ansible has finished running you can inspect the log file which has been created on the ansible-controller
@ -170,26 +164,28 @@ For Ansible this can be done by ensuring you are only running against one remote
`ad-hoc` refers to running Ansible to perform some quick command using ``/usr/bin/ansible``, rather than the orchestration language, which is ``/usr/bin/ansible-playbook``. In this case we can ensure connectivity by attempting to execute a single command on the remote device::
ansible -m eos_command -a 'commands=?' -i inventory switch1.example.net -e 'ansible_connection=local' -u admin -k
ansible -m arista.eos.eos_command -a 'commands=?' -i inventory switch1.example.net -e 'ansible_connection=ansible.netcommon.network_cli' -u admin -k
In the above example, we:
* connect to ``switch1.example.net`` specified in the inventory file ``inventory``
* use the module ``eos_command``
* use the module ``arista.eos.eos_command``
* run the command ``?``
* connect using the username ``admin``
* inform ansible to prompt for the ssh password by specifying ``-k``
* inform the ``ansible`` command to prompt for the SSH password by specifying ``-k``
If you have SSH keys configured correctly, you don't need to specify the ``-k`` parameter
If you have SSH keys configured correctly, you don't need to specify the ``-k`` parameter.
If the connection still fails you can combine it with the enable_network_logging parameter. For example::
If the connection still fails you can combine it with the enable_network_logging parameter. For example:
.. code-block:: text
# Specify the location for the log file
export ANSIBLE_LOG_PATH=~/ansible.log
# Enable Debug
export ANSIBLE_DEBUG=True
# Run with 4*v for connection level verbosity
ansible -m eos_command -a 'commands=?' -i inventory switch1.example.net -e 'ansible_connection=local' -u admin -k
# Run with ``-vvvv`` for connection level verbosity
ansible -m arista.eos.eos_command -a 'commands=?' -i inventory switch1.example.net -e 'ansible_connection=ansible.netcommon.network_cli' -u admin -k
Then review the log file and find the relevant error message in the rest of this document.
@ -202,7 +198,7 @@ Troubleshooting socket path issues
**Platforms:** Any
The ``Socket path does not exist or cannot be found`` and ``Unable to connect to socket`` messages are new in Ansible 2.5. These messages indicate that the socket used to communicate with the remote network device is unavailable or does not exist.
The ``Socket path does not exist or cannot be found`` and ``Unable to connect to socket`` messages indicate that the socket used to communicate with the remote network device is unavailable or does not exist.
For example:
@ -259,7 +255,7 @@ Category "Unable to open shell"
**Platforms:** Any
The ``unable to open shell`` message is new in Ansible 2.3. This message means that the ``ansible-connection`` daemon has not been able to successfully talk to the remote network device. This generally means that there is an authentication issue. It is a "catch all" message, meaning you need to enable :ref:logging`a_note_about_logging` to find the underlying issues.
The ``unable to open shell`` message means that the ``ansible-connection`` daemon has not been able to successfully talk to the remote network device. This generally means that there is an authentication issue. It is a "catch all" message, meaning you need to enable :ref:`logging <a_note_about_logging>` to find the underlying issues.
@ -508,21 +504,18 @@ Suggestions to resolve:
.. code-block:: yaml
- name: save running-config
ios_command:
cisco.ios.ios_command:
commands: copy running-config startup-config
provider: "{{ cli }}"
timeout: 30
For network_cli, netconf connection type (applicable from 2.7 onwards):
.. FIXME: Detail error here
Suggestions to resolve:
.. code-block:: yaml
- name: save running-config
ios_command:
cisco.ios.ios_command:
commands: copy running-config startup-config
vars:
ansible_command_timeout: 60
@ -611,7 +604,7 @@ This section details issues are caused by issues with the Playbook itself.
Error: "Unable to enter configuration mode"
-------------------------------------------
**Platforms:** eos and ios
**Platforms:** Arista EOS and Cisco IOS
This occurs when you attempt to run a task that requires privileged mode in a user mode shell.
@ -629,35 +622,7 @@ For example:
Suggestions to resolve:
In Ansible prior to 2.5 :
Add ``authorize: yes`` to the task. For example:
.. code-block:: yaml
- name: configure hostname
ios_system:
provider:
hostname: foo
authorize: yes
register: result
If the user requires a password to go into privileged mode, this can be specified with ``auth_pass``; if ``auth_pass`` isn't set, the environment variable `ANSIBLE_NET_AUTHORIZE` will be used instead.
Add ``authorize: yes`` to the task. For example:
.. code-block:: yaml
- name: configure hostname
ios_system:
provider:
hostname: foo
authorize: yes
auth_pass: "{{ mypasswordvar }}"
register: result
.. note:: Starting with Ansible 2.5 we recommend using ``connection: network_cli`` and ``become: yes``
Use ``connection: ansible.netcommon.network_cli`` and ``become: yes``
Proxy Issues
@ -668,10 +633,8 @@ Proxy Issues
delegate_to vs ProxyCommand
---------------------------
The new connection framework for Network Modules in Ansible 2.3 that uses ``cli`` transport
no longer supports the use of the ``delegate_to`` directive.
In order to use a bastion or intermediate jump host to connect to network devices over ``cli``
transport, network modules now support the use of ``ProxyCommand``.
transport, network modules support the use of ``ProxyCommand``.
To use ``ProxyCommand``, configure the proxy settings in the Ansible inventory
file to specify the proxy host.
@ -751,8 +714,8 @@ Example Ansible inventory file
junos01
[junos:vars]
ansible_connection=netconf
ansible_network_os=junos
ansible_connection=ansible.netcommon.netconf
ansible_network_os=junipernetworks.junos.junos
ansible_user=myuser
ansible_password=!vault...
@ -768,11 +731,11 @@ Miscellaneous Issues
====================
Intermittent failure while using ``network_cli`` connection type
----------------------------------------------------------------
Intermittent failure while using ``ansible.netcommon.network_cli`` connection type
------------------------------------------------------------------------------------
If the command prompt received in response is not matched correctly within
the ``network_cli`` connection plugin the task might fail intermittently with truncated
the ``ansible.netcommon.network_cli`` connection plugin the task might fail intermittently with truncated
response or with the error message ``operation requires privilege escalation``.
Starting in 2.7.1 a new buffer read timer is added to ensure prompts are matched properly
and a complete response is send in output. The timer default value is 0.2 seconds and
@ -783,7 +746,7 @@ Example Per task timer setting
.. code-block:: yaml
- name: gather ios facts
ios_facts:
cisco.ios.ios_facts:
gather_subset: all
register: result
vars:
@ -800,10 +763,10 @@ To make this a global setting, add the following to your ``ansible.cfg`` file:
This timer delay per command executed on remote host can be disabled by setting the value to zero.
Task failure due to mismatched error regex within command response using ``network_cli`` connection type
--------------------------------------------------------------------------------------------------------
Task failure due to mismatched error regex within command response using ``ansible.netcommon.network_cli`` connection type
----------------------------------------------------------------------------------------------------------------------------
In Ansible 2.9 and later, the network_cli connection plugin configuration options are added
In Ansible 2.9 and later, the ``ansible.netcommon.network_cli`` connection plugin configuration options are added
to handle the stdout and stderr regex to identify if the command execution response consist
of a normal response or an error response. These options can be set group/host variables or as
tasks variables.
@ -813,7 +776,7 @@ Example: For mismatched error response
.. code-block:: yaml
- name: fetch logs from remote host
ios_command:
cisco.ios.ios_command:
commands:
- show logging
@ -836,7 +799,7 @@ Modify the error regex for individual task.
.. code-block:: yaml
- name: fetch logs from remote host
ios_command:
cisco.ios.ios_command:
commands:
- show logging
vars:
@ -849,10 +812,10 @@ The terminal plugin regex options ``ansible_terminal_stderr_re`` and ``ansible_t
the ``re.compile`` python method.
Intermittent failure while using ``network_cli`` connection type due to slower network or remote target host
------------------------------------------------------------------------------------------------------------
Intermittent failure while using ``ansible.netcommon.network_cli`` connection type due to slower network or remote target host
----------------------------------------------------------------------------------------------------------------------------------
In Ansible 2.9 and later, the ``network_cli`` connection plugin configuration option is added to control
In Ansible 2.9 and later, the ``ansible.netcommon.network_cli`` connection plugin configuration option is added to control
the number of attempts to connect to a remote host. The default number of attempts is three.
After every retry attempt the delay between retries is increased by power of 2 in seconds until either the
maximum attempts are exhausted or either the ``persistent_command_timeout`` or ``persistent_connect_timeout`` timers are triggered.

22
docs/docsite/rst/network/user_guide/network_resource_modules.rst
View file

@ -1,21 +1,15 @@
.. _resource_modules:
************************
Network resource modules
Network Resource Modules
************************
Ansible 2.9 introduced network resource modules to simplify and standardize how you manage different network devices.
Ansible network resource modules simplify and standardize how you manage different network devices. Network devices separate configuration into sections (such as interfaces and VLANs) that apply to a network service. Ansible network resource modules take advantage of this to allow you to configure subsections or *resources* within the network device configuration. Network resource modules provide a consistent experience across different network devices.
.. contents::
:local:
Understanding network resource modules
=======================================
Network devices separate configuration into sections (such as interfaces, VLANS, etc) that apply to a network service. Ansible network resource modules take advantage of this to allow you to configure subsections or *resources* within the network device configuration. Network resource modules provide a consistent experience across different network devices.
Network resource module states
===============================
@ -45,12 +39,12 @@ parsed
Using network resource modules
==============================
This example configures L3 interface resource on a Cisco IOS device, based on different state settings.
This example configures the L3 interface resource on a Cisco IOS device, based on different state settings.
.. code-block:: YAML
.. code-block:: yaml
- name: configure l3 interface
ios_l3_interfaces:
cisco.ios.ios_l3_interfaces:
config: "{{ config }}"
state: <state>
@ -127,7 +121,7 @@ Network resource modules return the following details:
Example: Verifying the network device configuration has not changed
====================================================================
The following playbook uses the :ref:`eos_l3_interfaces <eos_l3_interfaces_module>` module to gather a subset of the network device configuration (Layer 3 interfaces only) and verifies the information is accurate and has not changed. This playbook passes the results of :ref:`eos_facts <eos_facts_module>` directly to the ``eos_l3_interfaces`` module.
The following playbook uses the :ref:`arista.eos.eos_l3_interfaces <ansible_collections.arista.eos.eos_l3_interfaces_module>` module to gather a subset of the network device configuration (Layer 3 interfaces only) and verifies the information is accurate and has not changed. This playbook passes the results of :ref:`arista.eos.eos_facts <ansible_collections.arista.eos.eos_facts_module>` directly to the ``arista.eos.eos_l3_interfaces`` module.
.. code-block:: yaml
@ -137,12 +131,12 @@ The following playbook uses the :ref:`eos_l3_interfaces <eos_l3_interfaces_modul
gather_facts: false
tasks:
- name: grab arista eos facts
eos_facts:
arista.eos.eos_facts:
gather_subset: min
gather_network_resources: l3_interfaces
- name: Ensure that the IP address information is accurate.
eos_l3_interfaces:
arista.eos.eos_l3_interfaces:
config: "{{ ansible_network_resources['l3_interfaces'] }}"
register: result

12
docs/docsite/rst/network/user_guide/network_working_with_command_output.rst
View file

@ -30,7 +30,7 @@ For example::
---
- name: wait for interface to be admin enabled
eos_command:
arista.eos.eos_command:
commands:
- show interface Ethernet4 | json
wait_for:
@ -49,7 +49,7 @@ results in an interface. For instance::
---
- name: wait for interfaces to be admin enabled
eos_command:
arista.eos.eos_command:
commands:
- show interface Ethernet4 | json
- show interface Ethernet5 | json
@ -70,19 +70,19 @@ command index in ``[]``, where ``0`` is the first command in the commands list,
Handling prompts in network modules
===================================
Network devices may require that you answer a prompt before performing a change on the device. Individual network modules such as :ref:`ios_command <ios_command_module>` and :ref:`nxos_command <nxos_command_module>` can handle this with a ``prompt`` parameter.
Network devices may require that you answer a prompt before performing a change on the device. Individual network modules such as :ref:`cisco.ios.ios_command <ansible_collections.cisco.ios.ios_command_module>` and :ref:`cisco.nxos.nxos_command <ansible_collections.cisco.nxos.nxos_command_module>` can handle this with a ``prompt`` parameter.
.. note::
``prompt`` is a Python regex. If you add special characters such as ``?`` in the ``prompt`` value, the prompt won't match and you will get a timeout. To avoid this, ensure that the ``prompt`` value is a Python regex that matches the actual device prompt. Any special characters must be handled correctly in the ``prompt`` regex.
You can also use the :ref:`cli_command <cli_command_module>` to handle multiple prompts.
You can also use the :ref:`ansible.netcommon.cli_command <ansible_collections.ansible.netcommon.cli_command_module>` to handle multiple prompts.
.. code-block:: yaml
---
- name: multiple prompt, multiple answer (mandatory check for all prompts)
cli_command:
ansible.netcommon.cli_command:
command: "copy sftp sftp://user@host//user/test.img"
check_all: True
prompt:
@ -104,7 +104,7 @@ In the following example, the second answer would be ignored and ``y`` would be
---
- name: reboot ios device
cli_command:
ansible.netcommon.cli_command:
command: reload
prompt:
- Save\?

70
docs/docsite/rst/network/user_guide/platform_index.rst
View file

@ -54,41 +54,43 @@ Settings by Platform
.. table::
:name: network-platform-table
=============================== ======================= =========== ======= ======= ===========
.. ``ansible_connection:`` settings available
-------------------------------------------------------- ------------------------------------------
Network OS ``ansible_network_os:`` network_cli netconf httpapi local
=============================== ======================= =========== ======= ======= ===========
`Arista EOS`_ `[†]`_ ``eos`` ✓ ✓ ✓
`Cisco ASA`_ `[†]`_ ``asa`` ✓ ✓
`Cisco IOS`_ `[†]`_ ``ios`` ✓ ✓
`Cisco IOS XR`_ `[†]`_ ``iosxr`` ✓ ✓
`Cisco NX-OS`_ `[†]`_ ``nxos`` ✓ ✓ ✓
`Cloudengine OS`_ ``ce`` ✓ ✓ ✓
`Dell OS6`_ ``dellos6`` ✓ ✓
`Dell OS9`_ ``dellos9`` ✓ ✓
`Dell OS10`_ ``dellos10`` ✓ ✓
`Ericsson ECCLI`_ ``eric_eccli`` ✓ ✓
`Extreme EXOS`_ ``exos`` ✓ ✓
`Extreme IronWare`_ ``ironware`` ✓ ✓
`Extreme NOS`_ ``nos`` ✓
`Extreme SLX-OS`_ ``slxos`` ✓
`Extreme VOSS`_ ``voss`` ✓
`F5 BIG-IP`_ ✓
`F5 BIG-IQ`_ ✓
`Junos OS`_ `[†]`_ ``junos`` ✓ ✓ ✓
`Lenovo CNOS`_ ``cnos`` ✓ ✓
`Lenovo ENOS`_ ``enos`` ✓ ✓
`Meraki`_ ``meraki`` ✓
`MikroTik RouterOS`_ ``routeros`` ✓
`Nokia SR OS`_ ``sros`` ✓ ✓
`Pluribus Netvisor`_ ``netvisor`` ✓
`Ruckus ICX`_ ``icx`` ✓
`VyOS`_ `[†]`_ ``vyos`` ✓ ✓
OS that supports Netconf `[†]`_ ``<network-os>`` ✓ ✓
=============================== ======================= =========== ======= ======= ===========
=============================== ================================ =========== ======= ======= ===========
.. ``ansible_connection:`` settings available
----------------------------------------------------------------- ------------------------------------------
Network OS ``ansible_network_os:`` network_cli netconf httpapi local
=============================== ================================ =========== ======= ======= ===========
`Arista EOS`_ `[†]`_ ``arista.eos.eos`` ✓ ✓ ✓
`Ciena SAOS6`_ ``ciena.saos6.saos6`` ✓ ✓
`Cisco ASA`_ `[†]`_ ``cisco.asa.asa`` ✓ ✓
`Cisco IOS`_ `[†]`_ ``cisco.ios.ios`` ✓ ✓
`Cisco IOS XR`_ `[†]`_ ``cisco.iosxr.iosxr`` ✓ ✓
`Cisco NX-OS`_ `[†]`_ ``cisco.nxos.nxos`` ✓ ✓ ✓
`Cloudengine OS`_ ``community.network.ce`` ✓ ✓ ✓
`Dell OS6`_ ``dellemc.os6.os6`` ✓ ✓
`Dell OS9`_ ``dellemc.os9.os9`` ✓ ✓
`Dell OS10`_ ``dellemc.os10.0s10`` ✓ ✓
`Ericsson ECCLI`_ ``community.network.eric_eccli`` ✓ ✓
`Extreme EXOS`_ ``community.network.exos`` ✓ ✓
`Extreme IronWare`_ ``community.network.ironware`` ✓ ✓
`Extreme NOS`_ ``community.network.nos`` ✓
`Extreme SLX-OS`_ ``community.network.slxos`` ✓
`Extreme VOSS`_ ``community.network.voss`` ✓
`F5 BIG-IP`_ ✓
`F5 BIG-IQ`_ ✓
`Junos OS`_ `[†]`_ ``junipernetworks.junos.junos`` ✓ ✓ ✓
`Lenovo CNOS`_ ``community.network.cnos`` ✓ ✓
`Lenovo ENOS`_ ``community.network.enos`` ✓ ✓
`Meraki`_ ✓
`MikroTik RouterOS`_ ``community.network.routeros`` ✓
`Nokia SR OS`_ ✓
`Pluribus Netvisor`_ ``community.network.netvisor`` ✓
`Ruckus ICX`_ ``community.network.icx`` ✓
`VyOS`_ `[†]`_ ``vyos.vyos.vyos`` ✓ ✓
OS that supports Netconf `[†]`_ ``<network-os>`` ✓ ✓
=============================== ================================ =========== ======= ======= ===========
.. _Arista EOS: https://galaxy.ansible.com/arista/eos
.. _Ciena SAOS6: https://galaxy.ansible.com/ciena/saos6
.. _Cisco ASA: https://galaxy.ansible.com/cisco/asa
.. _Cisco IOS: https://galaxy.ansible.com/cisco/ios
.. _Cisco IOS XR: https://galaxy.ansible.com/cisco/iosxr
@ -96,7 +98,7 @@ Settings by Platform
.. _Cloudengine OS: https://galaxy.ansible.com/community/network
.. _Dell OS6: https://github.com/ansible-collections/dellemc.os6
.. _Dell OS9: https://github.com/ansible-collections/dellemc.os9
.. _Dell OS10: https://galaxy.ansible.com/dellemc_networking/os10
.. _Dell OS10: https://galaxy.ansible.com/dellemc/os10
.. _Ericsson ECCLI: https://galaxy.ansible.com/community/network
.. _Extreme EXOS: https://galaxy.ansible.com/community/network
.. _Extreme IronWare: https://galaxy.ansible.com/community/network

19
docs/docsite/rst/plugins/cliconf.rst
View file

@ -7,15 +7,9 @@ Cliconf Plugins
:local:
:depth: 2
.. warning::
Cliconf plugins are abstractions over the CLI interface to network devices. They provide a standard interface for Ansible to execute tasks on those network devices.
Links on this page may not point to the most recent versions of plugins. In preparation for the release of 2.10, many plugins and modules have migrated to Collections on `Ansible Galaxy <https://galaxy.ansible.com>`_. For the current development status of Collections and FAQ see `Ansible Collections Community Guide <https://github.com/ansible-collections/overview/blob/master/README.rst>`_.
Cliconf plugins are abstractions over the CLI interface to network devices. They provide a standard interface
for Ansible to execute tasks on those network devices.
These plugins generally correspond one-to-one to network device platforms. The appropriate cliconf plugin will
thus be automatically loaded based on the ``ansible_network_os`` variable.
These plugins generally correspond one-to-one to network device platforms. Ansible loads the appropriate cliconf plugin automatically based on the ``ansible_network_os`` variable.
.. _enabling_cliconf:
@ -31,17 +25,16 @@ Using cliconf plugins
The cliconf plugin to use is determined automatically from the ``ansible_network_os`` variable. There should be no reason to override this functionality.
Most cliconf plugins can operate without configuration. A few have additional options that can be set to impact how
tasks are translated into CLI commands.
Most cliconf plugins can operate without configuration. A few have additional options that can be set to affect how tasks are translated into CLI commands.
Plugins are self-documenting. Each plugin should document its configuration options.
.. _cliconf_plugin_list:
Plugin list
-----------
Viewing cliconf plugins
-----------------------
These plugins have migrated to a collection. Updates on where to find and how to use them will be coming soon.
These plugins have migrated to collections on `Ansible Galaxy <https://galaxy.ansible.com>`_. If you installed Ansible version 2.10 or later using ``pip``, you have access to several cliconf plugins. To list all available cliconf plugins on your control node, type ``ansible-doc -t cliconf -l``. To view plugin-specific documentation and examples, use ``ansible-doc -t cliconf``.
.. seealso::

16
docs/docsite/rst/plugins/httpapi.rst
View file

@ -7,15 +7,11 @@ Httpapi Plugins
:local:
:depth: 2
.. warning::
Links on this page may not point to the most recent versions of plugins. In preparation for the release of 2.10, many plugins and modules have migrated to Collections on `Ansible Galaxy <https://galaxy.ansible.com>`_. For the current development status of Collections and FAQ see `Ansible Collections Community Guide <https://github.com/ansible-collections/overview/blob/master/README.rst>`_.
Httpapi plugins tell Ansible how to interact with a remote device's HTTP-based API and execute tasks on the
device.
Each plugin represents a particular dialect of API. Some are platform-specific (Arista eAPI, Cisco NXAPI), while
others might be usable on a variety of platforms (RESTCONF).
Each plugin represents a particular dialect of API. Some are platform-specific (Arista eAPI, Cisco NXAPI), while others might be usable on a variety of platforms (RESTCONF). Ansible loads the appropriate httpapi plugin automatically based on the ``ansible_network_os`` variable.
.. _enabling_httpapi:
@ -55,14 +51,14 @@ The following sample playbook shows the httpapi plugin for an Arista network dev
debug:
var: command_output.stdout[0]["version"]
See the full working example at https://github.com/network-automation/httpapi.
See the full working example `on GitHub <https://github.com/network-automation/httpapi>`_.
.. _httpapi_plugin_list:
Plugin List
-----------
Viewing httpapi plugins
-----------------------
These plugins have migrated to a collection. Updates on where to find and how to use them will be coming soon.
These plugins have migrated to collections on `Ansible Galaxy <https://galaxy.ansible.com>`_. If you installed Ansible version 2.10 or later using ``pip``, you have access to several httpapi plugins. To list all available httpapi plugins on your control node, type ``ansible-doc -t httpapi -l``. To view plugin-specific documentation and examples, use ``ansible-doc -t httpapi``.
.. seealso::

56
docs/docsite/rst/plugins/inventory.rst
View file

@ -15,25 +15,16 @@ Inventory plugins allow users to point at data sources to compile the inventory
Enabling inventory plugins
--------------------------
Most inventory plugins shipped with Ansible are disabled by default and need to be whitelisted in your
:ref:`ansible.cfg <ansible_configuration_settings>` file in order to function. This is how the default whitelist looks in the
config file that ships with Ansible:
Most inventory plugins shipped with Ansible are enabled by default or can be used by with the ``auto`` plugin.
In some circumstances, for example, if the inventory plugin does not use a YAML configuration file, you may need to enable the specific plugin. You can do this by setting ``enable_plugins`` in your :ref:`ansible.cfg <ansible_configuration_settings>` file in the ``[inventory]`` section. Modifying this will override the default list of enabled plugins. Here is the default list of enabled plugins that ships with Ansible:
.. code-block:: ini
[inventory]
enable_plugins = host_list, script, auto, yaml, ini, toml
This list also establishes the order in which each plugin tries to parse an inventory source. Any plugins left out of the list will not be considered, so you can 'optimize' your inventory loading by minimizing it to what you actually use. For example:
.. code-block:: ini
[inventory]
enable_plugins = advanced_host_list, constructed, yaml
The ``auto`` inventory plugin can be used to automatically determines which inventory plugin to use for a YAML configuration file. It can also be used for inventory plugins in a collection.
To whitelist specific inventory plugins in a collection you need to use the fully qualified name:
If the plugin is in a collection you need to use the fully qualified name:
.. code-block:: ini
@ -46,31 +37,22 @@ To whitelist specific inventory plugins in a collection you need to use the full
Using inventory plugins
-----------------------
The only requirement for using an inventory plugin after it is enabled is to provide an inventory source to parse.
Ansible will try to use the list of enabled inventory plugins, in order, against each inventory source provided.
Once an inventory plugin succeeds at parsing a source, any remaining inventory plugins will be skipped for that source.
To use an inventory plugin you need to provide an inventory source. Most of the time this is a file containing host information or a YAML configuration file with options for the plugin. You can use the ``-i`` flag to provide inventory sources or configure a default inventory path.
To start using an inventory plugin with a YAML configuration source, create a file with the accepted filename schema for the plugin in question, then add ``plugin: plugin_name``. Each plugin documents any naming restrictions. For example, the aws_ec2 inventory plugin has to end with ``aws_ec2.(yml|yaml)``
.. code-block:: bash
ansible hostname -i inventory_source -m ping
To start using an inventory plugin with a YAML configuration source, create a file with the accepted filename schema documented for the plugin in question, then add ``plugin: plugin_name``. Use the fully qualified name if the plugin is in a collection.
.. code-block:: yaml
# demo.aws_ec2.yml
plugin: aws_ec2
# demo.aws_ec2.yml
plugin: amazon.aws.aws_ec2
Or for the openstack plugin the file has to be called ``clouds.yml`` or ``openstack.(yml|yaml)``:
Each plugin should document any naming restrictions. In addition, the YAML config file must end with the extension ``yml`` or ``yaml`` to be enabled by default with the ``auto`` plugin (otherwise, see the section above on enabling plugins).
.. code-block:: yaml
# clouds.yml or openstack.(yml|yaml)
plugin: openstack
To use a plugin in a collection provide the fully qualified name:
.. code-block:: yaml
plugin: namespace.collection_name.inventory_plugin_name
The ``auto`` inventory plugin is enabled by default and works by using the ``plugin`` field to indicate the plugin that should attempt to parse it. You can configure the whitelist/precedence of inventory plugins used to parse source using the `ansible.cfg` ['inventory'] ``enable_plugins`` list. After enabling the plugin and providing any required options, you can view the populated inventory with ``ansible-inventory -i demo.aws_ec2.yml --graph``:
After providing any required options, you can view the populated inventory with ``ansible-inventory -i demo.aws_ec2.yml --graph``:
.. code-block:: text
@ -82,8 +64,6 @@ The ``auto`` inventory plugin is enabled by default and works by using the ``plu
If you are using an inventory plugin in a playbook-adjacent collection and want to test your setup with ``ansible-inventory``, you will need to use the ``--playbook-dir`` flag.
You can set the default inventory path (via ``inventory`` in the `ansible.cfg` [defaults] section or the :envvar:`ANSIBLE_INVENTORY` environment variable) to your inventory source(s). Now running ``ansible-inventory --graph`` should yield the same output as when you passed your YAML configuration source(s) directly. You can add custom inventory plugins to your plugin path to use in the same way.
Your inventory source might be a directory of inventory configuration files. The constructed inventory plugin only operates on those hosts already in inventory, so you may want the constructed inventory configuration parsed at a particular point (such as last). Ansible parses the directory recursively, alphabetically. You cannot configure the parsing approach, so name your files to make it work predictably. Inventory plugins that extend constructed features directly can work around that restriction by adding constructed options in addition to the inventory plugin options. Otherwise, you can use ``-i`` with multiple sources to impose a specific order, e.g. ``-i demo.aws_ec2.yml -i clouds.yml -i constructed.yml``.
You can create dynamic groups using host variables with the constructed ``keyed_groups`` option. The option ``groups`` can also be used to create groups and ``compose`` creates and modifies host variables. Here is an aws_ec2 example utilizing constructed features:
@ -127,14 +107,14 @@ Now the output of ``ansible-inventory -i demo.aws_ec2.yml --graph``:
If a host does not have the variables in the configuration above (i.e. ``tags.Name``, ``tags``, ``private_ip_address``), the host will not be added to groups other than those that the inventory plugin creates and the ``ansible_host`` host variable will not be modified.
If an inventory plugin supports caching, you can enable and set caching options for an individual YAML configuration source or for multiple inventory sources using environment variables or Ansible configuration files. If you enable caching for an inventory plugin without providing inventory-specific caching options, the inventory plugin will use fact-caching options. Here is an example of enabling caching for an individual YAML configuration file:
Inventory plugins that support caching can use the general settings for the fact cache defined in the ``ansible.cfg`` file's ``[defaults]`` section or define inventory-specific settings in the ``[inventory]`` section. Individual plugins can define plugin-specific cache settings in their config file:
.. code-block:: yaml
# demo.aws_ec2.yml
plugin: aws_ec2
cache: yes
cache_plugin: jsonfile
cache_plugin: ansible.builtin.jsonfile
cache_timeout: 7200
cache_connection: /tmp/aws_inventory
cache_prefix: aws_ec2
@ -144,7 +124,7 @@ Here is an example of setting inventory caching with some fact caching defaults
.. code-block:: ini
[defaults]
fact_caching = jsonfile
fact_caching = ansible.builtin.jsonfile
fact_caching_connection = /tmp/ansible_facts
cache_timeout = 3600
@ -152,8 +132,6 @@ Here is an example of setting inventory caching with some fact caching defaults
cache = yes
cache_connection = /tmp/ansible_inventory
Besides cache plugins shipped with Ansible, cache plugins eligible for caching inventory can also reside in a custom cache plugin path or in a collection. Use FQCN if the cache plugin is in a collection.
.. _inventory_plugin_list:
Plugin List

21
docs/docsite/rst/plugins/netconf.rst
View file

@ -7,17 +7,9 @@ Netconf Plugins
:local:
:depth: 2
.. warning::
Links on this page may not point to the most recent versions of plugins. In preparation for the release of 2.10, many plugins and modules have migrated to Collections on `Ansible Galaxy <https://galaxy.ansible.com>`_. For the current development status of Collections and FAQ see `Ansible Collections Community Guide <https://github.com/ansible-collections/overview/blob/master/README.rst>`_.
Netconf plugins are abstractions over the Netconf interface to network devices. They provide a standard interface for Ansible to execute tasks on those network devices.
These plugins generally correspond one-to-one to network device platforms. The appropriate netconf plugin will
thus be automatically loaded based on the ``ansible_network_os`` variable. If the platform supports standard
Netconf implementation as defined in the Netconf RFC specification the ``default`` netconf plugin will be used.
In case if the platform supports propriety Netconf RPC's in that case the interface can be defined in platform
specific netconf plugin.
These plugins generally correspond one-to-one to network device platforms. Ansible loads the appropriate netconf plugin automatically based on the ``ansible_network_os`` variable. If the platform supports standard Netconf implementation as defined in the Netconf RFC specification, Ansible loads the ``default`` netconf plugin. If the platform supports propriety Netconf RPCs, Ansible loads the platform-specific netconf plugin.
.. _enabling_netconf:
@ -33,19 +25,16 @@ Using netconf plugins
The netconf plugin to use is determined automatically from the ``ansible_network_os`` variable. There should be no reason to override this functionality.
Most netconf plugins can operate without configuration. A few have additional options that can be set to impact how
tasks are translated into netconf commands. A ncclient device specific handler name can be set in the netconf plugin
or else the value of ``default`` is used as per ncclient device handler.
Most netconf plugins can operate without configuration. A few have additional options that can be set to affect how tasks are translated into netconf commands. A ncclient device specific handler name can be set in the netconf plugin or else the value of ``default`` is used as per ncclient device handler.
Plugins are self-documenting. Each plugin should document its configuration options.
.. _netconf_plugin_list:
Plugin list
-----------
Listing netconf plugins
-----------------------
These plugins have migrated to a collection. Updates on where to find and how to use them will be coming soon.
These plugins have migrated to collections on `Ansible Galaxy <https://galaxy.ansible.com>`_. If you installed Ansible version 2.10 or later using ``pip``, you have access to several netconf plugins. To list all available netconf plugins on your control node, type ``ansible-doc -t netconf -l``. To view plugin-specific documentation and examples, use ``ansible-doc -t netconf``.
.. seealso::

2
docs/docsite/rst/porting_guides/porting_guide_2.10.rst
View file

@ -9,7 +9,7 @@ Ansible 2.10 Porting Guide
.. warning::
In preparation for the release of 2.10, many plugins and modules have migrated to Collections on `Ansible Galaxy <https://galaxy.ansible.com>`_. For the current development status of Collections and FAQ see `Ansible Collections Community Guide <https://github.com/ansible-collections/overview/blob/master/README.rst>`_. We expect the 2.10 Porting Guide to change frequently up to the 2.10 release. Follow the conversations about collections on our various :ref:`communication` channels for the latest information on the status of the ``devel`` branch.
In preparation for the release of 2.10, many plugins and modules have migrated to Collections on `Ansible Galaxy <https://galaxy.ansible.com>`_. For the current development status of Collections and FAQ see `Ansible Collections Community Guide <https://github.com/ansible-collections/overview/blob/main/README.rst>`_. We expect the 2.10 Porting Guide to change frequently up to the 2.10 release. Follow the conversations about collections on our various :ref:`communication` channels for the latest information on the status of the ``devel`` branch.
This section discusses the behavioral changes between Ansible 2.9 and Ansible 2.10.

2
docs/docsite/rst/porting_guides/porting_guide_base_2.10.rst
View file

@ -7,7 +7,7 @@ Ansible-base 2.10 Porting Guide
.. warning::
In preparation for the release of 2.10, many plugins and modules have migrated to Collections on `Ansible Galaxy <https://galaxy.ansible.com>`_. For the current development status of Collections and FAQ see `Ansible Collections Community Guide <https://github.com/ansible-collections/overview/blob/master/README.rst>`_. We expect the 2.10 Porting Guide to change frequently up to the 2.10 release. Follow the conversations about collections on our various :ref:`communication` channels for the latest information on the status of the ``devel`` branch.
In preparation for the release of 2.10, many plugins and modules have migrated to Collections on `Ansible Galaxy <https://galaxy.ansible.com>`_. For the current development status of Collections and FAQ see `Ansible Collections Community Guide <https://github.com/ansible-collections/overview/blob/main/README.rst>`_. We expect the 2.10 Porting Guide to change frequently up to the 2.10 release. Follow the conversations about collections on our various :ref:`communication` channels for the latest information on the status of the ``devel`` branch.
This section discusses the behavioral changes between Ansible 2.9 and Ansible-base 2.10.

2
docs/docsite/rst/roadmap/ROADMAP_2_10.rst
View file

@ -48,4 +48,4 @@ moving much of the plugins into smaller collection repositories that will be shi
The following links have more information about this process:
- https://groups.google.com/d/msg/ansible-devel/oKqgCeYTs-M/cHrOgMw8CAAJ
- https://github.com/ansible-collections/overview/blob/master/README.rst
- https://github.com/ansible-collections/overview/blob/main/README.rst

26
docs/docsite/rst/scenario_guides/guide_aws.rst
View file

@ -169,32 +169,32 @@ 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 :ref:`dynamic_inventory`.
in text files. Rather, the best way to handle this is to use the aws_ec2 inventory plugin. See :ref:`dynamic_inventory`.
This will also dynamically select nodes that were even created outside of Ansible, and allow Ansible to manage them.
See :ref:`dynamic_inventory` for how to use this, then return to this chapter.
The plugin will also return instances that were created outside of Ansible and allow Ansible to manage them.
.. _aws_tags_and_groups:
Tags And Groups And Variables
`````````````````````````````
When using the ec2 inventory script, hosts automatically appear in groups based on how they are tagged in EC2.
When using the inventory plugin, you can configure extra inventory structure based on the metadata returned by AWS.
For instance, if a host is given the "class" tag with the value of "webserver",
it will be automatically discoverable via a dynamic group like so::
For instance, you might use ``keyed_groups`` to create groups from instance tags::
plugin: aws_ec2
keyed_groups:
- prefix: tag
key: tags
You can then target all instances with a "class" tag where the value is "webserver" in a play::
- hosts: tag_class_webserver
tasks:
- ping
Using this philosophy can be a great way to keep systems separated by the function they perform.
In this example, if we wanted to define variables that are automatically applied to each machine tagged with the 'class' of 'webserver', 'group_vars'
in ansible can be used. See :ref:`splitting_out_vars`.
Similar groups are available for regions and other classifications, and can be similarly assigned variables using the same mechanism.
You can also use these groups with 'group_vars' to set variables that are automatically applied to matching instances. See :ref:`splitting_out_vars`.
.. _aws_pull:

36
docs/docsite/rst/scenario_guides/guide_kubernetes.rst
View file

@ -9,19 +9,19 @@ Requirements
To use the modules, you'll need the following:
- Run Ansible from source. For assistance, view :ref:`from_source`.
- `OpenShift Rest Client <https://github.com/openshift/openshift-restclient-python>`_ installed on the host that will execute the modules
- `OpenShift Rest Client <https://github.com/openshift/openshift-restclient-python>`_ installed on the host that will execute the modules.
Installation and use
--------------------
The individual modules, as of this writing, are not part of the Ansible repository, but they can be accessed by installing the role, `ansible.kubernetes-modules <https://galaxy.ansible.com/ansible/kubernetes-modules/>`_, and including it in a playbook.
The Kubernetes modules are part of the `Ansible Kubernetes collection <https://github.com/ansible-collections/community.kubernetes>`_.
To install, run the following:
To install the collection, run the following:
.. code-block:: bash
$ ansible-galaxy install ansible.kubernetes-modules
$ ansible-galaxy collection install community.kubernetes
Next, include it in a playbook, as follows:
@ -29,14 +29,23 @@ Next, include it in a playbook, as follows:
---
- hosts: localhost
remote_user: root
roles:
- role: ansible.kubernetes-modules
- role: hello-world
tasks:
- name: Create a pod
community.kubernetes.k8s:
state: present
definition:
apiVersion: v1
kind: Pod
metadata:
name: "utilitypod-1"
namespace: default
labels:
app: galaxy
spec:
containers:
- name: utilitypod
image: busybox
Because the role is referenced, ``hello-world`` is able to access the modules, and use them to deploy an application.
The modules are found in the ``library`` folder of the role. Each includes full documentation for parameters and the returned data structure. However, not all modules include examples, only those where `testing data <https://github.com/openshift/openshift-restclient-python/tree/release-0.8/openshift/ansiblegen/examples>`_ has been created.
Authenticating with the API
---------------------------
@ -50,6 +59,5 @@ To disable SSL certificate verification, set ``verify_ssl`` to false.
Filing issues
`````````````
If you find a bug or have a suggestion regarding individual modules or the role, please file issues at `OpenShift Rest Client issues <https://github.com/openshift/openshift-restclient-python/issues>`_.
There is also a utility module, k8s_common.py, that is part of the `Ansible <https://github.com/ansible/ansible>`_ repo. If you find a bug or have suggestions regarding it, please file issues at `Ansible issues <https://github.com/ansible/ansible/issues>`_.
If you find a bug or have a suggestion regarding modules, please file issues at `Ansible Kubernetes collection <https://github.com/ansible-collections/community.kubernetes>`_.
If you find a bug regarding OpenShift client, please file issues at `OpenShift REST Client issues <https://github.com/openshift/openshift-restclient-python/issues>`_.

2
docs/docsite/rst/user_guide/collections_using.rst
View file

@ -10,7 +10,7 @@ Collections are a distribution format for Ansible content that can include playb
You can install and use collections through `Ansible Galaxy <https://galaxy.ansible.com>`_.
* For details on how to *develop* collections see :ref:`developing_collections`.
* For the current development status of Collections and FAQ see `Ansible Collections Community Guide <https://github.com/ansible-collections/overview/blob/master/README.rst>`_.
* For the current development status of Collections and FAQ see `Ansible Collections Community Guide <https://github.com/ansible-collections/overview/blob/main/README.rst>`_.
.. contents::
:local:

158
docs/docsite/rst/user_guide/intro_dynamic_inventory.rst
View file

@ -106,164 +106,6 @@ And technically, though there is no major good reason to do it, this also works
So in other words, you can use those variables in arguments/actions as well.
.. _aws_example:
Inventory script example: AWS EC2
=================================
If you use Amazon Web Services EC2, maintaining an inventory file might not be the best approach, because hosts may come and go over time, be managed by external applications, or you might even be using AWS autoscaling. For this reason, you can use the `EC2 external inventory <https://raw.githubusercontent.com/ansible-collections/community.aws/main/scripts/inventory/ec2.py>`_ script.
You can use this script in one of two ways. The easiest is to use Ansible's ``-i`` command line option and specify the path to the script after marking it executable:
.. code-block:: bash
ansible -i ec2.py -u ubuntu us-east-1d -m ping
The second option is to copy the script to `/etc/ansible/hosts` and `chmod +x` it. You must also copy the `ec2.ini <https://raw.githubusercontent.com/ansible-collections/community.aws/main/scripts/inventory/ec2.ini>`_ file to `/etc/ansible/ec2.ini`. Then you can run ansible as you would normally.
To make a successful API call to AWS, you must configure Boto (the Python interface to AWS). You can do this in `several ways <http://docs.pythonboto.org/en/latest/boto_config_tut.html>`_ available, but the simplest is to export two environment variables:
.. code-block:: bash
export AWS_ACCESS_KEY_ID='AK123'
export AWS_SECRET_ACCESS_KEY='abc123'
You can test the script by itself to make sure your config is correct:
.. code-block:: bash
cd /etc/ansible/
wget https://raw.githubusercontent.com/ansible-collections/community.aws/main/scripts/inventory/ec2.py
./ec2.py --list
After a few moments, you should see your entire EC2 inventory across all regions in JSON.
If you use Boto profiles to manage multiple AWS accounts, you can pass ``--profile PROFILE`` name to the ``ec2.py`` script. An example profile might be:
.. code-block:: text
[profile dev]
aws_access_key_id = <dev access key>
aws_secret_access_key = <dev secret key>
[profile prod]
aws_access_key_id = <prod access key>
aws_secret_access_key = <prod secret key>
You can then run ``ec2.py --profile prod`` to get the inventory for the prod account, although this option is not supported by ``ansible-playbook``.
You can also use the ``AWS_PROFILE`` variable - for example: ``AWS_PROFILE=prod ansible-playbook -i ec2.py myplaybook.yml``
Since each region requires its own API call, if you are only using a small set of regions, you can edit the ``ec2.ini`` file and comment out the regions you are not using.
There are other config options in ``ec2.ini``, including cache control and destination variables. By default, the ``ec2.ini`` file is configured for **all Amazon cloud services**, but you can comment out any features that aren't applicable. For example, if you don't have ``RDS`` or ``elasticache``, you can set them to ``False`` :
.. code-block:: text
[ec2]
...
# To exclude RDS instances from the inventory, uncomment and set to False.
rds = False
# To exclude ElastiCache instances from the inventory, uncomment and set to False.
elasticache = False
...
At their heart, inventory files are simply a mapping from some name to a destination address. The default ``ec2.ini`` settings are configured for running Ansible from outside EC2 (from your laptop for example) -- and this is not the most efficient way to manage EC2.
If you are running Ansible from within EC2, internal DNS names and IP addresses may make more sense than public DNS names. In this case, you can modify the ``destination_variable`` in ``ec2.ini`` to be the private DNS name of an instance. This is particularly important when running Ansible within a private subnet inside a VPC, where the only way to access an instance is via its private IP address. For VPC instances, `vpc_destination_variable` in ``ec2.ini`` provides a means of using which ever `boto.ec2.instance variable <http://docs.pythonboto.org/en/latest/ref/ec2.html#module-boto.ec2.instance>`_ makes the most sense for your use case.
The EC2 external inventory provides mappings to instances from several groups:
Global
All instances are in group ``ec2``.
Instance ID
These are groups of one since instance IDs are unique.
e.g.
``i-00112233``
``i-a1b1c1d1``
Region
A group of all instances in an AWS region.
e.g.
``us-east-1``
``us-west-2``
Availability Zone
A group of all instances in an availability zone.
e.g.
``us-east-1a``
``us-east-1b``
Security Group
Instances belong to one or more security groups. A group is created for each security group, with all characters except alphanumerics, converted to underscores (_). Each group is prefixed by ``security_group_``. Currently, dashes (-) are also converted to underscores (_). You can change using the replace_dash_in_groups setting in ec2.ini (this has changed across several versions so check the ec2.ini for details).
e.g.
``security_group_default``
``security_group_webservers``
``security_group_Pete_s_Fancy_Group``
Tags
Each instance can have a variety of key/value pairs associated with it called Tags. The most common tag key is 'Name', though anything is possible. Each key/value pair is its own group of instances, again with special characters converted to underscores, in the format ``tag_KEY_VALUE``
e.g.
``tag_Name_Web`` can be used as is
``tag_Name_redis-master-001`` becomes ``tag_Name_redis_master_001``
``tag_aws_cloudformation_logical-id_WebServerGroup`` becomes ``tag_aws_cloudformation_logical_id_WebServerGroup``
When the Ansible is interacting with a specific server, the EC2 inventory script is called again with the ``--host HOST`` option. This looks up the HOST in the index cache to get the instance ID, and then makes an API call to AWS to get information about that specific instance. It then makes information about that instance available as variables to your playbooks. Each variable is prefixed by ``ec2_``. Here are some of the variables available:
- ec2_architecture
- ec2_description
- ec2_dns_name
- ec2_id
- ec2_image_id
- ec2_instance_type
- ec2_ip_address
- ec2_kernel
- ec2_key_name
- ec2_launch_time
- ec2_monitored
- ec2_ownerId
- ec2_placement
- ec2_platform
- ec2_previous_state
- ec2_private_dns_name
- ec2_private_ip_address
- ec2_public_dns_name
- ec2_ramdisk
- ec2_region
- ec2_root_device_name
- ec2_root_device_type
- ec2_security_group_ids
- ec2_security_group_names
- ec2_spot_instance_request_id
- ec2_state
- ec2_state_code
- ec2_state_reason
- ec2_status
- ec2_subnet_id
- ec2_tag_Name
- ec2_tenancy
- ec2_virtualization_type
- ec2_vpc_id
Both ``ec2_security_group_ids`` and ``ec2_security_group_names`` are comma-separated lists of all security groups. Each EC2 tag is a variable in the format ``ec2_tag_KEY``.
To see the complete list of variables available for an instance, run the script by itself:
.. code-block:: bash
cd /etc/ansible
wget https://raw.githubusercontent.com/ansible-collections/community.aws/main/scripts/inventory/ec2.py
./ec2.py --host ec2-12-12-12-12.compute-1.amazonaws.com
Note that the AWS inventory script will cache results to avoid repeated API calls, and this cache setting is configurable in ec2.ini. To
explicitly clear the cache, you can run the ec2.py script with the ``--refresh-cache`` parameter:
.. code-block:: bash
./ec2.py --refresh-cache
.. _openstack_example:
Inventory script example: OpenStack

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

@ -268,8 +268,7 @@ In YAML:
ansible_port: 5555
ansible_host: 192.0.2.50
In the above example, running Ansible against the host alias "jumper" will connect to 192.0.2.50 on port 5555.
This only works for hosts with static IPs, or when you are connecting through tunnels.
In the above example, running Ansible against the host alias "jumper" will connect to 192.0.2.50 on port 5555. See :ref:`behavioral inventory parameters <behavioral_parameters>` to further customize the connection to hosts.
.. note::
Values passed in the INI format using the ``key=value`` syntax are interpreted differently depending on where they are declared:

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

@ -258,12 +258,22 @@ Ansible only executes each role once, even if you define it multiple times, unle
- bar
- foo
You have two options to force Ansible to run a role more than once:
You have two options to force Ansible to run a role more than once.
#. Pass different parameters in each role definition.
#. Add ``allow_duplicates: true`` to the ``meta/main.yml`` file for the role.
Passing different parameters
----------------------------
Example 1 - passing different parameters:
You can pass different parameters in each role definition as:
.. code-block:: yaml
---
- hosts: webservers
roles:
- { role: foo, vars: { message: "first" } }
- { role: foo, vars: { message: "second" } }
or
.. code-block:: yaml
@ -273,11 +283,16 @@ Example 1 - passing different parameters:
- role: foo
vars:
message: "first"
- { role: foo, vars: { message: "second" } }
- role: foo
vars:
message: "second"
In this example, because each role definition has different parameters, Ansible runs ``foo`` twice.
Example 2 - using ``allow_duplicates: true``:
Using ``allow_duplicates: true``
--------------------------------
Add ``allow_duplicates: true`` to the ``meta/main.yml`` file for the role:
.. code-block:: yaml
@ -324,7 +339,7 @@ Ansible always executes role dependencies before the role that includes them. An
Running role dependencies multiple times in one playbook
--------------------------------------------------------
Ansible treats duplicate role dependencies like duplicate roles listed under ``roles:``: Ansible only executes role dependencies once, even if defined multiple times, unless the parameters defined on the role are different for each definition. If two roles in a playbook both list a third role as a dependency, Ansible only runs that role dependency once, unless you pass different parameters or use ``allow_duplicates: true`` in the dependent (third) role. See :ref:`Galaxy role dependencies <galaxy_dependencies>` for more details.
Ansible treats duplicate role dependencies like duplicate roles listed under ``roles:``: Ansible only executes role dependencies once, even if defined multiple times, unless the parameters, tags, or when clause defined on the role are different for each definition. If two roles in a playbook both list a third role as a dependency, Ansible only runs that role dependency once, unless you pass different parameters, tags, when clause, or use ``allow_duplicates: true`` in the dependent (third) role. See :ref:`Galaxy role dependencies <galaxy_dependencies>` for more details.
For example, a role named ``car`` depends on a role named ``wheel`` as follows:

14
docs/docsite/rst/user_guide/shared_snippets/with2loop.txt
View file

@ -97,6 +97,20 @@ with_together
msg: "{{ item.0 }} - {{ item.1 }}"
loop: "{{ list_one|zip(list_two)|list }}"
Another example with complex data
.. code-block:: yaml+jinja
- name: with_together -> loop
debug:
msg: "{{ item.0 }} - {{ item.1 }} - {{ item.2 }}"
loop: "{{ data[0]|zip(*data[1:])|list }}"
vars:
data:
- ['a', 'b', 'c']
- ['d', 'e', 'f']
- ['g', 'h', 'i']
with_dict
---------

78
docs/docsite/rst/user_guide/vault.rst
View file

@ -7,7 +7,7 @@ Encrypting content with Ansible Vault
Ansible Vault encrypts variables and files so you can protect sensitive content such as passwords or keys rather than leaving it visible as plaintext in playbooks or roles. To use Ansible Vault you need one or more passwords to encrypt and decrypt content. If you store your vault passwords in a third-party tool such as a secret manager, you need a script to access them. Use the passwords with the :ref:`ansible-vault` command-line tool to create and view encrypted variables, create encrypted files, encrypt existing files, or edit, re-key, or decrypt files. You can then place encrypted content under source control and share it more safely.
.. warning::
* Encryption with Ansible Vault ONLY protects 'data at rest'. Once the content is decrypted ('data in use'), play and plugin authors are responsible for avoiding any secret disclosure, see :ref:`no_log <keep_secret_data>` for details on hiding output.
* Encryption with Ansible Vault ONLY protects 'data at rest'. Once the content is decrypted ('data in use'), play and plugin authors are responsible for avoiding any secret disclosure, see :ref:`no_log <keep_secret_data>` for details on hiding output and :ref:`vault_securing_editor` for security considerations on editors you use with Ansible Vault.
You can use encrypted variables and files in ad-hoc commands and playbooks by supplying the passwords you used to encrypt them. You can modify your ``ansible.cfg`` file to specify the location of a password file or to always prompt for the password.
@ -218,7 +218,7 @@ To encrypt the string 'letmein' read from stdin, add the vault ID 'test' using t
The command above creates this output::
Reading plaintext input from stdin. (ctrl-d to end input)
Reading plaintext input from stdin. (ctrl-d to end input, twice if your content does not already have a new line)
db_password: !vault |
$ANSIBLE_VAULT;1.2;AES256;dev
61323931353866666336306139373937316366366138656131323863373866376666353364373761
@ -237,7 +237,7 @@ The command above triggers this prompt:
.. code-block:: text
Reading plaintext input from stdin. (ctrl-d to end input)
Reading plaintext input from stdin. (ctrl-d to end input, twice if your content does not already have a new line)
Type the string to encrypt (for example, 'hunter2'), hit ctrl-d, and wait.
@ -288,6 +288,11 @@ Ansible Vault can encrypt any structured data file used by Ansible, including:
The full file is encrypted in the vault.
.. note::
Ansible Vault uses an editor to create or modify encrypted files. See :ref:`vault_securing_editor` for some guidance on securing the editor.
Advantages and disadvantages of encrypting files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -396,6 +401,73 @@ If you have an encrypted file that you no longer want to keep encrypted, you can
ansible-vault decrypt foo.yml bar.yml baz.yml
.. _vault_securing_editor:
Steps to secure your editor
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Ansible Vault relies on your configured editor, which can be a source of disclosures. Most editors have ways to prevent loss of data, but these normally rely on extra plain text files that can have a clear text copy of your secrets. Consult your editor documentation to configure the editor to avoid disclosing secure data. The following sections provide some guidance on common editors but should not be taken as a complete guide to securing your editor.
vim
...
You can set the following ``vim`` options in command mode to avoid cases of disclosure. There may be more settings you need to modify to ensure security, especially when using plugins, so consult the ``vim`` documentation.
1. Disable swapfiles that act like an autosave in case of crash or interruption.
.. code-block:: text
set noswapfile
2. Disable creation of backup files.
.. code-block:: text
set nobackup
set nowritebackup
3. Disable the viminfo file from copying data from your current session.
.. code-block:: text
set viminfo=
4. Disable copying to the system clipboard.
.. code-block:: text
set clipboard=
You can optionally add these settings in ``.vimrc`` for all files, or just specific paths or extensions. See the ``vim`` manual for details.
Emacs
......
You can set the following Emacs options to avoid cases of disclosure. There may be more settings you need to modify to ensure security, especially when using plugins, so consult the Emacs documentation.
1. Do not copy data to the system clipboard.
.. code-block:: text
(setq x-select-enable-clipboard nil)
2. Disable creation of backup files.
.. code-block:: text
(setq make-backup-files nil)
3. Disable autosave files.
.. code-block:: text
(setq auto-save-default nil)
.. _playbooks_vault:
.. _providing_vault_passwords:

31
examples/ansible.cfg
View file

@ -492,3 +492,34 @@
# Set how many context lines to show in diff
#context = 3
[galaxy]
# Controls whether the display wheel is shown or not
#display_progress=
# Validate TLS certificates for Galaxy server
#ignore_certs = False
# Role or collection skeleton directory to use as a template for
# the init action in ansible-galaxy command
#role_skeleton=
# Patterns of files to ignore inside a Galaxy role or collection
# skeleton directory
#role_skeleton_ignore="^.git$", "^.*/.git_keep$"
# Galaxy Server URL
#server=https://galaxy.ansible.com
# A list of Galaxy servers to use when installing a collection.
#server_list=automation_hub, release_galaxy
# Server specific details which are mentioned in server_list
#[galaxy_server.automation_hub]
#url=https://cloud.redhat.com/api/automation-hub/
#auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
#token=my_ah_token
#
#[galaxy_server.release_galaxy]
#url=https://galaxy.ansible.com/
#token=my_token

2
lib/ansible/cli/vault.py
View file

@ -312,7 +312,7 @@ class VaultCLI(CLI):
# read from stdin
if self.encrypt_string_read_stdin:
if sys.stdout.isatty():
display.display("Reading plaintext input from stdin. (ctrl-d to end input)", stderr=True)
display.display("Reading plaintext input from stdin. (ctrl-d to end input, twice if your content does not already have a newline)", stderr=True)
stdin_text = sys.stdin.read()
if stdin_text == '':

2
lib/ansible/modules/meta.py
View file

@ -40,7 +40,7 @@ notes:
- C(clear_facts) will remove the persistent facts from M(ansible.builtin.set_fact) using C(cacheable=True),
but not the current host variable it creates for the current run.
- Looping on meta tasks is not supported.
- Skipping C(meta) tasks using tags is not supported.
- Skipping C(meta) tasks with tags is not supported before Ansible 2.11.
- This module is also supported for Windows targets.
seealso:
- module: ansible.builtin.assert

3
lib/ansible/modules/service.py
View file

@ -49,6 +49,7 @@ options:
substring to look for as would be found in the output of the I(ps)
command as a stand-in for a status result.
- If the string is found, the service will be assumed to be started.
- While using remote hosts with systemd this setting will be ignored.
type: str
version_added: "0.7"
enabled:
@ -60,11 +61,13 @@ options:
description:
- For OpenRC init scripts (e.g. Gentoo) only.
- The runlevel that this service belongs to.
- While using remote hosts with systemd this setting will be ignored.
type: str
default: default
arguments:
description:
- Additional arguments provided on the command line.
- While using remote hosts with systemd this setting will be ignored.
type: str
aliases: [ args ]
use:

14
lib/ansible/modules/uri.py
View file

@ -278,6 +278,20 @@ EXAMPLES = r'''
src: /path/to/my/file.json
remote_src: yes
- name: Create workspaces in Log analytics Azure
uri:
url: https://www.mms.microsoft.com/Embedded/Api/ConfigDataSources/LogManagementData/Save
method: POST
body_format: json
status_code: [200, 202]
return_content: true
headers:
Content-Type: application/json
x-ms-client-workspace-path: /subscriptions/{{ sub_id }}/resourcegroups/{{ res_group }}/providers/microsoft.operationalinsights/workspaces/{{ w_spaces }}
x-ms-client-platform: ibiza
x-ms-client-auth-token: "{{ token_az }}"
body:
- name: Pause play until a URL is reachable from this host
uri:
url: "http://192.0.2.1/some/test"

2
lib/ansible/plugins/doc_fragments/files.py
View file

@ -25,8 +25,6 @@ options:
number which will have unexpected results.
- As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or
C(u=rw,g=r,o=r)).
- As of Ansible 2.6, the mode may also be the special string C(preserve).
- When set to C(preserve) the file will be given the same permissions as the source file.
type: raw
owner:
description:

8
lib/ansible/plugins/inventory/constructed.py
View file

@ -53,18 +53,18 @@ EXAMPLES = r'''
- prefix: distro
key: ansible_distribution
# the following examples assume the first inventory is from contrib/inventory/ec2.py
# the following examples assume the first inventory is from the `aws_ec2` plugin
# this creates a group per ec2 architecture and assign hosts to the matching ones (arch_x86_64, arch_sparc, etc)
- prefix: arch
key: ec2_architecture
key: architecture
# this creates a group per ec2 region like "us_west_1"
- prefix: ""
separator: ""
key: ec2_region
key: placement.region
# this creates a common parent group for all ec2 availability zones
- key: ec2_placement
- key: placement.availability_zone
parent_group: all_ec2_zones
'''