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

Docs [2.10] Backportapalooza 6 (#71129)

Browse source 
* Misc typo fixes (#71089)

(cherry picked from commit 504ef607f3)

* Add some documentation for the format of meta/runtime.yml (#71035)

* Document the format of meta/runtime.yml

* Document multiple Ansible versions

Clarify difference between deprecation and tombstone fields

* add note

(cherry picked from commit a9eb8b0488)

* add note to uninstall older versions of ansible for pip (#71023)

* add note to uninstall older versions of ansible for pip

* combine with the other PR

(cherry picked from commit 72d3d44163)

* VMware: Inventory scenario guide for hostnames (#71055)

Added a scenario guide for ``hostnames`` parameter
for vmware_vm_inventory.

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

* Document string tests a bit more (#71049)

- Explain how `regex` differs from `match` and `search`.
- Document `multiline` and `ignorecase`.

Signed-off-by: Rick Elrod <rick@elrod.me>
(cherry picked from commit 701c638757)

* docs: Add a note about package requirements for fact gathering (#70796)

Fixes: #26148

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

* added note about fakeroot (#71018)

see #70895

(cherry picked from commit 11a31e99e6)

* Update documentation of httpapi's handle_httperror method for clarity (#70991)

(cherry picked from commit a0523e5b8a)

* DOCS: add 2.10 collections roadmap (#70975)

* draft of 2.10 collections roadmap

* incorporates feedback from felixfontein

* gundalow and samccann feedback, fix link

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

* updates changelog types; some updates for easier translation (#71027)

Co-authored-by: Alicia Cozine <acozine@users.noreply.github.com>
Co-authored-by: Felix Fontein <felix@fontein.de>
(cherry picked from commit 4f4436c124)

* Document common return values with examples (#71046)

* adding return value examples
* shift to console code blocks
* cleaning up whitespace and shortening invocation example
* reordering diff section

(cherry picked from commit 864573a38d)

* Update intro_getting_started.rst (#71039)

Added two additional learning resources in the See also: section- forgot closing backticks

(cherry picked from commit 9850915bd6)

* Guide users to use ansible-runner (#71063)

Update the docs to guide users to use `ansible-runner` instead of using Python API directly. In many use cases, executing Ansible playbooks are sufficient. In those use cases, `ansible-runner` is easier and much stable to use comparing with Python API, but there is no mention of it.

(cherry picked from commit 0c855dc70b)

* Porting guides for ansible-base 2.10 and ansible 2.10 (#70891)

* Fix changelog link title.

* Rename Ansible 2.10 and 2.11 porting guides to Ansible-base porting guides.

* Add stub for automatically generated 2.10 porting guide.

* Move things that should not be in the ansible-base porting guide to the ansible porting guide.

* Apply changes to base porting guides.

* Add remark that ansible-base is mainly for developers.

* Ansible Base -> Ansible-base

* Fix link in base porting guide.

* Add generated porting guide.

* Use same header signs as antsibull-changelog's RST builder.

* Update generated porting guide.

(cherry picked from commit 61b36c6f30)

* Update network platform guides with FQCN (#70699)

* fqcn all the docs things!

(cherry picked from commit 54bee7152b)

* Document how to upgrade to ansible with pip (#70768)

Fixes #70348

(cherry picked from commit 5019335660)

* document how to migrate between collections (#70243)

* document how to migrate between collections
* Apply suggestions from code review

Co-authored-by: John R Barker <john@johnrbarker.com>
Co-authored-by: Felix Fontein <felix@fontein.de>
(cherry picked from commit 58145dff9c)

* remove github link from plugins (#70951)

(cherry picked from commit e28b20d729)

* Add latest rc from ansible-base (#70974)

* Add latest rc from ansible-base

(cherry picked from commit d62dffafb3)

* Document to_json will convert to ASCII strings by default (#70954)

... as reported in issue #68702

(cherry picked from commit 8c48366f1c)

* Update the porting guide for ansible-2.10.0a8 (#71141)

(cherry picked from commit 0a9638ce4b)

Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com>
Co-authored-by: Sloane Hertel <shertel@redhat.com>
Co-authored-by: Rick Elrod <rick@elrod.me>
Co-authored-by: Brian Coca <bcoca@users.noreply.github.com>
Co-authored-by: Nathaniel Case <ncase@redhat.com>
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
Co-authored-by: Terciero <terciero@users.noreply.github.com>
Co-authored-by: Brendon O'Sullivan <49501251+bjosullivan@users.noreply.github.com>
Co-authored-by: EthanHur <ethan0311@gmail.com>
Co-authored-by: Felix Fontein <felix@fontein.de>
Co-authored-by: Baptiste Mille-Mathias <baptiste.millemathias@gmail.com>
Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
This commit is contained in:
Sandra McCann 2020-08-07 17:04:19 -04:00 committed by GitHub
parent 4b03d898f3
commit b9a406f890
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
42 changed files with 1050 additions and 303 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
docs/docsite/_themes/sphinx_rtd_theme/breadcrumbs.html
View file

@ -44,10 +44,14 @@
<a href="{{ meta['github_url'] }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
{% else %}
<!-- Ansible-specific additions for modules etc -->
{% if pagename.endswith('_module') %}
<a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/{{ theme_vcs_pageview_mode|default("blob") }}/{{ github_module_version }}{{ meta.get('source', '') }}?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
{% elif pagename.startswith('plugins') and meta.get('source', None) %}
<a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/{{ theme_vcs_pageview_mode|default("blob") }}/{{ github_root_dir }}/{{ pagename }}.py?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
{% if (pagename.endswith('_module')) or (pagename.endswith('_become'))
or (pagename.endswith('_cache')) or (pagename.endswith('_callback'))
or (pagename.endswith('_connection')) or (pagename.endswith('_inventory'))
or (pagename.endswith('_lookup')) or (pagename.endswith('_shell'))
or (pagename.endswith('_strategy')) or (pagename.endswith('_vars'))
%}
<!-- <a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/{{ theme_vcs_pageview_mode|default("blob") }}/{{ github_module_version }}{{ meta.get('source', '') }}?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr" class="fa fa-github"> {{ _('Edit on GitHub') }}</a> -->
<br>
{% elif pagename.startswith('cli') and meta.get('source', None) %}
<a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/{{ theme_vcs_pageview_mode|default("blob") }}/{{ github_cli_version }}{{ meta.get('source', '') }}?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
{% elif (not 'list_of' in pagename) and (not 'category' in pagename) %}

45
docs/docsite/rst/community/development_process.rst
View file

@ -43,7 +43,7 @@ Here's an overview of the PR lifecycle:
Automated PR review: ansibullbot
--------------------------------
Because Ansible receives many pull requests, and because we love automating things, we've automated several steps of the process of reviewing and merging pull requests with a tool called Ansibullbot, or Ansibot for short.
Because Ansible receives many pull requests, and because we love automating things, we have automated several steps of the process of reviewing and merging pull requests with a tool called Ansibullbot, or Ansibot for short.
`Ansibullbot <https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md>`_ serves many functions:
@ -139,11 +139,7 @@ We don't merge every PR. Here are some tips for making your PR useful, attractiv
Changelogs
----------
Changelogs help users and developers keep up with changes to Ansible.
Ansible builds a changelog for each release from fragments.
You **must** add a changelog fragment to any PR that changes functionality or fixes a bug in ansible-base.
You don't have to add a changelog fragment for PRs that add new
modules and plugins, because our tooling does that for you automatically.
Changelogs help users and developers keep up with changes to Ansible. Ansible builds a changelog for each release from fragments. You **must** add a changelog fragment to any PR that changes functionality or fixes a bug in ansible-base. You do not have to add a changelog fragment for PRs that add new modules and plugins, because our tooling does that for you automatically.
We build short summary changelogs for minor releases as well as for major releases. If you backport a bugfix, include a changelog fragment with the backport PR.
@ -152,35 +148,29 @@ We build short summary changelogs for minor releases as well as for major releas
Creating a changelog fragment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A basic changelog fragment is a ``.yaml`` file placed in the
``changelogs/fragments/`` directory. Each file contains a yaml dict with
keys like ``bugfixes`` or ``major_changes`` followed by a list of
changelog entries of bugfixes or features. Each changelog entry is
rst embedded inside of the yaml file which means that certain
constructs would need to be escaped so they can be interpreted by rst
and not by yaml (or escaped for both yaml and rst if that's your
desire). Each PR **must** use a new fragment file rather than adding to
an existing one, so we can trace the change back to the PR that introduced it.
A basic changelog fragment is a ``.yaml`` file placed in the ``changelogs/fragments/`` directory. Each file contains a yaml dict with keys like ``bugfixes`` or ``major_changes`` followed by a list of changelog entries of bugfixes or features. Each changelog entry is rst embedded inside of the yaml file which means that certain constructs would need to be escaped so they can be interpreted by rst and not by yaml (or escaped for both yaml and rst if you prefer). Each PR **must** use a new fragment file rather than adding to an existing one, so we can trace the change back to the PR that introduced it.
To create a changelog entry, create a new file with a unique name in the ``changelogs/fragments/`` directory of corresponding repository.
The file name should include the PR number and a description of the change.
It must end with the file extension ``.yaml``. For example: ``40696-user-backup-shadow-file.yaml``
To create a changelog entry, create a new file with a unique name in the ``changelogs/fragments/`` directory of the corresponding repository. The file name should include the PR number and a description of the change. It must end with the file extension ``.yaml``. For example: ``40696-user-backup-shadow-file.yaml``
A single changelog fragment may contain multiple sections but most will only contain one section.
The toplevel keys (bugfixes, major_changes, and so on) are defined in the
`config file <https://github.com/ansible/ansible/blob/devel/changelogs/config.yaml>`_ for our release note tool. Here are the valid sections and a description of each:
A single changelog fragment may contain multiple sections but most will only contain one section. The toplevel keys (bugfixes, major_changes, and so on) are defined in the `config file <https://github.com/ansible/ansible/blob/devel/changelogs/config.yaml>`_ for our `release note tool <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst>`_. Here are the valid sections and a description of each:
**breaking_changes**
Changes that break existing playbooks or roles. This includes any change to existing behavior that forces users to update tasks. Displayed in both the changelogs and the :ref:`Porting Guides <porting_guides>`.
**major_changes**
Major changes to Ansible itself. Generally does not include module or plugin changes.
Major changes to Ansible itself. Generally does not include module or plugin changes. Displayed in both the changelogs and the :ref:`Porting Guides <porting_guides>`.
**minor_changes**
Minor changes to Ansible, modules, or plugins. This includes new features, new parameters added to modules, or behavior changes to existing parameters.
**deprecated_features**
Features that have been deprecated and are scheduled for removal in a future release.
Features that have been deprecated and are scheduled for removal in a future release. Displayed in both the changelogs and the :ref:`Porting Guides <porting_guides>`.
**removed_features**
Features that were previously deprecated and are now removed.
Features that were previously deprecated and are now removed. Displayed in both the changelogs and the :ref:`Porting Guides <porting_guides>`.
**security_fixes**
Fixes that address CVEs or resolve security concerns. Include links to CVE information.
**bugfixes**
Fixes that resolve issues.
@ -188,8 +178,7 @@ The toplevel keys (bugfixes, major_changes, and so on) are defined in the
**known_issues**
Known issues that are currently not fixed or will not be fixed.
Each changelog entry must contain a link to its issue between parentheses at the end.
If there is no corresponding issue, the entry must contain a link to the PR itself.
Each changelog entry must contain a link to its issue between parentheses at the end. If there is no corresponding issue, the entry must contain a link to the PR itself.
Most changelog entries will be ``bugfixes`` or ``minor_changes``. When writing a changelog entry that pertains to a particular module, start the entry with ``- [module name] -`` and the following sentence with a lowercase letter.
@ -222,9 +211,7 @@ Once you've written the changelog fragment for your PR, commit the file and incl
Backporting merged PRs
======================
All Ansible PRs must be merged to the ``devel`` branch first.
After a pull request has been accepted and merged to the ``devel`` branch, the following instructions will help you create a
pull request to backport the change to a previous stable branch.
All Ansible PRs must be merged to the ``devel`` branch first. After a pull request has been accepted and merged to the ``devel`` branch, the following instructions will help you create a pull request to backport the change to a previous stable branch.
We do **not** backport features.

2
docs/docsite/rst/dev_guide/developing_api.rst
View file

@ -6,7 +6,7 @@ Python API
.. contents:: Topics
.. note:: This API is intended for internal Ansible use. Ansible may make changes to this API at any time that could break backward compatibility with older versions of the API. Because of this, external use is not supported by Ansible.
.. note:: This API is intended for internal Ansible use. Ansible may make changes to this API at any time that could break backward compatibility with older versions of the API. Because of this, external use is not supported by Ansible. If you want to use Python API only for executing playbooks or modules, consider `ansible-runner <https://ansible-runner.readthedocs.io/en/latest/>`_ first.
There are several ways to use Ansible from an API perspective. You can use
the Ansible Python API to control nodes, you can extend Ansible to respond to various Python events, you can

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

@ -25,6 +25,8 @@ Collections follow a simple data structure. None of the directories are required
collection/
├── docs/
├── galaxy.yml
├── meta/
│ └── runtime.yml
├── plugins/
│ ├── modules/
│ │ └── module1.py
@ -194,6 +196,64 @@ command completion, or environment variables are presented throughout the
Ansible Collection Testing because the act of installing the stable release of
Ansible containing `ansible-test` is expected to setup those things for you.
.. _meta_runtime_yml:
meta directory
--------------
A collection can store some additional metadata in a ``runtime.yml`` file in the collection's ``meta`` directory. The ``runtime.yml`` file supports the top level keys:
- *requires_ansible*:
The version of Ansible required to use the collection. Multiple versions can be separated with a comma.
.. code:: yaml
requires_ansible: ">=2.10,<2.11"
.. note:: although the version is a `PEP440 Version Specifier <https://www.python.org/dev/peps/pep-0440/#version-specifiers>`_ under the hood, Ansible deviates from PEP440 behavior by truncating prerelease segments from the Ansible version. This means that Ansible 2.11.0b1 is compatible with something that ``requires_ansible: ">=2.11"``.
- *plugin_routing*:
Content in a collection that Ansible needs to load from another location or that has been deprecated/removed.
The top level keys of ``plugin_routing`` are types of plugins, with individual plugin names as subkeys.
To define a new location for a plugin, set the ``redirect`` field to another name.
To deprecate a plugin, use the ``deprecation`` field to provide a custom warning message and the removal date or version. If the plugin has been renamed or moved to a new location, the ``redirect`` field should also be provided. If a plugin is being removed entirely, ``tombstone`` can be used for the fatal error message and removal date or version.
.. code:: yaml
plugin_routing:
inventory:
kubevirt:
redirect: community.general.kubevirt
my_inventory:
tombstone:
removal_version: "2.0.0"
warning_text: my_inventory has been removed. Please use other_inventory instead.
modules:
my_module:
deprecation:
removal_date: "2021-11-30"
warning_text: my_module will be removed in a future release of this collection. Use another.collection.new_module instead.
redirect: another.collection.new_module
podman_image:
redirect: containers.podman.podman_image
module_utils:
ec2:
redirect: amazon.aws.ec2
util_dir.subdir.my_util:
redirect: namespace.name.my_util
- *import_redirection*
A mapping of names for Python import statements and their redirected locations.
.. code:: yaml
import_redirection:
ansible.module_utils.old_utility:
redirect: ansible_collections.collection_name.plugins.module_utils.new_location
.. _creating_collections_skeleton:
@ -469,16 +529,63 @@ Collection versions use `Semantic Versioning <https://semver.org/>`_ for version
.. _migrate_to_collection:
Migrating Ansible content to a collection
=========================================
Migrating Ansible content to a different collection
====================================================
To migrate content from one collection to another, you need to create three PRs as follows:
#. Create a PR against the old collection to remove the content.
#. Create a PR against the new collection to add the files removed in step 1.
#. Update the ``ansible/ansible:devel`` branch entries for all files moved.
Removing the content from the old collection
----------------------------------------------
Create a PR against the old collection repo to remove the modules, module_utils, plugins, and docs_fragments related to this migration:
#. If you are removing an action plugin, remove the corresponding module that contains the documentation.
#. If you are removing a module, remove any corresponding action plugin that should stay with it.
#. Remove any entries about removed plugins from ``meta/runtime.yml``. Ensure they are added into the new repo.
#. Remove sanity ignore lines from ``tests/sanity/ignore\*.txt``
#. Remove associated integration tests from ``tests/integrations/targets/`` and unit tests from ``tests/units/plugins/``.
#. if you are removing from content from ``community.general`` or ``community.network``, remove entries from ``.github/BOTMETA.yml``.
#. Carefully review ``meta/runtime.yml`` for any entries you may need to remove or update, in particular deprecated entries.
#. Update ``meta/runtime.yml`` to contain redirects for EVERY PLUGIN, pointing to the new collection name.
#. If possible, do not yet add deprecation warnings to the new ``meta/runtime.yml`` entries, but only for a later major release. So the order should be:
1. Remove content, add redirects in 3.0.0;
2. Deprecate redirects in 4.0.0;
3. Set removal version to 5.0.0 or later.
You can experiment with migrating existing modules into a collection using the `content_collector tool <https://github.com/ansible/content_collector>`_. The ``content_collector`` is a playbook that helps you migrate content from an Ansible distribution into a collection.
.. warning::
This tool is in active development and is provided only for experimentation and feedback at this point.
Maintainers for the old collection have to make sure that the PR is merged in a way that it does not break user experience and semantic versioning:
See the `content_collector README <https://github.com/ansible/content_collector>`_ for full details and usage guidelines.
#. A new version containing the merged PR must not be released before the collection the content has been moved to has been released again, with that content contained in it. Otherwise the redirects cannot work and users relying on that content will experience breakage.
#. Once 1.0.0 of the collection from which the content has been removed has been released, such PRs can only be merged for a new **major** version (i.e. 2.0.0, 3.0.0, etc.).
Adding the content to the new collection
-----------------------------------------
Create a PR in the new collection to:
#. Add ALL the files removed in first PR (from the old collection).
#. If it is an action plugin, include the corresponding module with documentation.
#. If it is a module, check if it has a corresponding action plugin that should move with it.
#. Check ``meta/ `` for relevant updates to ``action_groups.yml`` and ``runtime.yml`` if they exist.
#. Carefully check the moved ``tests/integration`` and ``tests/units`` and update for FQCN.
#. Review ``tests/sanity/ignore-\*.txt`` entries.
#. Update ``meta/runtime.yml``.
Updating ``ansible/ansible:devel`` branch entries for all files moved
----------------------------------------------------------------------
Create a third PR on ``ansible/ansible`` repository to:
#. Update ``lib/ansible/config/ansible_builtin_runtime.yml`` (the redirect entry).
#. Update ``.github/BOTMETA.yml`` (the migrated_to entry)
BOTMETA.yml
-----------
@ -486,7 +593,6 @@ BOTMETA.yml
The `BOTMETA.yml <https://github.com/ansible/ansible/blob/devel/.github/BOTMETA.yml>`_ in the ansible/ansible GitHub repository is the source of truth for:
* ansibullbot
* the docs build for collections-based modules
Ansibulbot will know how to redirect existing issues and PRs to the new repo.
The build process for docs.ansible.com will know where to find the module docs.

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

@ -232,6 +232,10 @@ The preferred way to install Ansible on a Mac is with ``pip``.
The instructions can be found in :ref:`from_pip`. If you are running macOS version 10.12 or older, then you should upgrade to the latest ``pip`` to connect to the Python Package Index securely. It should be noted that pip must be run as a module on macOS, and the linked ``pip`` instructions will show you how to do that.
.. note::
If you have Ansible 2.9 or older installed, you need to use ``pip uninstall ansible`` first to remove older versions of Ansible before re-installing it.
If you are installing on macOS Mavericks (10.9), you may encounter some noise from your compiler. A workaround is to do the following::
$ CFLAGS=-Qunused-arguments CPPFLAGS=-Qunused-arguments pip install --user ansible
@ -301,6 +305,10 @@ Ansible can be installed with ``pip``, the Python package manager. If ``pip`` is
$ curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
$ python get-pip.py --user
.. note::
If you have Ansible 2.9 or older installed, you need to use ``pip uninstall ansible`` first to remove older versions of Ansible before re-installing it.
Then install Ansible [1]_::
$ python -m pip install --user ansible
@ -324,6 +332,33 @@ If you wish to install Ansible globally, run the following commands::
Please make sure you have the latest version of ``pip`` before installing Ansible.
If you have an older version of ``pip`` installed, you can upgrade by following `pip's upgrade instructions <https://pip.pypa.io/en/stable/installing/#upgrading-pip>`_ .
Upgrading Ansible from version 2.9 and older to version 2.10 or later
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Starting in version 2.10, Ansible is made of two packages. You need to first uninstall the old Ansible version (2.9 or earlier) before upgrading.
If you do not uninstall the older version of Ansible, you will see the following message, and no change will be performed:
.. code-block:: console
Cannot install ansible-base with a pre-existing ansible==2.x installation.
Installing ansible-base with ansible-2.9 or older currently installed with
pip is known to cause problems. Please uninstall ansible and install the new
version:
pip uninstall ansible
pip install ansible-base
...
As explained by the message, to upgrade you must first remove the version of Ansible installed and then install it
to the latest version.
.. code-block:: console
$ pip uninstall ansible
$ pip install ansible
.. _from_pip_devel:
Installing the development version of Ansible
@ -333,6 +368,10 @@ Installing the development version of Ansible
You should only run Ansible from ``devel`` if you are modifying the Ansible engine, or trying out features under development. This is a rapidly changing source of code and can become unstable at any point.
.. note::
If you have Ansible 2.9 or older installed, you need to use ``pip uninstall ansible`` first to remove older versions of Ansible before re-installing it.
The development version of Ansible can be directly installed from GitHub with pip::
$ python -m pip install --user https://github.com/ansible/ansible/archive/devel.tar.gz
@ -348,6 +387,10 @@ See :ref:`from_source` for instructions on how to run Ansible directly from sour
Virtual Environments
^^^^^^^^^^^^^^^^^^^^
.. note::
If you have Ansible 2.9 or older installed, you need to use ``pip uninstall ansible`` first to remove older versions of Ansible before re-installing it.
Ansible can also be installed inside a new or existing ``virtualenv``::
$ python -m virtualenv ansible # Create a virtualenv if one does not already exist

4
docs/docsite/rst/network/dev_guide/developing_plugins_network.rst
View file

@ -113,7 +113,9 @@ The ``handle_httperror(self, exception)`` method can deal with status codes retu
* A value of ``true`` means that the request can be retried. This my be used to indicate a transient error, or one that has been resolved. For example, the default implementation will try to call ``login()`` when presented with a 401, and return ``true`` if successful.
* A value of ``false`` means that the plugin is unable to recover from this response. The status code will be returned to the calling module as an exception. Any other value will be taken as a nonfatal response from the request. This may be useful if the server returns error messages in the body of the response. Returning the original exception is usually sufficient in this case, as HTTPError objects have the same interface as a successful response.
* A value of ``false`` means that the plugin is unable to recover from this response. The status code will be raised as an exception to the calling module.
* Any other value will be taken as a nonfatal response from the request. This may be useful if the server returns error messages in the body of the response. Returning the original exception is usually sufficient in this case, as HTTPError objects have the same interface as a successful response.
For example httpapi plugins, see the `source code for the httpapi plugins <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/httpapi>`_ included with Ansible Core.

188
docs/docsite/rst/network/user_guide/platform_ce.rst
View file

@ -4,11 +4,12 @@
CloudEngine OS Platform Options
***************************************
CloudEngine CE OS supports multiple connections. This page offers details on how each connection works in Ansible and how to use it.
CloudEngine CE OS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and supports multiple connections. This page offers details on how each connection works in Ansible and how to use it.
.. contents:: Topics
.. contents::
:local:
Connections Available
Connections available
================================================================================
.. table::
@ -27,7 +28,8 @@ Connections Available
Indirect Access via a bastion (jump host) via a bastion (jump host)
Connection Settings ``ansible_connection: network_cli`` ``ansible_connection: netconf``
Connection Settings ``ansible_connection:`` ``ansible_connection:``
``ansible.netcommon.network_cli`` ``ansible.netcommon.netconf``
|enable_mode| not supported by ce OS not supported by ce OS
@ -36,7 +38,7 @@ Connections Available
.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation)
For legacy playbooks, Ansible still supports ``ansible_connection=local`` on all CloudEngine modules. We recommend modernizing to use ``ansible_connection=netconf`` or ``ansible_connection=network_cli`` as soon as possible.
The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.netconf`` or ``ansible_connection=ansible.netcommon.network_cli`` instead.
Using CLI in Ansible
====================
@ -47,8 +49,8 @@ Example CLI inventory ``[ce:vars]``
.. code-block:: yaml
[ce:vars]
ansible_connection=network_cli
ansible_network_os=ce
ansible_connection=ansible.netcommon.network_cli
ansible_network_os=community.network.ce
ansible_user=myuser
ansible_password=!vault...
ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"'
@ -58,15 +60,15 @@ Example CLI inventory ``[ce:vars]``
- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration.
- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.
Example CLI Task
Example CLI task
----------------
.. code-block:: yaml
- name: Retrieve CE OS version
ce_command:
community.network.ce_command:
commands: display version
when: ansible_network_os == 'ce'
when: ansible_network_os == 'community.network.ce'
Using NETCONF in Ansible
@ -80,16 +82,16 @@ Before you can use NETCONF to connect to a switch, you must:
- install the ``ncclient`` python package on your control node(s) with ``pip install ncclient``
- enable NETCONF on the CloudEngine OS device(s)
To enable NETCONF on a new switch via Ansible, use the ``ce_config`` module via the CLI connection. Set up your platform-level variables just like in the CLI example above, then run a playbook task like this:
To enable NETCONF on a new switch using Ansible, use the ``community.network.ce_config`` module with the CLI connection. Set up your platform-level variables just like in the CLI example above, then run a playbook task like this:
.. code-block:: yaml
- name: Enable NETCONF
connection: network_cli
ce_config:
connection: ansible.netcommon.network_cli
community.network.ce_config:
lines:
- snetconf server enable
when: ansible_network_os == 'ce'
when: ansible_network_os == 'community.network.ce'
Once NETCONF is enabled, change your variables to use the NETCONF connection.
@ -99,110 +101,110 @@ Example NETCONF inventory ``[ce:vars]``
.. code-block:: yaml
[ce:vars]
ansible_connection=netconf
ansible_network_os=ce
ansible_connection=ansible.netcommon.netconf
ansible_network_os=community.network.ce
ansible_user=myuser
ansible_password=!vault |
ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"'
Example NETCONF Task
Example NETCONF task
--------------------
.. code-block:: yaml
- name: Create a vlan, id is 50(ce)
ce_vlan:
community.network.ce_vlan:
vlan_id: 50
name: WEB
when: ansible_network_os == 'ce'
when: ansible_network_os == 'community.network.ce'
Notes
========================
Modules work with connection C(network_cli)
--------------------------------------------
Modules that work with ``ansible.netcommon.network_cli``
---------------------------------------------------------
.. code-block:: yaml
ce_acl_interface
ce_command
ce_config
ce_evpn_bgp
ce_evpn_bgp_rr
ce_evpn_global
ce_facts
ce_mlag_interface
ce_mtu
ce_netstream_aging
ce_netstream_export
ce_netstream_global
ce_netstream_template
ce_ntp_auth
ce_rollback
ce_snmp_contact
ce_snmp_location
ce_snmp_traps
ce_startup
ce_stp
ce_vxlan_arp
ce_vxlan_gateway
ce_vxlan_global
community.network.ce_acl_interface
community.network.ce_command
community.network.ce_config
community.network.ce_evpn_bgp
community.network.ce_evpn_bgp_rr
community.network.ce_evpn_global
community.network.ce_facts
community.network.ce_mlag_interface
community.network.ce_mtu
community.network.ce_netstream_aging
community.network.ce_netstream_export
community.network.ce_netstream_global
community.network.ce_netstream_template
community.network.ce_ntp_auth
community.network.ce_rollback
community.network.ce_snmp_contact
community.network.ce_snmp_location
community.network.ce_snmp_traps
community.network.ce_startup
community.network.ce_stp
community.network.ce_vxlan_arp
community.network.ce_vxlan_gateway
community.network.ce_vxlan_global
Modules work with connection C(netconf)
--------------------------------------------
Modules that work with ``ansible.netcommon.netconf``
-----------------------------------------------------
.. code-block:: yaml
ce_aaa_server
ce_aaa_server_host
ce_acl
ce_acl_advance
ce_bfd_global
ce_bfd_session
ce_bfd_view
ce_bgp
ce_bgp_af
ce_bgp_neighbor
ce_bgp_neighbor_af
ce_dldp
ce_dldp_interface
ce_eth_trunk
ce_evpn_bd_vni
ce_file_copy
ce_info_center_debug
ce_info_center_global
ce_info_center_log
ce_info_center_trap
ce_interface
ce_interface_ospf
ce_ip_interface
ce_lacp
ce_link_status
ce_lldp
ce_lldp_interface
ce_mlag_config
ce_netconf
ce_ntp
ce_ospf
ce_ospf_vrf
ce_reboot
ce_sflow
ce_snmp_community
ce_snmp_target_host
ce_snmp_user
ce_static_route
ce_static_route_bfd
ce_switchport
ce_vlan
ce_vrf
ce_vrf_af
ce_vrf_interface
ce_vrrp
ce_vxlan_tunnel
ce_vxlan_vap
community.network.ce_aaa_server
community.network.ce_aaa_server_host
community.network.ce_acl
community.network.ce_acl_advance
community.network.ce_bfd_global
community.network.ce_bfd_session
community.network.ce_bfd_view
community.network.ce_bgp
community.network.ce_bgp_af
community.network.ce_bgp_neighbor
community.network.ce_bgp_neighbor_af
community.network.ce_dldp
community.network.ce_dldp_interface
community.network.ce_eth_trunk
community.network.ce_evpn_bd_vni
community.network.ce_file_copy
community.network.ce_info_center_debug
community.network.ce_info_center_global
community.network.ce_info_center_log
community.network.ce_info_center_trap
community.network.ce_interface
community.network.ce_interface_ospf
community.network.ce_ip_interface
community.network.ce_lacp
community.network.ce_link_status
community.network.ce_lldp
community.network.ce_lldp_interface
community.network.ce_mlag_config
community.network.ce_netconf
community.network.ce_ntp
community.network.ce_ospf
community.network.ce_ospf_vrf
community.network.ce_reboot
community.network.ce_sflow
community.network.ce_snmp_community
community.network.ce_snmp_target_host
community.network.ce_snmp_user
community.network.ce_static_route
community.network.ce_static_route_bfd
community.network.ce_switchport
community.network.ce_vlan
community.network.ce_vrf
community.network.ce_vrf_af
community.network.ce_vrf_interface
community.network.ce_vrrp
community.network.ce_vxlan_tunnel
community.network.ce_vxlan_vap
.. include:: shared_snippets/SSH_warning.txt

21
docs/docsite/rst/network/user_guide/platform_cnos.rst
View file

@ -4,11 +4,12 @@
CNOS Platform Options
***************************************
CNOS supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on CNOS in Ansible.
CNOS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on CNOS in Ansible.
.. contents:: Topics
.. contents::
:local:
Connections Available
Connections available
================================================================================
.. table::
@ -25,7 +26,7 @@ Connections Available
Indirect Access via a bastion (jump host)
Connection Settings ``ansible_connection: network_cli``
Connection Settings ``ansible_connection: ansible.netcommon.network_cli``
|enable_mode| supported: use ``ansible_become: yes``
with ``ansible_become_method: enable``
@ -36,7 +37,7 @@ Connections Available
.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation)
For legacy playbooks, CNOS still supports ``ansible_connection: local``. We recommend modernizing to use ``ansible_connection: network_cli`` as soon as possible.
The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead.
Using CLI in Ansible
================================================================================
@ -46,8 +47,8 @@ Example CLI ``group_vars/cnos.yml``
.. code-block:: yaml
ansible_connection: network_cli
ansible_network_os: cnos
ansible_connection: ansible.netcommon.network_cli
ansible_network_os: community.network.cnos
ansible_user: myuser
ansible_password: !vault...
ansible_become: yes
@ -60,15 +61,15 @@ Example CLI ``group_vars/cnos.yml``
- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration.
- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.
Example CLI Task
Example CLI task
----------------
.. code-block:: yaml
- name: Retrieve CNOS OS version
cnos_command:
community.network.cnos_command:
commands: show version
when: ansible_network_os == 'cnos'
when: ansible_network_os == 'community.network.cnos'
.. include:: shared_snippets/SSH_warning.txt

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

@ -4,11 +4,12 @@
Dell OS10 Platform Options
***************************************
OS10 supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS10 in Ansible.
The `dellemc.os10 <https://galaxy.ansible.com/dellemc_networking/os10>`_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS10 in Ansible.
.. contents:: Topics
.. contents::
:local:
Connections Available
Connections available
================================================================================
.. table::
@ -25,7 +26,7 @@ Connections Available
Indirect Access via a bastion (jump host)
Connection Settings ``ansible_connection: network_cli``
Connection Settings ``ansible_connection: ansible.netcommon.network_cli``
|enable_mode| supported: use ``ansible_become: yes``
with ``ansible_become_method: enable``
@ -36,7 +37,8 @@ Connections Available
.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation)
For legacy playbooks, OS10 still supports ``ansible_connection: local``. We recommend modernizing to use ``ansible_connection: network_cli`` as soon as possible.
The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead.
Using CLI in Ansible
================================================================================
@ -46,8 +48,8 @@ Example CLI ``group_vars/dellos10.yml``
.. code-block:: yaml
ansible_connection: network_cli
ansible_network_os: dellos10
ansible_connection: ansible.netcommon.network_cli
ansible_network_os: dellemc.os10.os10
ansible_user: myuser
ansible_password: !vault...
ansible_become: yes
@ -60,16 +62,16 @@ Example CLI ``group_vars/dellos10.yml``
- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration.
- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.
Example CLI Task
Example CLI task
----------------
.. code-block:: yaml
- name: Backup current switch config (dellos10)
dellos10_config:
dellemc.os10.os10_config:
backup: yes
register: backup_dellos10_location
when: ansible_network_os == 'dellos10'
when: ansible_network_os == 'dellemc.os10.os10'
.. include:: shared_snippets/SSH_warning.txt

21
docs/docsite/rst/network/user_guide/platform_dellos6.rst
View file

@ -4,11 +4,12 @@
Dell OS6 Platform Options
***************************************
OS6 supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS6 in Ansible.
The `dellemc.os6 <https://github.com/ansible-collections/dellemc.os6>`_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS6 in Ansible.
.. contents:: Topics
.. contents::
:local:
Connections Available
Connections available
================================================================================
.. table::
@ -25,7 +26,7 @@ Connections Available
Indirect Access via a bastion (jump host)
Connection Settings ``ansible_connection: network_cli``
Connection Settings ``ansible_connection: ansible.netcommon.network_cli``
|enable_mode| supported: use ``ansible_become: yes``
with ``ansible_become_method: enable``
@ -36,7 +37,7 @@ Connections Available
.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation)
For legacy playbooks, OS6 still supports ``ansible_connection: local``. We recommend modernizing to use ``ansible_connection: network_cli`` as soon as possible.
The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead.
Using CLI in Ansible
================================================================================
@ -46,8 +47,8 @@ Example CLI ``group_vars/dellos6.yml``
.. code-block:: yaml
ansible_connection: network_cli
ansible_network_os: dellos6
ansible_connection: ansible.netcommon.network_cli
ansible_network_os: dellemc.os6.os6
ansible_user: myuser
ansible_password: !vault...
ansible_become: yes
@ -60,16 +61,16 @@ Example CLI ``group_vars/dellos6.yml``
- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration.
- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.
Example CLI Task
Example CLI task
----------------
.. code-block:: yaml
- name: Backup current switch config (dellos6)
dellos6_config:
dellemc.os6.os6_config:
backup: yes
register: backup_dellso6_location
when: ansible_network_os == 'dellos6'
when: ansible_network_os == 'dellemc.os6.os6'
.. include:: shared_snippets/SSH_warning.txt

21
docs/docsite/rst/network/user_guide/platform_dellos9.rst
View file

@ -4,11 +4,12 @@
Dell OS9 Platform Options
***************************************
OS9 supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS9 in Ansible.
The `dellemc.os9 <https://github.com/ansible-collections/dellemc.os9>`_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS9 in Ansible.
.. contents:: Topics
.. contents::
:local:
Connections Available
Connections available
================================================================================
.. table::
@ -25,7 +26,7 @@ Connections Available
Indirect Access via a bastion (jump host)
Connection Settings ``ansible_connection: network_cli``
Connection Settings ``ansible_connection: ansible.netcommon.network_cli``
|enable_mode| supported: use ``ansible_become: yes``
with ``ansible_become_method: enable``
@ -36,7 +37,7 @@ Connections Available
.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation)
For legacy playbooks, OS9 still supports ``ansible_connection: local``. We recommend modernizing to use ``ansible_connection: network_cli`` as soon as possible.
The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead.
Using CLI in Ansible
================================================================================
@ -46,8 +47,8 @@ Example CLI ``group_vars/dellos9.yml``
.. code-block:: yaml
ansible_connection: network_cli
ansible_network_os: dellos9
ansible_connection: ansible.netcommon.network_cli
ansible_network_os: dellemc.os9.os9
ansible_user: myuser
ansible_password: !vault...
ansible_become: yes
@ -60,16 +61,16 @@ Example CLI ``group_vars/dellos9.yml``
- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration.
- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.
Example CLI Task
Example CLI task
----------------
.. code-block:: yaml
- name: Backup current switch config (dellos9)
dellos9_config:
dellemc.os9.os9_config:
backup: yes
register: backup_dellos9_location
when: ansible_network_os == 'dellos9'
when: ansible_network_os == 'dellemc.os9.os9'
.. include:: shared_snippets/SSH_warning.txt

21
docs/docsite/rst/network/user_guide/platform_enos.rst
View file

@ -4,11 +4,12 @@
ENOS Platform Options
***************************************
ENOS supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on ENOS in Ansible.
ENOS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on ENOS in Ansible.
.. contents:: Topics
.. contents::
:local:
Connections Available
Connections available
================================================================================
.. table::
@ -25,7 +26,7 @@ Connections Available
Indirect Access via a bastion (jump host)
Connection Settings ``ansible_connection: network_cli``
Connection Settings ``ansible_connection: ansible.netcommon.network_cli``
|enable_mode| supported: use ``ansible_become: yes``
with ``ansible_become_method: enable``
@ -38,7 +39,7 @@ Connections Available
+---------------------------+-----------------------------------------------+
For legacy playbooks, ENOS still supports ``ansible_connection: local``. We recommend modernizing to use ``ansible_connection: network_cli`` as soon as possible.
The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead.
Using CLI in Ansible
================================================================================
@ -48,8 +49,8 @@ Example CLI ``group_vars/enos.yml``
.. code-block:: yaml
ansible_connection: network_cli
ansible_network_os: enos
ansible_connection: ansible.netcommon.network_cli
ansible_network_os: community.network.enos
ansible_user: myuser
ansible_password: !vault...
ansible_become: yes
@ -62,15 +63,15 @@ Example CLI ``group_vars/enos.yml``
- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration.
- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.
Example CLI Task
Example CLI task
----------------
.. code-block:: yaml
- name: Retrieve ENOS OS version
enos_command:
community.network.enos_command:
commands: show version
when: ansible_network_os == 'enos'
when: ansible_network_os == 'community.network.enos'
.. include:: shared_snippets/SSH_warning.txt

21
docs/docsite/rst/network/user_guide/platform_eric_eccli.rst
View file

@ -4,11 +4,12 @@
ERIC_ECCLI Platform Options
***************************************
Extreme ERIC_ECCLI Ansible modules only supports CLI connections today. This page offers details on how to use ``network_cli`` on ERIC_ECCLI in Ansible.
Extreme ERIC_ECCLI is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and only supports CLI connections today. This page offers details on how to use ``ansible.netcommon.network_cli`` on ERIC_ECCLI in Ansible.
.. contents:: Topics
.. contents::
:local:
Connections Available
Connections available
================================================================================
.. table::
@ -25,7 +26,7 @@ Connections Available
Indirect Access via a bastion (jump host)
Connection Settings ``ansible_connection: network_cli``
Connection Settings ``ansible_connection: ansible.netcommon.network_cli``
|enable_mode| not supported by ERIC_ECCLI
@ -34,7 +35,7 @@ Connections Available
.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation)
ERIC_ECCLI does not support ``ansible_connection: local``. You must use ``ansible_connection: network_cli``.
ERIC_ECCLI does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``.
Using CLI in Ansible
====================
@ -44,8 +45,8 @@ Example CLI ``group_vars/eric_eccli.yml``
.. code-block:: yaml
ansible_connection: network_cli
ansible_network_os: eric_eccli
ansible_connection: ansible.netcommon.network_cli
ansible_network_os: community.network.eric_eccli
ansible_user: myuser
ansible_password: !vault...
ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"'
@ -55,15 +56,15 @@ Example CLI ``group_vars/eric_eccli.yml``
- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration.
- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.
Example CLI Task
Example CLI task
----------------
.. code-block:: yaml
- name: run show version on remote devices (eric_eccli)
eric_eccli_command:
community.network.eric_eccli_command:
commands: show version
when: ansible_network_os == 'eric_eccli'
when: ansible_network_os == 'community.network.eric_eccli'
.. include:: shared_snippets/SSH_warning.txt

32
docs/docsite/rst/network/user_guide/platform_exos.rst
View file

@ -4,11 +4,12 @@
EXOS Platform Options
***************************************
Extreme EXOS Ansible modules support multiple connections. This page offers details on how each connection works in Ansible and how to use it.
Extreme EXOS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and supports multiple connections. This page offers details on how each connection works in Ansible and how to use it.
.. contents:: Topics
.. contents::
:local:
Connections Available
Connections available
================================================================================
@ -26,7 +27,8 @@ Connections Available
Indirect Access via a bastion (jump host) via a web proxy
Connection Settings ``ansible_connection: network_cli`` ``ansible_connection: httpapi``
Connection Settings ``ansible_connection:`` ``ansible_connection:``
``ansible.netcommon.network_cli`` ``ansible.netcommon.httpapi``
|enable_mode| not supported by EXOS not supported by EXOS
@ -35,7 +37,7 @@ Connections Available
.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation)
EXOS does not support ``ansible_connection: local``. You must use ``ansible_connection: network_cli`` or ``ansible_connection: httpapi``
EXOS does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli`` or ``ansible_connection: ansible.netcommon.httpapi``.
Using CLI in Ansible
====================
@ -45,8 +47,8 @@ Example CLI ``group_vars/exos.yml``
.. code-block:: yaml
ansible_connection: network_cli
ansible_network_os: exos
ansible_connection: ansible.netcommon.network_cli
ansible_network_os: community.network.exos
ansible_user: myuser
ansible_password: !vault...
ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"'
@ -56,15 +58,15 @@ Example CLI ``group_vars/exos.yml``
- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration.
- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.
Example CLI Task
Example CLI task
----------------
.. code-block:: yaml
- name: Retrieve EXOS OS version
exos_command:
community.network.exos_command:
commands: show version
when: ansible_network_os == 'exos'
when: ansible_network_os == 'community.network.exos'
@ -76,8 +78,8 @@ Example EXOS-API ``group_vars/exos.yml``
.. code-block:: yaml
ansible_connection: httpapi
ansible_network_os: exos
ansible_connection: ansible.netcommon.httpapi
ansible_network_os: community.network.exos
ansible_user: myuser
ansible_password: !vault...
proxy_env:
@ -87,15 +89,15 @@ Example EXOS-API ``group_vars/exos.yml``
- If you are accessing your host through a web proxy using ``https``, change ``http_proxy`` to ``https_proxy``.
Example EXOS-API Task
Example EXOS-API task
---------------------
.. code-block:: yaml
- name: Retrieve EXOS OS version
exos_command:
community.network.exos_command:
commands: show version
when: ansible_network_os == 'exos'
when: ansible_network_os == 'community.network.exos'
In this example the ``proxy_env`` variable defined in ``group_vars`` gets passed to the ``environment`` option of the module used in the task.

19
docs/docsite/rst/network/user_guide/platform_icx.rst
View file

@ -4,11 +4,12 @@
ICX Platform Options
***************************************
ICX supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on ICX in Ansible.
ICX is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on ICX in Ansible.
.. contents:: Topics
.. contents::
:local:
Connections Available
Connections available
================================================================================
.. table::
@ -25,7 +26,7 @@ Connections Available
Indirect Access via a bastion (jump host)
Connection Settings ``ansible_connection: network_cli``
Connection Settings ``ansible_connection: ansible.netcommon.network_cli``
|enable_mode| supported: use ``ansible_become: yes`` with
``ansible_become_method: enable`` and ``ansible_become_password:``
@ -44,8 +45,8 @@ Example CLI ``group_vars/icx.yml``
.. code-block:: yaml
ansible_connection: network_cli
ansible_network_os: icx
ansible_connection: ansible.netcommon.network_cli
ansible_network_os: community.network.icx
ansible_user: myuser
ansible_password: !vault...
ansible_become: yes
@ -58,16 +59,16 @@ Example CLI ``group_vars/icx.yml``
- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration.
- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.
Example CLI Task
Example CLI task
----------------
.. code-block:: yaml
- name: Backup current switch config (icx)
icx_config:
community.network.icx_config:
backup: yes
register: backup_icx_location
when: ansible_network_os == 'icx'
when: ansible_network_os == 'community.network.icx'
.. include:: shared_snippets/SSH_warning.txt

21
docs/docsite/rst/network/user_guide/platform_ironware.rst
View file

@ -4,11 +4,12 @@
IronWare Platform Options
***************************************
IronWare supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on IronWare in Ansible.
IronWare is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on IronWare in Ansible.
.. contents:: Topics
.. contents::
:local:
Connections Available
Connections available
================================================================================
.. table::
@ -25,7 +26,7 @@ Connections Available
Indirect Access via a bastion (jump host)
Connection Settings ``ansible_connection: network_cli``
Connection Settings ``ansible_connection: ansible.netcommon.network_cli``
|enable_mode| supported: use ``ansible_become: yes``
with ``ansible_become_method: enable``
@ -37,7 +38,7 @@ Connections Available
.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation)
For legacy playbooks, IronWare still supports ``ansible_connection: local``. We recommend modernizing to use ``ansible_connection: network_cli`` as soon as possible.
The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead.
Using CLI in Ansible
====================
@ -47,8 +48,8 @@ Example CLI ``group_vars/mlx.yml``
.. code-block:: yaml
ansible_connection: network_cli
ansible_network_os: ironware
ansible_connection: ansible.netcommon.network_cli
ansible_network_os: community.network.ironware
ansible_user: myuser
ansible_password: !vault...
ansible_become: yes
@ -61,16 +62,16 @@ Example CLI ``group_vars/mlx.yml``
- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration.
- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.
Example CLI Task
Example CLI task
----------------
.. code-block:: yaml
- name: Backup current switch config (ironware)
ironware_config:
community.network.ironware_config:
backup: yes
register: backup_ironware_location
when: ansible_network_os == 'ironware'
when: ansible_network_os == 'community.network.ironware'
.. include:: shared_snippets/SSH_warning.txt

11
docs/docsite/rst/network/user_guide/platform_meraki.rst
View file

@ -4,11 +4,12 @@
Meraki Platform Options
***************************************
Meraki only support supports the ``local`` connection type at this time.
The `cisco.meraki <https://galaxy.ansible.com/cisco/meraki>`_ collection only supports the ``local`` connection type at this time.
.. contents:: Topics
.. contents::
:local:
Connections Available
Connections available
================================================================================
.. table::
@ -27,12 +28,12 @@ Connections Available
==================== ==========================================
Example Meraki Task
Example Meraki task
-------------------
.. code-block:: yaml
meraki_organization:
cisco.meraki.meraki_organization:
auth_key: abc12345
org_name: YourOrg
state: present

23
docs/docsite/rst/network/user_guide/platform_netvisor.rst
View file

@ -4,12 +4,13 @@
Pluribus NETVISOR Platform Options
**********************************
Pluribus NETVISOR Ansible modules only support CLI connections today. ``httpapi`` modules may be added in future.
This page offers details on how to use ``network_cli`` on NETVISOR in Ansible.
Pluribus NETVISOR Ansible is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future.
This page offers details on how to use ``ansible.netcommon.network_cli`` on NETVISOR in Ansible.
.. contents:: Topics
.. contents::
:local:
Connections Available
Connections available
================================================================================
.. table::
@ -26,7 +27,7 @@ Connections Available
Indirect Access via a bastion (jump host)
Connection Settings ``ansible_connection: network_cli``
Connection Settings ``ansible_connection: ansible.netcommon.network_cli``
|enable_mode| not supported by NETVISOR
@ -35,7 +36,7 @@ Connections Available
.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation)
Pluribus NETVISOR does not support ``ansible_connection: local``. You must use ``ansible_connection: network_cli``.
Pluribus NETVISOR does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``.
Using CLI in Ansible
====================
@ -45,8 +46,8 @@ Example CLI ``group_vars/netvisor.yml``
.. code-block:: yaml
ansible_connection: network_cli
ansible_network_os: netvisor
ansible_connection: ansible.netcommon.network_cli
ansible_network_os: community.netcommon.netvisor
ansible_user: myuser
ansible_password: !vault...
ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"'
@ -56,18 +57,18 @@ Example CLI ``group_vars/netvisor.yml``
- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration.
- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.
Example CLI Task
Example CLI task
----------------
.. code-block:: yaml
- name: Create access list
pn_access_list:
community.network.pn_access_list:
pn_name: "foo"
pn_scope: "local"
state: "present"
register: acc_list
when: ansible_network_os == 'netvisor'
when: ansible_network_os == 'community.network.netvisor'
.. include:: shared_snippets/SSH_warning.txt

23
docs/docsite/rst/network/user_guide/platform_nos.rst
View file

@ -4,12 +4,13 @@
NOS Platform Options
***************************************
Extreme NOS Ansible modules only support CLI connections today. ``httpapi`` modules may be added in future.
This page offers details on how to use ``network_cli`` on NOS in Ansible.
Extreme NOS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future.
This page offers details on how to use ``ansible.netcommon.network_cli`` on NOS in Ansible.
.. contents:: Topics
.. contents::
:local:
Connections Available
Connections available
================================================================================
.. table::
@ -26,7 +27,7 @@ Connections Available
Indirect Access via a bastion (jump host)
Connection Settings ``ansible_connection: network_cli``
Connection Settings ``ansible_connection: community.netcommon.network_cli``
|enable_mode| not supported by NOS
@ -35,7 +36,7 @@ Connections Available
.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation)
NOS does not support ``ansible_connection: local``. You must use ``ansible_connection: network_cli``.
NOS does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``.
Using CLI in Ansible
====================
@ -45,8 +46,8 @@ Example CLI ``group_vars/nos.yml``
.. code-block:: yaml
ansible_connection: network_cli
ansible_network_os: nos
ansible_connection: ansible.netcommon.network_cli
ansible_network_os: community.network.nos
ansible_user: myuser
ansible_password: !vault...
ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"'
@ -56,16 +57,16 @@ Example CLI ``group_vars/nos.yml``
- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration.
- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.
Example CLI Task
Example CLI task
----------------
.. code-block:: yaml
- name: Get version information (nos)
nos_command:
community.network.nos_command:
commands: "show version"
register: show_ver
when: ansible_network_os == 'nos'
when: ansible_network_os == 'community.network.nos'
.. include:: shared_snippets/SSH_warning.txt

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

@ -4,9 +4,13 @@
RouterOS Platform Options
***************************************
.. contents:: Topics
RouterOS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future.
This page offers details on how to use ``ansible.netcommon.network_cli`` on RouterOS in Ansible.
Connections Available
.. contents::
:local:
Connections available
================================================================================
.. table::
@ -23,7 +27,7 @@ Connections Available
Indirect Access via a bastion (jump host)
Connection Settings ``ansible_connection: network_cli``
Connection Settings ``ansible_connection: ansible.network.network_cli``
|enable_mode| not supported by RouterOS
@ -33,7 +37,7 @@ Connections Available
.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation)
RouterOS does not support ``ansible_connection: local``. You must use ``ansible_connection: network_cli``.
RouterOS does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``.
Using CLI in Ansible
====================
@ -43,8 +47,8 @@ Example CLI ``group_vars/routeros.yml``
.. code-block:: yaml
ansible_connection: network_cli
ansible_network_os: routeros
ansible_connection: ansible.netcommon.network_cli
ansible_network_os: community.network.routeros
ansible_user: myuser
ansible_password: !vault...
ansible_become: yes
@ -58,16 +62,16 @@ Example CLI ``group_vars/routeros.yml``
- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.
- If you are getting timeout errors you may want to add ``+cet1024w`` suffix to your username which will disable console colors, enable "dumb" mode, tell RouterOS not to try detecting terminal capabilities and set terminal width to 1024 columns. See article `Console login process <https://wiki.mikrotik.com/wiki/Manual:Console_login_process>`_ in MikroTik wiki for more information.
Example CLI Task
Example CLI task
----------------
.. code-block:: yaml
- name: Display resource statistics (routeros)
routeros_command:
community.network.routeros_command:
commands: /system resource print
register: routeros_resources
when: ansible_network_os == 'routeros'
when: ansible_network_os == 'community.network.routeros'
.. include:: shared_snippets/SSH_warning.txt

23
docs/docsite/rst/network/user_guide/platform_slxos.rst
View file

@ -4,12 +4,13 @@
SLX-OS Platform Options
***************************************
Extreme SLX-OS Ansible modules only support CLI connections today. ``httpapi`` modules may be added in future.
This page offers details on how to use ``network_cli`` on SLX-OS in Ansible.
Extreme SLX-OS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future.
This page offers details on how to use ``ansible.netcommon.network_cli`` on SLX-OS in Ansible.
.. contents:: Topics
.. contents::
:local:
Connections Available
Connections available
================================================================================
.. table::
@ -26,7 +27,7 @@ Connections Available
Indirect Access via a bastion (jump host)
Connection Settings ``ansible_connection: network_cli``
Connection Settings ``ansible_connection: ansible.netcommon.network_cli``
|enable_mode| not supported by SLX-OS
@ -36,7 +37,7 @@ Connections Available
.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation)
SLX-OS does not support ``ansible_connection: local``. You must use ``ansible_connection: network_cli``.
SLX-OS does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``.
Using CLI in Ansible
====================
@ -46,8 +47,8 @@ Example CLI ``group_vars/slxos.yml``
.. code-block:: yaml
ansible_connection: network_cli
ansible_network_os: slxos
ansible_connection: ansible.netcommon.network_cli
ansible_network_os: community.network.slxos
ansible_user: myuser
ansible_password: !vault...
ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"'
@ -57,16 +58,16 @@ Example CLI ``group_vars/slxos.yml``
- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration.
- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.
Example CLI Task
Example CLI task
----------------
.. code-block:: yaml
- name: Backup current switch config (slxos)
slxos_config:
community.network.slxos_config:
backup: yes
register: backup_slxos_location
when: ansible_network_os == 'slxos'
when: ansible_network_os == 'community.network.slxos'
.. include:: shared_snippets/SSH_warning.txt

23
docs/docsite/rst/network/user_guide/platform_voss.rst
View file

@ -4,12 +4,13 @@
VOSS Platform Options
***************************************
Extreme VOSS Ansible modules only support CLI connections today. This page offers details on how to
use ``network_cli`` on VOSS in Ansible.
Extreme VOSS is part of the `community.network <https://galaxy.ansible.com/community/network>`_ collection and only supports CLI connections today. This page offers details on how to
use ``ansible.netcommon.network_cli`` on VOSS in Ansible.
.. contents:: Topics
.. contents::
:local:
Connections Available
Connections available
================================================================================
.. table::
@ -26,7 +27,7 @@ Connections Available
Indirect Access via a bastion (jump host)
Connection Settings ``ansible_connection: network_cli``
Connection Settings ``ansible_connection: ansible.netcommon.network_cli``
|enable_mode| supported: use ``ansible_become: yes``
with ``ansible_become_method: enable``
@ -37,7 +38,7 @@ Connections Available
.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation)
VOSS does not support ``ansible_connection: local``. You must use ``ansible_connection: network_cli``.
VOSS does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``.
Using CLI in Ansible
====================
@ -47,8 +48,8 @@ Example CLI ``group_vars/voss.yml``
.. code-block:: yaml
ansible_connection: network_cli
ansible_network_os: voss
ansible_connection: ansible.netcommon.network_cli
ansible_network_os: community.network.voss
ansible_user: myuser
ansible_become: yes
ansible_become_method: enable
@ -60,15 +61,15 @@ Example CLI ``group_vars/voss.yml``
- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration.
- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.
Example CLI Task
Example CLI task
----------------
.. code-block:: yaml
- name: Retrieve VOSS info
voss_command:
community.network.voss_command:
commands: show sys-info
when: ansible_network_os == 'voss'
when: ansible_network_os == 'community.network.voss'
.. include:: shared_snippets/SSH_warning.txt

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

@ -19,7 +19,7 @@ We suggest you read this page along with the `Ansible Changelog for 2.10 <https:
Since 2.10, ansible consists of two parts:
* ansible-base, which are the ansible command line tools with a very small selection of plugins and modules, and
* a `set of collections <https://github.com/ansible-community/ansible-build-data/blob/main/2.10/acd.in>`_.
* a `set of collections <https://github.com/ansible-community/ansible-build-data/blob/main/2.10/ansible.in>`_.
The :ref:`porting_2.10_guide_base` is included in this porting guide. The complete list of porting guides can be found at :ref:`porting guides <porting_guides>`.
@ -165,6 +165,71 @@ Networking
No notable changes
Porting Guide for v2.10.0a8
===========================
Breaking Changes
----------------
community.general
~~~~~~~~~~~~~~~~~
- log_plays callback - add missing information to the logs generated by the callback plugin. This changes the log message format (https://github.com/ansible-collections/community.general/pull/442).
- pkgng - passing ``name: *`` with ``state: absent`` will no longer remove every installed package from the system. It is now a noop. (https://github.com/ansible-collections/community.general/pull/569).
- pkgng - passing ``name: *`` with ``state: latest`` or ``state: present`` will no longer install every package from the configured package repositories. Instead, ``name: *, state: latest`` will upgrade all already-installed packages, and ``name: *, state: present`` is a noop. (https://github.com/ansible-collections/community.general/pull/569).
community.vmware
~~~~~~~~~~~~~~~~
- vmware_datastore_maintenancemode - now returns ``datastore_status`` instead of Ansible internal key ``results``.
- vmware_guest_custom_attributes - does not require VM name which was a required parameter for releases prior to Ansible 2.10.
- vmware_guest_find - the ``datacenter`` option has been removed.
- vmware_host_kernel_manager - now returns ``host_kernel_status`` instead of Ansible internal key ``results``.
- vmware_host_ntp - now returns ``host_ntp_status`` instead of Ansible internal key ``results``.
- vmware_host_service_manager - now returns ``host_service_status`` instead of Ansible internal key ``results``.
- vmware_tag - now returns ``tag_status`` instead of Ansible internal key ``results``.
- vmware_vmkernel - the options ``ip_address`` and ``subnet_mask`` have been removed; use the suboptions ``ip_address`` and ``subnet_mask`` of the ``network`` option instead.
Removed Features
----------------
community.general
~~~~~~~~~~~~~~~~~
- conjur_variable lookup - has been moved to the ``cyberark.conjur`` collection. A redirection is active, which will be removed in version 2.0.0 (https://github.com/ansible-collections/community.general/pull/570).
- digital_ocean_* - all DigitalOcean modules have been moved to the ``community.digitalocean`` collection. A redirection is active, which will be removed in version 2.0.0 (https://github.com/ansible-collections/community.general/pull/622).
- infini_* - all infinidat modules have been moved to the ``infinidat.infinibox`` collection. A redirection is active, which will be removed in version 2.0.0 (https://github.com/ansible-collections/community.general/pull/607).
- logicmonitor - the module has been removed in 1.0.0 since it is unmaintained and the API used by the module has been turned off in 2017 (https://github.com/ansible-collections/community.general/issues/539, https://github.com/ansible-collections/community.general/pull/541).
- logicmonitor_facts - the module has been removed in 1.0.0 since it is unmaintained and the API used by the module has been turned off in 2017 (https://github.com/ansible-collections/community.general/issues/539, https://github.com/ansible-collections/community.general/pull/541).
- mysql_* - all MySQL modules have been moved to the ``community.mysql`` collection. A redirection is active, which will be removed in version 2.0.0 (https://github.com/ansible-collections/community.general/pull/633).
- proxysql_* - all ProxySQL modules have been moved to the ``community.proxysql`` collection. A redirection is active, which will be removed in version 2.0.0 (https://github.com/ansible-collections/community.general/pull/624).
community.network
~~~~~~~~~~~~~~~~~
- onyx - all onyx modules and plugins have been moved to the mellanox.onyx collection. Redirects have been added that will be removed in community.network 2.0.0 (https://github.com/ansible-collections/community.network/pull/83).
community.vmware
~~~~~~~~~~~~~~~~
- vmware_portgroup - removed 'inbound_policy', and 'rolling_order' deprecated options.
Deprecated Features
-------------------
community.general
~~~~~~~~~~~~~~~~~
- The ldap_attr module has been deprecated and will be removed in a later release; use ldap_attrs instead.
- xbps - the ``force`` option never had any effect. It is now deprecated, and will be removed in 3.0.0 (https://github.com/ansible-collections/community.general/pull/568).
community.vmware
~~~~~~~~~~~~~~~~
- The vmware_dns_config module has been deprecated and will be removed in a later release; use vmware_host_dns instead.
- vca - vca_fw, vca_nat, vca_app are deprecated since these modules rely on deprecated part of Pyvcloud library.
- vmware_tag_info - in a later release, the module will not return ``tag_facts`` since it does not return multiple tags with the same name and different category id. To maintain the existing behavior use ``tag_info`` which is a list of tag metadata.
Porting Guide for v2.10.0a7
===========================
@ -283,8 +348,6 @@ community.general
~~~~~~~~~~~~~~~~~
- core - remove support for ``check_invalid_arguments`` in ``UTMModule``.
- logicmonitor - the module has been removed in 1.0.0 since it is unmaintained and the API used by the module has been turned off in 2017 (https://github.com/ansible-collections/community.general/issues/539, https://github.com/ansible-collections/community.general/pull/541).
- logicmonitor_facts - the module has been removed in 1.0.0 since it is unmaintained and the API used by the module has been turned off in 2017 (https://github.com/ansible-collections/community.general/issues/539, https://github.com/ansible-collections/community.general/pull/541).
- pacman - Removed deprecated ``recurse`` option, use ``extra_args=--recursive`` instead
community.vmware
@ -326,7 +389,6 @@ community.general
- redfish_config - the ``bios_attribute_name`` and ``bios_attribute_value`` options will be removed. To maintain the existing behavior use the ``bios_attributes`` option instead.
- redfish_config and redfish_command - the behavior to select the first System, Manager, or Chassis resource to modify when multiple are present will be removed. Use the new ``resource_id`` option to specify target resource to modify.
- redfish_config, redfish_command - Behavior to modify the first System, Mananger, or Chassis resource when multiple are present is deprecated. Use the new ``resource_id`` option to specify target resource to modify.
- xbps - the ``force`` option never had any effect. It is now deprecated, and will be removed in 3.0.0 (https://github.com/ansible-collections/community.general/pull/568).
- zabbix_proxy - deprecates ``interface`` sub-options ``type`` and ``main`` when proxy type is set to passive via ``status=passive``. Make sure these suboptions are removed from your playbook as they were never supported by Zabbix in the first place.
community.vmware
@ -346,7 +408,6 @@ Breaking Changes
* Junction points are no longer reported as ``islnk``, use ``isjunction`` to properly report these files. This behaviour matches the ansible.windows.win_stat module
* Directories no longer return a ``size``, this matches the ``stat`` and ``find`` behaviour and has been removed due to the difficulties in correctly reporting the size of a directory
- cisco.nxos.nxos_igmp_interface - no longer supports the deprecated ``oif_prefix`` and ``oif_source`` options. These have been superceeded by ``oif_ps``.
- community.general.pacman - the deprecated ``recurse`` option has been removed, you should use ``extra_args=--recursive`` instead.
- community.grafana.grafana_dashboard - the parameter ``message`` is renamed to ``commit_message`` since ``message`` is used by Ansible Core engine internally.
- community.vmware.vmware_datastore_maintenancemode - now returns ``datastore_status`` instead of Ansible internal key ``results``.
- community.vmware.vmware_guest_custom_attributes - does not require VM name which was a required parameter for releases prior to Ansible 2.10.
@ -392,7 +453,6 @@ Removed Features
Deprecated Features
-------------------
- The community.general.ldap_attr module has been deprecated and will be removed in a later release; use community.general.ldap_attrs instead.
- The community.vmware.vmware_dns_config module has been deprecated and will be removed in a later release; use community.vmware.vmware_host_dns instead.
- The vyos.vyos.vyos_static_route module has been deprecated and will be removed in a later release; use vyos.vyos.vyos_static_routes instead.
- amazon.aws.cloudformation - the ``template_format`` option has been deprecated and will be removed in a later release. It has been ignored by the module since Ansible 2.3.

156
docs/docsite/rst/porting_guides/porting_guide_base_2.11.rst Normal file
View file

@ -0,0 +1,156 @@
.. _porting_2.11_guide_base:
*******************************
Ansible-base 2.11 Porting Guide
*******************************
This section discusses the behavioral changes between Ansible-base 2.10 and Ansible-base 2.11.
It is intended to assist in updating your playbooks, plugins and other parts of your Ansible infrastructure so they will work with this version of Ansible-base.
We suggest you read this page along with the `Ansible-base Changelog for 2.11 <https://github.com/ansible/ansible/blob/stable-2.11/changelogs/CHANGELOG-v2.11.rst>`_ to understand what updates you may need to make.
Ansible-base is mainly of interest for developers and users who only want to use a small, controlled subset of the available collections. Regular users should install ansible.
The complete list of porting guides can be found at :ref:`porting guides <porting_guides>`.
.. contents::
Playbook
========
* Fixed a bug on boolean keywords that made random strings return 'False', now they should return an error if they are not a proper boolean
Example: `diff: yes-` was returning `False`.
* A new fact, ``ansible_processor_nproc`` reflects the number of vcpus
available to processes (falls back to the number of vcpus available to
the scheduler).
Command Line
============
No notable changes
Deprecated
==========
* Windows Server 2008 and 2008 R2 will no longer be supported or tested in the next Ansible release, see :ref:`windows_faq_server2008`.
Modules
=======
Change to Default File Permissions
----------------------------------
To address CVE-2020-1736, the default permissions for certain files created by Ansible using ``atomic_move()`` were changed from ``0o666`` to ``0o600``. The default permissions value was only used for the temporary file before it was moved into its place or newly created files. If the file existed when the new temporary file was moved into place, Ansible would use the permissions of the existing file. If there was no existing file, Ansible would retain the default file permissions, combined with the system ``umask``, of the temporary file.
Most modules that call ``atomic_move()`` also call ``set_fs_attributes_if_different()`` or ``set_mode_if_different()``, which will set the permissions of the file to what is specified in the task.
A new warning will be displayed when all of the following conditions are true:
- The file at the final destination, not the temporary file, does not exist
- A module supports setting ``mode`` but it was not specified for the task
- The module calls ``atomic_move()`` but does not later call ``set_fs_attributes_if_different()`` or ``set_mode_if_different()`` with a ``mode`` specified
The following modules call ``atomic_move()`` but do not call ``set_fs_attributes_if_different()`` or ``set_mode_if_different()`` and do not support setting ``mode``. This means for files they create, the default permissions have changed and there is no indication:
- M(known_hosts)
- M(service)
Code Audit
~~~~~~~~~~
The code was audited for modules that use ``atomic_move()`` but **do not** later call ``set_fs_attributes_if_different()`` or ``set_mode_if_different()``. Modules that provide no means for specifying the ``mode`` will not display a warning message since there is no way for the playbook author to remove the warning. The behavior of each module with regards to the default permissions of temporary files and the permissions of newly created files is explained below.
known_hosts
^^^^^^^^^^^
The M(known_hosts) module uses ``atomic_move()`` to operate on the ``known_hosts`` file specified by the ``path`` parameter in the module. It creates a temporary file using ``tempfile.NamedTemporaryFile()`` which creates a temporary file that is readable and writable only by the creating user ID.
service
^^^^^^^
The M(service) module uses ``atomic_move()`` to operate on the default rc file, which is the first found of ``/etc/rc.conf``, ``/etc/rc.conf.local``, and ``/usr/local/etc/rc.conf``. Since these files almost always exist on the target system, they will not be created and the existing permissions of the file will be used.
**The following modules were included in Ansible <= 2.9. They have moved to collections but are documented here for completeness.**
authorized_key
^^^^^^^^^^^^^^
The M(authorized_key) module uses ``atomic_move()`` to operate on the the ``authorized_key`` file. A temporary file is created with ``tempfile.mkstemp()`` before being moved into place. The temporary file is readable and writable only by the creating user ID. The M(authorized_key) module manages the permissions of the the ``.ssh`` direcotry and ``authorized_keys`` files if ``managed_dirs`` is set to ``True``, which is the default. The module sets the ``ssh`` directory owner and group to the ``uid`` and ``gid`` of the user specified in the ``user`` parameter and directory permissions to ``700``. The module sets the ``authorized_key`` file owner and group to the ``uid`` and ``gid`` of the user specified in the ``user`` parameter and file permissions to ``600``. These values cannot be controlled by module parameters.
interfaces_file
^^^^^^^^^^^^^^^
The M(interfaces_file) module uses ``atomic_move()`` to operate on ``/etc/network/serivces`` or the ``dest`` specified by the module. A temporary file is created with ``tempfile.mkstemp()`` before being moved into place. The temporary file is readable and writable only by the creating user ID. If the file specified by ``path`` does not exist it will retain the permissions of the temporary file once moved into place.
pam_limits
^^^^^^^^^^
The M(pam_limits) module uses ``atomic_move()`` to operate on ``/etc/security/limits.conf`` or the value of ``dest``. A temporary file is created using ``tempfile.NamedTemporaryFile()``, which is only readable and writable by the creating user ID. The temporary file will inherit the permissions of the file specified by ``dest``, or it will retain the permissions that only allow the creating user ID to read and write the file.
pamd
^^^^
The M(pamd) module uses ``atomic_move()`` to operate on a file in ``/etc/pam.d``. The path and the file can be specified by setting the ``path`` and ``name`` parameters. A temporary file is created using ``tempfile.NamedTemporaryFile()``, which is only readable and writable by the creating user ID. The temporary file will inherit the permissions of the file located at ``[dest]/[name]``, or it will retain the permissions of the temporary file that only allow the creating user ID to read and write the file.
redhat_subscription
^^^^^^^^^^^^^^^^^^^
The M(redhat_subscription) module uses ``atomic_move()`` to operate on ``/etc/yum/pluginconf.d/rhnplugin.conf`` and ``/etc/yum/pluginconf.d/subscription-manager.conf``. A temporary file is created with ``tempfile.mkstemp()`` before being moved into place. The temporary file is readable and writable only by the creating user ID and the temporary file will inherit the permissions of the existing file once it is moved in to place.
selinux
^^^^^^^
The M(selinux) module uses ``atomic_move()`` to operate on ``/etc/selinux/config`` on the value specified by ``configfile``. The module will fail if ``configfile`` does not exist before any temporary data is written to disk. A temporary file is created with ``tempfile.mkstemp()`` before being moved into place. The temporary file is readable and writable only by the creating user ID. Since the file specified by ``configfile`` must exist, the temporary file will inherit the permissions of that file once it is moved in to place.
sysctl
^^^^^^
The M(sysctl) module uses ``atomic_move()`` to operate on ``/etc/sysctl.conf`` or the value specified by ``sysctl_file``. The module will fail if ``sysctl_file`` does not exist before any temporary data is written to disk. A temporary file is created with ``tempfile.mkstemp()`` before being moved into place. The temporary file is readable and writable only by the creating user ID. Since the file specified by ``sysctl_file`` must exist, the temporary file will inherit the permissions of that file once it is moved in to place.
.. warning::
Links on this page may not point to the most recent versions of modules. We will update them when we can.
Noteworthy module changes
-------------------------
* Ansible modules created with ``add_file_common_args=True`` added a number of undocumented arguments which were mostly there to ease implementing certain action plugins. The undocumented arguments ``src``, ``follow``, ``force``, ``content``, ``backup``, ``remote_src``, ``regexp``, ``delimiter``, and ``directory_mode`` are now no longer added. Modules relying on these options to be added need to specify them by themselves.
* Ansible no longer looks for Python modules in the current working directory (typically the ``remote_user``'s home directory) when an Ansible module is run. This is to fix becoming an unprivileged user on OpenBSD and to mitigate any attack vector if the current working directory is writable by a malicious user. Install any Python modules needed to run the Ansible modules on the managed node in a system-wide location or in another directory which is in the ``remote_user``'s ``$PYTHONPATH`` and readable by the ``become_user``.
Plugins
=======
Lookup plugin names case-sensitivity
------------------------------------
* Prior to Ansible ``2.10`` lookup plugin names passed in as an argument to the ``lookup()`` function were treated as case-insensitive as opposed to lookups invoked via ``with_<lookup_name>``. ``2.10`` brings consistency to ``lookup()`` and ``with_`` to be both case-sensitive.
Noteworthy plugin changes
-------------------------
* Cache plugins in collections can be used to cache data from inventory plugins. Previously, cache plugins in collections could only be used for fact caching.
* Some undocumented arguments from ``FILE_COMMON_ARGUMENTS`` have been removed; plugins using these, in particular action plugins, need to be adjusted. The undocumented arguments which were removed are ``src``, ``follow``, ``force``, ``content``, ``backup``, ``remote_src``, ``regexp``, ``delimiter``, and ``directory_mode``.
Action plugins which execute modules should use fully-qualified module names
----------------------------------------------------------------------------
* Action plugins that call modules should pass explicit, fully-qualified module names to ``_execute_module()`` whenever possible (eg, ``ansible.builtin.file`` rather than ``file``). This ensures that the task's collection search order is not consulted to resolve the module. Otherwise, a module from a collection earlier in the search path could be used when not intended.
Porting custom scripts
======================
No notable changes
Networking
==========
No notable changes

1
docs/docsite/rst/porting_guides/porting_guides.rst
View file

@ -12,6 +12,7 @@ Please note that this is not a complete list. If you believe any extra informati
:maxdepth: 1
:glob:
porting_guide_base_2.11
porting_guide_2.10
porting_guide_base_2.10
porting_guide_2.9

148
docs/docsite/rst/reference_appendices/common_return_values.rst
View file

@ -20,55 +20,201 @@ backup_file
```````````
For those modules that implement `backup=no|yes` when manipulating files, a path to the backup file created.
.. code-block:: console
"backup_file": "./foo.txt.32729.2020-07-30@06:24:19~"
changed
```````
A boolean indicating if the task had to make changes.
.. code-block:: console
"changed": true
diff
````
Information on differences between the previous and current state. Often a dictionary with entries ``before`` and ``after``, which will then be formatted by the callback plugin to a diff view.
.. code-block:: console
"diff": [
{
"after": "",
"after_header": "foo.txt (content)",
"before": "",
"before_header": "foo.txt (content)"
},
{
"after_header": "foo.txt (file attributes)",
"before_header": "foo.txt (file attributes)"
}
failed
``````
A boolean that indicates if the task was failed or not.
.. code-block:: console
"failed": false
invocation
``````````
Information on how the module was invoked.
.. code-block:: console
"invocation": {
"module_args": {
"_original_basename": "foo.txt",
"attributes": null,
"backup": true,
"checksum": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
"content": null,
"delimiter": null,
"dest": "./foo.txt",
"directory_mode": null,
"follow": false,
"force": true,
"group": null,
"local_follow": null,
"mode": "666",
"owner": null,
"regexp": null,
"remote_src": null,
"selevel": null,
"serole": null,
"setype": null,
"seuser": null,
"src": "/Users/foo/.ansible/tmp/ansible-tmp-1596115458.110205-105717464505158/source",
"unsafe_writes": null,
"validate": null
}
msg
```
A string with a generic message relayed to the user.
.. code-block:: console
"msg": "line added"
rc
``
Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, etc), this field contains 'return code' of these utilities.
.. code-block:: console
"rc": 257
results
```````
If this key exists, it indicates that a loop was present for the task and that it contains a list of the normal module 'result' per item.
.. code-block:: console
"results": [
{
"ansible_loop_var": "item",
"backup": "foo.txt.83170.2020-07-30@07:03:05~",
"changed": true,
"diff": [
{
"after": "",
"after_header": "foo.txt (content)",
"before": "",
"before_header": "foo.txt (content)"
},
{
"after_header": "foo.txt (file attributes)",
"before_header": "foo.txt (file attributes)"
}
],
"failed": false,
"invocation": {
"module_args": {
"attributes": null,
"backrefs": false,
"backup": true
}
},
"item": "foo",
"msg": "line added"
},
{
"ansible_loop_var": "item",
"backup": "foo.txt.83187.2020-07-30@07:03:05~",
"changed": true,
"diff": [
{
"after": "",
"after_header": "foo.txt (content)",
"before": "",
"before_header": "foo.txt (content)"
},
{
"after_header": "foo.txt (file attributes)",
"before_header": "foo.txt (file attributes)"
}
],
"failed": false,
"invocation": {
"module_args": {
"attributes": null,
"backrefs": false,
"backup": true
}
},
"item": "bar",
"msg": "line added"
}
]
skipped
```````
A boolean that indicates if the task was skipped or not
.. code-block:: console
"skipped": true
stderr
``````
Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, etc), this field contains the error output of these utilities.
.. code-block:: console
"stderr": "ls: foo: No such file or directory"
stderr_lines
````````````
When `stderr` is returned we also always provide this field which is a list of strings, one item per line from the original.
.. code-block:: console
"stderr_lines": [
"ls: doesntexist: No such file or directory"
]
stdout
``````
Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, etc). This field contains the normal output of these utilities.
.. code-block:: console
"stdout": "foo!"
stdout_lines
````````````
When `stdout` is returned, Ansible always provides a list of strings, each containing one item per line from the original output.
.. code-block:: console
"stdout_lines": [
"foo!"
]
.. _internal_return_values:

14
docs/docsite/rst/reference_appendices/faq.rst
View file

@ -283,6 +283,20 @@ There are a few common errors that one might run into when trying to execute Ans
zos1 ansible_shell_executable=/usr/lpp/bash/bin/bash
Running under fakeroot
----------------------
Some issues arise as ``fakeroot`` does not create a full nor POSIX compliant system by default.
It is known that it will not correctly expand the default tmp directory Ansible uses (:file:`~/.ansible/tmp`).
If you see module failures, this is likely the problem.
The simple workaround is to set ``remote_tmp`` to a path that will expand correctly (see documentation of the shell plugin you are using for specifics).
For example, in the ansible config file (or via environment variable) you can set::
remote_tmp=$HOME/.ansible/tmp
.. _use_roles:
What is the best way to make content reusable/redistributable?

39
docs/docsite/rst/roadmap/COLLECTIONS_2_10.rst Normal file
View file

@ -0,0 +1,39 @@
====================
Ansible project 2.10
====================
This release schedule includes dates for the `ansible <https://pypi.org/project/ansible/>`_ package, with a few dates for the `ansible-base <https://pypi.org/project/ansible-base/>`_ package as well. All dates are subject to change. See :ref:`base_roadmap_2_10` for the most recent updates on ansible-base.
.. contents::
:local:
Release Schedule
----------------
.. note:: Dates subject to change.
.. note:: We plan to post weekly alpha releases to the `PyPI ansible project <https://pypi.org/project/ansible/>`_ for testing.
- 2020-06-23: ansible-2.10 alpha freeze.
No net new collections will be added to the ``ansible-2.10`` package after this date.
- 2020-07-10: Ansible collections freeze date for content shuffling.
Content should be in its final collection for the ansible-2.10 series of releases. No more content should move out of the ``community.general`` or ``community.network`` collections.
- 2020-08-13: ansible-base 2.10 Release date, see :ref:`base_roadmap_2_10`.
- 2020-08-14: final ansible-2.10 alpha.
- 2020-08-18: Ansible 2.10 beta freeze.
- No new modules or major features will be added after this date. In practice this means we will freeze the semver collection versions to compatible release versions. For example, if the version of community.crypto on this date was community-crypto-1.1.0; ansible-2.10.0 could ship with community-crypto-1.1.1. It would not ship with community-crypto-1.2.0.
- 2020-09-01: ansible-2.10.0 beta1.
- 2020-09-08: ansible-2.10 final freeze/rc1.
- After this date only changes blocking a release are accepted.
- Collections will only be updated to a new version if a blocker is approved. Collection owners should discuss any blockers at a community IRC meeting (on 9-10 and 9-17) to decide whether to bump the version of the collection for a fix. See the `Community IRC meeting agenda <https://github.com/ansible/community/issues/539>`_.
** Additional release candidates to be published as needed as blockers are fixed **
- 2020-09-22: ansible-2.10 GA release date.
Ansible-2.10.x patch releases will occur roughly every three weeks if changes to collections have been made or if it is deemed necessary to force an upgrade to a later ansible-base-2.10.x. Ansible-2.10.x patch releases may contain new features but not backwards incompatibilities. In practice, this means we will include new collection versions where either the patch or the minor version number has changed but not when the major number has changed (example: Ansible-2.10 ships with community-crypto-1.1.0; ansible-2.10.1 may ship with community-crypto-1.2.0 but would not ship with community-crypto-2.0.0).
Breaking changes may be introduced in ansible-2.11.0 although we encourage collection owners to use deprecation periods that will show up in at least one Ansible release before being changed incompatibly.
The rough schedule for Ansible-2.11 and beyond (such as how many months we'll aim for between versions) is still to be discussed and likely will be made after 2.10.0 has been released.
For more information, reach out on a mailing list or an IRC channel - see :ref:`communication` for more details.

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

@ -1,3 +1,5 @@
.. _base_roadmap_2_10:
=================
Ansible-base 2.10
=================
@ -19,8 +21,10 @@ PRs must be raised well in advance of the dates below to have a chance of being
- 2020-06-16 Beta 1 **Feature freeze**
No new functionality (including modules/plugins) to any code
- 2020-07-14 Release Candidate 1
- 2020-??-?? Release Candidate 2 if needed
- 2020-07-21 Release Candidate 1 (bumped from 2020-07-14)
- 2020-07-24 Release Candidate 2
- 2020-07-25 Release Candidate 3
- 2020-07-30 Release Candidate 4
- 2020-08-13 Release
Release Manager

1
docs/docsite/rst/roadmap/index.rst
View file

@ -24,6 +24,7 @@ See :ref:`Ansible communication channels <communication>` for details on how to
:glob:
:caption: Ansible Release Roadmaps
COLLECTIONS_2_10
ROADMAP_2_10
ROADMAP_2_9
ROADMAP_2_8

1
docs/docsite/rst/scenario_guides/guide_vmware.rst
View file

@ -18,6 +18,7 @@ To get started, please select one of the following topics.
vmware_scenarios/vmware_requirements
vmware_scenarios/vmware_inventory
vmware_scenarios/vmware_inventory_vm_attributes
vmware_scenarios/vmware_inventory_hostnames
vmware_scenarios/vmware_scenarios
vmware_scenarios/vmware_troubleshooting
vmware_scenarios/vmware_external_doc_links

127
docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_hostnames.rst Normal file
View file

@ -0,0 +1,127 @@
.. _vmware_ansible_inventory_using_hostnames:
*************************************************
Using VMware dynamic inventory plugin - Hostnames
*************************************************
.. contents:: Topics
VMware dynamic inventory plugin - Customizing hostnames
=======================================================
VMware inventory plugin allows you to configure hostnames using the ``hostnames`` configuration parameter.
In this scenario guide we will see how you configure hostnames from the given VMware guest in the inventory.
Requirements
------------
To use the VMware dynamic inventory plugins, you must install `pyVmomi <https://github.com/vmware/pyvmomi>`_
on your control node (the host running Ansible).
To include tag-related information for the virtual machines in your dynamic inventory, you also need the `vSphere Automation SDK <https://code.vmware.com/web/sdk/65/vsphere-automation-python>`_, which supports REST API features such as tagging and content libraries, on your control node.
You can install the ``vSphere Automation SDK`` following `these instructions <https://github.com/vmware/vsphere-automation-sdk-python#installing-required-python-packages>`_.
.. code-block:: bash
$ pip install pyvmomi
Starting in Ansible 2.10, the VMware dynamic inventory plugin is available in the ``community.vmware`` collection included Ansible.
To install the latest ``community.vmware`` collection:
.. code-block:: bash
$ ansible-galaxy collection install community.vmware
To use this VMware dynamic inventory plugin:
1. Enable it first by specifying the following in the ``ansible.cfg`` file:
.. code-block:: ini
[inventory]
enable_plugins = community.vmware.vmware_vm_inventory
2. Create a file that ends in ``.vmware.yml`` or ``.vmware.yaml`` in your working directory.
The ``vmware_vm_inventory`` inventory plugin takes in the same authentication information as any other VMware modules does.
Here's an example of a valid inventory file with custom hostname for the given VMware guest:
.. code-block:: yaml
plugin: community.vmware.vmware_vm_inventory
strict: False
hostname: 10.65.223.31
username: administrator@vsphere.local
password: Esxi@123$%
validate_certs: False
with_tags: False
hostnames:
- config.name
Here, we have configured a custom hostname by setting the ``hostnames`` parameter to ``config.name``. This will retrieve
the ``config.name`` property from the virtual machine and populate it in the inventory.
You can check all allowed properties for the given virtual machine at :ref:`vmware_inventory_vm_attributes`.
Executing ``ansible-inventory --list -i <filename>.vmware.yml`` will create a list of the virtual machines that are ready to be configured using Ansible.
What to expect
--------------
You will notice that instead of default behavior of representing the hostname as ``config.name + _ + config.uuid``,
the inventory hosts show value as ``config.name``.
.. code-block:: yaml
{
"_meta": {
"hostvars": {
"template_001": {
"config.name": "template_001",
"guest.toolsRunningStatus": "guestToolsNotRunning",
...
"guest.toolsStatus": "toolsNotInstalled",
"name": "template_001"
},
"vm_8046": {
"config.name": "vm_8046",
"guest.toolsRunningStatus": "guestToolsNotRunning",
...
"guest.toolsStatus": "toolsNotInstalled",
"name": "vm_8046"
},
...
}
Troubleshooting
---------------
If the custom property specified in ``hostnames`` fails:
- Check if the values provided for username and password are correct.
- Make sure it is a valid property, see :ref:`vmware_inventory_vm_attributes`.
- Use ``strict: True`` to get more information about the error.
- Please make sure that you are using latest version VMware collection.
.. seealso::
`pyVmomi <https://github.com/vmware/pyvmomi>`_
The GitHub Page of pyVmomi
`pyVmomi Issue Tracker <https://github.com/vmware/pyvmomi/issues>`_
The issue tracker for the pyVmomi project
`vSphere Automation SDK GitHub Page <https://github.com/vmware/vsphere-automation-sdk-python>`_
The GitHub Page of vSphere Automation SDK for Python
`vSphere Automation SDK Issue Tracker <https://github.com/vmware/vsphere-automation-sdk-python/issues>`_
The issue tracker for vSphere Automation SDK for Python
:ref:`vmware_inventory_vm_attributes`
Using Virtual machine attributes in VMware dynamic inventory plugin
:ref:`working_with_playbooks`
An introduction to playbooks
:ref:`playbooks_vault`
Using Vault in playbooks

4
docs/docsite/rst/user_guide/intro_getting_started.rst
View file

@ -124,6 +124,10 @@ also has powerful configuration management and deployment features.
Examples of basic commands
:ref:`working_with_playbooks`
Learning Ansible's configuration management language
`Ansible Demos <https://github.com/ansible/product-demos>`_
Demonstrations of different Ansible usecases
`RHEL Labs <https://katacoda.com/rhel-labs>`_
Labs to provide further knowledge on different topics
`Mailing List <https://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups
`irc.freenode.net <http://irc.freenode.net>`_

18
docs/docsite/rst/user_guide/playbooks_filters.rst
View file

@ -240,6 +240,24 @@ for example::
- set_fact:
myvar: "{{ result.stdout | from_json }}"
Filter `to_json` and Unicode support
------------------------------------
By default `to_json` and `to_nice_json` will convert data received to ASCII, so::
{{ 'München'| to_json }}
will return::
'M\u00fcnchen'
To keep Unicode characters, pass the parameter `ensure_ascii=False` to the filter::
{{ 'München'| to_json(ensure_ascii=False) }}
'München'
.. versionadded:: 2.7
To parse multi-document YAML strings, the ``from_yaml_all`` filter is provided.

4
docs/docsite/rst/user_guide/playbooks_tests.rst
View file

@ -59,7 +59,9 @@ To match strings against a substring or a regular expression, use the ``match``,
msg: "matched pattern 4"
when: url is regex("example.com/\w+/foo")
``match`` succeeds if it finds the pattern at the beginning of the string, while ``search`` succeeds if it finds the pattern anywhere within string. By default, ``regex`` works like ``search``, but ``regex`` can be configured to perform other tests as well.
``match`` succeeds if it finds the pattern at the beginning of the string, while ``search`` succeeds if it finds the pattern anywhere within string. By default, ``regex`` works like ``search``, but ``regex`` can be configured to perform other tests as well, by passing the ``match_type`` keyword argument. In particular, ``match_type`` determines the ``re`` method that gets used to perform the search. The full list can be found in the relevant Python documentation `here <https://docs.python.org/3/library/re.html#regular-expression-objects>`_.
All of the string tests also take optional ``ignorecase`` and ``multiline`` arguments. These correspond to ``re.I`` and ``re.M`` from Python's ``re`` library, respectively.
.. _testing_vault:

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

@ -491,6 +491,15 @@ To reference the system hostname::
You can use facts in conditionals (see :ref:`playbooks_conditionals`) and also in templates. You can also use facts to create dynamic groups of hosts that match particular criteria, see the :ref:`group_by module <group_by_module>` documentation for details.
.. _fact_requirements:
Package requirements for fact gathering
---------------------------------------
On some distros, you may see missing fact values or facts set to default values because the packages that support gathering those facts are not installed by default. You can install the necessary packages on your remote hosts using the OS package manager. Known dependencies include:
* Linux Network fact gathering - Depends on the ``ip`` binary, commonly included in the ``iproute2`` package.
.. _fact_caching:
Caching facts

2
lib/ansible/executor/task_executor.py
View file

@ -514,7 +514,7 @@ class TaskExecutor:
try:
# TODO: remove play_context as this does not take delegation into account, task itself should hold values
# for connection/shell/become/terminal plugin options to finalize.
# Kept for now for backwards compatiblity and a few functions that are still exclusive to it.
# Kept for now for backwards compatibility and a few functions that are still exclusive to it.
# apply the given task's information to the connection info,
# which may override some fields already set by the play or

2
lib/ansible/plugins/connection/__init__.py
View file

@ -232,7 +232,7 @@ class ConnectionBase(AnsiblePlugin):
# NOTE: these password functions are all become specific, the name is
# confusing as it does not handle 'protocol passwords'
# DEPRECATED:
# These are kept for backwards compatiblity
# These are kept for backwards compatibility
# Use the methods provided by the become plugins instead
def check_become_success(self, b_output):
display.deprecated(

5
lib/ansible/plugins/httpapi/__init__.py
View file

@ -62,8 +62,9 @@ class HttpApiBase(AnsiblePlugin):
* True if the code has been handled in a way that the request
may be resent without changes.
* False if the error cannot be handled or recovered from by the
plugin. This will result in the HTTPError being returned to the
caller to deal with as appropriate.
plugin. This will result in the HTTPError being raised as an
exception for the caller to deal with as appropriate (most likely
by failing).
* Any other value returned is taken as a valid response from the
server without making another request. In many cases, this can just
be the original exception.

2
lib/ansible/template/__init__.py
View file

@ -179,7 +179,7 @@ def is_template(data, jinja_env):
comment = False
d2 = jinja_env.preprocess(data)
# This wraps a lot of code, but this is due to lex returing a generator
# This wraps a lot of code, but this is due to lex returning a generator
# so we may get an exception at any part of the loop
try:
for token in jinja_env.lex(d2):

2
lib/ansible/utils/vars.py
View file

@ -288,7 +288,7 @@ portable between the two. The following changes were made:
* True, False and None are reserved keywords (these are reserved keywords
on Python 3 as opposed to Python 2)
:arg ident: A text string of indentifier to check. Note: It is callers
:arg ident: A text string of identifier to check. Note: It is callers
responsibility to convert ident to text if it is not already.
Originally posted at http://stackoverflow.com/a/29586366

2
test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/ps_argspec.ps1
View file

@ -69,7 +69,7 @@ $powershell = [PowerShell]::Create()
$powershell.Runspace.SessionStateProxy.SetVariable("ErrorActionPreference", "Stop")
# Load the PowerShell module utils as the module may be using them to refer to shared module options. Currently we
# can only load the PowerShell utils due to cross platform compatiblity issues.
# can only load the PowerShell utils due to cross platform compatibility issues.
if ($manifest.Contains('ps_utils')) {
foreach ($util_info in $manifest.ps_utils.GetEnumerator()) {
$util_name = $util_info.Key