diff options
| author | Lee Garrett <lgarrett@rocketjump.eu> | 2022-12-13 16:16:06 +0100 |
|---|---|---|
| committer | Lee Garrett <lgarrett@rocketjump.eu> | 2022-12-13 16:16:06 +0100 |
| commit | 46bbbf9f8e527b7ab4329a0aa16e3d38bfbb0c13 (patch) | |
| tree | c4925ce2c3e7691925ebd7cbc4706707cdfcd86f | |
| parent | a6f601d820bf261c5f160bfcadb7ca6aa14d6ec2 (diff) | |
| download | debian-ansible-core-46bbbf9f8e527b7ab4329a0aa16e3d38bfbb0c13.zip | |
New upstream version 2.14.1
104 files changed, 1692 insertions, 1018 deletions
@@ -1,6 +1,6 @@ Metadata-Version: 2.1 Name: ansible-core -Version: 2.14.0 +Version: 2.14.1 Summary: Radically simple IT automation Home-page: https://ansible.com/ Author: Ansible, Inc. diff --git a/bin/ansible-galaxy b/bin/ansible-galaxy index acc3f120..f4148d92 100755 --- a/bin/ansible-galaxy +++ b/bin/ansible-galaxy @@ -17,7 +17,9 @@ import shutil import sys import textwrap import time +import typing as t +from dataclasses import dataclass from yaml.error import YAMLError import ansible.constants as C @@ -170,6 +172,30 @@ def validate_signature_count(value): return value +@dataclass +class RoleDistributionServer: + _api: t.Union[GalaxyAPI, None] + api_servers: list[GalaxyAPI] + + @property + def api(self): + if self._api: + return self._api + + for server in self.api_servers: + try: + if u'v1' in server.available_api_versions: + self._api = server + break + except Exception: + continue + + if not self._api: + self._api = self.api_servers[0] + + return self._api + + class GalaxyCLI(CLI): '''command to manage Ansible roles in shared repositories, the default of which is Ansible Galaxy *https://galaxy.ansible.com*.''' @@ -198,7 +224,7 @@ class GalaxyCLI(CLI): self.api_servers = [] self.galaxy = None - self._api = None + self.lazy_role_api = None super(GalaxyCLI, self).__init__(args) def init_parser(self): @@ -678,25 +704,15 @@ class GalaxyCLI(CLI): **galaxy_options )) + # checks api versions once a GalaxyRole makes an api call + # self.api can be used to evaluate the best server immediately + self.lazy_role_api = RoleDistributionServer(None, self.api_servers) + return context.CLIARGS['func']() @property def api(self): - if self._api: - return self._api - - for server in self.api_servers: - try: - if u'v1' in server.available_api_versions: - self._api = server - break - except Exception: - continue - - if not self._api: - self._api = self.api_servers[0] - - return self._api + return self.lazy_role_api.api def _get_default_collection_path(self): return C.COLLECTIONS_PATHS[0] @@ -757,7 +773,7 @@ class GalaxyCLI(CLI): display.vvv("found role %s in yaml file" % to_text(role)) if "name" not in role and "src" not in role: raise AnsibleError("Must specify name or src for role") - return [GalaxyRole(self.galaxy, self.api, **role)] + return [GalaxyRole(self.galaxy, self.lazy_role_api, **role)] else: b_include_path = to_bytes(requirement["include"], errors="surrogate_or_strict") if not os.path.isfile(b_include_path): @@ -766,7 +782,7 @@ class GalaxyCLI(CLI): with open(b_include_path, 'rb') as f_include: try: - return [GalaxyRole(self.galaxy, self.api, **r) for r in + return [GalaxyRole(self.galaxy, self.lazy_role_api, **r) for r in (RoleRequirement.role_yaml_parse(i) for i in yaml_load(f_include))] except Exception as e: raise AnsibleError("Unable to load data from include requirements file: %s %s" @@ -1182,7 +1198,7 @@ class GalaxyCLI(CLI): for role in context.CLIARGS['args']: role_info = {'path': roles_path} - gr = GalaxyRole(self.galaxy, self.api, role) + gr = GalaxyRole(self.galaxy, self.lazy_role_api, role) install_info = gr.install_info if install_info: @@ -1327,7 +1343,7 @@ class GalaxyCLI(CLI): # (and their dependencies, unless the user doesn't want us to). for rname in context.CLIARGS['args']: role = RoleRequirement.role_yaml_parse(rname.strip()) - role_requirements.append(GalaxyRole(self.galaxy, self.api, **role)) + role_requirements.append(GalaxyRole(self.galaxy, self.lazy_role_api, **role)) if not role_requirements and not collection_requirements: display.display("Skipping install, no requirements found") @@ -1438,7 +1454,7 @@ class GalaxyCLI(CLI): display.debug('Installing dep %s' % dep) dep_req = RoleRequirement() dep_info = dep_req.role_yaml_parse(dep) - dep_role = GalaxyRole(self.galaxy, self.api, **dep_info) + dep_role = GalaxyRole(self.galaxy, self.lazy_role_api, **dep_info) if '.' not in dep_role.name and '.' not in dep_role.src and dep_role.scm is None: # we know we can skip this, as it's not going to # be found on galaxy.ansible.com @@ -1522,7 +1538,7 @@ class GalaxyCLI(CLI): if role_name: # show the requested role, if it exists - gr = GalaxyRole(self.galaxy, self.api, role_name, path=os.path.join(role_path, role_name)) + gr = GalaxyRole(self.galaxy, self.lazy_role_api, role_name, path=os.path.join(role_path, role_name)) if os.path.isdir(gr.path): role_found = True display.display('# %s' % os.path.dirname(gr.path)) @@ -1541,7 +1557,7 @@ class GalaxyCLI(CLI): display.display('# %s' % role_path) path_files = os.listdir(role_path) for path_file in path_files: - gr = GalaxyRole(self.galaxy, self.api, path_file, path=path) + gr = GalaxyRole(self.galaxy, self.lazy_role_api, path_file, path=path) if gr.metadata: _display_role(gr) diff --git a/bin/ansible-pull b/bin/ansible-pull index 99da8c4f..dc8f055b 100755 --- a/bin/ansible-pull +++ b/bin/ansible-pull @@ -38,6 +38,9 @@ class PullCLI(CLI): This inverts the default *push* architecture of ansible into a *pull* architecture, which has near-limitless scaling potential. + None of the CLI tools are designed to run concurrently with themselves, + you should use an external scheduler and/or locking to ensure there are no clashing operations. + The setup playbook can be tuned to change the cron frequency, logging locations, and parameters to ansible-pull. This is useful both for extreme scale-out as well as periodic remediation. Usage of the 'fetch' module to retrieve logs from ansible-pull runs would be an diff --git a/changelogs/CHANGELOG-v2.14.rst b/changelogs/CHANGELOG-v2.14.rst index c849089b..59056fc5 100644 --- a/changelogs/CHANGELOG-v2.14.rst +++ b/changelogs/CHANGELOG-v2.14.rst @@ -5,6 +5,31 @@ ansible-core 2.14 "C'mon Everybody" Release Notes .. contents:: Topics +v2.14.1 +======= + +Release Summary +--------------- + +| Release Date: 2022-12-06 +| `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__ + + +Minor Changes +------------- + +- ansible-test - Improve consistency of executed ``pylint`` commands by making the plugins ordered. + +Bugfixes +-------- + +- Fixes leftover _valid_attrs usage. +- ansible-galaxy - make initial call to Galaxy server on-demand only when installing, getting info about, and listing roles. +- copy module will no longer move 'non files' set as src when remote_src=true. +- display - reduce risk of post-fork output deadlocks (https://github.com/ansible/ansible/pull/79522) +- jinja2_native: preserve quotes in strings (https://github.com/ansible/ansible/issues/79083) +- updated error messages to include 'acl' and not just mode changes when failing to set required permissions on remote. + v2.14.0 ======= diff --git a/changelogs/changelog.yaml b/changelogs/changelog.yaml index a687b456..e2fd0ea0 100644 --- a/changelogs/changelog.yaml +++ b/changelogs/changelog.yaml @@ -843,3 +843,45 @@ releases: - ansible-test-pylint-2.15.5.yml - v2.14.0rc2_summary.yaml release_date: '2022-10-31' + 2.14.1: + changes: + bugfixes: + - display - reduce risk of post-fork output deadlocks (https://github.com/ansible/ansible/pull/79522) + release_summary: '| Release Date: 2022-12-06 + + | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__ + + ' + codename: C'mon Everybody + fragments: + - fork_safe_stdio.yml + - v2.14.1_summary.yaml + release_date: '2022-12-06' + 2.14.1rc1: + changes: + bugfixes: + - Fixes leftover _valid_attrs usage. + - ansible-galaxy - make initial call to Galaxy server on-demand only when installing, + getting info about, and listing roles. + - copy module will no longer move 'non files' set as src when remote_src=true. + - 'jinja2_native: preserve quotes in strings (https://github.com/ansible/ansible/issues/79083)' + - updated error messages to include 'acl' and not just mode changes when failing + to set required permissions on remote. + minor_changes: + - ansible-test - Improve consistency of executed ``pylint`` commands by making + the plugins ordered. + release_summary: '| Release Date: 2022-11-28 + + | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__ + + ' + codename: C'mon Everybody + fragments: + - 79083-jinja2_native-preserve-quotes-in-strings.yml + - 79376-replace-valid-attrs-with-fattributes.yaml + - ansible-galaxy-install-delay-initial-api-call.yml + - ansible-test-pylint-command.yml + - dont_move_non_files.yml + - mention_acl.yml + - v2.14.1rc1_summary.yaml + release_date: '2022-11-28' diff --git a/docs/docsite/known_good_reqs.txt b/docs/docsite/known_good_reqs.txt new file mode 100644 index 00000000..14c968bc --- /dev/null +++ b/docs/docsite/known_good_reqs.txt @@ -0,0 +1,14 @@ +# pip packages required to build docsite +# These requirements drift from test/sanity/code-smell/docs-build.requirements.txt +# only for antsibull-docs minor (bugfix) releases. + +jinja2==3.1.2 +PyYAML==6.0 +resolvelib==0.8.1 +rstcheck==3.5.0 +sphinx == 4.2.0 +sphinx-ansible-theme==0.9.1 +sphinx-notfound-page==0.8.3 +straight.plugin==1.5.0 +antsibull-docs == 1.7.3 # Drifted from CI. currently approved version + diff --git a/docs/docsite/rst/command_guide/command_line_tools.rst b/docs/docsite/rst/command_guide/command_line_tools.rst index 56561b59..232cd259 100644 --- a/docs/docsite/rst/command_guide/command_line_tools.rst +++ b/docs/docsite/rst/command_guide/command_line_tools.rst @@ -6,6 +6,9 @@ Working with command line tools Most users are familiar with `ansible` and `ansible-playbook`, but those are not the only utilities Ansible provides. Below is a complete list of Ansible utilities. Each page contains a description of the utility and a listing of supported parameters. +.. note:: + You should not run most Ansible CLI tools in parallel against the same targets. + .. toctree:: :maxdepth: 1 diff --git a/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst b/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst index d48cb24f..f8ba7edf 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst @@ -22,9 +22,13 @@ Releasing major collection versions The new version is assumed to be ``X.0.0``. -1. If you are going to release the ``community.general`` and ``community.network`` collections, create new ``backport-X`` and ``needs_backport_to_stable_X`` labels in the corresponding repositories. Copy the styles and descriptions from the corresponding existing labels. +1. Make sure that ``galaxy.yml`` contains the correct version number ``X.0.0``. If that is not the case, create a PR to update it. This will make sanity tests fail for all deprecations that have to be removed in ``X.0.0``, so this is potentially a lot of work and should have been done weeks before the major release. -2. Ensure you are in a default branch in your local fork. These examples use ``main``. +2. Check the collection for deprecations that are planned for removal in the major release that were not reported by the sanity tests. Use past changelogs or run ``grep -r `X.0.0` plugins/`` in the repository. + +3. If you are going to release the ``community.general`` and ``community.network`` collections, create a new ``backport-X`` label in the corresponding repositories. Copy the styles and descriptions from the corresponding existing labels. + +4. Ensure you are in a default branch in your local fork. These examples use ``main``. .. code-block:: bash @@ -32,7 +36,7 @@ The new version is assumed to be ``X.0.0``. git checkout main # if needed -3. Update your local fork: +5. Update your local fork: .. code-block:: bash @@ -79,9 +83,17 @@ Creating the changelogs 5. Switch to the ``stable-X`` branch. -6. In the ``stable-X`` branch, ensure that ``galaxy.yml`` contains the correct version number ``X.0.0``. If not, update it. +6. In the ``stable-X`` branch, verify that ``galaxy.yml`` contains the correct version number ``X.0.0``. -7. In the ``stable-X`` branch, add a changelog fragment ``changelogs/fragments/X.0.0.yml`` with the content: +7. In the ``stable-X`` branch, ensure that ``changelogs/changelog.yml`` contains a correct ancestor's version: + + .. code-block:: yaml + + ancestor: X-1.0.0 + releases: {} + + +8. In the ``stable-X`` branch, add a changelog fragment ``changelogs/fragments/X.0.0.yml`` with the content: .. code-block:: yaml @@ -90,6 +102,7 @@ Creating the changelogs The format is reStructuredText, but not a list as for regular changelog fragments. This text will be inserted into the changelog. + For example: .. code-block:: yaml @@ -97,18 +110,18 @@ Creating the changelogs release_summary: This is release 2.0.0 of ``community.foo``, released on YYYY-MM-DD. -8. In the ``stable-X`` branch, generate the changelogs: +9. In the ``stable-X`` branch, generate the changelogs: .. code-block:: bash antsibull-changelog release --cummulative-release -9. In the ``stable-X`` branch, verify that the ``CHANGELOG.rst`` looks as expected. +10. In the ``stable-X`` branch, verify that the ``CHANGELOG.rst`` looks as expected. -10. In the ``stable-X`` branch, update ``README.md`` so that the changelog link points to ``/tree/stable-X/`` and no longer to ``/tree/main/``, and change badges respectively, for example, in case of AZP, add ``?branchName=stable-X`` to the AZP CI badge (https://dev.azure.com/ansible/community.xxx/_apis/build/status/CI?branchName=stable-X). +11. In the ``stable-X`` branch, update ``README.md`` so that the changelog link points to ``/tree/stable-X/`` and no longer to ``/tree/main/``, and change badges respectively, for example, in case of AZP, add ``?branchName=stable-X`` to the AZP CI badge (https://dev.azure.com/ansible/community.xxx/_apis/build/status/CI?branchName=stable-X). -11. In the ``stable-X`` branch, add, commit, and push changes to ``README.md``, ``CHANGELOG.rst`` and ``changelogs/changelog.yaml``, and potentially deleted/archived fragments to the **upstream** repository, NOT to the ``origin``. +12. In the ``stable-X`` branch, add, commit, and push changes to ``README.md``, ``CHANGELOG.rst`` and ``changelogs/changelog.yaml``, and potentially deleted/archived fragments to the **upstream** repository, NOT to the ``origin``. Publishing the collection @@ -123,16 +136,25 @@ Publishing the collection git push upstream NEW_VERSION -2. Wait until the new version is published on the collection's `Ansible Galaxy <https://galaxy.ansible.com/>`_ page. It will appear in a list of tarballs available to download. +2. If the collection uses `Zuul <https://github.com/ansible/zuul-config/blob/master/README.rst>`_ for publishing its releases, wait until the new version is published on the collection's `Ansible Galaxy <https://galaxy.ansible.com/>`_ page. It will appear in a list of tarballs available to download. -3. Add a GitHub release for the new tag. The title should be the version and content, such as - ``See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes``. +3. If the release tarball did not appear within several hours after pushing the tag, try to re-tag the release commit and push the tag again. In the ``stable-X`` branch being at the release commit: + .. code-block:: bash -4. Announce the release through the `Bullhorn Newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_. + git tag --delete NEW_VERSION + git push upstream :NEW_VERSION + git tag -a NEW_VERSION -m "comment here" # the comment can be, for example, "community.foo: 2.0.0" + git push upstream NEW_VERSION + + +4. Add a GitHub release for the new tag. The title should be the version and content, such as - ``See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes``. + +5. Announce the release through the `Bullhorn Newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_. -5. Announce the release in the pinned release issue/community pinboard of the collection and in the ``#ansible-community`` `Matrix/Libera.Chat IRC channel <https://docs.ansible.com/ansible/devel/community/communication.html#real-time-chat>`_. +6. Announce the release in the pinned release issue/community pinboard of the collection and in the ``#ansible-community`` `Matrix/Libera.Chat IRC channel <https://docs.ansible.com/ansible/devel/community/communication.html#real-time-chat>`_. -6. In the ``stable-X`` branch, update the version in ``galaxy.yml`` to the next **expected** version, for example, ``X.1.0``. Add, commit and push to the **upstream** repository. +7. In the ``stable-X`` branch, update the version in ``galaxy.yml`` to the next **expected** version, for example, ``X.1.0``. Add, commit and push to the **upstream** repository. Releasing minor collection versions diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index 4cdef1b2..87a37e86 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -102,6 +102,7 @@ Working groups Many of our community `Working Groups <https://github.com/ansible/community/wiki#working-groups>`_ meet in chat. If you want to get involved in a working group, join the Matrix room or IRC channel where it meets or comment on the agenda. +- `AAP Configuration as Code <https://github.com/redhat-cop/controller_configuration/wiki/AAP-Configuration-as-Code>`_ - Matrix: `#aap_config_as_code:ansible.com <https://matrix.to/#/#aap_config_as_code:ansible.com>`_ - `Amazon (AWS) Working Group <https://github.com/ansible/community/wiki/AWS>`_ - Matrix: `#aws:ansible.com <https://matrix.to:/#/#aws:ansible.com>`_ | IRC: ``#ansible-aws`` - `Ansible Lockdown Working Group <https://github.com/ansible/community/wiki/Lockdown>`_ (`Security playbooks/roles <https://github.com/ansible/ansible-lockdown>`_) - Matrix: `#lockdown:ansible.com <https://matrix.to:/#/#lockdown:ansible.com>`_ | IRC: ``#ansible-lockdown`` - `AWX Working Group <https://github.com/ansible/awx>`_ - Matrix: `#awx:ansible.com <https://matrix.to:/#/#awx:ansible.com>`_ | IRC: ``#ansible-awx`` @@ -118,9 +119,11 @@ Many of our community `Working Groups <https://github.com/ansible/community/wiki - `Kubernetes Working Group <https://github.com/ansible/community/wiki/Kubernetes>`_ - Matrix: `#kubernetes:ansible.com <https://matrix.to:/#/#kubernetes:ansible.com>`_ | IRC: ``#ansible-kubernetes`` - `Linode Working Group <https://github.com/ansible/community/wiki/Linode>`_ - Matrix: `#linode:ansible.com <https://matrix.to:/#/#linode:ansible.com>`_ | IRC: ``#ansible-linode`` - `Molecule Working Group <https://github.com/ansible/community/wiki/Molecule>`_ (`testing platform for Ansible playbooks and roles <https://molecule.readthedocs.io>`_) - Matrix: `#molecule:ansible.im <https://matrix.to:/#/#molecule:ansible.im>`_ | IRC: ``#ansible-molecule`` +- `MySQL Working Group <https://github.com/ansible-collections/community.mysql/wiki/MySQL-Working-Group>`_ - Matrix: `#mysql:ansible.com <https://matrix.to:/#/#mysql:ansible.com>`_ - `Network Working Group <https://github.com/ansible/community/wiki/Network>`_ - Matrix: `#network:ansible.com <https://matrix.to:/#/#network:ansible.com>`_ | IRC: ``#ansible-network`` - `PostgreSQL Working Group <https://github.com/ansible-collections/community.postgresql/wiki/PostgreSQL-Working-Group>`_ - Matrix: `#postgresql:ansible.com <https://matrix.to:/#/#postgresql:ansible.com>`_ - `Remote Management Working Group <https://github.com/ansible/community/issues/409>`_ - Matrix: `#devel:ansible.com <https://matrix.to:/#/#devel:ansible.com>`_ | IRC: ``#ansible-devel`` +- `Storage Working Group <https://github.com/ansible/community/wiki/Storage>`_ - Matrix: `#storage:ansible.com <https://matrix.to/#/#storage:ansible.com>`_ | IRC: ``#ansible-storage`` - `Testing Working Group <https://github.com/ansible/community/wiki/Testing>`_ - Matrix: `#devel:ansible.com <https://matrix.to:/#/#devel:ansible.com>`_ | IRC: ``#ansible-devel`` - `VMware Working Group <https://github.com/ansible/community/wiki/VMware>`_ - Matrix: `#vmware:ansible.com <https://matrix.to:/#/#vmware:ansible.com>`_ | IRC: ``#ansible-vmware`` - `Windows Working Group <https://github.com/ansible/community/wiki/Windows>`_ - Matrix: `#windows:ansible.com <https://matrix.to:/#/#windows:ansible.com>`_ | IRC: ``#ansible-windows`` diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst index 5fa5bc4d..26f87356 100644 --- a/docs/docsite/rst/community/development_process.rst +++ b/docs/docsite/rst/community/development_process.rst @@ -23,8 +23,8 @@ If you want to follow the conversation about what features will be added to ``an * the :ref:`ansible-core project branches and tags <core_branches_and_tags>` * various GitHub `projects <https://github.com/ansible/ansible/projects>`_ - for example: - * the `2.12 release project <https://github.com/ansible/ansible/projects/43>`_ - * the `core documentation project <https://github.com/ansible/ansible/projects/27>`_ + * the `2.15 release project <https://github.com/ansible/ansible/projects/46>`_ + * the `core documentation project <https://github.com/orgs/ansible/projects/94/views/1>`_ .. _community_pull_requests: @@ -330,7 +330,7 @@ We do **not** backport features. These instructions assume that: - * ``stable-2.13`` is the targeted release branch for the backport + * ``stable-2.14`` is the targeted release branch for the backport * ``https://github.com/ansible/ansible.git`` is configured as a ``git remote`` named ``upstream``. If you do not use a ``git remote`` named ``upstream``, adjust the instructions accordingly. * ``https://github.com/<yourgithubaccount>/ansible.git`` is configured as a ``git remote`` named ``origin``. If you do not use a ``git remote`` named ``origin``, adjust the instructions accordingly. @@ -339,7 +339,7 @@ We do **not** backport features. .. code-block:: shell git fetch upstream - git checkout -b backport/2.13/[PR_NUMBER_FROM_DEVEL] upstream/stable-2.13 + git checkout -b backport/2.14/[PR_NUMBER_FROM_DEVEL] upstream/stable-2.14 #. Cherry pick the relevant commit SHA from the devel branch into your feature branch, handling merge conflicts as necessary: @@ -353,15 +353,15 @@ We do **not** backport features. .. code-block:: shell - git push origin backport/2.13/[PR_NUMBER_FROM_DEVEL] + git push origin backport/2.14/[PR_NUMBER_FROM_DEVEL] -#. Submit the pull request for ``backport/2.13/[PR_NUMBER_FROM_DEVEL]`` against the ``stable-2.13`` branch +#. Submit the pull request for ``backport/2.14/[PR_NUMBER_FROM_DEVEL]`` against the ``stable-2.14`` branch #. The Release Manager will decide whether to merge the backport PR before the next minor release. There isn't any need to follow up. Just ensure that the automated tests (CI) are green. .. note:: - The branch name ``backport/2.13/[PR_NUMBER_FROM_DEVEL]`` is somewhat arbitrary but conveys meaning about the purpose of the branch. This branch name format is not required, but it can be helpful, especially when making multiple backport PRs for multiple stable branches. + The branch name ``backport/2.14/[PR_NUMBER_FROM_DEVEL]`` is somewhat arbitrary but conveys meaning about the purpose of the branch. This branch name format is not required, but it can be helpful, especially when making multiple backport PRs for multiple stable branches. .. note:: diff --git a/docs/docsite/rst/dev_guide/developing_inventory.rst b/docs/docsite/rst/dev_guide/developing_inventory.rst index d2ecc1f5..8697e943 100644 --- a/docs/docsite/rst/dev_guide/developing_inventory.rst +++ b/docs/docsite/rst/dev_guide/developing_inventory.rst @@ -189,6 +189,26 @@ The specifics will vary depending on API and structure returned. Remember that i For examples on how to implement an inventory plugin, see the source code here: `lib/ansible/plugins/inventory <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/inventory>`_. +.. _inventory_object: + +inventory object +^^^^^^^^^^^^^^^^ + +The ``inventory`` object passed to ``parse`` has helpful methods for populating inventory. + +``add_group`` adds a group to inventory if it doesn't already exist. It takes the group name as the only positional argument. + +``add_child`` adds a group or host that exists in inventory to a parent group in inventory. It takes two positional arguments, the name of the parent group and the name of the child group or host. + +``add_host`` adds a host to inventory if it doesn't already exist, optionally to a specific group. It takes the host name as the first argument and accepts two optional keyword arguments, ``group`` and ``port``. ``group`` is the name of a group in inventory, and ``port`` is an integer. + +``set_variable`` adds a variable to a group or host in inventory. It takes three positional arguments: the name of the group or host, the name of the variable, and the value of the variable. + +To create groups and variables using Jinja2 expressions, see the section on implementing ``constructed`` features below. + +To see other inventory object methods, see the source code here: +`lib/ansible/inventory/data.py <https://github.com/ansible/ansible/tree/devel/lib/ansible/inventory/data.py>`_. + .. _inventory_plugin_caching: inventory cache @@ -286,7 +306,19 @@ Inventory plugins can create host variables and groups from Jinja2 expressions a NAME = 'ns.coll.myplugin' -The three main options from the ``constructed`` documentation fragment are ``compose``, ``keyed_groups``, and ``groups``. See the ``constructed`` inventory plugin for examples on using these. ``compose`` is a dictionary of variable names and Jinja2 expressions. Once a host is added to inventory and any initial variables have been set, call the method ``_set_composite_vars`` to add composed host variables. If this is done before adding ``keyed_groups`` and ``groups``, the group generation will be able to use the composed variables. +There are three main options in the ``constructed`` documentation fragment: + +``compose`` creates variables using Jinja2 expressions. This is implemented by calling the ``_set_composite_vars`` method. +``keyed_groups`` creates groups of hosts based on variable values. This is implemented by calling the ``_add_host_to_keyed_groups`` method. +``groups`` creates groups based on Jinja2 conditionals. This is implemented by calling the ``_add_host_to_composed_groups`` method. + +Each method should be called for every host added to inventory. Three positional arguments are required: the constructed option, a dictionary of variables, and a host name. Calling the method ``_set_composite_vars`` first will allow ``keyed_groups`` and ``groups`` to use the composed variables. + +By default, undefined variables are ignored. This is permitted by default for ``compose`` so you can make the variable definitions depend on variables that will be populated later in a play from other sources. For groups, it allows using variables that are not always present without having to use the ``default`` filter. To support configuring undefined variables to be an error, pass the constructed option ``strict`` to each of the methods as a keyword argument. + +``keyed_groups`` and ``groups`` use any variables already associated with the host (for example, from an earlier inventory source). ``_add_host_to_keyed_groups`` and ``add_host_to_composed_groups`` can turn this off by passing the keyword argument ``fetch_hostvars``. + +Here is an example using all three methods: .. code-block:: python @@ -296,14 +328,12 @@ The three main options from the ``constructed`` documentation fragment are ``com for var_name, var_value in host_vars.items(): self.inventory.set_variable(hostname, var_name, var_value) - # Determines if composed variables or groups using nonexistent variables is an error strict = self.get_option('strict') # Add variables created by the user's Jinja2 expressions to the host self._set_composite_vars(self.get_option('compose'), host_vars, hostname, strict=True) - # The following two methods combine the provided variables dictionary with the latest host variables - # Using these methods after _set_composite_vars() allows groups to be created with the composed variables + # Create user-defined groups using variables and Jinja2 conditionals self._add_host_to_composed_groups(self.get_option('groups'), host_vars, hostname, strict=strict) self._add_host_to_keyed_groups(self.get_option('keyed_groups'), host_vars, hostname, strict=strict) diff --git a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst index 82ffaf3c..d896c544 100644 --- a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst +++ b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst @@ -114,7 +114,7 @@ Non-native want JSON modules ---------------------------- If a module has the string ``WANT_JSON`` in it anywhere, Ansible treats -it as a non-native module that accepts a filename as its only command line +it as a non-native module that accepts a filename as its only command-line parameter. The filename is for a temporary file containing a :term:`JSON` string containing the module's parameters. The module needs to open the file, read and parse the parameters, operate on the data, and print its return data @@ -173,7 +173,7 @@ Executor/task_executor ---------------------- The TaskExecutor receives the module name and parameters that were parsed from -the :term:`playbook <playbooks>` (or from the command line in the case of +the :term:`playbook <playbooks>` (or from the command-line in the case of :command:`/usr/bin/ansible`). It uses the name to decide whether it's looking at a module or an :ref:`Action Plugin <flow_action_plugins>`. If it's a module, it loads the :ref:`Normal Action Plugin <flow_normal_action_plugin>` @@ -279,12 +279,12 @@ substitutions: this is better accessed by instantiating an `AnsibleModule` and then using :attr:`AnsibleModule.params`. - :code:`<<SELINUX_SPECIAL_FILESYSTEMS>>` substitutes a string which is - a comma separated list of file systems which have a file system dependent + a comma-separated list of file systems which have a file system dependent security context in SELinux. In new-style Python modules, if you really need this you should instantiate an `AnsibleModule` and then use :attr:`AnsibleModule._selinux_special_fs`. The variable has also changed - from a comma separated string of file system names to an actual python - list of filesystem names. + from a comma-separated string of file system names to an actual python + list of file system names. - :code:`<<INCLUDE_ANSIBLE_MODULE_JSON_ARGS>>` substitutes the module parameters as a JSON string. Care must be taken to properly quote the string as JSON data may contain quotes. This pattern is not substituted @@ -322,7 +322,7 @@ importing a module. This lets Ansible run both the wrapper script and the module * Ansible wraps the zipfile in the Python script for two reasons: * for compatibility with Python 2.6 which has a less - functional version of Python's ``-m`` command line switch. + functional version of Python's ``-m`` command-line switch. * so that pipelining will function properly. Pipelining needs to pipe the Python module into the Python interpreter on the remote node. Python @@ -378,79 +378,69 @@ Internal arguments ------------------ Both :ref:`module_replacer` and :ref:`Ansiballz` send additional arguments to -the module beyond those which the user specified in the playbook. These +the Ansible module beyond those which the user specified in the playbook. These additional arguments are internal parameters that help implement global -Ansible features. Modules often do not need to know about these explicitly as -the features are implemented in :py:mod:`ansible.module_utils.basic` but certain -features need support from the module so it's good to know about them. +Ansible features. Modules often do not need to know about these explicitly because +the features are implemented in :py:mod:`ansible.module_utils.basic`. However, certain +features need support from modules and some knowledge of the internal arguments is useful. + +The internal arguments in this section are global. If you need to add a local internal argument to a custom module, create an action plugin for that specific module. See ``_original_basename`` in the `copy action plugin <https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/action/copy.py#L329>`_ for an example. -The internal arguments listed here are global. If you need to add a local internal argument to a custom module, create an action plugin for that specific module - see ``_original_basename`` in the `copy action plugin <https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/action/copy.py#L329>`_ for an example. _ansible_no_log ^^^^^^^^^^^^^^^ -Boolean. Set to True whenever a parameter in a task or play specifies ``no_log``. Any module that calls :py:meth:`AnsibleModule.log` handles this automatically. If a module implements its own logging then -it needs to check this value. To access in a module, instantiate an -``AnsibleModule`` and then check the value of :attr:`AnsibleModule.no_log`. +Type: ``bool`` + +Set to ``True`` whenever an argument in a task or play specifies ``no_log``. Any module that calls the :py:meth:`AnsibleModule.log` function handles this action automatically. If you have a module that implements its own logging then you need to check the value of ``_ansible_no_log``. To access ``_ansible_no_log`` in a module, instantiate the ``AnsibleModule`` utility and then check the value of :attr:`AnsibleModule.no_log`. .. note:: - ``no_log`` specified in a module's argument_spec is handled by a different mechanism. + ``no_log`` specified in a module's ``argument_spec`` is handled by a different mechanism. + _ansible_debug -^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^ + +Type: ``bool`` + +Operates verbose logging and logging of external commands that a module executes. If the module uses the :py:meth:`AnsibleModule.debug` function rather than the :py:meth:`AnsibleModule.log` function then the messages are only logged if you set the ``_ansible_debug`` argument to ``True``. To access ``_ansible_debug`` in a module, instantiate the ``AnsibleModule`` utility and access :attr:`AnsibleModule._debug`. For more details, see :ref:`DEFAULT_DEBUG`. -Boolean. Turns more verbose logging on or off and turns on logging of -external commands that the module executes. If a module uses -:py:meth:`AnsibleModule.debug` rather than :py:meth:`AnsibleModule.log` then -the messages are only logged if ``_ansible_debug`` is set to ``True``. -To set, add ``debug: True`` to :file:`ansible.cfg` or set the environment -variable :envvar:`ANSIBLE_DEBUG`. To access in a module, instantiate an -``AnsibleModule`` and access :attr:`AnsibleModule._debug`. _ansible_diff -^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^ + +Type: ``bool`` + +With this parameter you can configure your module to show a unified diff of changes that will be applied to the templated files. To access ``_ansible_diff`` in a module, instantiate the ``AnsibleModule`` utility and access :attr:`AnsibleModule._diff`. You can also access this parameter using the ``diff`` keyword in your playbook, or the relevant environment variable. For more details, see :ref:`playbook_keywords` and the :ref:`DIFF_ALWAYS` configuration option. -Boolean. If a module supports it, tells the module to show a unified diff of -changes to be made to templated files. To set, pass the ``--diff`` command line -option. To access in a module, instantiate an `AnsibleModule` and access -:attr:`AnsibleModule._diff`. _ansible_verbosity ^^^^^^^^^^^^^^^^^^ -Unused. This value could be used for finer grained control over logging. +Type: ``int`` + +You can use this argument to control the level (0 for none) of verbosity in logging. + _ansible_selinux_special_fs ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -List. Names of filesystems which should have a special SELinux -context. They are used by the `AnsibleModule` methods which operate on -files (changing attributes, moving, and copying). To set, add a comma separated string of filesystem names in :file:`ansible.cfg`: +Type: ``list`` +Elements: ``strings`` -.. code-block:: ini +This argument provides modules with the names of file systems which should have a special SELinux context. They are used by the ``AnsibleModule`` methods which operate on files (changing attributes, moving, and copying). - # ansible.cfg - [selinux] - special_context_filesystems=nfs,vboxsf,fuse,ramfs,vfat +Most modules can use the built-in ``AnsibleModule`` methods to manipulate files. To access in a module that needs to know about these special context file systems, instantiate ``AnsibleModule`` and examine the list in :attr:`AnsibleModule._selinux_special_fs`. -Most modules can use the built-in ``AnsibleModule`` methods to manipulate -files. To access in a module that needs to know about these special context filesystems, instantiate an ``AnsibleModule`` and examine the list in -:attr:`AnsibleModule._selinux_special_fs`. - -This replaces :attr:`ansible.module_utils.basic.SELINUX_SPECIAL_FS` from -:ref:`module_replacer`. In module replacer it was a comma separated string of -filesystem names. Under Ansiballz it's an actual list. +This argument replaces :attr:`ansible.module_utils.basic.SELINUX_SPECIAL_FS` from :ref:`module_replacer`. In the module replacer framework the argument was formatted as a comma-separated string of file system names. Under the Ansiballz framework it is a list. You can access ``_ansible_selinux_special_fs`` using the corresponding environment variable. For more details, see the :ref:`DEFAULT_SELINUX_SPECIAL_FS` configuration option. .. versionadded:: 2.1 + _ansible_syslog_facility ^^^^^^^^^^^^^^^^^^^^^^^^ -This parameter controls which syslog facility Ansible module logs to. To set, change the ``syslog_facility`` value in :file:`ansible.cfg`. Most -modules should just use :meth:`AnsibleModule.log` which will then make use of -this. If a module has to use this on its own, it should instantiate an -`AnsibleModule` and then retrieve the name of the syslog facility from -:attr:`AnsibleModule._syslog_facility`. The Ansiballz code is less hacky than the old :ref:`module_replacer` code: +This argument controls which syslog facility the module logs to. Most modules should just use the :meth:`AnsibleModule.log` function which will then make use of this. If a module has to use this on its own, it should instantiate the ``AnsibleModule`` method and then retrieve the name of the syslog facility from :attr:`AnsibleModule._syslog_facility`. The Ansiballz code is less elegant than the :ref:`module_replacer` code: .. code-block:: python @@ -464,20 +454,77 @@ this. If a module has to use this on its own, it should instantiate an facility = getattr(syslog, facility_name, syslog.LOG_USER) syslog.openlog(NAME, 0, facility) +For more details, see the :ref:`DEFAULT_SYSLOG_FACILITY` configuration option. + .. versionadded:: 2.1 + _ansible_version ^^^^^^^^^^^^^^^^ -This parameter passes the version of Ansible that runs the module. To access -it, a module should instantiate an `AnsibleModule` and then retrieve it -from :attr:`AnsibleModule.ansible_version`. This replaces -:attr:`ansible.module_utils.basic.ANSIBLE_VERSION` from -:ref:`module_replacer`. +This argument passes the version of Ansible to the module. To access it, a module should instantiate the ``AnsibleModule`` method and then retrieve the version from :attr:`AnsibleModule.ansible_version`. This replaces :attr:`ansible.module_utils.basic.ANSIBLE_VERSION` from :ref:`module_replacer`. .. versionadded:: 2.1 +_ansible_module_name +^^^^^^^^^^^^^^^^^^^^ + +Type: ``str`` + +This argument passes the information to modules about their name. For more details see, the configuration option :ref:`DEFAULT_MODULE_NAME`. + + +_ansible_string_conversion_action +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This argument provides instructions about what modules should do after the values of the user-specified module parameters are converted to strings. For more details, see the :ref:`STRING_CONVERSION_ACTION` configuration option. + + +_ansible_keep_remote_files +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Type: ``bool`` + +This argument provides instructions that modules must be ready if they need to keep the remote files. For more details, see the :ref:`DEFAULT_KEEP_REMOTE_FILES` configuration option. + + +_ansible_socket +^^^^^^^^^^^^^^^ +This argument provides modules with a socket for persistent connections. The argument is created using the :ref:`PERSISTENT_CONTROL_PATH_DIR` configuration option. + + +_ansible_shell_executable +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Type: ``bool`` + +This argument ensures that modules use the designated shell executable. For more details, see the :ref:`ansible_shell_executable` remote host environment parameter. + + +_ansible_tmpdir +^^^^^^^^^^^^^^^ + +Type: ``str`` + +This argument provides instructions to modules that all commands must use the designated temporary directory, if created. The action plugin designs this temporary directory. + +Modules can access this parameter by using the public ``tmpdir`` property. The ``tmpdir`` property will create a temporary directory if the action plugin did not set the parameter. + +The directory name is generated randomly, and the the root of the directory is determined by one of these: + +* :ref:`DEFAULT_LOCAL_TMP` +* `remote_tmp <https://docs.ansible.com/ansible/latest/collections/ansible/builtin/sh_shell.html#parameter-remote_tmp>`_ +* `system_tmpdirs <https://docs.ansible.com/ansible/latest/collections/ansible/builtin/sh_shell.html#parameter-system_tmpdirs>`_ + +As a result, using the ``ansible.cfg`` configuration file to activate or customize this setting will not guarantee that you control the full value. + + +_ansible_remote_tmp +^^^^^^^^^^^^^^^^^^^ + +The module's ``tmpdir`` property creates a randomized directory name in this directory if the action plugin did not set ``_ansible_tmpdir``. For more details, see the `remote_tmp <https://docs.ansible.com/ansible/latest/collections/ansible/builtin/sh_shell.html#parameter-remote_tmp>`_ parameter of the shell plugin. + + .. _flow_module_return_values: Module return values & Unsafe strings diff --git a/docs/docsite/rst/dev_guide/testing/sanity/pep8.rst b/docs/docsite/rst/dev_guide/testing/sanity/pep8.rst index 8595d986..9424bda8 100644 --- a/docs/docsite/rst/dev_guide/testing/sanity/pep8.rst +++ b/docs/docsite/rst/dev_guide/testing/sanity/pep8.rst @@ -1,6 +1,24 @@ +.. _testing_pep8: + pep8 ==== Python static analysis for PEP 8 style guideline compliance. -See :ref:`testing_pep8` for more information. +`PEP 8`_ style guidelines are enforced by `pycodestyle`_ on all python files in the repository by default. + +Running locally +----------------- + +The `PEP 8`_ check can be run locally as follows: + +.. code-block:: shell + + ansible-test sanity --test pep8 [file-or-directory-path-to-check] ... + + + +.. _PEP 8: https://www.python.org/dev/peps/pep-0008/ +.. _pycodestyle: https://pypi.org/project/pycodestyle/ + + diff --git a/docs/docsite/rst/dev_guide/testing/sanity/validate-modules.rst b/docs/docsite/rst/dev_guide/testing/sanity/validate-modules.rst index efb58f20..dcb78c05 100644 --- a/docs/docsite/rst/dev_guide/testing/sanity/validate-modules.rst +++ b/docs/docsite/rst/dev_guide/testing/sanity/validate-modules.rst @@ -1,6 +1,140 @@ +.. _testing_validate-modules: + validate-modules ================ Analyze modules for common issues in code and documentation. -See :ref:`testing_validate-modules` for more information. +.. contents:: + :local: + +Usage +------ + +.. code:: shell + + cd /path/to/ansible/source + source hacking/env-setup + ansible-test sanity --test validate-modules + +Help +----- + +Type ``ansible-test sanity validate-modules -h`` to display help for using this sanity test. + + + +Extending validate-modules +--------------------------- + +The ``validate-modules`` tool has a `schema.py <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/schema.py>`_ that is used to validate the YAML blocks, such as ``DOCUMENTATION`` and ``RETURNS``. + + +Codes +------ + +============================================================ ================== ==================== ========================================================================================= + **Error Code** **Type** **Level** **Sample Message** +------------------------------------------------------------ ------------------ -------------------- ----------------------------------------------------------------------------------------- + ansible-deprecated-module Documentation Error A module is deprecated and supposed to be removed in the current or an earlier Ansible version + collection-deprecated-module Documentation Error A module is deprecated and supposed to be removed in the current or an earlier collection version + ansible-deprecated-version Documentation Error A feature is deprecated and supposed to be removed in the current or an earlier Ansible version + ansible-module-not-initialized Syntax Error Execution of the module did not result in initialization of AnsibleModule + collection-deprecated-version Documentation Error A feature is deprecated and supposed to be removed in the current or an earlier collection version + deprecated-date Documentation Error A date before today appears as ``removed_at_date`` or in ``deprecated_aliases`` + deprecation-mismatch Documentation Error Module marked as deprecated or removed in at least one of the filename, its metadata, or in DOCUMENTATION (setting DOCUMENTATION.deprecated for deprecation or removing all Documentation for removed) but not in all three places. + doc-choices-do-not-match-spec Documentation Error Value for "choices" from the argument_spec does not match the documentation + doc-choices-incompatible-type Documentation Error Choices value from the documentation is not compatible with type defined in the argument_spec + doc-default-does-not-match-spec Documentation Error Value for "default" from the argument_spec does not match the documentation + doc-default-incompatible-type Documentation Error Default value from the documentation is not compatible with type defined in the argument_spec + doc-elements-invalid Documentation Error Documentation specifies elements for argument, when "type" is not ``list``. + doc-elements-mismatch Documentation Error Argument_spec defines elements different than documentation does + doc-missing-type Documentation Error Documentation doesn't specify a type but argument in ``argument_spec`` use default type (``str``) + doc-required-mismatch Documentation Error argument in argument_spec is required but documentation says it is not, or vice versa + doc-type-does-not-match-spec Documentation Error Argument_spec defines type different than documentation does + documentation-error Documentation Error Unknown ``DOCUMENTATION`` error + documentation-syntax-error Documentation Error Invalid ``DOCUMENTATION`` schema + illegal-future-imports Imports Error Only the following ``from __future__`` imports are allowed: ``absolute_import``, ``division``, and ``print_function``. + import-before-documentation Imports Error Import found before documentation variables. All imports must appear below ``DOCUMENTATION``/``EXAMPLES``/``RETURN`` + import-error Documentation Error ``Exception`` attempting to import module for ``argument_spec`` introspection + import-placement Locations Warning Imports should be directly below ``DOCUMENTATION``/``EXAMPLES``/``RETURN`` + imports-improper-location Imports Error Imports should be directly below ``DOCUMENTATION``/``EXAMPLES``/``RETURN`` + incompatible-choices Documentation Error Choices value from the argument_spec is not compatible with type defined in the argument_spec + incompatible-default-type Documentation Error Default value from the argument_spec is not compatible with type defined in the argument_spec + invalid-argument-name Documentation Error Argument in argument_spec must not be one of 'message', 'syslog_facility' as it is used internally by Ansible Core Engine + invalid-argument-spec Documentation Error Argument in argument_spec must be a dictionary/hash when used + invalid-argument-spec-options Documentation Error Suboptions in argument_spec are invalid + invalid-documentation Documentation Error ``DOCUMENTATION`` is not valid YAML + invalid-documentation-markup Documentation Error ``DOCUMENTATION`` or ``RETURN`` contains invalid markup + invalid-documentation-options Documentation Error ``DOCUMENTATION.options`` must be a dictionary/hash when used + invalid-examples Documentation Error ``EXAMPLES`` is not valid YAML + invalid-extension Naming Error Official Ansible modules must have a ``.py`` extension for python modules or a ``.ps1`` for powershell modules + invalid-module-schema Documentation Error ``AnsibleModule`` schema validation error + invalid-removal-version Documentation Error The version at which a feature is supposed to be removed cannot be parsed (for collections, it must be a `semantic version <https://semver.org/>`_) + invalid-requires-extension Naming Error Module ``#AnsibleRequires -CSharpUtil`` should not end in .cs, Module ``#Requires`` should not end in .psm1 + missing-doc-fragment Documentation Error ``DOCUMENTATION`` fragment missing + missing-existing-doc-fragment Documentation Warning Pre-existing ``DOCUMENTATION`` fragment missing + missing-documentation Documentation Error No ``DOCUMENTATION`` provided + missing-examples Documentation Error No ``EXAMPLES`` provided + missing-gplv3-license Documentation Error GPLv3 license header not found + missing-module-utils-basic-import Imports Warning Did not find ``ansible.module_utils.basic`` import + missing-module-utils-import-csharp-requirements Imports Error No ``Ansible.ModuleUtils`` or C# Ansible util requirements/imports found + missing-powershell-interpreter Syntax Error Interpreter line is not ``#!powershell`` + missing-python-interpreter Syntax Error Interpreter line is not ``#!/usr/bin/python`` + missing-return Documentation Error No ``RETURN`` documentation provided + missing-return-legacy Documentation Warning No ``RETURN`` documentation provided for legacy module + missing-suboption-docs Documentation Error Argument in argument_spec has sub-options but documentation does not define sub-options + module-incorrect-version-added Documentation Error Module level ``version_added`` is incorrect + module-invalid-version-added Documentation Error Module level ``version_added`` is not a valid version number + module-utils-specific-import Imports Error ``module_utils`` imports should import specific components, not ``*`` + multiple-utils-per-requires Imports Error ``Ansible.ModuleUtils`` requirements do not support multiple modules per statement + multiple-csharp-utils-per-requires Imports Error Ansible C# util requirements do not support multiple utils per statement + no-default-for-required-parameter Documentation Error Option is marked as required but specifies a default. Arguments with a default should not be marked as required + no-log-needed Parameters Error Option name suggests that the option contains a secret value, while ``no_log`` is not specified for this option in the argument spec. If this is a false positive, explicitly set ``no_log=False`` + nonexistent-parameter-documented Documentation Error Argument is listed in DOCUMENTATION.options, but not accepted by the module + option-incorrect-version-added Documentation Error ``version_added`` for new option is incorrect + option-invalid-version-added Documentation Error ``version_added`` for option is not a valid version number + parameter-invalid Documentation Error Argument in argument_spec is not a valid python identifier + parameter-invalid-elements Documentation Error Value for "elements" is valid only when value of "type" is ``list`` + implied-parameter-type-mismatch Documentation Error Argument_spec implies ``type="str"`` but documentation defines it as different data type + parameter-type-not-in-doc Documentation Error Type value is defined in ``argument_spec`` but documentation doesn't specify a type + parameter-alias-repeated Parameters Error argument in argument_spec has at least one alias specified multiple times in aliases + parameter-alias-self Parameters Error argument in argument_spec is specified as its own alias + parameter-documented-multiple-times Documentation Error argument in argument_spec with aliases is documented multiple times + parameter-list-no-elements Parameters Error argument in argument_spec "type" is specified as ``list`` without defining "elements" + parameter-state-invalid-choice Parameters Error Argument ``state`` includes ``get``, ``list`` or ``info`` as a choice. Functionality should be in an ``_info`` or (if further conditions apply) ``_facts`` module. + python-syntax-error Syntax Error Python ``SyntaxError`` while parsing module + removal-version-must-be-major Documentation Error According to the semantic versioning specification (https://semver.org/), the only versions in which features are allowed to be removed are major versions (x.0.0) + return-syntax-error Documentation Error ``RETURN`` is not valid YAML, ``RETURN`` fragments missing or invalid + return-invalid-version-added Documentation Error ``version_added`` for return value is not a valid version number + subdirectory-missing-init Naming Error Ansible module subdirectories must contain an ``__init__.py`` + try-except-missing-has Imports Warning Try/Except ``HAS_`` expression missing + undocumented-parameter Documentation Error Argument is listed in the argument_spec, but not documented in the module + unidiomatic-typecheck Syntax Error Type comparison using ``type()`` found. Use ``isinstance()`` instead + unknown-doc-fragment Documentation Warning Unknown pre-existing ``DOCUMENTATION`` error + use-boto3 Imports Error ``boto`` import found, new modules should use ``boto3`` + use-fail-json-not-sys-exit Imports Error ``sys.exit()`` call found. Should be ``exit_json``/``fail_json`` + use-module-utils-urls Imports Error ``requests`` import found, should use ``ansible.module_utils.urls`` instead + use-run-command-not-os-call Imports Error ``os.call`` used instead of ``module.run_command`` + use-run-command-not-popen Imports Error ``subprocess.Popen`` used instead of ``module.run_command`` + use-short-gplv3-license Documentation Error GPLv3 license header should be the :ref:`short form <copyright>` for new modules + mutually_exclusive-type Documentation Error mutually_exclusive entry contains non-string value + mutually_exclusive-collision Documentation Error mutually_exclusive entry has repeated terms + mutually_exclusive-unknown Documentation Error mutually_exclusive entry contains option which does not appear in argument_spec (potentially an alias of an option?) + required_one_of-type Documentation Error required_one_of entry contains non-string value + required_one_of-collision Documentation Error required_one_of entry has repeated terms + required_one_of-unknown Documentation Error required_one_of entry contains option which does not appear in argument_spec (potentially an alias of an option?) + required_together-type Documentation Error required_together entry contains non-string value + required_together-collision Documentation Error required_together entry has repeated terms + required_together-unknown Documentation Error required_together entry contains option which does not appear in argument_spec (potentially an alias of an option?) + required_if-is_one_of-type Documentation Error required_if entry has a fourth value which is not a bool + required_if-requirements-type Documentation Error required_if entry has a third value (requirements) which is not a list or tuple + required_if-requirements-collision Documentation Error required_if entry has repeated terms in requirements + required_if-requirements-unknown Documentation Error required_if entry's requirements contains option which does not appear in argument_spec (potentially an alias of an option?) + required_if-unknown-key Documentation Error required_if entry's key does not appear in argument_spec (potentially an alias of an option?) + required_if-key-in-requirements Documentation Error required_if entry contains its key in requirements list/tuple + required_if-value-type Documentation Error required_if entry's value is not of the type specified for its key + required_by-collision Documentation Error required_by entry has repeated terms + required_by-unknown Documentation Error required_by entry contains option which does not appear in argument_spec (potentially an alias of an option?) + version-added-must-be-major-or-minor Documentation Error According to the semantic versioning specification (https://semver.org/), the only versions in which features are allowed to be added are major and minor versions (x.y.0) +============================================================ ================== ==================== ========================================================================================= diff --git a/docs/docsite/rst/dev_guide/testing_pep8.rst b/docs/docsite/rst/dev_guide/testing_pep8.rst index 7c19b2a1..c634914d 100644 --- a/docs/docsite/rst/dev_guide/testing_pep8.rst +++ b/docs/docsite/rst/dev_guide/testing_pep8.rst @@ -1,25 +1,8 @@ :orphan: -.. _testing_pep8: ***** PEP 8 ***** -.. contents:: Topics - -`PEP 8`_ style guidelines are enforced by `pycodestyle`_ on all python files in the repository by default. - -Running Locally -=============== - -The `PEP 8`_ check can be run locally with: - -.. code-block:: shell - - ansible-test sanity --test pep8 [file-or-directory-path-to-check] ... - - - -.. _PEP 8: https://www.python.org/dev/peps/pep-0008/ -.. _pycodestyle: https://pypi.org/project/pycodestyle/ +This page has moved to :ref:`testing_pep8`.
\ No newline at end of file diff --git a/docs/docsite/rst/dev_guide/testing_validate-modules.rst b/docs/docsite/rst/dev_guide/testing_validate-modules.rst index b937df59..1c74fe39 100644 --- a/docs/docsite/rst/dev_guide/testing_validate-modules.rst +++ b/docs/docsite/rst/dev_guide/testing_validate-modules.rst @@ -1,165 +1,7 @@ :orphan: -.. _testing_validate-modules: - **************** validate-modules **************** -.. contents:: Topics - -Python program to help test or validate Ansible modules. - -``validate-modules`` is one of the ``ansible-test`` Sanity Tests, see :ref:`testing_sanity` for more information. - -Originally developed by Matt Martz (@sivel) - - -Usage -===== - -.. code:: shell - - cd /path/to/ansible/source - source hacking/env-setup - ansible-test sanity --test validate-modules - -Help -==== - -.. code:: shell - - usage: validate-modules [-h] [-w] [--exclude EXCLUDE] [--arg-spec] - [--base-branch BASE_BRANCH] [--format {json,plain}] - [--output OUTPUT] - modules [modules ...] - - positional arguments: - modules Path to module or module directory - - optional arguments: - -h, --help show this help message and exit - -w, --warnings Show warnings - --exclude EXCLUDE RegEx exclusion pattern - --arg-spec Analyze module argument spec - --base-branch BASE_BRANCH - Used in determining if new options were added - --format {json,plain} - Output format. Default: "plain" - --output OUTPUT Output location, use "-" for stdout. Default "-" - - -Extending validate-modules -========================== - -The ``validate-modules`` tool has a `schema.py <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/schema.py>`_ that is used to validate the YAML blocks, such as ``DOCUMENTATION`` and ``RETURNS``. - - -Codes -===== - -============================================================ ================== ==================== ========================================================================================= - **Error Code** **Type** **Level** **Sample Message** ------------------------------------------------------------- ------------------ -------------------- ----------------------------------------------------------------------------------------- - ansible-deprecated-module Documentation Error A module is deprecated and supposed to be removed in the current or an earlier Ansible version - collection-deprecated-module Documentation Error A module is deprecated and supposed to be removed in the current or an earlier collection version - ansible-deprecated-version Documentation Error A feature is deprecated and supposed to be removed in the current or an earlier Ansible version - ansible-module-not-initialized Syntax Error Execution of the module did not result in initialization of AnsibleModule - collection-deprecated-version Documentation Error A feature is deprecated and supposed to be removed in the current or an earlier collection version - deprecated-date Documentation Error A date before today appears as ``removed_at_date`` or in ``deprecated_aliases`` - deprecation-mismatch Documentation Error Module marked as deprecated or removed in at least one of the filename, its metadata, or in DOCUMENTATION (setting DOCUMENTATION.deprecated for deprecation or removing all Documentation for removed) but not in all three places. - doc-choices-do-not-match-spec Documentation Error Value for "choices" from the argument_spec does not match the documentation - doc-choices-incompatible-type Documentation Error Choices value from the documentation is not compatible with type defined in the argument_spec - doc-default-does-not-match-spec Documentation Error Value for "default" from the argument_spec does not match the documentation - doc-default-incompatible-type Documentation Error Default value from the documentation is not compatible with type defined in the argument_spec - doc-elements-invalid Documentation Error Documentation specifies elements for argument, when "type" is not ``list``. - doc-elements-mismatch Documentation Error Argument_spec defines elements different than documentation does - doc-missing-type Documentation Error Documentation doesn't specify a type but argument in ``argument_spec`` use default type (``str``) - doc-required-mismatch Documentation Error argument in argument_spec is required but documentation says it is not, or vice versa - doc-type-does-not-match-spec Documentation Error Argument_spec defines type different than documentation does - documentation-error Documentation Error Unknown ``DOCUMENTATION`` error - documentation-syntax-error Documentation Error Invalid ``DOCUMENTATION`` schema - illegal-future-imports Imports Error Only the following ``from __future__`` imports are allowed: ``absolute_import``, ``division``, and ``print_function``. - import-before-documentation Imports Error Import found before documentation variables. All imports must appear below ``DOCUMENTATION``/``EXAMPLES``/``RETURN`` - import-error Documentation Error ``Exception`` attempting to import module for ``argument_spec`` introspection - import-placement Locations Warning Imports should be directly below ``DOCUMENTATION``/``EXAMPLES``/``RETURN`` - imports-improper-location Imports Error Imports should be directly below ``DOCUMENTATION``/``EXAMPLES``/``RETURN`` - incompatible-choices Documentation Error Choices value from the argument_spec is not compatible with type defined in the argument_spec - incompatible-default-type Documentation Error Default value from the argument_spec is not compatible with type defined in the argument_spec - invalid-argument-name Documentation Error Argument in argument_spec must not be one of 'message', 'syslog_facility' as it is used internally by Ansible Core Engine - invalid-argument-spec Documentation Error Argument in argument_spec must be a dictionary/hash when used - invalid-argument-spec-options Documentation Error Suboptions in argument_spec are invalid - invalid-documentation Documentation Error ``DOCUMENTATION`` is not valid YAML - invalid-documentation-markup Documentation Error ``DOCUMENTATION`` or ``RETURN`` contains invalid markup - invalid-documentation-options Documentation Error ``DOCUMENTATION.options`` must be a dictionary/hash when used - invalid-examples Documentation Error ``EXAMPLES`` is not valid YAML - invalid-extension Naming Error Official Ansible modules must have a ``.py`` extension for python modules or a ``.ps1`` for powershell modules - invalid-module-schema Documentation Error ``AnsibleModule`` schema validation error - invalid-removal-version Documentation Error The version at which a feature is supposed to be removed cannot be parsed (for collections, it must be a `semantic version <https://semver.org/>`_) - invalid-requires-extension Naming Error Module ``#AnsibleRequires -CSharpUtil`` should not end in .cs, Module ``#Requires`` should not end in .psm1 - missing-doc-fragment Documentation Error ``DOCUMENTATION`` fragment missing - missing-existing-doc-fragment Documentation Warning Pre-existing ``DOCUMENTATION`` fragment missing - missing-documentation Documentation Error No ``DOCUMENTATION`` provided - missing-examples Documentation Error No ``EXAMPLES`` provided - missing-gplv3-license Documentation Error GPLv3 license header not found - missing-module-utils-basic-import Imports Warning Did not find ``ansible.module_utils.basic`` import - missing-module-utils-import-csharp-requirements Imports Error No ``Ansible.ModuleUtils`` or C# Ansible util requirements/imports found - missing-powershell-interpreter Syntax Error Interpreter line is not ``#!powershell`` - missing-python-interpreter Syntax Error Interpreter line is not ``#!/usr/bin/python`` - missing-return Documentation Error No ``RETURN`` documentation provided - missing-return-legacy Documentation Warning No ``RETURN`` documentation provided for legacy module - missing-suboption-docs Documentation Error Argument in argument_spec has sub-options but documentation does not define sub-options - module-incorrect-version-added Documentation Error Module level ``version_added`` is incorrect - module-invalid-version-added Documentation Error Module level ``version_added`` is not a valid version number - module-utils-specific-import Imports Error ``module_utils`` imports should import specific components, not ``*`` - multiple-utils-per-requires Imports Error ``Ansible.ModuleUtils`` requirements do not support multiple modules per statement - multiple-csharp-utils-per-requires Imports Error Ansible C# util requirements do not support multiple utils per statement - no-default-for-required-parameter Documentation Error Option is marked as required but specifies a default. Arguments with a default should not be marked as required - no-log-needed Parameters Error Option name suggests that the option contains a secret value, while ``no_log`` is not specified for this option in the argument spec. If this is a false positive, explicitly set ``no_log=False`` - nonexistent-parameter-documented Documentation Error Argument is listed in DOCUMENTATION.options, but not accepted by the module - option-incorrect-version-added Documentation Error ``version_added`` for new option is incorrect - option-invalid-version-added Documentation Error ``version_added`` for option is not a valid version number - parameter-invalid Documentation Error Argument in argument_spec is not a valid python identifier - parameter-invalid-elements Documentation Error Value for "elements" is valid only when value of "type" is ``list`` - implied-parameter-type-mismatch Documentation Error Argument_spec implies ``type="str"`` but documentation defines it as different data type - parameter-type-not-in-doc Documentation Error Type value is defined in ``argument_spec`` but documentation doesn't specify a type - parameter-alias-repeated Parameters Error argument in argument_spec has at least one alias specified multiple times in aliases - parameter-alias-self Parameters Error argument in argument_spec is specified as its own alias - parameter-documented-multiple-times Documentation Error argument in argument_spec with aliases is documented multiple times - parameter-list-no-elements Parameters Error argument in argument_spec "type" is specified as ``list`` without defining "elements" - parameter-state-invalid-choice Parameters Error Argument ``state`` includes ``get``, ``list`` or ``info`` as a choice. Functionality should be in an ``_info`` or (if further conditions apply) ``_facts`` module. - python-syntax-error Syntax Error Python ``SyntaxError`` while parsing module - removal-version-must-be-major Documentation Error According to the semantic versioning specification (https://semver.org/), the only versions in which features are allowed to be removed are major versions (x.0.0) - return-syntax-error Documentation Error ``RETURN`` is not valid YAML, ``RETURN`` fragments missing or invalid - return-invalid-version-added Documentation Error ``version_added`` for return value is not a valid version number - subdirectory-missing-init Naming Error Ansible module subdirectories must contain an ``__init__.py`` - try-except-missing-has Imports Warning Try/Except ``HAS_`` expression missing - undocumented-parameter Documentation Error Argument is listed in the argument_spec, but not documented in the module - unidiomatic-typecheck Syntax Error Type comparison using ``type()`` found. Use ``isinstance()`` instead - unknown-doc-fragment Documentation Warning Unknown pre-existing ``DOCUMENTATION`` error - use-boto3 Imports Error ``boto`` import found, new modules should use ``boto3`` - use-fail-json-not-sys-exit Imports Error ``sys.exit()`` call found. Should be ``exit_json``/``fail_json`` - use-module-utils-urls Imports Error ``requests`` import found, should use ``ansible.module_utils.urls`` instead - use-run-command-not-os-call Imports Error ``os.call`` used instead of ``module.run_command`` - use-run-command-not-popen Imports Error ``subprocess.Popen`` used instead of ``module.run_command`` - use-short-gplv3-license Documentation Error GPLv3 license header should be the :ref:`short form <copyright>` for new modules - mutually_exclusive-type Documentation Error mutually_exclusive entry contains non-string value - mutually_exclusive-collision Documentation Error mutually_exclusive entry has repeated terms - mutually_exclusive-unknown Documentation Error mutually_exclusive entry contains option which does not appear in argument_spec (potentially an alias of an option?) - required_one_of-type Documentation Error required_one_of entry contains non-string value - required_one_of-collision Documentation Error required_one_of entry has repeated terms - required_one_of-unknown Documentation Error required_one_of entry contains option which does not appear in argument_spec (potentially an alias of an option?) - required_together-type Documentation Error required_together entry contains non-string value - required_together-collision Documentation Error required_together entry has repeated terms - required_together-unknown Documentation Error required_together entry contains option which does not appear in argument_spec (potentially an alias of an option?) - required_if-is_one_of-type Documentation Error required_if entry has a fourth value which is not a bool - required_if-requirements-type Documentation Error required_if entry has a third value (requirements) which is not a list or tuple - required_if-requirements-collision Documentation Error required_if entry has repeated terms in requirements - required_if-requirements-unknown Documentation Error required_if entry's requirements contains option which does not appear in argument_spec (potentially an alias of an option?) - required_if-unknown-key Documentation Error required_if entry's key does not appear in argument_spec (potentially an alias of an option?) - required_if-key-in-requirements Documentation Error required_if entry contains its key in requirements list/tuple - required_if-value-type Documentation Error required_if entry's value is not of the type specified for its key - required_by-collision Documentation Error required_by entry has repeated terms - required_by-unknown Documentation Error required_by entry contains option which does not appear in argument_spec (potentially an alias of an option?) - version-added-must-be-major-or-minor Documentation Error According to the semantic versioning specification (https://semver.org/), the only versions in which features are allowed to be added are major and minor versions (x.y.0) -============================================================ ================== ==================== ========================================================================================= +This page has moved to :ref:`testing_validate-modules`. diff --git a/docs/docsite/rst/os_guide/windows_setup.rst b/docs/docsite/rst/os_guide/windows_setup.rst index 7baf837e..37ea6093 100644 --- a/docs/docsite/rst/os_guide/windows_setup.rst +++ b/docs/docsite/rst/os_guide/windows_setup.rst @@ -10,23 +10,15 @@ This document discusses the setup that is required before Ansible can communicat Host Requirements ````````````````` For Ansible to communicate to a Windows host and use Windows modules, the -Windows host must meet these requirements: +Windows host must meet these base requirements for connectivity: -* Ansible can generally manage Windows versions under current - and extended support from Microsoft. Ansible can manage desktop OSs including - Windows 8.1, and 10, and server OSs including Windows Server 2012, 2012 R2, - 2016, 2019, and 2022. +* With Ansible you can generally manage Windows versions under the current and extended support from Microsoft. You can also manage desktop OSs including Windows 8.1, and 10, and server OSs including Windows Server 2012, 2012 R2, 2016, 2019, and 2022. -* Ansible requires PowerShell 3.0 or newer and at least .NET 4.0 to be - installed on the Windows host. +* You need to install PowerShell 3.0 or newer and at least .NET 4.0 on the Windows host. -* A WinRM listener should be created and activated. More details for this can be - found below. +* You need to create and activate a WinRM listener. More details, see `WinRM Setup <https://docs.ansible.com/ansible/latest//user_guide/windows_setup.html#winrm-listener>`_. -.. Note:: While these are the base requirements for Ansible connectivity, some Ansible - modules have additional requirements, such as a newer OS or PowerShell - version. Please consult the module's documentation page - to determine whether a host meets those requirements. +.. Note:: Some Ansible modules have additional requirements, such as a newer OS or PowerShell version. Consult the module documentation page to determine whether a host meets those requirements. Upgrading PowerShell and .NET Framework --------------------------------------- @@ -46,53 +38,44 @@ This is an example of how to run this script from PowerShell: (New-Object -TypeName System.Net.WebClient).DownloadFile($url, $file) Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Force - # Version can be 3.0, 4.0 or 5.1 &$file -Version 5.1 -Username $username -Password $password -Verbose -Once completed, you will need to remove auto logon -and set the execution policy back to the default (``Restricted `` for Windows clients, or ``RemoteSigned`` for Windows servers). You can -do this with the following PowerShell commands: +In the script, the ``file`` value can be the PowerShell version 3.0, 4.0, or 5.1. +Once completed, you need to run the following PowerShell commands: + +1. As an optional but good security practice, you can set the execution policy back to the default. + .. code-block:: powershell - # This isn't needed but is a good security practice to complete Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Force +Use the ``RemoteSigned`` value for Windows servers, or ``Restricted`` for Windows clients. + +2. Remove the auto logon. + +.. code-block:: powershell + $reg_winlogon_path = "HKLM:\Software\Microsoft\Windows NT\CurrentVersion\Winlogon" Set-ItemProperty -Path $reg_winlogon_path -Name AutoAdminLogon -Value 0 Remove-ItemProperty -Path $reg_winlogon_path -Name DefaultUserName -ErrorAction SilentlyContinue Remove-ItemProperty -Path $reg_winlogon_path -Name DefaultPassword -ErrorAction SilentlyContinue -The script works by checking to see what programs need to be installed -(such as .NET Framework 4.5.2) and what PowerShell version is required. If a reboot -is required and the ``username`` and ``password`` parameters are set, the -script will automatically reboot and logon when it comes back up from the -reboot. The script will continue until no more actions are required and the -PowerShell version matches the target version. If the ``username`` and -``password`` parameters are not set, the script will prompt the user to -manually reboot and logon when required. When the user is next logged in, the -script will continue where it left off and the process continues until no more +The script determines what programs you need to install (such as .NET Framework 4.5.2) and what PowerShell version needs to be present. If a reboot is needed and the ``username`` and ``password`` parameters are set, the script will automatically reboot the machine and then logon. If the ``username`` and ``password`` parameters are not set, the script will prompt the user to manually reboot and logon when required. When the user is next logged in, the script will continue where it left off and the process continues until no more actions are required. -.. Note:: If running on Server 2008, then SP2 must be installed. If running on - Server 2008 R2 or Windows 7, then SP1 must be installed. +.. Note:: If you run the script on Server 2008, then you need to install SP2. For Server 2008 R2 or Windows 7 you need SP1. + + On Windows Server 2008 you can install only PowerShell 3.0. A newer version will result in the script failure. -.. Note:: Windows Server 2008 can only install PowerShell 3.0; specifying a - newer version will result in the script failing. + The ``username`` and ``password`` parameters are stored in plain text in the registry. Run the cleanup commands after the script finishes to ensure no credentials are stored on the host. -.. Note:: The ``username`` and ``password`` parameters are stored in plain text - in the registry. Make sure the cleanup commands are run after the script finishes - to ensure no credentials are still stored on the host. WinRM Memory Hotfix ------------------- -When running on PowerShell v3.0, there is a bug with the WinRM service that -limits the amount of memory available to WinRM. Without this hotfix installed, -Ansible will fail to execute certain commands on the Windows host. These -hotfixes should be installed as part of the system bootstrapping or -imaging process. The script `Install-WMF3Hotfix.ps1 <https://github.com/jborean93/ansible-windows/blob/master/scripts/Install-WMF3Hotfix.ps1>`_ can be used to install the hotfix on affected hosts. +On PowerShell v3.0, there is a bug that limits the amount of memory available to the WinRM service. Use the `Install-WMF3Hotfix.ps1 <https://github.com/jborean93/ansible-windows/blob/master/scripts/Install-WMF3Hotfix.ps1>`_ script to install a hotfix on affected hosts as part of the system bootstrapping or imaging process. Without this hotfix, Ansible fails to execute certain commands on the Windows host. -The following PowerShell command will install the hotfix: +To install the hotfix: .. code-block:: powershell @@ -103,22 +86,17 @@ The following PowerShell command will install the hotfix: (New-Object -TypeName System.Net.WebClient).DownloadFile($url, $file) powershell.exe -ExecutionPolicy ByPass -File $file -Verbose -For more details, please refer to the `Hotfix document <https://support.microsoft.com/en-us/help/2842230/out-of-memory-error-on-a-computer-that-has-a-customized-maxmemorypersh>`_ from Microsoft. +For more details, refer to the `"Out of memory" error on a computer that has a customized MaxMemoryPerShellMB quota set and has WMF 3.0 installed <https://support.microsoft.com/en-us/help/2842230/out-of-memory-error-on-a-computer-that-has-a-customized-maxmemorypersh>`_ article. WinRM Setup ``````````` -Once Powershell has been upgraded to at least version 3.0, the final step is to -configure the WinRM service so that Ansible can connect to it. There are two -main components of the WinRM service that governs how Ansible can interface with -the Windows host: the ``listener`` and the ``service`` configuration settings. +You need to configure the WinRM service so that Ansible can connect to it. There are two main components of the WinRM service that governs how Ansible can interface with the Windows host: the ``listener`` and the ``service`` configuration settings. WinRM Listener -------------- -The WinRM services listens for requests on one or more ports. Each of these ports must have a -listener created and configured. +The WinRM services listen for requests on one or more ports. Each of these ports must have a listener created and configured. -To view the current listeners that are running on the WinRM service, run the -following command: +To view the current listeners that are running on the WinRM service: .. code-block:: powershell @@ -150,26 +128,15 @@ This will output something like: ListeningOn = 10.0.2.15, 127.0.0.1, 192.168.56.155, ::1, fe80::5efe:10.0.2.15%6, fe80::5efe:192.168.56.155%8, fe80:: ffff:ffff:fffe%2, fe80::203d:7d97:c2ed:ec78%3, fe80::e8ea:d765:2c69:7756%7 -In the example above there are two listeners activated; one is listening on -port 5985 over HTTP and the other is listening on port 5986 over HTTPS. Some of -the key options that are useful to understand are: +In the example above there are two listeners activated. One is listening on port 5985 over HTTP and the other is listening on port 5986 over HTTPS. Some of the key options that are useful to understand are: -* ``Transport``: Whether the listener is run over HTTP or HTTPS, it is - recommended to use a listener over HTTPS as the data is encrypted without - any further changes required. +* ``Transport``: Whether the listener is run over HTTP or HTTPS. We recommend you use a listener over HTTPS because the data is encrypted without any further changes required. -* ``Port``: The port the listener runs on, by default it is ``5985`` for HTTP - and ``5986`` for HTTPS. This port can be changed to whatever is required and - corresponds to the host var ``ansible_port``. +* ``Port``: The port the listener runs on. By default it is ``5985`` for HTTP and ``5986`` for HTTPS. This port can be changed to whatever is required and corresponds to the host var ``ansible_port``. -* ``URLPrefix``: The URL prefix to listen on, by default it is ``wsman``. If - this is changed, the host var ``ansible_winrm_path`` must be set to the same - value. +* ``URLPrefix``: The URL prefix to listen on. By default it is ``wsman``. If you change this option, you need to set the host var ``ansible_winrm_path`` to the same value. -* ``CertificateThumbprint``: If running over an HTTPS listener, this is the - thumbprint of the certificate in the Windows Certificate Store that is used - in the connection. To get the details of the certificate itself, run this - command with the relevant certificate thumbprint in PowerShell: +* ``CertificateThumbprint``: If you use an HTTPS listener, this is the thumbprint of the certificate in the Windows Certificate Store that is used in the connection. To get the details of the certificate itself, run this command with the relevant certificate thumbprint in PowerShell: .. code-block:: powershell @@ -180,19 +147,11 @@ Setup WinRM Listener ++++++++++++++++++++ There are three ways to set up a WinRM listener: -* Using ``winrm quickconfig`` for HTTP or - ``winrm quickconfig -transport:https`` for HTTPS. This is the easiest option - to use when running outside of a domain environment and a simple listener is - required. Unlike the other options, this process also has the added benefit of - opening up the Firewall for the ports required and starts the WinRM service. +* Using ``winrm quickconfig`` for HTTP or ``winrm quickconfig -transport:https`` for HTTPS. This is the easiest option to use when running outside of a domain environment and a simple listener is required. Unlike the other options, this process also has the added benefit of opening up the firewall for the ports required and starts the WinRM service. -* Using Group Policy Objects. This is the best way to create a listener when the - host is a member of a domain because the configuration is done automatically - without any user input. For more information on group policy objects, see the - `Group Policy Objects documentation <https://msdn.microsoft.com/en-us/library/aa374162(v=vs.85).aspx>`_. +* Using Group Policy Objects (GPO). This is the best way to create a listener when the host is a member of a domain because the configuration is done automatically without any user input. For more information on group policy objects, see the `Group Policy Objects documentation <https://msdn.microsoft.com/en-us/library/aa374162(v=vs.85).aspx>`_. -* Using PowerShell to create the listener with a specific configuration. This - can be done by running the following PowerShell commands: +* Using PowerShell to create a listener with a specific configuration. This can be done by running the following PowerShell commands: .. code-block:: powershell @@ -206,36 +165,32 @@ There are three ways to set up a WinRM listener: New-WSManInstance -ResourceURI "winrm/config/Listener" -SelectorSet $selector_set -ValueSet $value_set - To see the other options with this PowerShell cmdlet, see - `New-WSManInstance <https://docs.microsoft.com/en-us/powershell/module/microsoft.wsman.management/new-wsmaninstance?view=powershell-5.1>`_. + To see the other options with this PowerShell command, refer to the + `New-WSManInstance <https://docs.microsoft.com/en-us/powershell/module/microsoft.wsman.management/new-wsmaninstance?view=powershell-5.1>`_ documentation. -.. Note:: When creating an HTTPS listener, an existing certificate needs to be - created and stored in the ``LocalMachine\My`` certificate store. Without a - certificate being present in this store, most commands will fail. +.. Note:: When creating an HTTPS listener, you must create and store a certificate in the ``LocalMachine\My`` certificate store. Delete WinRM Listener +++++++++++++++++++++ -To remove a WinRM listener: +* To remove all WinRM listeners: .. code-block:: powershell - # Remove all listeners Remove-Item -Path WSMan:\localhost\Listener\* -Recurse -Force - # Only remove listeners that are run over HTTPS +* To remove only those listeners that run over HTTPS: + +.. code-block:: powershell + Get-ChildItem -Path WSMan:\localhost\Listener | Where-Object { $_.Keys -contains "Transport=HTTPS" } | Remove-Item -Recurse -Force -.. Note:: The ``Keys`` object is an array of strings, so it can contain different - values. By default it contains a key for ``Transport=`` and ``Address=`` - which correspond to the values from winrm enumerate winrm/config/Listeners. +.. Note:: The ``Keys`` object is an array of strings, so it can contain different values. By default, it contains a key for ``Transport=`` and ``Address=`` which correspond to the values from the ``winrm enumerate winrm/config/Listeners`` command. WinRM Service Options --------------------- -There are a number of options that can be set to control the behavior of the WinRM service component, -including authentication options and memory settings. +You can control the behavior of the WinRM service component, including authentication options and memory settings. -To get an output of the current service configuration options, run the -following command: +To get an output of the current service configuration options, run the following command: .. code-block:: powershell @@ -280,79 +235,71 @@ This will output something like: MaxMemoryPerShellMB = 2147483647 MaxShellsPerUser = 2147483647 -While many of these options should rarely be changed, a few can easily impact -the operations over WinRM and are useful to understand. Some of the important -options are: +You do not need to change the majority of these options. However, some of the important ones to know about are: -* ``Service\AllowUnencrypted``: This option defines whether WinRM will allow - traffic that is run over HTTP without message encryption. Message level - encryption is only possible when ``ansible_winrm_transport`` is ``ntlm``, - ``kerberos`` or ``credssp``. By default this is ``false`` and should only be - set to ``true`` when debugging WinRM messages. +* ``Service\AllowUnencrypted`` - specifies whether WinRM will allow HTTP traffic without message encryption. Message level encryption is only possible when the ``ansible_winrm_transport`` variable is ``ntlm``, ``kerberos`` or ``credssp``. By default, this is ``false`` and you should only set it to ``true`` when debugging WinRM messages. -* ``Service\Auth\*``: These flags define what authentication - options are allowed with the WinRM service. By default, ``Negotiate (NTLM)`` - and ``Kerberos`` are enabled. +* ``Service\Auth\*`` - defines what authentication options you can use with the WinRM service. By default, ``Negotiate (NTLM)`` and ``Kerberos`` are enabled. -* ``Service\Auth\CbtHardeningLevel``: Specifies whether channel binding tokens are - not verified (None), verified but not required (Relaxed), or verified and - required (Strict). CBT is only used when connecting with NTLM or Kerberos - over HTTPS. +* ``Service\Auth\CbtHardeningLevel`` - specifies whether channel binding tokens are not verified (None), verified but not required (Relaxed), or verified and required (Strict). CBT is only used when connecting with NT LAN Manager (NTLM) or Kerberos over HTTPS. -* ``Service\CertificateThumbprint``: This is the thumbprint of the certificate - used to encrypt the TLS channel used with CredSSP authentication. By default - this is empty; a self-signed certificate is generated when the WinRM service - starts and is used in the TLS process. +* ``Service\CertificateThumbprint`` - thumbprint of the certificate for encrypting the TLS channel used with CredSSP authentication. By default, this is empty. A self-signed certificate is generated when the WinRM service starts and is used in the TLS process. -* ``Winrs\MaxShellRunTime``: This is the maximum time, in milliseconds, that a - remote command is allowed to execute. +* ``Winrs\MaxShellRunTime`` - maximum time, in milliseconds, that a remote command is allowed to execute. -* ``Winrs\MaxMemoryPerShellMB``: This is the maximum amount of memory allocated - per shell, including the shell's child processes. +* ``Winrs\MaxMemoryPerShellMB`` - maximum amount of memory allocated per shell, including its child processes. -To modify a setting under the ``Service`` key in PowerShell: +To modify a setting under the ``Service`` key in PowerShell, you need to provide a path to the option after ``winrm/config/Service``: .. code-block:: powershell - # substitute {path} with the path to the option after winrm/config/Service - Set-Item -Path WSMan:\localhost\Service\{path} -Value "value here" + Set-Item -Path WSMan:\localhost\Service\{path} -Value {some_value} + +For example, to change ``Service\Auth\CbtHardeningLevel``: + +.. code-block:: powershell - # for example, to change Service\Auth\CbtHardeningLevel run Set-Item -Path WSMan:\localhost\Service\Auth\CbtHardeningLevel -Value Strict -To modify a setting under the ``Winrs`` key in PowerShell: +To modify a setting under the ``Winrs`` key in PowerShell, you need to provide a path to the option after ``winrm/config/Winrs``: .. code-block:: powershell - # Substitute {path} with the path to the option after winrm/config/Winrs - Set-Item -Path WSMan:\localhost\Shell\{path} -Value "value here" + Set-Item -Path WSMan:\localhost\Shell\{path} -Value {some_value} + +For example, to change ``Winrs\MaxShellRunTime``: + +.. code-block:: powershell - # For example, to change Winrs\MaxShellRunTime run Set-Item -Path WSMan:\localhost\Shell\MaxShellRunTime -Value 2147483647 -.. Note:: If running in a domain environment, some of these options are set by - GPO and cannot be changed on the host itself. When a key has been - configured with GPO, it contains the text ``[Source="GPO"]`` next to the value. +.. Note:: If you run the command in a domain environment, some of these options are set by + GPO and cannot be changed on the host itself. When you configured a key with GPO, it contains the text ``[Source="GPO"]`` next to the value. Common WinRM Issues ------------------- -Because WinRM has a wide range of configuration options, it can be difficult -to setup and configure. Because of this complexity, issues that are shown by Ansible -could in fact be issues with the host setup instead. +WinRM has a wide range of configuration options, which makes its configuration complex. As a result, errors that Ansible displays could in fact be problems with the host setup instead. -One easy way to determine whether a problem is a host issue is to -run the following command from another Windows host to connect to the -target Windows host: +To identify a host issue, run the following command from another Windows host to connect to the target Windows host. + +* To test HTTP: .. code-block:: powershell - # Test out HTTP winrs -r:http://server:5985/wsman -u:Username -p:Password ipconfig - # Test out HTTPS (will fail if the cert is not verifiable) +* To test HTTPS: + +.. code-block:: powershell + winrs -r:https://server:5986/wsman -u:Username -p:Password -ssl ipconfig - # Test out HTTPS, ignoring certificate verification +The command will fail if the certificate is not verifiable. + +* To test HTTPS ignoring certificate verification: + +.. code-block:: powershell + $username = "Username" $password = ConvertTo-SecureString -String "Password" -AsPlainText -Force $cred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $username, $password @@ -360,82 +307,67 @@ target Windows host: $session_option = New-PSSessionOption -SkipCACheck -SkipCNCheck -SkipRevocationCheck Invoke-Command -ComputerName server -UseSSL -ScriptBlock { ipconfig } -Credential $cred -SessionOption $session_option -If this fails, the issue is probably related to the WinRM setup. If it works, the issue may not be related to the WinRM setup; please continue reading for more troubleshooting suggestions. +If any of the above commands fail, the issue is probably related to the WinRM setup. HTTP 401/Credentials Rejected +++++++++++++++++++++++++++++ -A HTTP 401 error indicates the authentication process failed during the initial -connection. Some things to check for this are: +An HTTP 401 error indicates the authentication process failed during the initial +connection. You can check the following to troubleshoot: -* Verify that the credentials are correct and set properly in your inventory with - ``ansible_user`` and ``ansible_password`` +* The credentials are correct and set properly in your inventory with the ``ansible_user`` and ``ansible_password`` variables. -* Ensure that the user is a member of the local Administrators group or has been explicitly - granted access (a connection test with the ``winrs`` command can be used to - rule this out). +* The user is a member of the local Administrators group, or has been explicitly granted access. You can perform a connection test with the ``winrs`` command to rule this out. -* Make sure that the authentication option set by ``ansible_winrm_transport`` is enabled under - ``Service\Auth\*`` +* The authentication option set by the ``ansible_winrm_transport`` variable is enabled under ``Service\Auth\*``. -* If running over HTTP and not HTTPS, use ``ntlm``, ``kerberos`` or ``credssp`` - with ``ansible_winrm_message_encryption: auto`` to enable message encryption. - If using another authentication option or if the installed pywinrm version cannot be - upgraded, the ``Service\AllowUnencrypted`` can be set to ``true`` but this is - only recommended for troubleshooting +* If running over HTTP and not HTTPS, use ``ntlm``, ``kerberos`` or ``credssp`` with the ``ansible_winrm_message_encryption: auto`` custom inventory variable to enable message encryption. If you use another authentication option, or if it is not possible to upgrade the installed ``pywinrm`` package, you can set ``Service\AllowUnencrypted`` to ``true``. This is recommended only for troubleshooting. -* Ensure the downstream packages ``pywinrm``, ``requests-ntlm``, - ``requests-kerberos``, and/or ``requests-credssp`` are up to date using ``pip``. +* The downstream packages ``pywinrm``, ``requests-ntlm``, ``requests-kerberos``, and/or ``requests-credssp`` are up to date using ``pip``. -* If using Kerberos authentication, ensure that ``Service\Auth\CbtHardeningLevel`` is - not set to ``Strict``. +* For Kerberos authentication, ensure that ``Service\Auth\CbtHardeningLevel`` is not set to ``Strict``. -* When using Basic or Certificate authentication, make sure that the user is a local account and - not a domain account. Domain accounts do not work with Basic and Certificate - authentication. +* For Basic or Certificate authentication, make sure that the user is a local account. Domain accounts do not work with Basic and Certificate authentication. HTTP 500 Error ++++++++++++++ -These indicate an error has occurred with the WinRM service. Some things -to check for include: +An HTTP 500 error indicates a problem with the WinRM service. You can check the following to troubleshoot: -* Verify that the number of current open shells has not exceeded either - ``WinRsMaxShellsPerUser`` or any of the other Winrs quotas haven't been - exceeded. +* The number of your currently open shells has not exceeded either ``WinRsMaxShellsPerUser``. Alternatively, you did not exceed any of the other Winrs quotas. Timeout Errors +++++++++++++++ -These usually indicate an error with the network connection where -Ansible is unable to reach the host. Some things to check for include: +Sometimes Ansible is unable to reach the host. These instances usually indicate a problem with the network connection. You can check the following to troubleshoot: -* Make sure the firewall is not set to block the configured WinRM listener ports -* Ensure that a WinRM listener is enabled on the port and path set by the host vars -* Ensure that the ``winrm`` service is running on the Windows host and configured for - automatic start +* The firewall is not set to block the configured WinRM listener ports. +* A WinRM listener is enabled on the port and path set by the host vars. +* The ``winrm`` service is running on the Windows host and is configured for the automatic start. Connection Refused Errors +++++++++++++++++++++++++ -These usually indicate an error when trying to communicate with the -WinRM service on the host. Some things to check for: +When you communicate with the WinRM service on the host you can encounter some problems. Check the following to help the troubleshooting: -* Ensure that the WinRM service is up and running on the host. Use - ``(Get-Service -Name winrm).Status`` to get the status of the service. -* Check that the host firewall is allowing traffic over the WinRM port. By default - this is ``5985`` for HTTP and ``5986`` for HTTPS. +* The WinRM service is up and running on the host. Use the ``(Get-Service -Name winrm).Status`` command to get the status of the service. +* The host firewall is allowing traffic over the WinRM port. By default this is ``5985`` for HTTP and ``5986`` for HTTPS. -Sometimes an installer may restart the WinRM or HTTP service and cause this error. The -best way to deal with this is to use ``win_psexec`` from another -Windows host. +Sometimes an installer may restart the WinRM or HTTP service and cause this error. The best way to deal with this is to use the ``win_psexec`` module from another Windows host. Failure to Load Builtin Modules +++++++++++++++++++++++++++++++ -If powershell fails with an error message similar to ``The 'Out-String' command was found in the module 'Microsoft.PowerShell.Utility', but the module could not be loaded.`` -then there could be a problem trying to access all the paths specified by the ``PSModulePath`` environment variable. -A common cause of this issue is that the ``PSModulePath`` environment variable contains a UNC path to a file share and -because of the double hop/credential delegation issue the Ansible process cannot access these folders. The way around -this problems is to either: +Sometimes PowerShell fails with an error message similar to: + +.. code-block:: powershell + + The 'Out-String' command was found in the module 'Microsoft.PowerShell.Utility', but the module could not be loaded. + +In that case, there could be a problem when trying to access all the paths specified by the ``PSModulePath`` environment variable. + +A common cause of this issue is that ``PSModulePath`` contains a Universal Naming Convention (UNC) path to a file share. Additionally, the double hop/credential delegation issue causes that the Ansible process cannot access these folders. To work around this problem is to either: + +* Remove the UNC path from ``PSModulePath``. + +or -* Remove the UNC path from the ``PSModulePath`` environment variable, or -* Use an authentication option that supports credential delegation like ``credssp`` or ``kerberos`` with credential delegation enabled +* Use an authentication option that supports credential delegation like ``credssp`` or ``kerberos``. You need to have the credential delegation enabled. See `KB4076842 <https://support.microsoft.com/en-us/help/4076842>`_ for more information on this problem. @@ -444,36 +376,29 @@ Windows SSH Setup Ansible 2.8 has added an experimental SSH connection for Windows managed nodes. .. warning:: - Use this feature at your own risk! - Using SSH with Windows is experimental, the implementation may make - backwards incompatible changes in feature releases. The server side - components can be unreliable depending on the version that is installed. + Use this feature at your own risk! Using SSH with Windows is experimental. This implementation may make + backwards incompatible changes in future releases. The server-side components can be unreliable depending on your installed version. Installing OpenSSH using Windows Settings ----------------------------------------- -OpenSSH can be used to connect Window 10 clients to Windows Server 2019. -OpenSSH Client is available to install on Windows 10 build 1809 and later, while OpenSSH Server is available to install on Windows Server 2019 and later. +You can use OpenSSH to connect Window 10 clients to Windows Server 2019. OpenSSH Client is available to install on Windows 10 build 1809 and later. OpenSSH Server is available to install on Windows Server 2019 and later. -Please refer `this guide <https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse>`_. +For more information, refer to `Get started with OpenSSH for Windows <https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse>`_. Installing Win32-OpenSSH ------------------------ -The first step to using SSH with Windows is to install the `Win32-OpenSSH <https://github.com/PowerShell/Win32-OpenSSH>`_ -service on the Windows host. Microsoft offers a way to install ``Win32-OpenSSH`` through a Windows -capability but currently the version that is installed through this process is -too old to work with Ansible. To install ``Win32-OpenSSH`` for use with +To install the `Win32-OpenSSH <https://github.com/PowerShell/Win32-OpenSSH>`_ service for use with Ansible, select one of these installation options: -* Manually install the service, following the `install instructions <https://github.com/PowerShell/Win32-OpenSSH/wiki/Install-Win32-OpenSSH>`_ - from Microsoft. +* Manually install ``Win32-OpenSSH``, following the `install instructions <https://github.com/PowerShell/Win32-OpenSSH/wiki/Install-Win32-OpenSSH>`_ from Microsoft. -* Install the `openssh <https://chocolatey.org/packages/openssh>`_ package using Chocolatey: +* Use Chocolatey: .. code-block:: powershell choco install --package-parameters=/SSHServerFeature openssh -* Use ``win_chocolatey`` to install the service +* Use the ``win_chocolatey`` Ansible module: .. code-block:: yaml @@ -483,16 +408,16 @@ Ansible, select one of these installation options: package_params: /SSHServerFeature state: present -* Use an existing Ansible Galaxy role like `jborean93.win_openssh <https://galaxy.ansible.com/jborean93/win_openssh>`_: +* Install an Ansible Galaxy role for example `jborean93.win_openssh <https://galaxy.ansible.com/jborean93/win_openssh>`_: .. code-block:: powershell - # Make sure the role has been downloaded first ansible-galaxy install jborean93.win_openssh +* Use the role in your playbook: + .. code-block:: yaml - # main.yml - name: install Win32-OpenSSH service hosts: windows gather_facts: false @@ -500,16 +425,14 @@ Ansible, select one of these installation options: - role: jborean93.win_openssh opt_openssh_setup_service: True -.. note:: ``Win32-OpenSSH`` is still a beta product and is constantly - being updated to include new features and bugfixes. If you are using SSH as - a connection option for Windows, it is highly recommend you install the - latest release from one of the 3 methods above. +.. note:: ``Win32-OpenSSH`` is still a beta product and is constantly being updated to include new features and bugfixes. If you use SSH as a connection option for Windows, we highly recommend you install the latest version. Configuring the Win32-OpenSSH shell ----------------------------------- -By default ``Win32-OpenSSH`` will use ``cmd.exe`` as a shell. To configure a -different shell, use an Ansible task to define the registry setting: +By default ``Win32-OpenSSH`` uses ``cmd.exe`` as a shell. + +* To configure a different shell, use an Ansible playbook with a task to define the registry setting: .. code-block:: yaml @@ -521,7 +444,10 @@ different shell, use an Ansible task to define the registry setting: type: string state: present - # Or revert the settings back to the default, cmd +* To revert the settings back to the default shell: + +.. code-block:: yaml + - name: set the default shell to cmd win_regedit: path: HKLM:\SOFTWARE\OpenSSH @@ -530,20 +456,18 @@ different shell, use an Ansible task to define the registry setting: Win32-OpenSSH Authentication ---------------------------- -Win32-OpenSSH authentication with Windows is similar to SSH -authentication on Unix/Linux hosts. You can use a plaintext password or -SSH public key authentication, add public keys to an ``authorized_key`` file -in the ``.ssh`` folder of the user's profile directory, and configure the -service using the ``sshd_config`` file used by the SSH service as you would on -a Unix/Linux host. +Win32-OpenSSH authentication with Windows is similar to SSH authentication on Unix/Linux hosts. You can use a plaintext password or SSH public key authentication. + +For the key-based authentication: + +* Add your public keys to an ``authorized_key`` file in the ``.ssh`` folder of the user's profile directory. + +* Configure the SSH service using the ``sshd_config`` file. -When using SSH key authentication with Ansible, the remote session won't have access to the -user's credentials and will fail when attempting to access a network resource. -This is also known as the double-hop or credential delegation issue. There are -two ways to work around this issue: +When using SSH key authentication with Ansible, the remote session will not have access to user credentials and will fail when attempting to access a network resource. This is also known as the double-hop or credential delegation issue. To work around this problem: -* Use plaintext password auth by setting ``ansible_password`` -* Use ``become`` on the task with the credentials of the user that needs access to the remote resource +* Use plaintext password authentication by setting the ``ansible_password`` variable. +* Use the ``become`` directive on the task with the credentials of the user that needs access to the remote resource. Configuring Ansible for SSH on Windows -------------------------------------- @@ -552,17 +476,14 @@ To configure Ansible to use SSH for Windows hosts, you must set two connection v * set ``ansible_connection`` to ``ssh`` * set ``ansible_shell_type`` to ``cmd`` or ``powershell`` -The ``ansible_shell_type`` variable should reflect the ``DefaultShell`` -configured on the Windows host. Set to ``cmd`` for the default shell or set to -``powershell`` if the ``DefaultShell`` has been changed to PowerShell. +The ``ansible_shell_type`` variable should reflect the ``DefaultShell`` configured on the Windows host. Set ``ansible_shell_type`` to ``cmd`` for the default shell. Alternatively, set ``ansible_shell_type`` to ``powershell`` if you changed ``DefaultShell`` to PowerShell. Known issues with SSH on Windows -------------------------------- -Using SSH with Windows is experimental, and we expect to uncover more issues. -Here are the known ones: +Using SSH with Windows is experimental. Currently existing issues are: -* Win32-OpenSSH versions older than ``v7.9.0.0p1-Beta`` do not work when ``powershell`` is the shell type -* While SCP should work, SFTP is the recommended SSH file transfer mechanism to use when copying or fetching a file +* Win32-OpenSSH versions older than ``v7.9.0.0p1-Beta`` do not work when ``powershell`` is the shell type. +* While Secure Copy Protocol (SCP) should work, SSH File Transfer Protocol (SFTP) is the recommended mechanism to use when copying or fetching a file. .. seealso:: diff --git a/docs/docsite/rst/os_guide/windows_winrm.rst b/docs/docsite/rst/os_guide/windows_winrm.rst index dc95e8e0..242cd1f7 100644 --- a/docs/docsite/rst/os_guide/windows_winrm.rst +++ b/docs/docsite/rst/os_guide/windows_winrm.rst @@ -5,7 +5,7 @@ Windows Remote Management Unlike Linux/Unix hosts, which use SSH by default, Windows hosts are configured with WinRM. This topic covers how to configure and use WinRM with Ansible. -.. contents:: +.. contents:: :local: :depth: 2 @@ -117,6 +117,8 @@ be enabled by running the following in PowerShell: .. Note:: Encrypted private keys cannot be used as the urllib3 library that is used by Ansible for WinRM does not support this functionality. +.. Note:: Certificate authentication does not work with a TLS 1.3 connection. + .._winrm_certificate_generate: Generate a Certificate @@ -633,7 +635,7 @@ The WinRM protocol considers the channel to be encrypted if using TLS over HTTP recommended option as it works with all authentication options, but requires a certificate to be created and used on the WinRM listener. -If in a domain environment, ADCS can create a certificate for the host that +If in a domain environment, ADCS can create a certificate for the host that is issued by the domain itself. If using HTTPS is not an option, then HTTP can be used when the authentication diff --git a/docs/docsite/rst/playbook_guide/complex_data_manipulation.rst b/docs/docsite/rst/playbook_guide/complex_data_manipulation.rst index 2f508e48..f94fb88f 100644 --- a/docs/docsite/rst/playbook_guide/complex_data_manipulation.rst +++ b/docs/docsite/rst/playbook_guide/complex_data_manipulation.rst @@ -35,7 +35,7 @@ Use a loop to create exponential backoff for retries/until. ping: retries: 10 delay: '{{item|int}}' - loop: '{{ range(1, 10)|map('pow', 2) }}' + loop: '{{ range(1, 10)|map("pow", 2) }}' .. _keys_from_dict_matching_list: diff --git a/docs/docsite/rst/playbook_guide/playbook_pathing.rst b/docs/docsite/rst/playbook_guide/playbook_pathing.rst index d52f3a70..a049ef0f 100644 --- a/docs/docsite/rst/playbook_guide/playbook_pathing.rst +++ b/docs/docsite/rst/playbook_guide/playbook_pathing.rst @@ -14,6 +14,7 @@ Config paths By default these should be relative to the config file, some are specifically relative to the current working directory or the playbook and should have this noted in their description. Things like ssh keys are left to use the current working directory because it mirrors how the underlying tools would use it. +.. _playbook_task_paths: Task paths ========== diff --git a/docs/docsite/rst/playbook_guide/playbooks_filters.rst b/docs/docsite/rst/playbook_guide/playbooks_filters.rst index 1b5a7d1b..6063c061 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_filters.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_filters.rst @@ -2061,6 +2061,8 @@ As of version 2.6, you can define the type of encoding to use, the default is `` .. note:: The ``string`` filter is only required for Python 2 and ensures that text to encode is a unicode string. Without that filter before b64encode the wrong value will be encoded. +.. note:: The return value of b64decode is a string. If you decrypt a binary blob using b64decode and then try to use it (for example by using :ref:`copy <copy_module>` to write it to a file) you will mostly likely find that your binary has been corrupted. If you need to take a base64 encoded binary and write it to disk, it is best to use the system ``base64`` command with the :ref:`shell module <shell_module>`, piping in the encoded data using the ``stdin`` parameter. For example: ``shell: cmd="base64 --decode > myfile.bin" stdin="{{ encoded }}"`` + .. versionadded:: 2.6 Managing UUIDs diff --git a/docs/docsite/rst/playbook_guide/shared_snippets/with2loop.txt b/docs/docsite/rst/playbook_guide/shared_snippets/with2loop.txt index 5217f942..c563dcec 100644 --- a/docs/docsite/rst/playbook_guide/shared_snippets/with2loop.txt +++ b/docs/docsite/rst/playbook_guide/shared_snippets/with2loop.txt @@ -146,9 +146,10 @@ with_sequence - name: with_sequence -> loop ansible.builtin.debug: msg: "{{ 'testuser%02x' | format(item) }}" - # range is exclusive of the end point loop: "{{ range(0, 4 + 1, 2)|list }}" +The range of the loop is exclusive of the end point. + with_subelements ---------------- diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.0.rst b/docs/docsite/rst/porting_guides/porting_guide_2.0.rst index 9efa1b81..876ca5e2 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.0.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.0.rst @@ -21,16 +21,26 @@ Playbook This section discusses any changes you may need to make to your playbooks. +* Syntax in 1.9.x + .. code-block:: yaml - # Syntax in 1.9.x - debug: msg: "{{ 'test1_junk 1\\\\3' | regex_replace('(.*)_junk (.*)', '\\\\1 \\\\2') }}" - # Syntax in 2.0.x + + +* Syntax in 2.0.x + +.. code-block:: yaml + - debug: msg: "{{ 'test1_junk 1\\3' | regex_replace('(.*)_junk (.*)', '\\1 \\2') }}" - # Output: + +* Output: + +.. code-block:: yaml + "msg": "test1 1\\3" To make an escaped string that will work on all versions you have two options:: @@ -48,7 +58,11 @@ uses key=value escaping which has not changed. The other option is to check for relied on the trailing newline being stripped, you can change your playbook using the following as an example:: - # Syntax in 1.9.x + + * Syntax in 1.9.x + + .. code-block:: yaml + vars: message: > Testing @@ -57,7 +71,11 @@ uses key=value escaping which has not changed. The other option is to check for - debug: msg: "{{ message }}" - # Syntax in 2.0.x + + * Syntax in 2.0.x + + .. code-block:: yaml + vars: old_message: > Testing @@ -65,7 +83,12 @@ uses key=value escaping which has not changed. The other option is to check for message: "{{ old_message[:-1] }}" - debug: msg: "{{ message }}" - # Output + + + * Output + + .. code-block:: yaml + "msg": "Testing some things" * Behavior of templating DOS-type text files changes with Ansible v2. @@ -75,7 +98,9 @@ uses key=value escaping which has not changed. The other option is to check for * When specifying complex args as a variable, the variable must use the full jinja2 variable syntax (```{{var_name}}```) - bare variable names there are no longer accepted. In fact, even specifying args with variables has been deprecated, and will not be - allowed in future versions:: + allowed in future versions: + +.. code-block:: yaml --- - hosts: localhost @@ -87,7 +112,7 @@ uses key=value escaping which has not changed. The other option is to check for - { path: /tmp/3b, state: directory, mode: 0700 } tasks: - file: - args: "{{item}}" # <- args here uses the full variable syntax + args: "{{item}}" with_items: "{{my_dirs}}" * porting task includes @@ -111,7 +136,9 @@ While all items listed here will show a deprecation warning message, they still * Bare variables in ``with_`` loops should instead use the ``"{{ var }}"`` syntax, which helps eliminate ambiguity. * The ansible-galaxy text format requirements file. Users should use the YAML format for requirements instead. * Undefined variables within a ``with_`` loop's list currently do not interrupt the loop, but they do issue a warning; in the future, they will issue an error. -* Using dictionary variables to set all task parameters is unsafe and will be removed in a future version. For example:: +* Using dictionary variables to set all task parameters is unsafe and will be removed in a future version. Example of a deprecated variant: + +.. code-block:: yaml - hosts: localhost gather_facts: no @@ -119,14 +146,22 @@ While all items listed here will show a deprecation warning message, they still debug_params: msg: "hello there" tasks: - # These are both deprecated: - debug: "{{debug_params}}" - debug: args: "{{debug_params}}" - # Use this instead: +Example of a recommended variant: + +.. code-block:: yaml + + - hosts: localhost + gather_facts: no + vars: + debug_params: + msg: "hello there" + tasks: - debug: - msg: "{{debug_params['msg']}}" + msg: "{{debug_params['msg']}}" * Host patterns should use a comma (,) or colon (:) instead of a semicolon (;) to separate hosts/groups in the pattern. * Ranges specified in host patterns should use the [x:y] syntax, instead of [x-y]. diff --git a/docs/docsite/rst/porting_guides/porting_guide_6.rst b/docs/docsite/rst/porting_guides/porting_guide_6.rst index 06225c93..87756b2e 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_6.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_6.rst @@ -99,6 +99,60 @@ Networking No notable changes +Porting Guide for v6.6.0 +======================== + +Added Collections +----------------- + +- lowlydba.sqlserver (version 1.0.4) + +Known Issues +------------ + +community.routeros +~~~~~~~~~~~~~~~~~~ + +- The ``community.routeros.command`` module claims to support check mode. Since it cannot judge whether the commands executed modify state or not, this behavior is incorrect. Since this potentially breaks existing playbooks, we will not change this behavior until community.routeros 3.0.0. + +Breaking Changes +---------------- + +community.general +~~~~~~~~~~~~~~~~~ + +- newrelic_deployment - ``revision`` is required for v2 API (https://github.com/ansible-collections/community.general/pull/5341). + +Major Changes +------------- + +community.general +~~~~~~~~~~~~~~~~~ + +- newrelic_deployment - removed New Relic v1 API, added support for v2 API (https://github.com/ansible-collections/community.general/pull/5341). + +Deprecated Features +------------------- + +- The mellanox.onyx collection is considered unmaintained and will be removed from Ansible 8 if no one starts maintaining it again before Ansible 8. See `the removal process for details on how this works <https://github.com/ansible-collections/overview/blob/main/removal_from_ansible.rst#cancelling-removal-of-an-unmaintained-collection>`__ (https://github.com/ansible-community/community-topics/issues/136). + +cisco.mso +~~~~~~~~~ + +- The mso_schema_template_contract_filter contract_filter_type attribute is deprecated. The value is now deduced from filter_type. + +community.general +~~~~~~~~~~~~~~~~~ + +- ArgFormat module utils - deprecated along ``CmdMixin``, in favor of the ``cmd_runner_fmt`` module util (https://github.com/ansible-collections/community.general/pull/5370). +- CmdMixin module utils - deprecated in favor of the ``CmdRunner`` module util (https://github.com/ansible-collections/community.general/pull/5370). +- CmdModuleHelper module utils - deprecated in favor of the ``CmdRunner`` module util (https://github.com/ansible-collections/community.general/pull/5370). +- CmdStateModuleHelper module utils - deprecated in favor of the ``CmdRunner`` module util (https://github.com/ansible-collections/community.general/pull/5370). +- django_manage - support for Django releases older than 4.1 has been deprecated and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5400). +- django_manage - support for the commands ``cleanup``, ``syncdb`` and ``validate`` that have been deprecated in Django long time ago will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5400). +- django_manage - the behavior of "creating the virtual environment when missing" is being deprecated and will be removed in community.general version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5405). +- newrelic_deployment - ``appname`` and ``environment`` are no longer valid options in the v2 API. They will be removed in community.general 7.0.0 (https://github.com/ansible-collections/community.general/pull/5341). + Porting Guide for v6.5.0 ======================== @@ -108,7 +162,7 @@ Major Changes infoblox.nios_modules ~~~~~~~~~~~~~~~~~~~~~ -- Feature for extra layer security , with ``cert`` and ``key`` parameters in playbooks for authenticating using certificate and key ``*.pem`` file absolute path `#154 <https://github.com/infobloxopen/infoblox-ansible/pull/154>`_ +- Feature for extra layer security , with `cert` and `key` parameters in playbooks for authenticating using certificate and key ``*.pem`` file absolute path `#154 <https://github.com/infobloxopen/infoblox-ansible/pull/154>`_ - Fix to remove issue causing due to template attr in deleting network using Ansible module nios network `#147 <https://github.com/infobloxopen/infoblox-ansible/pull/147>`_ Deprecated Features diff --git a/docs/docsite/rst/porting_guides/porting_guide_7.rst b/docs/docsite/rst/porting_guides/porting_guide_7.rst index 029cf4a2..5c3d6fae 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_7.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_7.rst @@ -92,40 +92,73 @@ Networking No notable changes -Porting Guide for v7.0.0a2 -========================== +Porting Guide for v7.0.0 +======================== Added Collections ----------------- -- lowlydba.sqlserver (version 1.0.3) +- ibm.spectrum_virtualize (version 1.10.0) +- inspur.ispim (version 1.2.0) +- lowlydba.sqlserver (version 1.0.4) +- purestorage.fusion (version 1.1.1) +- vultr.cloud (version 1.3.1) Known Issues ------------ +community.routeros +~~~~~~~~~~~~~~~~~~ + +- The ``community.routeros.command`` module claims to support check mode. Since it cannot judge whether the commands executed modify state or not, this behavior is incorrect. Since this potentially breaks existing playbooks, we will not change this behavior until community.routeros 3.0.0. + dellemc.openmanage ~~~~~~~~~~~~~~~~~~ - idrac_user - Issue(192043) The module may error out with the message ``unable to perform the import or export operation because there are pending attribute changes or a configuration job is in progress``. Wait for the job to complete and run the task again. +- ome_application_alerts_smtp - Issue(212310) - The module does not provide a proper error message if the destination_address is more than 255 characters. - ome_application_alerts_syslog - Issue(215374) - The module does not provide a proper error message if the destination_address is more than 255 characters. +- ome_device_local_access_configuration - Issue(215035) - The module reports ``Successfully updated the local access setting`` if an unsupported value is provided for the parameter timeout_limit. However, this value is not actually applied on OpenManage Enterprise Modular. +- ome_device_local_access_configuration - Issue(217865) - The module does not display a proper error message if an unsupported value is provided for the user_defined and lcd_language parameters. - ome_device_network_services - Issue(212681) - The module does not provide a proper error message if unsupported values are provided for the parameters- port_number, community_name, max_sessions, max_auth_retries, and idle_timeout. - ome_device_power_settings - Issue(212679) - The module displays the following message if the value provided for the parameter ``power_cap`` is not within the supported range of 0 to 32767, ``Unable to complete the request because PowerCap does not exist or is not applicable for the resource URI.`` +- ome_device_quick_deploy - Issue(216352) - The module does not display a proper error message if an unsupported value is provided for the ipv6_prefix_length and vlan_id parameters. - ome_smart_fabric_uplink - Issue(186024) - The module does not allow the creation of multiple uplinks of the same name even though it is supported by OpenManage Enterprise Modular. If an uplink is created using the same name as an existing uplink, the existing uplink is modified. +netapp.ontap +~~~~~~~~~~~~ + +- na_ontap_snapshot - added documentation to use UTC format for ``expiry_time``. + Breaking Changes ---------------- +- Ansible 7 requires Python 3.9 on the controller, same as ansible-core 2.14. + Ansible-core ~~~~~~~~~~~~ +- Allow for lazy evaluation of Jinja2 expressions (https://github.com/ansible/ansible/issues/56017) +- The default ansible-galaxy role skeletons no longer contain .travis.yml files. You can configure ansible-galaxy to use a custom role skeleton that contains a .travis.yml file to continue using Galaxy's integration with Travis CI. +- ansible - At startup the filesystem encoding and locale are checked to verify they are UTF-8. If not, the process exits with an error reporting the errant encoding. +- ansible - Increase minimum Python requirement to Python 3.9 for CLI utilities and controller code +- ansible-test - At startup the filesystem encoding is checked to verify it is UTF-8. If not, the process exits with an error reporting the errant encoding. +- ansible-test - At startup the locale is configured as ``en_US.UTF-8``, with a fallback to ``C.UTF-8``. If neither encoding is available the process exits with an error. If the fallback is used, a warning is displayed. In previous versions the ``en_US.UTF-8`` locale was always requested. However, no startup checking was performed to verify the locale was successfully configured. - ansible-test validate-modules - Removed the ``missing-python-doc`` error code in validate modules, ``missing-documentation`` is used instead for missing PowerShell module documentation. +- strategy plugins - Make ``ignore_unreachable`` to increase ``ignored`` and ``ok`` and counter, not ``skipped`` and ``unreachable``. (https://github.com/ansible/ansible/issues/77690) amazon.aws ~~~~~~~~~~ +- Tags beginning with ``aws:`` will not be removed when purging tags, these tags are reserved by Amazon and may not be updated or deleted (https://github.com/ansible-collections/amazon.aws/issues/817). - amazon.aws collection - Support for ansible-core < 2.11 has been dropped (https://github.com/ansible-collections/amazon.aws/pull/1087). - amazon.aws collection - The amazon.aws collection has dropped support for ``botocore<1.21.0`` and ``boto3<1.18.0``. Most modules will continue to work with older versions of the AWS SDK, however compatability with older versions of the SDK is not guaranteed and will not be tested. When using older versions of the SDK a warning will be emitted by Ansible (https://github.com/ansible-collections/amazon.aws/pull/934). +- amazon.aws collection - the ``profile`` parameter is now mutually exclusive with the ``aws_access_key``, ``aws_secret_key`` and ``security_token`` parameters (https://github.com/ansible-collections/amazon.aws/pull/834). +- aws_az_info - the module alias ``aws_az_facts`` was deprecated in Ansible 2.9 and has now been removed (https://github.com/ansible-collections/amazon.aws/pull/832). +- aws_s3 - the default value for ``ensure overwrite`` has been changed to ``different`` instead of ``always`` so that the module is idempotent by default (https://github.com/ansible-collections/amazon.aws/issues/811). +- aws_ssm - on_denied and on_missing now both default to error, for consistency with both aws_secret and the base Lookup class (https://github.com/ansible-collections/amazon.aws/issues/617). - doc_fragments - remove minimum collection requirements from doc_fragments/aws.py and allow pulling those from doc_fragments/aws_boto3.py instead (https://github.com/ansible-collections/amazon.aws/pull/985). +- ec2 - The ``ec2`` module has been removed in release 4.0.0 and replaced by the ``ec2_instance`` module (https://github.com/ansible-collections/amazon.aws/pull/630). - ec2_ami - the default value for ``purge_tags`` has been changed from ``False`` to ``True`` (https://github.com/ansible-collections/amazon.aws/pull/916). - ec2_ami - the parameter aliases ``DeviceName``, ``VirtualName`` and ``NoDevice`` were previously deprecated and have been removed, please use ``device_name``, ``virtual_name`` and ``no_device`` instead (https://github.com/ansible-collections/amazon.aws/pull/913). - ec2_eni_info - the mutual exclusivity of the ``eni_id`` and ``filters`` parameters is now enforced, previously ``filters`` would be ignored if ``eni_id`` was set (https://github.com/ansible-collections/amazon.aws/pull/954). @@ -134,17 +167,30 @@ amazon.aws - ec2_vol - the default value for ``purge_tags`` has been changed from ``False`` to ``True`` (https://github.com/ansible-collections/amazon.aws/pull/916). - ec2_vpc_dhcp_option_info - the parameter aliases ``DhcpOptionIds`` and ``DryRun`` were previously deprecated and have been removed, please use ``dhcp_options_ids`` and ``no_device`` instead (https://github.com/ansible-collections/amazon.aws/pull/913). - ec2_vpc_endpoint - the default value for ``purge_tags`` has been changed from ``False`` to ``True`` (https://github.com/ansible-collections/amazon.aws/pull/916). +- ec2_vpc_igw_info - The default value for ``convert_tags`` has been changed to ``True`` (https://github.com/ansible-collections/amazon.aws/pull/835). - ec2_vpc_net - the default value for ``purge_tags`` has been changed from ``False`` to ``True`` (https://github.com/ansible-collections/amazon.aws/pull/916). - ec2_vpc_route_table - the default value for ``purge_tags`` has been changed from ``False`` to ``True`` (https://github.com/ansible-collections/amazon.aws/pull/916). +- elb_classic_lb - the ``ec2_elb`` fact has been removed (https://github.com/ansible-collections/amazon.aws/pull/827). +- module_utils - Support for the original AWS SDK aka ``boto`` has been removed, including all relevant helper functions. All modules should now use the ``boto3``/``botocore`` AWS SDK (https://github.com/ansible-collections/amazon.aws/pull/630) - s3_bucket - the previously deprecated alias ``S3_URL`` for the ``s3_url`` parameter has been removed. Playbooks shuold be updated to use ``s3_url`` (https://github.com/ansible-collections/amazon.aws/pull/908). - s3_object - the previously deprecated alias ``S3_URL`` for the ``s3_url`` parameter has been removed. Playbooks should be updated to use ``s3_url`` (https://github.com/ansible-collections/amazon.aws/pull/908). +check_point.mgmt +~~~~~~~~~~~~~~~~ + +- cp_mgmt_access_role - the 'machines' parameter now accepts a single str and a new parameter 'machines_list' of type dict has been added. the 'users' parameter now accepts a single str and a new parameter 'users_list' of type dict has been added. +- cp_mgmt_access_rule - the 'vpn' parameter now accepts a single str and a new parameter 'vpn_list' of type dict has been added. the 'position_by_rule' parameter has been changed to 'relative_position' with support of positioning above/below a section (and not just a rule). the 'relative_position' parameter has also 'top' and 'bottom' suboptions which allows positioning a rule at the top and bottom of a section respectively. a new parameter 'search_entire_rulebase' has been added to allow the relative positioning to be unlimited (was previously limited to 50 rules) +- cp_mgmt_administrator - the 'permissions_profile' parameter now accepts a single str and a new parameter 'permissions_profile_list' of type dict has been added. +- cp_mgmt_publish - the 'uid' parameter has been removed. + community.aws ~~~~~~~~~~~~~ +- Tags beginning with ``aws:`` will not be removed when purging tags, these tags are reserved by Amazon and may not be updated or deleted (https://github.com/ansible-collections/amazon.aws/issues/817). - acm_certificate - the previously deprecated default value of ``purge_tags=False`` has been updated to ``purge_tags=True`` (https://github.com/ansible-collections/community.aws/pull/1343). - autoscaling_group - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.autoscaling_group``. - autoscaling_group_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.autoscaling_group_info``. +- aws_secret - tags are no longer removed when the ``tags`` parameter is not set. To remove all tags set ``tags={}`` (https://github.com/ansible-collections/community.aws/issues/1146). - cloudfront_distribution - the previously deprecated default value of ``purge_tags=False`` has been updated to ``purge_tags=True`` (https://github.com/ansible-collections/community.aws/pull/1343). - cloudtrail - The module has been migrated to the ``amazon.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.cloudtrail``. - cloudwatch_metric_alarm - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.cloudwatch_metric_alarm``. @@ -153,12 +199,18 @@ community.aws - cloudwatchlogs_log_group_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.cloudwatchlogs_log_group_info``. - cloudwatchlogs_log_group_metric_filter - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.cloudwatchlogs_log_group_metric_filter``. - community.aws collection - Support for ansible-core < 2.11 has been dropped (https://github.com/ansible-collections/community.aws/pull/1541). +- community.aws collection - The ``community.aws`` collection has now dropped support for and any requirements upon the original ``boto`` AWS SDK, and now uses the ``boto3``/``botocore`` AWS SDK (https://github.com/ansible-collections/community.aws/pull/898). - community.aws collection - The community.aws collection has dropped support for ``botocore<1.21.0`` and ``boto3<1.18.0``. Most modules will continue to work with older versions of the AWS SDK, however compatability with older versions of the SDK is not guaranteed and will not be tested. When using older versions of the SDK a warning will be emitted by Ansible (https://github.com/ansible-collections/community.aws/pull/1362). +- community.aws collection - the ``profile`` parameter is now mutually exclusive with the ``aws_access_key``, ``aws_secret_key`` and ``security_token`` parameters (https://github.com/ansible-collections/amazon.aws/pull/834). - ec2_eip - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.ec2_eip``. - ec2_eip_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.ec2_eip_info``. +- ec2_vpc_route_table - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.ec2_vpc_route_table``. +- ec2_vpc_route_table_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.ec2_vpc_route_table_info``. - ec2_vpc_vpn - the previously deprecated default value of ``purge_tags=False`` has been updated to ``purge_tags=True`` (https://github.com/ansible-collections/community.aws/pull/1343). - elb_application_lb - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.elb_application_lb``. - elb_application_lb_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.elb_application_lb_info``. +- elb_instance - the ``ec2_elbs`` fact has been removed, ``updated_elbs`` has been added the return values and includes the same information (https://github.com/ansible-collections/community.aws/pull/1173). +- elb_network_lb - the default value of ``state`` has changed from ``absent`` to ``present`` (https://github.com/ansible-collections/community.aws/pull/1167). - execute_lambda - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.execute_lambda``. - iam_policy - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_policy``. - iam_policy_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_policy_info``. @@ -194,12 +246,31 @@ community.aws - route53_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.route53_info``. - route53_zone - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.route53_zone``. - route53_zone - the previously deprecated default value of ``purge_tags=False`` has been updated to ``purge_tags=True`` (https://github.com/ansible-collections/community.aws/pull/1343). +- script_inventory_ec2 - The ec2.py inventory script has been moved to a new repository. The script can now be downloaded from https://github.com/ansible-community/contrib-scripts/blob/main/inventory/ec2.py and has been removed from this collection. We recommend migrating from the script to the amazon.aws.ec2 inventory plugin. (https://github.com/ansible-collections/community.aws/pull/898) - sqs_queue - the previously deprecated default value of ``purge_tags=False`` has been updated to ``purge_tags=True`` (https://github.com/ansible-collections/community.aws/pull/1343). +community.docker +~~~~~~~~~~~~~~~~ + +- This collection does not work with ansible-core 2.11 on Python 3.12+. Please either upgrade to ansible-core 2.12+, or use Python 3.11 or earlier (https://github.com/ansible-collections/community.docker/pull/271). +- docker_container - ``exposed_ports`` is no longer ignored in ``comparisons``. Before, its value was assumed to be identical with the value of ``published_ports`` (https://github.com/ansible-collections/community.docker/pull/422). +- docker_container - ``log_options`` can no longer be specified when ``log_driver`` is not specified (https://github.com/ansible-collections/community.docker/pull/422). +- docker_container - ``publish_all_ports`` is no longer ignored in ``comparisons`` (https://github.com/ansible-collections/community.docker/pull/422). +- docker_container - ``restart_retries`` can no longer be specified when ``restart_policy`` is not specified (https://github.com/ansible-collections/community.docker/pull/422). +- docker_container - ``stop_timeout`` is no longer ignored for idempotency if told to be not ignored in ``comparisons``. So far it defaulted to ``ignore`` there, and setting it to ``strict`` had no effect (https://github.com/ansible-collections/community.docker/pull/422). +- modules and plugins communicating directly with the Docker daemon - when connecting by SSH and not using ``use_ssh_client=true``, reject unknown host keys instead of accepting them. This is only a breaking change relative to older community.docker 3.0.0 pre-releases or with respect to Docker SDK for Python < 6.0.0. Docker SDK for Python 6.0.0 will also include this change (https://github.com/ansible-collections/community.docker/pull/434). + community.general ~~~~~~~~~~~~~~~~~ - newrelic_deployment - ``revision`` is required for v2 API (https://github.com/ansible-collections/community.general/pull/5341). +- scaleway_container_registry_info - no longer replace ``secret_environment_variables`` in the output by ``SENSITIVE_VALUE`` (https://github.com/ansible-collections/community.general/pull/5497). + +community.hashi_vault +~~~~~~~~~~~~~~~~~~~~~ + +- auth - the default value for ``token_validate`` has changed from ``true`` to ``false``, as previously announced (https://github.com/ansible-collections/community.hashi_vault/issues/248). +- vault_kv2_get lookup - as previously announced, the default value for ``engine_mount_point`` in the ``vault_kv2_get`` lookup has changed from ``kv`` to ``secret`` (https://github.com/ansible-collections/community.hashi_vault/issues/279). community.vmware ~~~~~~~~~~~~~~~~ @@ -217,12 +288,30 @@ community.vmware - vmware_vm_config_option - Dict item names in result are changed from strings joined with spaces to strings joined with underlines, e.g. `Guest fullname` is changed to `guest_fullname` (https://github.com/ansible-collections/community.vmware/issues/1268). - vmware_vspan_session - Remove support for vSphere API less than 6.7. +dellemc.enterprise_sonic +~~~~~~~~~~~~~~~~~~~~~~~~ + +- bgp_af - Add the route_advertise_list dictionary to the argspec to replace the deleted, obsolete advertise_prefix attribute used for SONiC 3.x images on the 1.x branch of this collection. This change corresponds to a SONiC 4.0 OC YANG REST compliance change for the BGP AF REST API. It enables specification of a route map in conjunction with each route advertisement prefix (https://github.com/ansible-collections/dellemc.enterprise_sonic/pull/63). +- bgp_af - remove the obsolete 'advertise_prefix' attribute from argspec and config code. This and subsequent co-req replacement with the new route advertise list argument structure require corresponding changes in playbooks previoulsly used for configuring route advertise prefixes for SONiC 3.x images. (https://github.com/ansible-collections/dellemc.enterprise_sonic/pull/60) +- bgp_neighbors - Replace the previously defined standalone "bfd" attribute with a bfd dictionary containing multiple attributes. This change corresponds to the revised SONiC 4.x implementation of OC YANG compatible REST APIs. Playbooks previously using the bfd attributes for SONiC 3.x images must be modified for useon SONiC 4.0 images to use the new definition for the bfd attribute argspec structure (https://github.com/ansible-collections/dellemc.enterprise_sonic/pull/72). +- bgp_neighbors - Replace, for BGP peer groups, the previously defined standalone "bfd" attribute with a bfd dictionary containing multiple attributes. This change corresponds to the revised SONiC 4.x implementation of OC YANG compatible REST APIs. Playbooks previously using the bfd attributes for SONiC 3.x images must be modified for useon SONiC 4.0 images to use the new definition for the bfd attribute argspec structure (https://github.com/ansible-collections/dellemc.enterprise_sonic/pull/81). + Major Changes ------------- +Ansible-core +~~~~~~~~~~~~ + +- Move handler processing into new ``PlayIterator`` phase to use the configured strategy (https://github.com/ansible/ansible/issues/65067) +- ansible - At startup the filesystem encoding and locale are checked to verify they are UTF-8. If not, the process exits with an error reporting the errant encoding. +- ansible - Increase minimum Python requirement to Python 3.9 for CLI utilities and controller code +- ansible-test - At startup the filesystem encoding is checked to verify it is UTF-8. If not, the process exits with an error reporting the errant encoding. +- ansible-test - At startup the locale is configured as ``en_US.UTF-8``, with a fallback to ``C.UTF-8``. If neither encoding is available the process exits with an error. If the fallback is used, a warning is displayed. In previous versions the ``en_US.UTF-8`` locale was always requested. However, no startup checking was performed to verify the locale was successfully configured. + amazon.aws ~~~~~~~~~~ +- amazon.aws collection - The amazon.aws collection has dropped support for ``botocore<1.20.0`` and ``boto3<1.17.0``. Most modules will continue to work with older versions of the AWS SDK, however compatability with older versions of the SDK is not guaranteed and will not be tested. When using older versions of the SDK a warning will be emitted by Ansible (https://github.com/ansible-collections/amazon.aws/pull/574). - autoscaling_group - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.autoscaling_group``. - autoscaling_group_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.autoscaling_group_info``. - cloudtrail - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.cloudtrail``. @@ -276,6 +365,17 @@ arista.eos - eos_static_route - eos_vlan +check_point.mgmt +~~~~~~~~~~~~~~~~ + +- plugins/httpapi/checkpoint - Support for Smart-1 Cloud with new variable 'ansible_cloud_mgmt_id' + +chocolatey.chocolatey +~~~~~~~~~~~~~~~~~~~~~ + +- win_chocolatey - Added bootstrap_script option to allow users to target a script URL for installing Chocolatey on clients. +- win_chocolatey_facts - Added outdated packages list to data returned. + cisco.asa ~~~~~~~~~ @@ -305,286 +405,6 @@ cisco.nxos - Please use either of the following connection types - network_cli, httpapi or netconf. - This release drops support for `connection: local` and provider dictionary. -community.general -~~~~~~~~~~~~~~~~~ - -- newrelic_deployment - removed New Relic v1 API, added support for v2 API (https://github.com/ansible-collections/community.general/pull/5341). - -dellemc.openmanage -~~~~~~~~~~~~~~~~~~ - -- idrac_bios - The module is enhanced to support clear pending BIOS attributes, reset BIOS to default settings, and configure BIOS attribute using Redfish. - -infoblox.nios_modules -~~~~~~~~~~~~~~~~~~~~~ - -- Feature for extra layer security , with ``cert`` and ``key`` parameters in playbooks for authenticating using certificate and key ``*.pem`` file absolute path `#154 <https://github.com/infobloxopen/infoblox-ansible/pull/154>`_ -- Fix to remove issue causing due to template attr in deleting network using Ansible module nios network `#147 <https://github.com/infobloxopen/infoblox-ansible/pull/147>`_ - -junipernetworks.junos -~~~~~~~~~~~~~~~~~~~~~ - -- Use of connection: local and the provider option are no longer valid on any modules in this collection. - -vyos.vyos -~~~~~~~~~ - -- Use of connection: local and the provider option are no longer valid on any modules in this collection. - -Removed Features ----------------- - -ansible.netcommon -~~~~~~~~~~~~~~~~~ - -- napalm - Removed unused connection plugin. -- net_banner - Use <network_os>_banner instead. -- net_interface - Use <network_os>_interfaces instead. -- net_l2_interface - Use <network_os>_l2_interfaces instead. -- net_l3_interface - Use <network_os>_l3_interfaces instead. -- net_linkagg - Use <network_os>_lag_interfaces instead. -- net_lldp - Use <network_os>_lldp_global instead. -- net_lldp_interface - Use <network_os>_lldp_interfaces instead. -- net_logging - Use <network_os>_logging_global instead. -- net_static_route - Use <network_os>_static_routes instead. -- net_system - Use <network_os>_system instead. -- net_user - Use <network_os>_user instead. -- net_vlan - Use <network_os>_vlans instead. -- net_vrf - Use <network_os>_vrf instead. - -cisco.ios -~~~~~~~~~ - -- ios_interface - use ios_interfaces instead. -- ios_l2_interface - use ios_l2_interfaces instead. -- ios_l3_interface - use ios_l3_interfaces instead. -- ios_static_route - use ios_static_routes instead. -- ios_vlan - use ios_vlans instead. - -cisco.iosxr -~~~~~~~~~~~ - -- iosxr_interface - use iosxr_interfaces instead. - -cisco.nxos -~~~~~~~~~~ - -- This release removes the following deprecated plugins that have reached their end-of-life. -- nxos_acl -- nxos_acl_interface -- nxos_interface -- nxos_interface_ospf -- nxos_l2_interface -- nxos_l3_interface -- nxos_linkagg -- nxos_lldp -- nxos_ospf -- nxos_ospf_vrf -- nxos_smu -- nxos_static_route -- nxos_vlan - -community.vmware -~~~~~~~~~~~~~~~~ - -- vca_fw - The deprecated module ``vca_fw`` has been removed. -- vca_nat - The deprecated module ``vca_nat`` has been removed. -- vca_vapp - The deprecated module ``vca_vapp`` has been removed. -- vmware_dns_config - The deprecated module ``vmware_dns_config`` has been removed, you can use ``vmware_host_dns`` instead. -- vmware_guest_network - The deprecated parameter ``networks`` has been removed, use loops to handle multiple interfaces (https://github.com/ansible-collections/community.vmware/pull/1459). -- vmware_guest_vnc - The deprecated module ``vmware_guest_vnc`` has been removed. The VNC support has been dropped with vSphere 7 and later (https://github.com/ansible-collections/community.vmware/pull/1454). -- vmware_host_firewall_manager - The module doesn't accept a list for ``allowed_hosts`` anymore, use a dict instead. Additionally, ``all_ip`` is now a required sub-option of ``allowed_hosts`` (https://github.com/ansible-collections/community.vmware/pull/1463). -- vsphere_copy - The deprecated parameters ``host`` and ``login`` have been removed. Use ``hostname`` and ``username`` instead (https://github.com/ansible-collections/community.vmware/pull/1456). - -junipernetworks.junos -~~~~~~~~~~~~~~~~~~~~~ - -- Remove following deprecated Junos Modules. -- junos_interface -- junos_l2_interface -- junos_l3_interface -- junos_linkagg -- junos_lldp -- junos_lldp_interface -- junos_static_route -- junos_vlan - -vyos.vyos -~~~~~~~~~ - -- vyos_interface - use vyos_interfaces instead. -- vyos_l3_interface - use vyos_l3_interfaces instead. -- vyos_linkagg - use vyos_lag_interfaces instead. -- vyos_lldp - use vyos_lldp_global instead. -- vyos_lldp_interface - use vyos_lldp_interfaces instead. -- vyos_static_route - use vyos_static_routes instead. - -Deprecated Features -------------------- - -- The dellemc.os10 collection is considered unmaintained and will be removed from Ansible 8 if no one starts maintaining it again before Ansible 8. See `the removal process for details on how this works <https://github.com/ansible-collections/overview/blob/main/removal_from_ansible.rst#cancelling-removal-of-an-unmaintained-collection>`__ (https://github.com/ansible-community/community-topics/issues/134). -- The dellemc.os6 collection is considered unmaintained and will be removed from Ansible 8 if no one starts maintaining it again before Ansible 8. See `the removal process for details on how this works <https://github.com/ansible-collections/overview/blob/main/removal_from_ansible.rst#cancelling-removal-of-an-unmaintained-collection>`__ (https://github.com/ansible-community/community-topics/issues/132). -- The dellemc.os9 collection is considered unmaintained and will be removed from Ansible 8 if no one starts maintaining it again before Ansible 8. See `the removal process for details on how this works <https://github.com/ansible-collections/overview/blob/main/removal_from_ansible.rst#cancelling-removal-of-an-unmaintained-collection>`__ (https://github.com/ansible-community/community-topics/issues/133). -- The mellanox.onyx collection is considered unmaintained and will be removed from Ansible 8 if no one starts maintaining it again before Ansible 8. See `the removal process for details on how this works <https://github.com/ansible-collections/overview/blob/main/removal_from_ansible.rst#cancelling-removal-of-an-unmaintained-collection>`__ (https://github.com/ansible-community/community-topics/issues/136). - -amazon.aws -~~~~~~~~~~ - -- amazon.aws collection - due to the AWS SDKs announcing the end of support for Python less than 3.7 (https://aws.amazon.com/blogs/developer/python-support-policy-updates-for-aws-sdks-and-tools/) support for Python less than 3.7 by this collection has been deprecated and will be removed in a release after 2023-05-31 (https://github.com/ansible-collections/amazon.aws/pull/935). -- inventory/aws_ec2 - the ``include_extra_api_calls`` is now deprecated, its value is silently ignored (https://github.com/ansible-collections/amazon.aws/pull/1097). - -cisco.mso -~~~~~~~~~ - -- The mso_schema_template_contract_filter contract_filter_type attribute is deprecated. The value is now deduced from filter_type. - -community.aws -~~~~~~~~~~~~~ - -- community.aws collection - due to the AWS SDKs announcing the end of support for Python less than 3.7 (https://aws.amazon.com/blogs/developer/python-support-policy-updates-for-aws-sdks-and-tools/) support for Python less than 3.7 by this collection has been deprecated and will be removed in a release after 2023-05-31 (https://github.com/ansible-collections/community.aws/pull/1361). - -community.general -~~~~~~~~~~~~~~~~~ - -- ArgFormat module utils - deprecated along ``CmdMixin``, in favor of the ``cmd_runner_fmt`` module util (https://github.com/ansible-collections/community.general/pull/5370). -- CmdMixin module utils - deprecated in favor of the ``CmdRunner`` module util (https://github.com/ansible-collections/community.general/pull/5370). -- CmdModuleHelper module utils - deprecated in favor of the ``CmdRunner`` module util (https://github.com/ansible-collections/community.general/pull/5370). -- CmdStateModuleHelper module utils - deprecated in favor of the ``CmdRunner`` module util (https://github.com/ansible-collections/community.general/pull/5370). -- django_manage - support for Django releases older than 4.1 has been deprecated and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5400). -- django_manage - support for the commands ``cleanup``, ``syncdb`` and ``validate`` that have been deprecated in Django long time ago will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5400). -- django_manage - the behavior of "creating the virtual environment when missing" is being deprecated and will be removed in community.general version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5405). -- lxc_container - the module will no longer make any effort to support Python 2 (https://github.com/ansible-collections/community.general/pull/5304). -- newrelic_deployment - ``appname`` and ``environment`` are no longer valid options in the v2 API. They will be removed in community.general 7.0.0 (https://github.com/ansible-collections/community.general/pull/5341). - -Porting Guide for v7.0.0a1 -========================== - -Added Collections ------------------ - -- ibm.spectrum_virtualize (version 1.9.0) -- inspur.ispim (version 1.0.1) -- purestorage.fusion (version 1.1.1) -- vultr.cloud (version 1.1.0) - -Known Issues ------------- - -dellemc.openmanage -~~~~~~~~~~~~~~~~~~ - -- idrac_user - Issue(192043) The module may error out with the message ``unable to perform the import or export operation because there are pending attribute changes or a configuration job is in progress``. Wait for the job to complete and run the task again. -- ome_application_alerts_smtp - Issue(212310) - The module does not provide a proper error message if the destination_address is more than 255 characters. -- ome_application_alerts_syslog - Issue(215374) - The module does not provide a proper error message if the destination_address is more than 255 characters. -- ome_device_local_access_configuration - Issue(215035) - The module reports ``Successfully updated the local access setting`` if an unsupported value is provided for the parameter timeout_limit. However, this value is not actually applied on OpenManage Enterprise Modular. -- ome_device_local_access_configuration - Issue(217865) - The module does not display a proper error message if an unsupported value is provided for the user_defined and lcd_language parameters. -- ome_device_network_services - Issue(212681) - The module does not provide a proper error message if unsupported values are provided for the parameters- port_number, community_name, max_sessions, max_auth_retries, and idle_timeout. -- ome_device_power_settings - Issue(212679) - The module displays the following message if the value provided for the parameter ``power_cap`` is not within the supported range of 0 to 32767, ``Unable to complete the request because PowerCap does not exist or is not applicable for the resource URI.`` -- ome_device_quick_deploy - Issue(216352) - The module does not display a proper error message if an unsupported value is provided for the ipv6_prefix_length and vlan_id parameters. -- ome_smart_fabric_uplink - Issue(186024) - The module does not allow the creation of multiple uplinks of the same name even though it is supported by OpenManage Enterprise Modular. If an uplink is created using the same name as an existing uplink, the existing uplink is modified. - -netapp.ontap -~~~~~~~~~~~~ - -- na_ontap_snapshot - added documentation to use UTC format for ``expiry_time``. - -Breaking Changes ----------------- - -- Ansible 7 requires Python 3.9 on the controller, same as ansible-core 2.14. - -Ansible-core -~~~~~~~~~~~~ - -- Allow for lazy evaluation of Jinja2 expressions (https://github.com/ansible/ansible/issues/56017) -- The default ansible-galaxy role skeletons no longer contain .travis.yml files. You can configure ansible-galaxy to use a custom role skeleton that contains a .travis.yml file to continue using Galaxy's integration with Travis CI. -- ansible - At startup the filesystem encoding and locale are checked to verify they are UTF-8. If not, the process exits with an error reporting the errant encoding. -- ansible - Increase minimum Python requirement to Python 3.9 for CLI utilities and controller code -- ansible-test - At startup the filesystem encoding is checked to verify it is UTF-8. If not, the process exits with an error reporting the errant encoding. -- ansible-test - At startup the locale is configured as ``en_US.UTF-8``, with a fallback to ``C.UTF-8``. If neither encoding is available the process exits with an error. If the fallback is used, a warning is displayed. In previous versions the ``en_US.UTF-8`` locale was always requested. However, no startup checking was performed to verify the locale was successfully configured. -- strategy plugins - Make ``ignore_unreachable`` to increase ``ignored`` and ``ok`` and counter, not ``skipped`` and ``unreachable``. (https://github.com/ansible/ansible/issues/77690) - -amazon.aws -~~~~~~~~~~ - -- Tags beginning with ``aws:`` will not be removed when purging tags, these tags are reserved by Amazon and may not be updated or deleted (https://github.com/ansible-collections/amazon.aws/issues/817). -- amazon.aws collection - the ``profile`` parameter is now mutually exclusive with the ``aws_access_key``, ``aws_secret_key`` and ``security_token`` parameters (https://github.com/ansible-collections/amazon.aws/pull/834). -- aws_az_info - the module alias ``aws_az_facts`` was deprecated in Ansible 2.9 and has now been removed (https://github.com/ansible-collections/amazon.aws/pull/832). -- aws_s3 - the default value for ``ensure overwrite`` has been changed to ``different`` instead of ``always`` so that the module is idempotent by default (https://github.com/ansible-collections/amazon.aws/issues/811). -- aws_ssm - on_denied and on_missing now both default to error, for consistency with both aws_secret and the base Lookup class (https://github.com/ansible-collections/amazon.aws/issues/617). -- ec2 - The ``ec2`` module has been removed in release 4.0.0 and replaced by the ``ec2_instance`` module (https://github.com/ansible-collections/amazon.aws/pull/630). -- ec2_vpc_igw_info - The default value for ``convert_tags`` has been changed to ``True`` (https://github.com/ansible-collections/amazon.aws/pull/835). -- elb_classic_lb - the ``ec2_elb`` fact has been removed (https://github.com/ansible-collections/amazon.aws/pull/827). -- module_utils - Support for the original AWS SDK aka ``boto`` has been removed, including all relevant helper functions. All modules should now use the ``boto3``/``botocore`` AWS SDK (https://github.com/ansible-collections/amazon.aws/pull/630) - -check_point.mgmt -~~~~~~~~~~~~~~~~ - -- cp_mgmt_access_role - the 'machines' parameter now accepts a single str and a new parameter 'machines_list' of type dict has been added. the 'users' parameter now accepts a single str and a new parameter 'users_list' of type dict has been added. -- cp_mgmt_access_rule - the 'vpn' parameter now accepts a single str and a new parameter 'vpn_list' of type dict has been added. the 'position_by_rule' parameter has been changed to 'relative_position' with support of positioning above/below a section (and not just a rule). the 'relative_position' parameter has also 'top' and 'bottom' suboptions which allows positioning a rule at the top and bottom of a section respectively. a new parameter 'search_entire_rulebase' has been added to allow the relative positioning to be unlimited (was previously limited to 50 rules) -- cp_mgmt_administrator - the 'permissions_profile' parameter now accepts a single str and a new parameter 'permissions_profile_list' of type dict has been added. -- cp_mgmt_publish - the 'uid' parameter has been removed. - -community.aws -~~~~~~~~~~~~~ - -- Tags beginning with ``aws:`` will not be removed when purging tags, these tags are reserved by Amazon and may not be updated or deleted (https://github.com/ansible-collections/amazon.aws/issues/817). -- aws_secret - tags are no longer removed when the ``tags`` parameter is not set. To remove all tags set ``tags={}`` (https://github.com/ansible-collections/community.aws/issues/1146). -- community.aws collection - The ``community.aws`` collection has now dropped support for and any requirements upon the original ``boto`` AWS SDK, and now uses the ``boto3``/``botocore`` AWS SDK (https://github.com/ansible-collections/community.aws/pull/898). -- community.aws collection - the ``profile`` parameter is now mutually exclusive with the ``aws_access_key``, ``aws_secret_key`` and ``security_token`` parameters (https://github.com/ansible-collections/amazon.aws/pull/834). -- ec2_vpc_route_table - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.ec2_vpc_route_table``. -- ec2_vpc_route_table_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.ec2_vpc_route_table_info``. -- elb_instance - the ``ec2_elbs`` fact has been removed, ``updated_elbs`` has been added the return values and includes the same information (https://github.com/ansible-collections/community.aws/pull/1173). -- elb_network_lb - the default value of ``state`` has changed from ``absent`` to ``present`` (https://github.com/ansible-collections/community.aws/pull/1167). -- script_inventory_ec2 - The ec2.py inventory script has been moved to a new repository. The script can now be downloaded from https://github.com/ansible-community/contrib-scripts/blob/main/inventory/ec2.py and has been removed from this collection. We recommend migrating from the script to the amazon.aws.ec2 inventory plugin. (https://github.com/ansible-collections/community.aws/pull/898) - -community.docker -~~~~~~~~~~~~~~~~ - -- This collection does not work with ansible-core 2.11 on Python 3.12+. Please either upgrade to ansible-core 2.12+, or use Python 3.11 or earlier (https://github.com/ansible-collections/community.docker/pull/271). -- docker_container - ``exposed_ports`` is no longer ignored in ``comparisons``. Before, its value was assumed to be identical with the value of ``published_ports`` (https://github.com/ansible-collections/community.docker/pull/422). -- docker_container - ``log_options`` can no longer be specified when ``log_driver`` is not specified (https://github.com/ansible-collections/community.docker/pull/422). -- docker_container - ``publish_all_ports`` is no longer ignored in ``comparisons`` (https://github.com/ansible-collections/community.docker/pull/422). -- docker_container - ``restart_retries`` can no longer be specified when ``restart_policy`` is not specified (https://github.com/ansible-collections/community.docker/pull/422). -- docker_container - ``stop_timeout`` is no longer ignored for idempotency if told to be not ignored in ``comparisons``. So far it defaulted to ``ignore`` there, and setting it to ``strict`` had no effect (https://github.com/ansible-collections/community.docker/pull/422). -- modules and plugins communicating directly with the Docker daemon - when connecting by SSH and not using ``use_ssh_client=true``, reject unknown host keys instead of accepting them. This is only a breaking change relative to older community.docker 3.0.0 pre-releases or with respect to Docker SDK for Python < 6.0.0. Docker SDK for Python 6.0.0 will also include this change (https://github.com/ansible-collections/community.docker/pull/434). - -dellemc.enterprise_sonic -~~~~~~~~~~~~~~~~~~~~~~~~ - -- bgp_af - Add the route_advertise_list dictionary to the argspec to replace the deleted, obsolete advertise_prefix attribute used for SONiC 3.x images on the 1.x branch of this collection. This change corresponds to a SONiC 4.0 OC YANG REST compliance change for the BGP AF REST API. It enables specification of a route map in conjunction with each route advertisement prefix (https://github.com/ansible-collections/dellemc.enterprise_sonic/pull/63). -- bgp_af - remove the obsolete 'advertise_prefix' attribute from argspec and config code. This and subsequent co-req replacement with the new route advertise list argument structure require corresponding changes in playbooks previoulsly used for configuring route advertise prefixes for SONiC 3.x images. (https://github.com/ansible-collections/dellemc.enterprise_sonic/pull/60) -- bgp_neighbors - Replace the previously defined standalone "bfd" attribute with a bfd dictionary containing multiple attributes. This change corresponds to the revised SONiC 4.x implementation of OC YANG compatible REST APIs. Playbooks previously using the bfd attributes for SONiC 3.x images must be modified for useon SONiC 4.0 images to use the new definition for the bfd attribute argspec structure (https://github.com/ansible-collections/dellemc.enterprise_sonic/pull/72). -- bgp_neighbors - Replace, for BGP peer groups, the previously defined standalone "bfd" attribute with a bfd dictionary containing multiple attributes. This change corresponds to the revised SONiC 4.x implementation of OC YANG compatible REST APIs. Playbooks previously using the bfd attributes for SONiC 3.x images must be modified for useon SONiC 4.0 images to use the new definition for the bfd attribute argspec structure (https://github.com/ansible-collections/dellemc.enterprise_sonic/pull/81). - -Major Changes -------------- - -Ansible-core -~~~~~~~~~~~~ - -- Move handler processing into new ``PlayIterator`` phase to use the configured strategy (https://github.com/ansible/ansible/issues/65067) -- ansible - At startup the filesystem encoding and locale are checked to verify they are UTF-8. If not, the process exits with an error reporting the errant encoding. -- ansible - Increase minimum Python requirement to Python 3.9 for CLI utilities and controller code -- ansible-test - At startup the filesystem encoding is checked to verify it is UTF-8. If not, the process exits with an error reporting the errant encoding. -- ansible-test - At startup the locale is configured as ``en_US.UTF-8``, with a fallback to ``C.UTF-8``. If neither encoding is available the process exits with an error. If the fallback is used, a warning is displayed. In previous versions the ``en_US.UTF-8`` locale was always requested. However, no startup checking was performed to verify the locale was successfully configured. - -amazon.aws -~~~~~~~~~~ - -- amazon.aws collection - The amazon.aws collection has dropped support for ``botocore<1.20.0`` and ``boto3<1.17.0``. Most modules will continue to work with older versions of the AWS SDK, however compatability with older versions of the SDK is not guaranteed and will not be tested. When using older versions of the SDK a warning will be emitted by Ansible (https://github.com/ansible-collections/amazon.aws/pull/574). - -check_point.mgmt -~~~~~~~~~~~~~~~~ - -- plugins/httpapi/checkpoint - Support for Smart-1 Cloud with new variable 'ansible_cloud_mgmt_id' - -chocolatey.chocolatey -~~~~~~~~~~~~~~~~~~~~~ - -- win_chocolatey - Added bootstrap_script option to allow users to target a script URL for installing Chocolatey on clients. -- win_chocolatey_facts - Added outdated packages list to data returned. - community.aws ~~~~~~~~~~~~~ @@ -612,11 +432,23 @@ community.docker - docker_volume - no longer uses the Docker SDK for Python. It requires ``requests`` to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (https://github.com/ansible-collections/community.docker/pull/411). - docker_volume_info - no longer uses the Docker SDK for Python. It requires ``requests`` to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (https://github.com/ansible-collections/community.docker/pull/412). +community.general +~~~~~~~~~~~~~~~~~ + +- The internal structure of the collection was changed for modules and action plugins. These no longer live in a directory hierarchy ordered by topic, but instead are now all in a single (flat) directory. This has no impact on users *assuming they did not use internal FQCNs*. These will still work, but result in deprecation warnings. They were never officially supported and thus the redirects are kept as a courtsey, and this is not labelled as a breaking change. Note that for example the Ansible VScode plugin started recommending these internal names. If you followed its recommendation, you will now have to change back to the short names to avoid deprecation warnings, and potential errors in the future as these redirects will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5461). +- newrelic_deployment - removed New Relic v1 API, added support for v2 API (https://github.com/ansible-collections/community.general/pull/5341). + community.mysql ~~~~~~~~~~~~~~~ - mysql_db - the ``pipefail`` argument's default value will be changed to ``true`` in community.mysql 4.0.0. If your target machines do not use ``bash`` as a default interpreter, set ``pipefail`` to ``false`` explicitly. However, we strongly recommend setting up ``bash`` as a default and ``pipefail=true`` as it will protect you from getting broken dumps you don't know about (https://github.com/ansible-collections/community.mysql/issues/407). +community.network +~~~~~~~~~~~~~~~~~ + +- The community.network collection no longer supports Ansible 2.9 and ansible-base 2.10. While we take no active measures to prevent usage, we will remove compatibility code and other compatility measures that will effectively prevent using most content from this collection with Ansible 2.9, and some content of this collection with ansible-base 2.10. Both Ansible 2.9 and ansible-base 2.10 will very soon be End of Life and if you are still using them, you should consider upgrading to ansible-core 2.11 or later as soon as possible (https://github.com/ansible-collections/community.network/pull/426). +- The internal structure of the collection was changed for modules and action plugins. These no longer live in a directory hierarchy ordered by topic, but instead are now all in a single (flat) directory. This has no impact on users *assuming they did not use internal FQCNs*. These will still work, but result in deprecation warnings. They were never officially supported and thus the redirects are kept as a courtsey, and this is not labelled as a breaking change. Note that for example the Ansible VScode plugin started recommending these internal names. If you followed its recommendation, you will now have to change back to the short names to avoid deprecation warnings, and potential errors in the future as these redirects will be removed in community.network 8.0.0 (https://github.com/ansible-collections/community.network/pull/482). + community.postgresql ~~~~~~~~~~~~~~~~~~~~ @@ -636,10 +468,21 @@ dellemc.openmanage - Added collection metadata for creating execution environments. - Refactored the Markdown (MD) files and content for better readability. - The share parameters are deprecated from the following modules - idrac_network, idrac_timezone_ntp, dellemc_configure_idrac_eventing, dellemc_configure_idrac_services, dellemc_idrac_lc_attributes, dellemc_system_lockdown_mode. +- idrac_bios - The module is enhanced to support clear pending BIOS attributes, reset BIOS to default settings, and configure BIOS attribute using Redfish. - idrac_boot - Support for configuring the boot settings on iDRAC. +- idrac_redfish_storage_controller - This module is enhanced to support LockVirtualDisk operation. +- idrac_virtual_media - This module allows to configure Remote File Share settings. - ome_device_group - The module is enhanced to support the removal of devices from a static device group. - ome_devices - Support for performing device-specific operations on OpenManage Enterprise. +fortinet.fortimanager +~~~~~~~~~~~~~~~~~~~~~ + +- Fix compatibility issue for ansible 2.9.x and ansible-base 2.10.x. +- Many fixes for Ansible sanity test warnings & errors. +- Support FortiManager Schema 7.2.0 , 98 new modules +- support Ansible changelogs. + fortinet.fortios ~~~~~~~~~~~~~~~~ @@ -649,9 +492,21 @@ fortinet.fortios infoblox.nios_modules ~~~~~~~~~~~~~~~~~~~~~ +- Feature for extra layer security , with `cert` and `key` parameters in playbooks for authenticating using certificate and key ``*.pem`` file absolute path `#154 <https://github.com/infobloxopen/infoblox-ansible/pull/154>`_ +- Fix to remove issue causing due to template attr in deleting network using Ansible module nios network `#147 <https://github.com/infobloxopen/infoblox-ansible/pull/147>`_ - Update `text` field of TXT Record `#128 <https://github.com/infobloxopen/infoblox-ansible/pull/128>`_ - Update operation using `old_name` and `new_name` for the object with dummy name in `old_name` (which does not exist in system) will not create a new object in the system. An error will be thrown stating the object does not exist in the system `#129 <https://github.com/infobloxopen/infoblox-ansible/pull/129>`_ +junipernetworks.junos +~~~~~~~~~~~~~~~~~~~~~ + +- Use of connection: local and the provider option are no longer valid on any modules in this collection. + +vyos.vyos +~~~~~~~~~ + +- Use of connection: local and the provider option are no longer valid on any modules in this collection. + Removed Collections ------------------- @@ -689,6 +544,56 @@ amazon.aws - ec2_vol - the previously deprecated state ``list`` has been removed. To list volumes the ``ec2_vol_info`` module can be used (https://github.com/ansible-collections/amazon.aws/pull/828). - module_utils.batch - the class ``ansible_collections.amazon.aws.plugins.module_utils.batch.AWSConnection`` has been removed. Please use ``AnsibleAWSModule.client()`` instead (https://github.com/ansible-collections/amazon.aws/pull/831). +ansible.netcommon +~~~~~~~~~~~~~~~~~ + +- napalm - Removed unused connection plugin. +- net_banner - Use <network_os>_banner instead. +- net_interface - Use <network_os>_interfaces instead. +- net_l2_interface - Use <network_os>_l2_interfaces instead. +- net_l3_interface - Use <network_os>_l3_interfaces instead. +- net_linkagg - Use <network_os>_lag_interfaces instead. +- net_lldp - Use <network_os>_lldp_global instead. +- net_lldp_interface - Use <network_os>_lldp_interfaces instead. +- net_logging - Use <network_os>_logging_global instead. +- net_static_route - Use <network_os>_static_routes instead. +- net_system - Use <network_os>_system instead. +- net_user - Use <network_os>_user instead. +- net_vlan - Use <network_os>_vlans instead. +- net_vrf - Use <network_os>_vrf instead. + +cisco.ios +~~~~~~~~~ + +- ios_interface - use ios_interfaces instead. +- ios_l2_interface - use ios_l2_interfaces instead. +- ios_l3_interface - use ios_l3_interfaces instead. +- ios_static_route - use ios_static_routes instead. +- ios_vlan - use ios_vlans instead. + +cisco.iosxr +~~~~~~~~~~~ + +- iosxr_interface - use iosxr_interfaces instead. + +cisco.nxos +~~~~~~~~~~ + +- This release removes the following deprecated plugins that have reached their end-of-life. +- nxos_acl +- nxos_acl_interface +- nxos_interface +- nxos_interface_ospf +- nxos_l2_interface +- nxos_l3_interface +- nxos_linkagg +- nxos_lldp +- nxos_ospf +- nxos_ospf_vrf +- nxos_smu +- nxos_static_route +- nxos_vlan + community.aws ~~~~~~~~~~~~~ @@ -791,10 +696,79 @@ community.docker - docker_container - the default of ``command_handling`` was changed from ``compatibility`` to ``correct``. Older versions were warning for every invocation of the module when this would result in a change of behavior (https://github.com/ansible-collections/community.docker/pull/399). - docker_stack - the return values ``out`` and ``err`` have been removed. Use ``stdout`` and ``stderr`` instead (https://github.com/ansible-collections/community.docker/pull/363). +community.general +~~~~~~~~~~~~~~~~~ + +- bitbucket* modules - ``username`` is no longer an alias of ``workspace``, but of ``user`` (https://github.com/ansible-collections/community.general/pull/5326). +- gem - the default of the ``norc`` option changed from ``false`` to ``true`` (https://github.com/ansible-collections/community.general/pull/5326). +- gitlab_group_members - ``gitlab_group`` must now always contain the full path, and no longer just the name or path (https://github.com/ansible-collections/community.general/pull/5326). +- keycloak_authentication - the return value ``flow`` has been removed. Use ``end_state`` instead (https://github.com/ansible-collections/community.general/pull/5326). +- keycloak_group - the return value ``group`` has been removed. Use ``end_state`` instead (https://github.com/ansible-collections/community.general/pull/5326). +- lxd_container - the default of the ``ignore_volatile_options`` option changed from ``true`` to ``false`` (https://github.com/ansible-collections/community.general/pull/5326). +- mail callback plugin - the ``sender`` option is now required (https://github.com/ansible-collections/community.general/pull/5326). +- module_helper module utils - remove the ``VarDict`` attribute from ``ModuleHelper``. Import ``VarDict`` from ``ansible_collections.community.general.plugins.module_utils.mh.mixins.vars`` instead (https://github.com/ansible-collections/community.general/pull/5326). +- proxmox inventory plugin - the default of the ``want_proxmox_nodes_ansible_host`` option changed from ``true`` to ``false`` (https://github.com/ansible-collections/community.general/pull/5326). +- vmadm - the ``debug`` option has been removed. It was not used anyway (https://github.com/ansible-collections/community.general/pull/5326). + +community.network +~~~~~~~~~~~~~~~~~ + +- aireos modules - removed deprecated ``connection: local`` support. Use ``connection: network_cli`` instead (https://github.com/ansible-collections/community.network/pull/440). +- aireos modules - removed deprecated ``provider`` option. Use ``connection: network_cli`` instead (https://github.com/ansible-collections/community.network/pull/440). +- aruba modules - removed deprecated ``connection: local`` support. Use ``connection: network_cli`` instead (https://github.com/ansible-collections/community.network/pull/440). +- aruba modules - removed deprecated ``provider`` option. Use ``connection: network_cli`` instead (https://github.com/ansible-collections/community.network/pull/440). +- ce modules - removed deprecated ``connection: local`` support. Use ``connection: network_cli`` instead (https://github.com/ansible-collections/community.network/pull/440). +- ce modules - removed deprecated ``provider`` option. Use ``connection: network_cli`` instead (https://github.com/ansible-collections/community.network/pull/440). +- enos modules - removed deprecated ``connection: local`` support. Use ``connection: network_cli`` instead (https://github.com/ansible-collections/community.network/pull/440). +- enos modules - removed deprecated ``provider`` option. Use ``connection: network_cli`` instead (https://github.com/ansible-collections/community.network/pull/440). +- ironware modules - removed deprecated ``connection: local`` support. Use ``connection: network_cli`` instead (https://github.com/ansible-collections/community.network/pull/440). +- ironware modules - removed deprecated ``provider`` option. Use ``connection: network_cli`` instead (https://github.com/ansible-collections/community.network/pull/440). +- sros modules - removed deprecated ``connection: local`` support. Use ``connection: network_cli`` instead (https://github.com/ansible-collections/community.network/pull/440). +- sros modules - removed deprecated ``provider`` option. Use ``connection: network_cli`` instead (https://github.com/ansible-collections/community.network/pull/440). + +community.vmware +~~~~~~~~~~~~~~~~ + +- vca_fw - The deprecated module ``vca_fw`` has been removed. +- vca_nat - The deprecated module ``vca_nat`` has been removed. +- vca_vapp - The deprecated module ``vca_vapp`` has been removed. +- vmware_dns_config - The deprecated module ``vmware_dns_config`` has been removed, you can use ``vmware_host_dns`` instead. +- vmware_guest_network - The deprecated parameter ``networks`` has been removed, use loops to handle multiple interfaces (https://github.com/ansible-collections/community.vmware/pull/1459). +- vmware_guest_vnc - The deprecated module ``vmware_guest_vnc`` has been removed. The VNC support has been dropped with vSphere 7 and later (https://github.com/ansible-collections/community.vmware/pull/1454). +- vmware_host_firewall_manager - The module doesn't accept a list for ``allowed_hosts`` anymore, use a dict instead. Additionally, ``all_ip`` is now a required sub-option of ``allowed_hosts`` (https://github.com/ansible-collections/community.vmware/pull/1463). +- vsphere_copy - The deprecated parameters ``host`` and ``login`` have been removed. Use ``hostname`` and ``username`` instead (https://github.com/ansible-collections/community.vmware/pull/1456). + +junipernetworks.junos +~~~~~~~~~~~~~~~~~~~~~ + +- Remove following deprecated Junos Modules. +- junos_interface +- junos_l2_interface +- junos_l3_interface +- junos_linkagg +- junos_lldp +- junos_lldp_interface +- junos_static_route +- junos_vlan + +vyos.vyos +~~~~~~~~~ + +- vyos_interface - use vyos_interfaces instead. +- vyos_l3_interface - use vyos_l3_interfaces instead. +- vyos_linkagg - use vyos_lag_interfaces instead. +- vyos_lldp - use vyos_lldp_global instead. +- vyos_lldp_interface - use vyos_lldp_interfaces instead. +- vyos_static_route - use vyos_static_routes instead. + Deprecated Features ------------------- +- The dellemc.os10 collection is considered unmaintained and will be removed from Ansible 8 if no one starts maintaining it again before Ansible 8. See `the removal process for details on how this works <https://github.com/ansible-collections/overview/blob/main/removal_from_ansible.rst#cancelling-removal-of-an-unmaintained-collection>`__ (https://github.com/ansible-community/community-topics/issues/134). +- The dellemc.os6 collection is considered unmaintained and will be removed from Ansible 8 if no one starts maintaining it again before Ansible 8. See `the removal process for details on how this works <https://github.com/ansible-collections/overview/blob/main/removal_from_ansible.rst#cancelling-removal-of-an-unmaintained-collection>`__ (https://github.com/ansible-community/community-topics/issues/132). +- The dellemc.os9 collection is considered unmaintained and will be removed from Ansible 8 if no one starts maintaining it again before Ansible 8. See `the removal process for details on how this works <https://github.com/ansible-collections/overview/blob/main/removal_from_ansible.rst#cancelling-removal-of-an-unmaintained-collection>`__ (https://github.com/ansible-community/community-topics/issues/133). - The google.cloud collection is considered unmaintained and will be removed from Ansible 8 if no one starts maintaining it again before Ansible 8. See `the removal process for details on how this works <https://github.com/ansible-collections/overview/blob/main/removal_from_ansible.rst#cancelling-removal-of-an-unmaintained-collection>`__ (https://github.com/ansible-community/community-topics/issues/105). +- The mellanox.onyx collection is considered unmaintained and will be removed from Ansible 8 if no one starts maintaining it again before Ansible 8. See `the removal process for details on how this works <https://github.com/ansible-collections/overview/blob/main/removal_from_ansible.rst#cancelling-removal-of-an-unmaintained-collection>`__ (https://github.com/ansible-community/community-topics/issues/136). Ansible-core ~~~~~~~~~~~~ @@ -811,6 +785,17 @@ Ansible-core amazon.aws ~~~~~~~~~~ +- amazon.aws collection - Support for the ``EC2_ACCESS_KEY`` environment variable has been deprecated and will be removed in a release after 2024-12-01. Please use the ``access_key`` parameter or ``AWS_ACCESS_KEY_ID`` environment variable instead (https://github.com/ansible-collections/amazon.aws/pull/1172). +- amazon.aws collection - Support for the ``EC2_REGION`` environment variable has been deprecated and will be removed in a release after 2024-12-01. Please use the ``region`` parameter or ``AWS_REGION`` environment variable instead (https://github.com/ansible-collections/amazon.aws/pull/1172). +- amazon.aws collection - Support for the ``EC2_SECRET_KEY`` environment variable has been deprecated and will be removed in a release after 2024-12-01. Please use the ``secret_key`` parameter or ``AWS_SECRET_ACCESS_KEY`` environment variable instead (https://github.com/ansible-collections/amazon.aws/pull/1172). +- amazon.aws collection - Support for the ``EC2_SECURITY_TOKEN`` environment variable has been deprecated and will be removed in a release after 2024-12-01. Please use the ``session_token`` parameter or ``AWS_SESSION_TOKEN`` environment variable instead (https://github.com/ansible-collections/amazon.aws/pull/1172). +- amazon.aws collection - Support for the ``EC2_URL`` and ``S3_URL`` environment variables has been deprecated and will be removed in a release after 2024-12-01. Please use the ``endpoint_url`` parameter or ``AWS_ENDPOINT_URL`` environment variable instead (https://github.com/ansible-collections/amazon.aws/pull/1172). +- amazon.aws collection - The ``access_token`` alias for the ``session_token`` parameter has been deprecated and will be removed in a release after 2024-12-01. Please use the ``session_token`` name instead (https://github.com/ansible-collections/amazon.aws/pull/1172). +- amazon.aws collection - The ``aws_security_token`` alias for the ``session_token`` parameter has been deprecated and will be removed in a release after 2024-12-01. Please use the ``session_token`` name instead (https://github.com/ansible-collections/amazon.aws/pull/1172). +- amazon.aws collection - The ``ec2_access_key`` alias for the ``access_key`` parameter has been deprecated and will be removed in a release after 2024-12-01. Please use the ``access_key`` name instead (https://github.com/ansible-collections/amazon.aws/pull/1172). +- amazon.aws collection - The ``ec2_region`` alias for the ``region`` parameter has been deprecated and will be removed in a release after 2024-12-01. Please use the ``region`` name instead (https://github.com/ansible-collections/amazon.aws/pull/1172). +- amazon.aws collection - The ``ec2_secret_key`` alias for the ``secret_key`` parameter has been deprecated and will be removed in a release after 2024-12-01. Please use the ``secret_key`` name instead (https://github.com/ansible-collections/amazon.aws/pull/1172). +- amazon.aws collection - The ``security_token`` alias for the ``session_token`` parameter has been deprecated and will be removed in a release after 2024-12-01. Please use the ``session_token`` name instead (https://github.com/ansible-collections/amazon.aws/pull/1172). - amazon.aws collection - due to the AWS SDKs announcing the end of support for Python less than 3.7 (https://aws.amazon.com/blogs/developer/python-support-policy-updates-for-aws-sdks-and-tools/) support for Python less than 3.7 by this collection has been deprecated and will be removed in a release after 2023-05-31 (https://github.com/ansible-collections/amazon.aws/pull/935). - aws_s3 - The ``S3_URL`` alias for the s3_url option has been deprecated and will be removed in release 5.0.0 (https://github.com/ansible-collections/community.aws/pull/795). - ec2_ami - The ``DeviceName`` alias for the device_name option has been deprecated and will be removed in release 5.0.0 (https://github.com/ansible-collections/community.aws/pull/795). @@ -820,13 +805,16 @@ amazon.aws - ec2_instance - The default value for ```instance_type``` has been deprecated, in the future release you must set an instance_type or a launch_template (https://github.com/ansible-collections/amazon.aws/pull/587). - ec2_instance - the current default value of ``False`` for ``purge_tags`` has been deprecated and will be updated in release 5.0.0 to ``True`` (https://github.com/ansible-collections/amazon.aws/pull/849). - ec2_key - the current default value of ``False`` for ``purge_tags`` has been deprecated and will be updated in release 5.0.0 to ``True`` (https://github.com/ansible-collections/amazon.aws/pull/846). +- ec2_security_group - support for passing nested lists to ``cidr_ip`` and ``cidr_ipv6`` has been deprecated. Nested lists can be passed through the ``flatten`` filter instead ``cidr_ip: '{{ my_cidrs | flatten }}'`` (https://github.com/ansible-collections/amazon.aws/pull/1213). - ec2_vol - the current default value of ``False`` for ``purge_tags`` has been deprecated and will be updated in release 5.0.0 to ``True`` (https://github.com/ansible-collections/amazon.aws/pull/846). - ec2_vpc_dhcp_option_info - The ``DhcpOptionIds`` alias for the dhcp_option_ids option has been deprecated and will be removed in release 5.0.0 (https://github.com/ansible-collections/community.aws/pull/795). - ec2_vpc_dhcp_option_info - The ``DryRun`` alias for the dry_run option has been deprecated and will be removed in release 5.0.0 (https://github.com/ansible-collections/community.aws/pull/795). - ec2_vpc_endpoint - the current default value of ``False`` for ``purge_tags`` has been deprecated and will be updated in release 5.0.0 to ``True`` (https://github.com/ansible-collections/amazon.aws/pull/846). - ec2_vpc_net - the current default value of ``False`` for ``purge_tags`` has been deprecated and will be updated in release 5.0.0 to ``True`` (https://github.com/ansible-collections/amazon.aws/pull/848). - ec2_vpc_route_table - the current default value of ``False`` for ``purge_tags`` has been deprecated and will be updated in release 5.0.0 to ``True`` (https://github.com/ansible-collections/amazon.aws/pull/846). +- inventory/aws_ec2 - the ``include_extra_api_calls`` is now deprecated, its value is silently ignored (https://github.com/ansible-collections/amazon.aws/pull/1097). - module_utils.cloud - removal of the ``CloudRetry.backoff`` has been delayed until release 6.0.0. It is recommended to update custom modules to use ``jittered_backoff`` or ``exponential_backoff`` instead (https://github.com/ansible-collections/amazon.aws/pull/951). +- module_utils.url - ``ansible_collections.amazon.aws.module_utils.urls`` is believed to be unused and has been deprecated and will be removed in release 7.0.0. - s3_bucket - The ``S3_URL`` alias for the s3_url option has been deprecated and will be removed in release 5.0.0 (https://github.com/ansible-collections/community.aws/pull/795). - s3_object - Support for creation and deletion of S3 buckets has been deprecated. Please use the ``amazon.aws.s3_bucket`` module to create and delete buckets (https://github.com/ansible-collections/amazon.aws/pull/869). @@ -835,6 +823,11 @@ cisco.ios - Deprecated ios_linkagg_module in favor of ios_lag_interfaces. +cisco.mso +~~~~~~~~~ + +- The mso_schema_template_contract_filter contract_filter_type attribute is deprecated. The value is now deduced from filter_type. + community.aws ~~~~~~~~~~~~~ @@ -864,12 +857,25 @@ community.docker - Support for Docker API version 1.20 to 1.24 has been deprecated and will be removed in community.docker 3.0.0. The first Docker version supporting API version 1.25 was Docker 1.13, released in January 2017. This affects the modules ``docker_container``, ``docker_container_exec``, ``docker_container_info``, ``docker_compose``, ``docker_login``, ``docker_image``, ``docker_image_info``, ``docker_image_load``, ``docker_host_info``, ``docker_network``, ``docker_network_info``, ``docker_node_info``, ``docker_swarm_info``, ``docker_swarm_service``, ``docker_swarm_service_info``, ``docker_volume_info``, and ``docker_volume``, whose minimally supported API version is between 1.20 and 1.24 (https://github.com/ansible-collections/community.docker/pull/396). - Support for Python 2.6 is deprecated and will be removed in the next major release (community.docker 3.0.0). Some modules might still work with Python 2.6, but we will no longer try to ensure compatibility (https://github.com/ansible-collections/community.docker/pull/388). +- docker_container - the ``ignore_image`` option is deprecated and will be removed in community.docker 4.0.0. Use ``image: ignore`` in ``comparisons`` instead (https://github.com/ansible-collections/community.docker/pull/487). +- docker_container - the ``purge_networks`` option is deprecated and will be removed in community.docker 4.0.0. Use ``networks: strict`` in ``comparisons`` instead, and make sure to provide ``networks``, with value ``[]`` if all networks should be removed (https://github.com/ansible-collections/community.docker/pull/487). community.general ~~~~~~~~~~~~~~~~~ +- ArgFormat module utils - deprecated along ``CmdMixin``, in favor of the ``cmd_runner_fmt`` module util (https://github.com/ansible-collections/community.general/pull/5370). +- CmdMixin module utils - deprecated in favor of the ``CmdRunner`` module util (https://github.com/ansible-collections/community.general/pull/5370). +- CmdModuleHelper module utils - deprecated in favor of the ``CmdRunner`` module util (https://github.com/ansible-collections/community.general/pull/5370). +- CmdStateModuleHelper module utils - deprecated in favor of the ``CmdRunner`` module util (https://github.com/ansible-collections/community.general/pull/5370). - cmd_runner module utils - deprecated ``fmt`` in favour of ``cmd_runner_fmt`` as the parameter format object (https://github.com/ansible-collections/community.general/pull/4777). +- django_manage - support for Django releases older than 4.1 has been deprecated and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5400). +- django_manage - support for the commands ``cleanup``, ``syncdb`` and ``validate`` that have been deprecated in Django long time ago will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/5400). +- django_manage - the behavior of "creating the virtual environment when missing" is being deprecated and will be removed in community.general version 9.0.0 (https://github.com/ansible-collections/community.general/pull/5405). +- gconftool2 - deprecates ``state=get`` in favor of using the module ``gconftool2_info`` (https://github.com/ansible-collections/community.general/pull/4778). +- lxc_container - the module will no longer make any effort to support Python 2 (https://github.com/ansible-collections/community.general/pull/5304). +- newrelic_deployment - ``appname`` and ``environment`` are no longer valid options in the v2 API. They will be removed in community.general 7.0.0 (https://github.com/ansible-collections/community.general/pull/5341). - proxmox - deprecated the current ``unprivileged`` default value, will be changed to ``true`` in community.general 7.0.0 (https://github.com/pull/5224). +- xfconf - deprecated parameter ``disable_facts``, as since version 4.0.0 it only allows value ``true`` (https://github.com/ansible-collections/community.general/pull/4520). community.hashi_vault ~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/docsite/rst/porting_guides/porting_guides.rst b/docs/docsite/rst/porting_guides/porting_guides.rst index 562ae57f..1e8f6a43 100644 --- a/docs/docsite/rst/porting_guides/porting_guides.rst +++ b/docs/docsite/rst/porting_guides/porting_guides.rst @@ -10,6 +10,7 @@ This section lists porting guides that can help you in updating playbooks, plugi :maxdepth: 1 :glob: + porting_guide_7 porting_guide_6 porting_guide_5 porting_guide_4 diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index 719db4bb..cb490edd 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -138,7 +138,7 @@ or globally by setting ``ssh_args`` in ``ansible.cfg``. How do I get Ansible to notice a dead target in a timely manner? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -You can add ``-o ServerAliveInterval=NumberOfSeconds`` in ``ssh_args`` from ``ansible.cfg``. Without this option, +You can add ``-o ServerAliveInterval=NumberOfSeconds`` with the ``ssh_args`` parameter in `SSH connection plugin <https://docs.ansible.com/ansible-core/devel/collections/ansible/builtin/ssh_connection.html#parameter-ssh_args>`_. Without this option, SSH and therefore Ansible will wait until the TCP connection times out. Another solution is to add ``ServerAliveInterval`` into your global SSH configuration. A good value for ``ServerAliveInterval`` is up to you to decide; keep in mind that ``ServerAliveCountMax=3`` is the SSH default so any value you set will be tripled before terminating the SSH session. @@ -618,10 +618,19 @@ Also array notation allows for dynamic variable composition, see dynamic_variabl Another problem with 'dot notation' is that some keys can cause problems because they collide with attributes and methods of python dictionaries. +* Example of incorrect syntax when ``item`` is a dictionary: + .. code-block:: jinja - item.update # this breaks if item is a dictionary, as 'update()' is a python method for dictionaries - item['update'] # this works + item.update + +This variant causes a syntax error because ``update()`` is a Python method for dictionaries. + +* Example of correct syntax: + +.. code-block:: jinja + + item['update'] .. _argsplat_unsafe: diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst index 8fa16d21..a5039fc4 100644 --- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst +++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst @@ -77,17 +77,19 @@ Ansible community changelogs This table links to the changelogs for each major Ansible release. These changelogs contain the dates and significant changes in each minor release. -================================== ============================ ========================= -Ansible Community Package Release Status Core version dependency -================================== ============================ ========================= -7.0.0 In development (unreleased) 2.14 -`6.x Changelogs`_ Current 2.13 -`5.x Changelogs`_ Unmaintained (end of life) 2.12 -`4.x Changelogs`_ Unmaintained (end of life) 2.11 -`3.x Changelogs`_ Unmaintained (end of life) 2.10 -`2.10 Changelogs`_ Unmaintained (end of life) 2.10 -================================== ============================ ========================= - +================================== ============================================== ========================= +Ansible Community Package Release Status Core version dependency +================================== ============================================== ========================= +8.0.0 In development (unreleased) 2.15 +`7.x Changelogs`_ Current 2.14 +`6.x Changelogs`_ Unmaintained (end of life) after Ansible 6.7.0 2.13 +`5.x Changelogs`_ Unmaintained (end of life) 2.12 +`4.x Changelogs`_ Unmaintained (end of life) 2.11 +`3.x Changelogs`_ Unmaintained (end of life) 2.10 +`2.10 Changelogs`_ Unmaintained (end of life) 2.10 +================================== ============================================== ========================= + +.. _7.x Changelogs: https://github.com/ansible-community/ansible-build-data/blob/main/7/CHANGELOG-v7.rst .. _6.x Changelogs: https://github.com/ansible-community/ansible-build-data/blob/main/6/CHANGELOG-v6.rst .. _5.x Changelogs: https://github.com/ansible-community/ansible-build-data/blob/main/5/CHANGELOG-v5.rst .. _4.x Changelogs: https://github.com/ansible-community/ansible-build-data/blob/main/4/CHANGELOG-v4.rst @@ -125,10 +127,11 @@ significant changes in each minor release. ``ansible-core``/``ansible-base`` Status Expected end of life Release ================================= ==================================================== ====================== -devel In development (ansible-core 2.14 unreleased, trunk) TBD -`2.13 ansible-core Changelogs`_ Maintained (security **and** general bug fixes) Nov 2023 -`2.12 ansible-core Changelogs`_ Maintained (security **and** critical bug fixes) May 2023 -`2.11 ansible-core Changelogs`_ Maintained (security bug fixes only) Nov 2022 +devel In development (ansible-core 2.15 unreleased, trunk) TBD +`2.14 ansible-core Changelogs`_ Maintained (security **and** general bug fixes) May 2024 +`2.13 ansible-core Changelogs`_ Maintained (security **and** critical bug fixes) Nov 2023 +`2.12 ansible-core Changelogs`_ Maintained (security bug fixes only) May 2023 +`2.11 ansible-core Changelogs`_ Unmaintained (end of life) EOL `2.10 ansible-base Changelogs`_ Unmaintained (end of life) EOL `2.9 Changelogs`_ Unmaintained (end of life) EOL `2.8 Changelogs`_ Unmaintained (end of life) EOL @@ -138,6 +141,8 @@ devel In development (ansible-core 2.14 unreleased, <2.5 Unmaintained (end of life) EOL ================================= ==================================================== ====================== +.. _2.14 ansible-core Changelogs: +.. _2.14: https://github.com/ansible/ansible/blob/stable-2.14/changelogs/CHANGELOG-v2.14.rst .. _2.13 ansible-core Changelogs: .. _2.13: https://github.com/ansible/ansible/blob/stable-2.13/changelogs/CHANGELOG-v2.13.rst .. _2.12 ansible-core Changelogs: diff --git a/docs/docsite/rst/roadmap/COLLECTIONS_7.rst b/docs/docsite/rst/roadmap/COLLECTIONS_7.rst index 1f6e9966..ca763408 100644 --- a/docs/docsite/rst/roadmap/COLLECTIONS_7.rst +++ b/docs/docsite/rst/roadmap/COLLECTIONS_7.rst @@ -26,9 +26,11 @@ Release schedule :2022-11-08: Create the ansible-build-data directory and files for Ansible-8. :2022-11-08: Ansible-7.0.0 beta1 -- feature freeze [1]_ (weekly beta releases; collection owners and interested users should test for bugs). :2022-11-15: Ansible-7.0.0 rc1 [2]_ [3]_ (weekly release candidates as needed; test and alert us to any blocker bugs). Blocker bugs will slip release. -:2022-11-29: Ansible-7.0.0 release. -:2022-12-06: Release of ansible-core 2.14.1. -:2022-12-20: Release of Ansible-7.1.0 (bugfix + compatible features: every three weeks.) +:2022-11-18: Last day to trigger an Ansible-7.0.0rc2 release because of major defects in Ansible-7.0.0rc1. +:2022-11-22: Ansible-7.0.0rc2 when necessary, otherwise Ansible-7.0.0 release. +:2022-11-29: Ansible-7.0.0 release when Ansible-7.0.0rc2 was necessary. +:2022-12-05: Release of ansible-core 2.14.1. +:2022-12-06: Release of Ansible-7.1.0 (bugfix + compatible features: every four weeks.) .. [1] No new modules or major features accepted 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 2.3.0; Ansible-7.0.0 could ship with community.crypto 2.3.1. It would not ship with community.crypto 2.4.0. @@ -44,7 +46,7 @@ Release schedule Ansible minor releases ======================= -Ansible 7.x minor releases will occur approximately every three weeks if changes to collections have been made or if it is deemed necessary to force an upgrade to a later ansible-core-2.14.x. Ansible 7.x minor 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. For example, if Ansible-7.0.0 ships with community.crypto 2.3.0; Ansible-6.1.0 may ship with community.crypto 2.4.0 but would not ship with community.crypto 3.0.0. +Ansible 7.x minor releases will occur approximately every four weeks if changes to collections have been made or to align to a later ansible-core-2.14.x. Ansible 7.x minor 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. For example, if Ansible-7.0.0 ships with community.crypto 2.3.0; Ansible-6.1.0 may ship with community.crypto 2.4.0 but would not ship with community.crypto 3.0.0. .. note:: diff --git a/docs/docsite/sphinx_conf/ansible_conf.py b/docs/docsite/sphinx_conf/ansible_conf.py index 9549061c..1ccf6966 100644 --- a/docs/docsite/sphinx_conf/ansible_conf.py +++ b/docs/docsite/sphinx_conf/ansible_conf.py @@ -32,7 +32,7 @@ sys.path.insert(0, os.path.join('ansible', 'lib')) # the repository version needs to be the one that is loaded: sys.path.insert(0, os.path.abspath(os.path.join('..', '..', '..', 'lib'))) -VERSION = 'devel' +VERSION = '7' AUTHOR = 'Ansible, Inc' @@ -164,7 +164,7 @@ html_context = { 'github_root_dir': 'devel/lib/ansible', 'github_cli_version': 'devel/lib/ansible/cli/', 'current_version': version, - 'latest_version': '6', + 'latest_version': '7', # list specifically out of order to make latest work 'available_versions': ('latest', '2.9', 'devel'), } diff --git a/docs/docsite/sphinx_conf/core_conf.py b/docs/docsite/sphinx_conf/core_conf.py index 8615bc63..58237467 100644 --- a/docs/docsite/sphinx_conf/core_conf.py +++ b/docs/docsite/sphinx_conf/core_conf.py @@ -32,7 +32,7 @@ sys.path.insert(0, os.path.join('ansible', 'lib')) # the repository version needs to be the one that is loaded: sys.path.insert(0, os.path.abspath(os.path.join('..', '..', '..', 'lib'))) -VERSION = 'devel' +VERSION = '2.14' AUTHOR = 'Ansible, Inc' @@ -201,9 +201,9 @@ html_context = { 'github_root_dir': 'devel/lib/ansible', 'github_cli_version': 'devel/lib/ansible/cli/', 'current_version': version, - 'latest_version': '2.13', + 'latest_version': '2.14', # list specifically out of order to make latest work - 'available_versions': ('2.13', '2.12', '2.11', 'devel',), + 'available_versions': ('2.14', '2.13', '2.12', 'devel',), } # Add extra CSS styles to the resulting HTML pages diff --git a/docs/docsite/sphinx_conf/core_lang_conf.py b/docs/docsite/sphinx_conf/core_lang_conf.py index 8ca4aa7e..9b84c87a 100644 --- a/docs/docsite/sphinx_conf/core_lang_conf.py +++ b/docs/docsite/sphinx_conf/core_lang_conf.py @@ -32,7 +32,7 @@ sys.path.insert(0, os.path.join('ansible', 'lib')) # the repository version needs to be the one that is loaded: sys.path.insert(0, os.path.abspath(os.path.join('..', '..', '..', 'lib'))) -VERSION = 'devel' +VERSION = '2.14_ja' AUTHOR = 'Ansible, Inc' @@ -201,9 +201,9 @@ html_context = { 'github_root_dir': 'devel/lib/ansible', 'github_cli_version': 'devel/lib/ansible/cli/', 'current_version': version, - 'latest_version': '2.13', + 'latest_version': '2.14', # list specifically out of order to make latest work - 'available_versions': ('2.13_ja', '2.12_ja', '2.11_ja',), + 'available_versions': ('2.14_ja', '2.13_ja', '2.12_ja',), } # Add extra CSS styles to the resulting HTML pages diff --git a/docs/man/man1/ansible-config.1 b/docs/man/man1/ansible-config.1 index b42d8b64..daf4a350 100644 --- a/docs/man/man1/ansible-config.1 +++ b/docs/man/man1/ansible-config.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "ANSIBLE-CONFIG" 1 "" "Ansible 2.14.0" "System administration commands" +.TH "ANSIBLE-CONFIG" 1 "" "Ansible 2.14.1" "System administration commands" .SH NAME ansible-config \- View ansible configuration. .SH SYNOPSIS diff --git a/docs/man/man1/ansible-console.1 b/docs/man/man1/ansible-console.1 index c360002c..b7dd9969 100644 --- a/docs/man/man1/ansible-console.1 +++ b/docs/man/man1/ansible-console.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "ANSIBLE-CONSOLE" 1 "" "Ansible 2.14.0" "System administration commands" +.TH "ANSIBLE-CONSOLE" 1 "" "Ansible 2.14.1" "System administration commands" .SH NAME ansible-console \- REPL console for executing Ansible tasks. .SH SYNOPSIS diff --git a/docs/man/man1/ansible-doc.1 b/docs/man/man1/ansible-doc.1 index 482e1970..9dae87a3 100644 --- a/docs/man/man1/ansible-doc.1 +++ b/docs/man/man1/ansible-doc.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "ANSIBLE-DOC" 1 "" "Ansible 2.14.0" "System administration commands" +.TH "ANSIBLE-DOC" 1 "" "Ansible 2.14.1" "System administration commands" .SH NAME ansible-doc \- plugin documentation tool .SH SYNOPSIS diff --git a/docs/man/man1/ansible-galaxy.1 b/docs/man/man1/ansible-galaxy.1 index 9c637b6c..32c13c98 100644 --- a/docs/man/man1/ansible-galaxy.1 +++ b/docs/man/man1/ansible-galaxy.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "ANSIBLE-GALAXY" 1 "" "Ansible 2.14.0" "System administration commands" +.TH "ANSIBLE-GALAXY" 1 "" "Ansible 2.14.1" "System administration commands" .SH NAME ansible-galaxy \- Perform various Role and Collection related operations. .SH SYNOPSIS diff --git a/docs/man/man1/ansible-inventory.1 b/docs/man/man1/ansible-inventory.1 index 5bcc5101..dc09adb0 100644 --- a/docs/man/man1/ansible-inventory.1 +++ b/docs/man/man1/ansible-inventory.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "ANSIBLE-INVENTORY" 1 "" "Ansible 2.14.0" "System administration commands" +.TH "ANSIBLE-INVENTORY" 1 "" "Ansible 2.14.1" "System administration commands" .SH NAME ansible-inventory \- None .SH SYNOPSIS diff --git a/docs/man/man1/ansible-playbook.1 b/docs/man/man1/ansible-playbook.1 index cba2f76a..872a62d7 100644 --- a/docs/man/man1/ansible-playbook.1 +++ b/docs/man/man1/ansible-playbook.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "ANSIBLE-PLAYBOOK" 1 "" "Ansible 2.14.0" "System administration commands" +.TH "ANSIBLE-PLAYBOOK" 1 "" "Ansible 2.14.1" "System administration commands" .SH NAME ansible-playbook \- Runs Ansible playbooks, executing the defined tasks on the targeted hosts. .SH SYNOPSIS diff --git a/docs/man/man1/ansible-pull.1 b/docs/man/man1/ansible-pull.1 index 78182d34..02947567 100644 --- a/docs/man/man1/ansible-pull.1 +++ b/docs/man/man1/ansible-pull.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "ANSIBLE-PULL" 1 "" "Ansible 2.14.0" "System administration commands" +.TH "ANSIBLE-PULL" 1 "" "Ansible 2.14.1" "System administration commands" .SH NAME ansible-pull \- pulls playbooks from a VCS repo and executes them for the local host .SH SYNOPSIS @@ -59,6 +59,10 @@ This inverts the default \fIpush\fP architecture of ansible into a \fIpull\fP architecture, which has near\-limitless scaling potential. .sp +None of the CLI tools are designed to run concurrently with themselves, +you should use an external scheduler and/or locking to ensure there are no +clashing operations. +.sp The setup playbook can be tuned to change the cron frequency, logging locations, and parameters to ansible\-pull. This is useful both for extreme scale\-out as well as periodic remediation. diff --git a/docs/man/man1/ansible-vault.1 b/docs/man/man1/ansible-vault.1 index 96a7e82b..27ec26c4 100644 --- a/docs/man/man1/ansible-vault.1 +++ b/docs/man/man1/ansible-vault.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "ANSIBLE-VAULT" 1 "" "Ansible 2.14.0" "System administration commands" +.TH "ANSIBLE-VAULT" 1 "" "Ansible 2.14.1" "System administration commands" .SH NAME ansible-vault \- encryption/decryption utility for Ansible data files .SH SYNOPSIS diff --git a/docs/man/man1/ansible.1 b/docs/man/man1/ansible.1 index 1342385b..add01897 100644 --- a/docs/man/man1/ansible.1 +++ b/docs/man/man1/ansible.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "ANSIBLE" 1 "" "Ansible 2.14.0" "System administration commands" +.TH "ANSIBLE" 1 "" "Ansible 2.14.1" "System administration commands" .SH NAME ansible \- Define and run a single task 'playbook' against a set of hosts .SH SYNOPSIS diff --git a/lib/ansible/cli/galaxy.py b/lib/ansible/cli/galaxy.py index acc3f120..f4148d92 100755 --- a/lib/ansible/cli/galaxy.py +++ b/lib/ansible/cli/galaxy.py @@ -17,7 +17,9 @@ import shutil import sys import textwrap import time +import typing as t +from dataclasses import dataclass from yaml.error import YAMLError import ansible.constants as C @@ -170,6 +172,30 @@ def validate_signature_count(value): return value +@dataclass +class RoleDistributionServer: + _api: t.Union[GalaxyAPI, None] + api_servers: list[GalaxyAPI] + + @property + def api(self): + if self._api: + return self._api + + for server in self.api_servers: + try: + if u'v1' in server.available_api_versions: + self._api = server + break + except Exception: + continue + + if not self._api: + self._api = self.api_servers[0] + + return self._api + + class GalaxyCLI(CLI): '''command to manage Ansible roles in shared repositories, the default of which is Ansible Galaxy *https://galaxy.ansible.com*.''' @@ -198,7 +224,7 @@ class GalaxyCLI(CLI): self.api_servers = [] self.galaxy = None - self._api = None + self.lazy_role_api = None super(GalaxyCLI, self).__init__(args) def init_parser(self): @@ -678,25 +704,15 @@ class GalaxyCLI(CLI): **galaxy_options )) + # checks api versions once a GalaxyRole makes an api call + # self.api can be used to evaluate the best server immediately + self.lazy_role_api = RoleDistributionServer(None, self.api_servers) + return context.CLIARGS['func']() @property def api(self): - if self._api: - return self._api - - for server in self.api_servers: - try: - if u'v1' in server.available_api_versions: - self._api = server - break - except Exception: - continue - - if not self._api: - self._api = self.api_servers[0] - - return self._api + return self.lazy_role_api.api def _get_default_collection_path(self): return C.COLLECTIONS_PATHS[0] @@ -757,7 +773,7 @@ class GalaxyCLI(CLI): display.vvv("found role %s in yaml file" % to_text(role)) if "name" not in role and "src" not in role: raise AnsibleError("Must specify name or src for role") - return [GalaxyRole(self.galaxy, self.api, **role)] + return [GalaxyRole(self.galaxy, self.lazy_role_api, **role)] else: b_include_path = to_bytes(requirement["include"], errors="surrogate_or_strict") if not os.path.isfile(b_include_path): @@ -766,7 +782,7 @@ class GalaxyCLI(CLI): with open(b_include_path, 'rb') as f_include: try: - return [GalaxyRole(self.galaxy, self.api, **r) for r in + return [GalaxyRole(self.galaxy, self.lazy_role_api, **r) for r in (RoleRequirement.role_yaml_parse(i) for i in yaml_load(f_include))] except Exception as e: raise AnsibleError("Unable to load data from include requirements file: %s %s" @@ -1182,7 +1198,7 @@ class GalaxyCLI(CLI): for role in context.CLIARGS['args']: role_info = {'path': roles_path} - gr = GalaxyRole(self.galaxy, self.api, role) + gr = GalaxyRole(self.galaxy, self.lazy_role_api, role) install_info = gr.install_info if install_info: @@ -1327,7 +1343,7 @@ class GalaxyCLI(CLI): # (and their dependencies, unless the user doesn't want us to). for rname in context.CLIARGS['args']: role = RoleRequirement.role_yaml_parse(rname.strip()) - role_requirements.append(GalaxyRole(self.galaxy, self.api, **role)) + role_requirements.append(GalaxyRole(self.galaxy, self.lazy_role_api, **role)) if not role_requirements and not collection_requirements: display.display("Skipping install, no requirements found") @@ -1438,7 +1454,7 @@ class GalaxyCLI(CLI): display.debug('Installing dep %s' % dep) dep_req = RoleRequirement() dep_info = dep_req.role_yaml_parse(dep) - dep_role = GalaxyRole(self.galaxy, self.api, **dep_info) + dep_role = GalaxyRole(self.galaxy, self.lazy_role_api, **dep_info) if '.' not in dep_role.name and '.' not in dep_role.src and dep_role.scm is None: # we know we can skip this, as it's not going to # be found on galaxy.ansible.com @@ -1522,7 +1538,7 @@ class GalaxyCLI(CLI): if role_name: # show the requested role, if it exists - gr = GalaxyRole(self.galaxy, self.api, role_name, path=os.path.join(role_path, role_name)) + gr = GalaxyRole(self.galaxy, self.lazy_role_api, role_name, path=os.path.join(role_path, role_name)) if os.path.isdir(gr.path): role_found = True display.display('# %s' % os.path.dirname(gr.path)) @@ -1541,7 +1557,7 @@ class GalaxyCLI(CLI): display.display('# %s' % role_path) path_files = os.listdir(role_path) for path_file in path_files: - gr = GalaxyRole(self.galaxy, self.api, path_file, path=path) + gr = GalaxyRole(self.galaxy, self.lazy_role_api, path_file, path=path) if gr.metadata: _display_role(gr) diff --git a/lib/ansible/cli/pull.py b/lib/ansible/cli/pull.py index 99da8c4f..dc8f055b 100755 --- a/lib/ansible/cli/pull.py +++ b/lib/ansible/cli/pull.py @@ -38,6 +38,9 @@ class PullCLI(CLI): This inverts the default *push* architecture of ansible into a *pull* architecture, which has near-limitless scaling potential. + None of the CLI tools are designed to run concurrently with themselves, + you should use an external scheduler and/or locking to ensure there are no clashing operations. + The setup playbook can be tuned to change the cron frequency, logging locations, and parameters to ansible-pull. This is useful both for extreme scale-out as well as periodic remediation. Usage of the 'fetch' module to retrieve logs from ansible-pull runs would be an diff --git a/lib/ansible/executor/process/worker.py b/lib/ansible/executor/process/worker.py index d925864b..5113b83d 100644 --- a/lib/ansible/executor/process/worker.py +++ b/lib/ansible/executor/process/worker.py @@ -87,10 +87,12 @@ class WorkerProcess(multiprocessing_context.Process): # type: ignore[name-defin ''' self._save_stdin() - try: - return super(WorkerProcess, self).start() - finally: - self._new_stdin.close() + # FUTURE: this lock can be removed once a more generalized pre-fork thread pause is in place + with display._lock: + try: + return super(WorkerProcess, self).start() + finally: + self._new_stdin.close() def _hard_exit(self, e): ''' diff --git a/lib/ansible/galaxy/role.py b/lib/ansible/galaxy/role.py index 7a13c971..99bb525e 100644 --- a/lib/ansible/galaxy/role.py +++ b/lib/ansible/galaxy/role.py @@ -33,6 +33,7 @@ from shutil import rmtree from ansible import context from ansible.errors import AnsibleError, AnsibleParserError +from ansible.galaxy.api import GalaxyAPI from ansible.galaxy.user_agent import user_agent from ansible.module_utils._text import to_native, to_text from ansible.module_utils.common.yaml import yaml_dump, yaml_load @@ -63,7 +64,7 @@ class GalaxyRole(object): display.debug('Validate TLS certificates: %s' % self._validate_certs) self.galaxy = galaxy - self.api = api + self._api = api self.name = name self.version = version @@ -104,6 +105,12 @@ class GalaxyRole(object): return self.name == other.name @property + def api(self): + if not isinstance(self._api, GalaxyAPI): + return self._api.api + return self._api + + @property def metadata(self): """ Returns role metadata diff --git a/lib/ansible/module_utils/ansible_release.py b/lib/ansible/module_utils/ansible_release.py index 1562b704..a38538f5 100644 --- a/lib/ansible/module_utils/ansible_release.py +++ b/lib/ansible/module_utils/ansible_release.py @@ -19,6 +19,6 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -__version__ = '2.14.0' +__version__ = '2.14.1' __author__ = 'Ansible, Inc.' __codename__ = "C'mon Everybody" diff --git a/lib/ansible/modules/apt.py b/lib/ansible/modules/apt.py index 1070c300..1b7c5d29 100644 --- a/lib/ansible/modules/apt.py +++ b/lib/ansible/modules/apt.py @@ -68,7 +68,7 @@ options: type: str install_recommends: description: - - Corresponds to the C(--no-install-recommends) option for I(apt). C(yes) installs recommended packages. C(no) does not install + - Corresponds to the C(--no-install-recommends) option for I(apt). C(true) installs recommended packages. C(false) does not install recommended packages. By default, Ansible will use the same defaults as the operating system. Suggested packages are never installed. aliases: [ install-recommends ] type: bool @@ -141,14 +141,14 @@ options: version_added: "1.6" autoremove: description: - - If C(yes), remove unused dependency packages for all module states except I(build-dep). It can also be used as the only option. + - If C(true), remove unused dependency packages for all module states except I(build-dep). It can also be used as the only option. - Previous to version 2.4, autoclean was also an alias for autoremove, now it is its own separate command. See documentation for further information. type: bool default: 'no' version_added: "2.1" autoclean: description: - - If C(yes), cleans the local repository of retrieved package files that can no longer be downloaded. + - If C(true), cleans the local repository of retrieved package files that can no longer be downloaded. type: bool default: 'no' version_added: "2.4" @@ -170,7 +170,7 @@ options: fail_on_autoremove: description: - 'Corresponds to the C(--no-remove) option for C(apt).' - - 'If C(yes), it is ensured that no packages will be removed or the task will fail.' + - 'If C(true), it is ensured that no packages will be removed or the task will fail.' - 'C(fail_on_autoremove) is only supported with state except C(absent)' type: bool default: 'no' @@ -202,7 +202,7 @@ attributes: platform: platforms: debian notes: - - Three of the upgrade modes (C(full), C(safe) and its alias C(yes)) required C(aptitude) up to 2.3, since 2.4 C(apt-get) is used as a fall-back. + - Three of the upgrade modes (C(full), C(safe) and its alias C(true)) required C(aptitude) up to 2.3, since 2.4 C(apt-get) is used as a fall-back. - In most cases, packages installed with apt will start newly installed services by default. Most distributions have mechanisms to avoid this. For example when installing Postgresql-9.5 in Debian 9, creating an excutable shell script (/usr/sbin/policy-rc.d) that throws a return code of 101 will stop Postgresql 9.5 starting up after install. Remove the file or remove its execute permission afterwards. diff --git a/lib/ansible/modules/apt_key.py b/lib/ansible/modules/apt_key.py index 18b88344..67caf6da 100644 --- a/lib/ansible/modules/apt_key.py +++ b/lib/ansible/modules/apt_key.py @@ -74,7 +74,7 @@ options: default: present validate_certs: description: - - If C(no), SSL certificates for the target url will not be validated. This should only be used + - If C(false), SSL certificates for the target url will not be validated. This should only be used on personally controlled sites using self-signed certificates. type: bool default: 'yes' diff --git a/lib/ansible/modules/apt_repository.py b/lib/ansible/modules/apt_repository.py index 09d45e2c..f9a0cd91 100644 --- a/lib/ansible/modules/apt_repository.py +++ b/lib/ansible/modules/apt_repository.py @@ -64,7 +64,7 @@ options: version_added: '2.10' validate_certs: description: - - If C(no), SSL certificates for the target repo will not be validated. This should only be used + - If C(false), SSL certificates for the target repo will not be validated. This should only be used on personally controlled sites using self-signed certificates. type: bool default: 'yes' diff --git a/lib/ansible/modules/assemble.py b/lib/ansible/modules/assemble.py index ba74a555..2b443ce8 100644 --- a/lib/ansible/modules/assemble.py +++ b/lib/ansible/modules/assemble.py @@ -36,7 +36,7 @@ options: required: true backup: description: - - Create a backup file (if C(yes)), including the timestamp information so + - Create a backup file (if C(true)), including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. type: bool @@ -48,8 +48,8 @@ options: version_added: '1.4' remote_src: description: - - If C(no), it will search for src at originating/master machine. - - If C(yes), it will go to the remote/target machine for the src. + - If C(false), it will search for src at originating/master machine. + - If C(true), it will go to the remote/target machine for the src. type: bool default: yes version_added: '1.4' diff --git a/lib/ansible/modules/assert.py b/lib/ansible/modules/assert.py index 71b2424e..0ef5eb04 100644 --- a/lib/ansible/modules/assert.py +++ b/lib/ansible/modules/assert.py @@ -36,7 +36,7 @@ options: version_added: "2.7" quiet: description: - - Set this to C(yes) to avoid verbose output. + - Set this to C(true) to avoid verbose output. type: bool default: no version_added: "2.8" diff --git a/lib/ansible/modules/blockinfile.py b/lib/ansible/modules/blockinfile.py index 2f914418..63fc0214 100644 --- a/lib/ansible/modules/blockinfile.py +++ b/lib/ansible/modules/blockinfile.py @@ -36,6 +36,8 @@ options: - The marker line template. - C({mark}) will be replaced with the values in C(marker_begin) (default="BEGIN") and C(marker_end) (default="END"). - Using a custom marker without the C({mark}) variable may result in the block being repeatedly inserted on subsequent playbook runs. + - Multi-line markers are not supported and will result in the block being repeatedly inserted on subsequent playbook runs. + - A newline is automatically appended by the module to C(marker_begin) and C(marker_end). type: str default: '# {mark} ANSIBLE MANAGED BLOCK' block: diff --git a/lib/ansible/modules/command.py b/lib/ansible/modules/command.py index ecf4d0f6..778d8a26 100644 --- a/lib/ansible/modules/command.py +++ b/lib/ansible/modules/command.py @@ -81,7 +81,7 @@ options: type: bool default: yes description: - - If set to C(yes), append a newline to stdin data. + - If set to C(true), append a newline to stdin data. version_added: "2.8" strip_empty_ends: description: diff --git a/lib/ansible/modules/copy.py b/lib/ansible/modules/copy.py index 7fed4a5c..37115faf 100644 --- a/lib/ansible/modules/copy.py +++ b/lib/ansible/modules/copy.py @@ -55,8 +55,8 @@ options: force: description: - Influence whether the remote file must always be replaced. - - If C(yes), the remote file will be replaced when contents are different than the source. - - If C(no), the file will only be transferred if the destination does not exist. + - If C(true), the remote file will be replaced when contents are different than the source. + - If C(false), the file will only be transferred if the destination does not exist. type: bool default: yes version_added: '1.1' @@ -87,8 +87,8 @@ options: remote_src: description: - Influence whether C(src) needs to be transferred or already is present remotely. - - If C(no), it will search for C(src) on the controller node. - - If C(yes) it will search for C(src) on the managed (remote) node. + - If C(false), it will search for C(src) on the controller node. + - If C(true) it will search for C(src) on the managed (remote) node. - C(remote_src) supports recursive copying as of version 2.8. - C(remote_src) only works with C(mode=preserve) as of version 2.6. - Autodecryption of files does not work when C(remote_src=yes). @@ -576,23 +576,24 @@ def main(): module.params['mode'] = '0%03o' % stat.S_IMODE(os.stat(b_src).st_mode) mode = module.params['mode'] + changed = False + checksum_dest = None + checksum_src = None + md5sum_src = None if os.path.isfile(src): - checksum_src = module.sha1(src) - else: - checksum_src = None - - # Backwards compat only. This will be None in FIPS mode - try: - if os.path.isfile(src): + try: + checksum_src = module.sha1(src) + except (OSError, IOError) as e: + module.warn("Unable to calculate src checksum, assuming change: %s" % to_native(e)) + try: + # Backwards compat only. This will be None in FIPS mode md5sum_src = module.md5(src) - else: - md5sum_src = None - except ValueError: - md5sum_src = None - - changed = False + except ValueError: + pass + elif remote_src and not os.path.isdir(src): + module.fail_json("Cannot copy invalid source '%s': not a file" % to_native(src)) if checksum and checksum_src != checksum: module.fail_json( @@ -657,6 +658,7 @@ def main(): backup_file = None if checksum_src != checksum_dest or os.path.islink(b_dest): + if not module.check_mode: try: if backup: @@ -680,8 +682,10 @@ def main(): (rc, out, err) = module.run_command(validate % src) if rc != 0: module.fail_json(msg="failed to validate", exit_status=rc, stdout=out, stderr=err) + b_mysrc = b_src if remote_src and os.path.isfile(b_src): + _, b_mysrc = tempfile.mkstemp(dir=os.path.dirname(b_dest)) shutil.copyfile(b_src, b_mysrc) @@ -701,6 +705,7 @@ def main(): # assume unwanted ACLs by default src_has_acls = True + # at this point we should always have tmp file module.atomic_move(b_mysrc, dest, unsafe_writes=module.params['unsafe_writes']) if PY3 and hasattr(os, 'listxattr') and platform.system() == 'Linux' and not remote_src: diff --git a/lib/ansible/modules/dnf.py b/lib/ansible/modules/dnf.py index ce8c5ea1..a3b09908 100644 --- a/lib/ansible/modules/dnf.py +++ b/lib/ansible/modules/dnf.py @@ -95,7 +95,7 @@ options: autoremove: description: - - If C(yes), removes all "leaf" packages from the system that were originally + - If C(true), removes all "leaf" packages from the system that were originally installed as dependencies of user-installed packages but which are no longer required by any such package. Should be used alone or when state is I(absent) type: bool @@ -132,14 +132,14 @@ options: version_added: "2.7" security: description: - - If set to C(yes), and C(state=latest) then only installs updates that have been marked security related. + - If set to C(true), and C(state=latest) then only installs updates that have been marked security related. - Note that, similar to C(dnf upgrade-minimal), this filter applies to dependencies as well. type: bool default: "no" version_added: "2.7" bugfix: description: - - If set to C(yes), and C(state=latest) then only installs updates that have been marked bugfix related. + - If set to C(true), and C(state=latest) then only installs updates that have been marked bugfix related. - Note that, similar to C(dnf upgrade-minimal), this filter applies to dependencies as well. default: "no" type: bool @@ -168,15 +168,15 @@ options: type: str validate_certs: description: - - This only applies if using a https url as the source of the rpm. e.g. for localinstall. If set to C(no), the SSL certificates will not be validated. - - This should only set to C(no) used on personally controlled sites using self-signed certificates as it avoids verifying the source site. + - This only applies if using a https url as the source of the rpm. e.g. for localinstall. If set to C(false), the SSL certificates will not be validated. + - This should only set to C(false) used on personally controlled sites using self-signed certificates as it avoids verifying the source site. type: bool default: "yes" version_added: "2.7" sslverify: description: - Disables SSL validation of the repository server for this transaction. - - This should be set to C(no) if one of the configured repositories is using an untrusted or self-signed certificate. + - This should be set to C(false) if one of the configured repositories is using an untrusted or self-signed certificate. type: bool default: "yes" version_added: "2.13" @@ -227,7 +227,7 @@ options: version_added: "2.8" allowerasing: description: - - If C(yes) it allows erasing of installed packages to resolve dependencies. + - If C(true) it allows erasing of installed packages to resolve dependencies. required: false type: bool default: "no" diff --git a/lib/ansible/modules/fetch.py b/lib/ansible/modules/fetch.py index 5ea1038a..646f78d9 100644 --- a/lib/ansible/modules/fetch.py +++ b/lib/ansible/modules/fetch.py @@ -36,9 +36,9 @@ options: fail_on_missing: version_added: '1.1' description: - - When set to C(yes), the task will fail if the remote file cannot be read for any reason. + - When set to C(true), the task will fail if the remote file cannot be read for any reason. - Prior to Ansible 2.5, setting this would only fail if the source file was missing. - - The default was changed to C(yes) in Ansible 2.5. + - The default was changed to C(true) in Ansible 2.5. type: bool default: yes validate_checksum: @@ -88,7 +88,7 @@ notes: file was impossible unless C(fail_on_missing) was set. - In Ansible 2.5 or later, playbook authors are encouraged to use C(fail_when) or C(ignore_errors) to get this ability. They may - also explicitly set C(fail_on_missing) to C(no) to get the + also explicitly set C(fail_on_missing) to C(false) to get the non-failing behaviour. seealso: - module: ansible.builtin.copy diff --git a/lib/ansible/modules/file.py b/lib/ansible/modules/file.py index 150ff641..b691d3d9 100644 --- a/lib/ansible/modules/file.py +++ b/lib/ansible/modules/file.py @@ -73,7 +73,7 @@ options: description: - This flag indicates that filesystem links, if they exist, should be followed. - I(follow=yes) and I(state=link) can modify I(src) when combined with parameters such as I(mode). - - Previous to Ansible 2.5, this was C(no) by default. + - Previous to Ansible 2.5, this was C(false) by default. type: bool default: yes version_added: '1.8' diff --git a/lib/ansible/modules/find.py b/lib/ansible/modules/find.py index 218f3893..b13c841c 100644 --- a/lib/ansible/modules/find.py +++ b/lib/ansible/modules/find.py @@ -102,29 +102,29 @@ options: default: mtime hidden: description: - - Set this to C(yes) to include hidden files, otherwise they will be ignored. + - Set this to C(true) to include hidden files, otherwise they will be ignored. type: bool default: no follow: description: - - Set this to C(yes) to follow symlinks in path for systems with python 2.6+. + - Set this to C(true) to follow symlinks in path for systems with python 2.6+. type: bool default: no get_checksum: description: - - Set this to C(yes) to retrieve a file's SHA1 checksum. + - Set this to C(true) to retrieve a file's SHA1 checksum. type: bool default: no use_regex: description: - - If C(no), the patterns are file globs (shell). - - If C(yes), they are python regexes. + - If C(false), the patterns are file globs (shell). + - If C(true), they are python regexes. type: bool default: no depth: description: - Set the maximum number of levels to descend into. - - Setting recurse to C(no) will override this value, which is effectively depth 1. + - Setting recurse to C(false) will override this value, which is effectively depth 1. - Default is unlimited depth. type: int version_added: "2.6" diff --git a/lib/ansible/modules/get_url.py b/lib/ansible/modules/get_url.py index 5de71912..4cf27159 100644 --- a/lib/ansible/modules/get_url.py +++ b/lib/ansible/modules/get_url.py @@ -68,11 +68,11 @@ options: version_added: '2.1' force: description: - - If C(yes) and C(dest) is not a directory, will download the file every - time and replace the file if the contents change. If C(no), the file + - If C(true) and C(dest) is not a directory, will download the file every + time and replace the file if the contents change. If C(false), the file will only be downloaded if the destination does not exist. Generally - should be C(yes) only for small local files. - - Prior to 0.6, this module behaved as if C(yes) was the default. + should be C(true) only for small local files. + - Prior to 0.6, this module behaved as if C(true) was the default. type: bool default: no version_added: '0.7' @@ -103,13 +103,13 @@ options: version_added: "2.0" use_proxy: description: - - if C(no), it will not use a proxy, even if one is defined in + - if C(false), it will not use a proxy, even if one is defined in an environment variable on the target hosts. type: bool default: yes validate_certs: description: - - If C(no), SSL certificates will not be validated. + - If C(false), SSL certificates will not be validated. - This should only be used on personally controlled sites using self-signed certificates. type: bool default: yes diff --git a/lib/ansible/modules/getent.py b/lib/ansible/modules/getent.py index fdfcf43b..1f763800 100644 --- a/lib/ansible/modules/getent.py +++ b/lib/ansible/modules/getent.py @@ -41,7 +41,7 @@ options: type: str fail_key: description: - - If a supplied key is missing this will make the task fail if C(yes). + - If a supplied key is missing this will make the task fail if C(true). type: bool default: 'yes' extends_documentation_fragment: diff --git a/lib/ansible/modules/git.py b/lib/ansible/modules/git.py index cca1e7a2..37477b3c 100644 --- a/lib/ansible/modules/git.py +++ b/lib/ansible/modules/git.py @@ -30,7 +30,7 @@ options: - The path of where the repository should be checked out. This is equivalent to C(git clone [repo_url] [directory]). The repository named in I(repo) is not appended to this path and the destination directory must be empty. This - parameter is required, unless I(clone) is set to C(no). + parameter is required, unless I(clone) is set to C(false). type: path required: true version: @@ -54,7 +54,7 @@ options: description: - As of OpenSSH 7.5, "-o StrictHostKeyChecking=accept-new" can be used which is safer and will only accepts host keys which are - not present or are the same. if C(yes), ensure that + not present or are the same. if C(true), ensure that "-o StrictHostKeyChecking=accept-new" is present as an ssh option. type: bool default: 'no' @@ -99,10 +99,10 @@ options: version_added: "1.9" force: description: - - If C(yes), any modified files in the working + - If C(true), any modified files in the working repository will be discarded. Prior to 0.7, this was always - C(yes) and could not be disabled. Prior to 1.9, the default was - C(yes). + C(true) and could not be disabled. Prior to 1.9, the default was + C(true). type: bool default: 'no' version_added: "0.7" @@ -115,13 +115,13 @@ options: version_added: "1.2" clone: description: - - If C(no), do not clone the repository even if it does not exist locally. + - If C(false), do not clone the repository even if it does not exist locally. type: bool default: 'yes' version_added: "1.9" update: description: - - If C(no), do not retrieve new revisions from the origin repository. + - If C(false), do not retrieve new revisions from the origin repository. - Operations like archive will work on the existing (old) repository and might not respond to changes to the options version or remote. type: bool @@ -135,7 +135,7 @@ options: version_added: "1.4" bare: description: - - If C(yes), repository will be created as a bare repo, otherwise + - If C(true), repository will be created as a bare repo, otherwise it will be a standard repo with a workspace. type: bool default: 'no' @@ -149,7 +149,7 @@ options: recursive: description: - - If C(no), repository will be cloned without the --recursive + - If C(false), repository will be cloned without the --recursive option, skipping sub-modules. type: bool default: 'yes' @@ -164,9 +164,9 @@ options: track_submodules: description: - - If C(yes), submodules will track the latest commit on their + - If C(true), submodules will track the latest commit on their master branch (or other branch specified in .gitmodules). If - C(no), submodules will be kept at the revision specified by the + C(false), submodules will be kept at the revision specified by the main project. This is equivalent to specifying the --remote flag to git submodule update. type: bool @@ -175,7 +175,7 @@ options: verify_commit: description: - - If C(yes), when cloning or checking out a I(version) verify the + - If C(true), when cloning or checking out a I(version) verify the signature of a GPG signed commit. This requires git version>=2.1.0 to be installed. The commit MUST be signed and the public key MUST be present in the GPG keyring. diff --git a/lib/ansible/modules/include_role.py b/lib/ansible/modules/include_role.py index 0124df6a..ea7c61e3 100644 --- a/lib/ansible/modules/include_role.py +++ b/lib/ansible/modules/include_role.py @@ -53,7 +53,7 @@ options: default: yes public: description: - - This option dictates whether the role's C(vars) and C(defaults) are exposed to the play. If set to C(yes) + - This option dictates whether the role's C(vars) and C(defaults) are exposed to the play. If set to C(true) the variables will be available to tasks following the C(include_role) task. This functionality differs from standard variable exposure for roles listed under the C(roles) header or C(import_role) as they are exposed to the play at playbook parsing time, and available to earlier roles and tasks as well. diff --git a/lib/ansible/modules/rpm_key.py b/lib/ansible/modules/rpm_key.py index cf40b118..f420eec5 100644 --- a/lib/ansible/modules/rpm_key.py +++ b/lib/ansible/modules/rpm_key.py @@ -33,7 +33,7 @@ options: choices: [ absent, present ] validate_certs: description: - - If C(no) and the C(key) is a url starting with https, SSL certificates will not be validated. + - If C(false) and the C(key) is a url starting with https, SSL certificates will not be validated. - This should only be used on personally controlled sites using self-signed certificates. type: bool default: 'yes' diff --git a/lib/ansible/modules/set_fact.py b/lib/ansible/modules/set_fact.py index 5609e5bc..5cb1f7d7 100644 --- a/lib/ansible/modules/set_fact.py +++ b/lib/ansible/modules/set_fact.py @@ -15,7 +15,7 @@ version_added: "1.2" description: - This action allows setting variables associated to the current host. - These variables will be available to subsequent plays during an ansible-playbook run via the host they were set on. - - Set C(cacheable) to C(yes) to save variables across executions using a fact cache. + - Set C(cacheable) to C(true) to save variables across executions using a fact cache. Variables will keep the set_fact precedence for the current run, but will used 'cached fact' precedence for subsequent ones. - Per the standard Ansible variable precedence rules, other types of variables have a higher priority, so this value may be overridden. options: diff --git a/lib/ansible/modules/set_stats.py b/lib/ansible/modules/set_stats.py index 2fd21da1..16d7bfef 100644 --- a/lib/ansible/modules/set_stats.py +++ b/lib/ansible/modules/set_stats.py @@ -28,7 +28,7 @@ options: default: no aggregate: description: - - Whether the provided value is aggregated to the existing stat C(yes) or will replace it C(no). + - Whether the provided value is aggregated to the existing stat C(true) or will replace it C(false). type: bool default: yes extends_documentation_fragment: @@ -55,7 +55,7 @@ attributes: support: none notes: - In order for custom stats to be displayed, you must set C(show_custom_stats) in section C([defaults]) in C(ansible.cfg) - or by defining environment variable C(ANSIBLE_SHOW_CUSTOM_STATS) to C(yes). See the C(default) callback plugin for details. + or by defining environment variable C(ANSIBLE_SHOW_CUSTOM_STATS) to C(true). See the C(default) callback plugin for details. version_added: "2.3" ''' diff --git a/lib/ansible/modules/stat.py b/lib/ansible/modules/stat.py index 918b588f..45ca78b2 100644 --- a/lib/ansible/modules/stat.py +++ b/lib/ansible/modules/stat.py @@ -48,7 +48,7 @@ options: - Use file magic and return data about the nature of the file. this uses the 'file' utility found on most Linux/Unix systems. - This will add both C(mime_type) and C(charset) fields to the return, if possible. - - In Ansible 2.3 this option changed from I(mime) to I(get_mime) and the default changed to C(yes). + - In Ansible 2.3 this option changed from I(mime) to I(get_mime) and the default changed to C(true). type: bool default: yes aliases: [ mime, mime_type, mime-type ] diff --git a/lib/ansible/modules/subversion.py b/lib/ansible/modules/subversion.py index a63de3c5..68aacfd2 100644 --- a/lib/ansible/modules/subversion.py +++ b/lib/ansible/modules/subversion.py @@ -36,8 +36,8 @@ options: aliases: [ rev, version ] force: description: - - If C(yes), modified files will be discarded. If C(no), module will fail if it encounters modified files. - Prior to 1.9 the default was C(yes). + - If C(true), modified files will be discarded. If C(false), module will fail if it encounters modified files. + Prior to 1.9 the default was C(true). type: bool default: "no" in_place: @@ -65,32 +65,32 @@ options: version_added: "1.4" checkout: description: - - If C(no), do not check out the repository if it does not exist locally. + - If C(false), do not check out the repository if it does not exist locally. type: bool default: "yes" version_added: "2.3" update: description: - - If C(no), do not retrieve new revisions from the origin repository. + - If C(false), do not retrieve new revisions from the origin repository. type: bool default: "yes" version_added: "2.3" export: description: - - If C(yes), do export instead of checkout/update. + - If C(true), do export instead of checkout/update. type: bool default: "no" version_added: "1.6" switch: description: - - If C(no), do not call svn switch before update. + - If C(false), do not call svn switch before update. default: "yes" version_added: "2.0" type: bool validate_certs: description: - - If C(no), passes the C(--trust-server-cert) flag to svn. - - If C(yes), does not pass the flag. + - If C(false), passes the C(--trust-server-cert) flag to svn. + - If C(true), does not pass the flag. default: "no" version_added: "2.11" type: bool diff --git a/lib/ansible/modules/template.py b/lib/ansible/modules/template.py index faff7aa9..7ee581ad 100644 --- a/lib/ansible/modules/template.py +++ b/lib/ansible/modules/template.py @@ -18,9 +18,9 @@ options: follow: description: - Determine whether symbolic links should be followed. - - When set to C(yes) symbolic links will be followed, if they exist. - - When set to C(no) symbolic links will not be followed. - - Previous to Ansible 2.4, this was hardcoded as C(yes). + - When set to C(true) symbolic links will be followed, if they exist. + - When set to C(false) symbolic links will not be followed. + - Previous to Ansible 2.4, this was hardcoded as C(true). type: bool default: no version_added: '2.4' diff --git a/lib/ansible/modules/unarchive.py b/lib/ansible/modules/unarchive.py index 69e769d0..26890b50 100644 --- a/lib/ansible/modules/unarchive.py +++ b/lib/ansible/modules/unarchive.py @@ -96,7 +96,7 @@ options: version_added: "2.1" remote_src: description: - - Set to C(yes) to indicate the archived file is already on the remote system and not local to the Ansible controller. + - Set to C(true) to indicate the archived file is already on the remote system and not local to the Ansible controller. - This option is mutually exclusive with C(copy). type: bool default: no @@ -104,8 +104,8 @@ options: validate_certs: description: - This only applies if using a https URL as the source of the file. - - This should only set to C(no) used on personally controlled sites using self-signed certificate. - - Prior to 2.2 the code worked as if this was set to C(yes). + - This should only set to C(false) used on personally controlled sites using self-signed certificate. + - Prior to 2.2 the code worked as if this was set to C(true). type: bool default: yes version_added: "2.2" diff --git a/lib/ansible/modules/uri.py b/lib/ansible/modules/uri.py index e67f90a4..958aefc9 100644 --- a/lib/ansible/modules/uri.py +++ b/lib/ansible/modules/uri.py @@ -104,8 +104,8 @@ options: - Whether or not the URI module should follow redirects. C(all) will follow all redirects. C(safe) will follow only "safe" redirects, where "safe" means that the client is only doing a GET or HEAD on the URI to which it is being redirected. C(none) will not follow - any redirects. Note that C(yes) and C(no) choices are accepted for backwards compatibility, - where C(yes) is the equivalent of C(all) and C(no) is the equivalent of C(safe). C(yes) and C(no) + any redirects. Note that C(true) and C(false) choices are accepted for backwards compatibility, + where C(true) is the equivalent of C(all) and C(false) is the equivalent of C(safe). C(true) and C(false) are deprecated and will be removed in some future version of Ansible. type: str choices: ['all', 'no', 'none', 'safe', 'urllib2', 'yes'] @@ -138,9 +138,9 @@ options: version_added: '2.1' validate_certs: description: - - If C(no), SSL certificates will not be validated. - - This should only set to C(no) used on personally controlled sites using self-signed certificates. - - Prior to 1.9.2 the code defaulted to C(no). + - If C(false), SSL certificates will not be validated. + - This should only set to C(false) used on personally controlled sites using self-signed certificates. + - Prior to 1.9.2 the code defaulted to C(false). type: bool default: yes version_added: '1.9.2' @@ -170,19 +170,19 @@ options: version_added: '2.7' remote_src: description: - - If C(no), the module will search for the C(src) on the controller node. - - If C(yes), the module will search for the C(src) on the managed (remote) node. + - If C(false), the module will search for the C(src) on the controller node. + - If C(true), the module will search for the C(src) on the managed (remote) node. type: bool default: no version_added: '2.7' force: description: - - If C(yes) do not get a cached copy. + - If C(true) do not get a cached copy. type: bool default: no use_proxy: description: - - If C(no), it will not use a proxy, even if one is defined in an environment variable on the target hosts. + - If C(false), it will not use a proxy, even if one is defined in an environment variable on the target hosts. type: bool default: yes unix_socket: diff --git a/lib/ansible/modules/user.py b/lib/ansible/modules/user.py index 9ad76a90..cb35e950 100644 --- a/lib/ansible/modules/user.py +++ b/lib/ansible/modules/user.py @@ -32,7 +32,7 @@ options: hidden: description: - macOS only, optionally hide the user from the login window and system preferences. - - The default will be C(yes) if the I(system) option is used. + - The default will be C(true) if the I(system) option is used. type: bool version_added: "2.6" non_unique: @@ -61,8 +61,8 @@ options: elements: str append: description: - - If C(yes), add the user to the groups specified in C(groups). - - If C(no), user will only be added to the groups specified in C(groups), + - If C(true), add the user to the groups specified in C(groups). + - If C(false), user will only be added to the groups specified in C(groups), removing them from all other groups. type: bool default: no @@ -101,7 +101,7 @@ options: default: present create_home: description: - - Unless set to C(no), a home directory will be made for the user + - Unless set to C(false), a home directory will be made for the user when the account is created or if the home directory does not exist. - Changed from C(createhome) to C(create_home) in Ansible 2.5. type: bool @@ -109,13 +109,13 @@ options: aliases: [ createhome ] move_home: description: - - "If set to C(yes) when used with C(home: ), attempt to move the user's old home + - "If set to C(true) when used with C(home: ), attempt to move the user's old home directory to the specified directory if it isn't there already and the old home exists." type: bool default: no system: description: - - When creating an account C(state=present), setting this to C(yes) makes the user a system account. + - When creating an account C(state=present), setting this to C(true) makes the user a system account. - This setting cannot be changed on existing users. type: bool default: no diff --git a/lib/ansible/modules/yum.py b/lib/ansible/modules/yum.py index cce8f4cb..040ee272 100644 --- a/lib/ansible/modules/yum.py +++ b/lib/ansible/modules/yum.py @@ -112,16 +112,16 @@ options: version_added: "1.9" validate_certs: description: - - This only applies if using a https url as the source of the rpm. e.g. for localinstall. If set to C(no), the SSL certificates will not be validated. - - This should only set to C(no) used on personally controlled sites using self-signed certificates as it avoids verifying the source site. - - Prior to 2.1 the code worked as if this was set to C(yes). + - This only applies if using a https url as the source of the rpm. e.g. for localinstall. If set to C(false), the SSL certificates will not be validated. + - This should only set to C(false) used on personally controlled sites using self-signed certificates as it avoids verifying the source site. + - Prior to 2.1 the code worked as if this was set to C(true). type: bool default: "yes" version_added: "2.1" sslverify: description: - Disables SSL validation of the repository server for this transaction. - - This should be set to C(no) if one of the configured repositories is using an untrusted or self-signed certificate. + - This should be set to C(false) if one of the configured repositories is using an untrusted or self-signed certificate. type: bool default: "yes" version_added: "2.13" @@ -142,13 +142,13 @@ options: version_added: "2.3" security: description: - - If set to C(yes), and C(state=latest) then only installs updates that have been marked security related. + - If set to C(true), and C(state=latest) then only installs updates that have been marked security related. type: bool default: "no" version_added: "2.4" bugfix: description: - - If set to C(yes), and C(state=latest) then only installs updates that have been marked bugfix related. + - If set to C(true), and C(state=latest) then only installs updates that have been marked bugfix related. default: "no" type: bool version_added: "2.6" @@ -187,7 +187,7 @@ options: version_added: "2.7" autoremove: description: - - If C(yes), removes all "leaf" packages from the system that were originally + - If C(true), removes all "leaf" packages from the system that were originally installed as dependencies of user-installed packages but which are no longer required by any such package. Should be used alone or when state is I(absent) - "NOTE: This feature requires yum >= 3.4.3 (RHEL/CentOS 7+)" diff --git a/lib/ansible/modules/yum_repository.py b/lib/ansible/modules/yum_repository.py index 52e176d9..84a10b92 100644 --- a/lib/ansible/modules/yum_repository.py +++ b/lib/ansible/modules/yum_repository.py @@ -21,7 +21,7 @@ description: options: async: description: - - If set to C(yes) Yum will download packages and metadata from this + - If set to C(true) Yum will download packages and metadata from this repo in parallel, if possible. - In ansible-core 2.11, 2.12, and 2.13 the default value is C(true). - This option has been deprecated in RHEL 8. If you're using one of the @@ -117,7 +117,7 @@ options: - Tells yum whether or not it should perform a GPG signature check on packages. - No default setting. If the value is not set, the system setting from - C(/etc/yum.conf) or system default of C(no) will be used. + C(/etc/yum.conf) or system default of C(false) will be used. type: bool gpgkey: description: @@ -289,7 +289,7 @@ options: default: 'no' skip_if_unavailable: description: - - If set to C(yes) yum will continue running if this repository cannot be + - If set to C(true) yum will continue running if this repository cannot be contacted for any reason. This should be set carefully as all repos are consulted for any given command. type: bool @@ -299,7 +299,7 @@ options: - Whether yum should check the permissions on the paths for the certificates on the repository (both remote and local). - If we can't read any of the files then yum will force - I(skip_if_unavailable) to be C(yes). This is most useful for non-root + I(skip_if_unavailable) to be C(true). This is most useful for non-root processes which use yum on repos that have client cert files which are readable only by root. type: bool diff --git a/lib/ansible/playbook/task.py b/lib/ansible/playbook/task.py index 50ac5df7..6a9136d2 100644 --- a/lib/ansible/playbook/task.py +++ b/lib/ansible/playbook/task.py @@ -244,7 +244,7 @@ class Task(Base, Conditional, Taggable, CollectionSearch): elif k.startswith('with_') and k.removeprefix("with_") in lookup_loader: # transform into loop property self._preprocess_with_loop(ds, new_ds, k, v) - elif C.INVALID_TASK_ATTRIBUTE_FAILED or k in self._valid_attrs: + elif C.INVALID_TASK_ATTRIBUTE_FAILED or k in self.fattributes: new_ds[k] = v else: display.warning("Ignoring invalid attribute: %s" % k) diff --git a/lib/ansible/plugins/action/__init__.py b/lib/ansible/plugins/action/__init__.py index 7db61378..d199207c 100644 --- a/lib/ansible/plugins/action/__init__.py +++ b/lib/ansible/plugins/action/__init__.py @@ -674,7 +674,7 @@ class ActionBase(ABC): res = self._remote_chmod(remote_paths, 'u+x') if res['rc'] != 0: raise AnsibleError( - 'Failed to set file mode on remote temporary files ' + 'Failed to set file mode or acl on remote temporary files ' '(rc: {0}, err: {1})'.format( res['rc'], to_native(res['stderr']))) @@ -689,9 +689,9 @@ class ActionBase(ABC): if remote_user in self._get_admin_users(): raise AnsibleError( 'Failed to change ownership of the temporary files Ansible ' - 'needs to create despite connecting as a privileged user. ' - 'Unprivileged become user would be unable to read the ' - 'file.') + '(via chmod nor setfacl) needs to create despite connecting as a ' + 'privileged user. Unprivileged become user would be unable to read' + ' the file.') # Step 3d: Try macOS's special chmod + ACL # macOS chmod's +a flag takes its own argument. As a slight hack, we diff --git a/lib/ansible/plugins/doc_fragments/action_common_attributes.py b/lib/ansible/plugins/doc_fragments/action_common_attributes.py index e9579974..c135df5e 100644 --- a/lib/ansible/plugins/doc_fragments/action_common_attributes.py +++ b/lib/ansible/plugins/doc_fragments/action_common_attributes.py @@ -46,7 +46,7 @@ attributes: FILES = r''' attributes: safe_file_operations: - description: Uses Ansbile's strict file operation functions to ensure proper permissions and avoid data corruption + description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption vault: description: Can automatically decrypt Ansible vaulted files ''' diff --git a/lib/ansible/plugins/doc_fragments/action_core.py b/lib/ansible/plugins/doc_fragments/action_core.py index 9968fef6..931ca14e 100644 --- a/lib/ansible/plugins/doc_fragments/action_core.py +++ b/lib/ansible/plugins/doc_fragments/action_core.py @@ -5,7 +5,7 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -# WARNING: this is mostly here as a convinence for documenting core behaviours, no plugin outside of ansbile-core should use this file +# WARNING: this is mostly here as a convinence for documenting core behaviours, no plugin outside of ansible-core should use this file class ModuleDocFragment(object): # requires action_common diff --git a/lib/ansible/plugins/filter/b64decode.yml b/lib/ansible/plugins/filter/b64decode.yml index 6edf4abf..30565fa9 100644 --- a/lib/ansible/plugins/filter/b64decode.yml +++ b/lib/ansible/plugins/filter/b64decode.yml @@ -5,6 +5,10 @@ DOCUMENTATION: short_description: Decode a base64 string description: - Base64 decoding function. + - The return value is a string. + - Trying to store a binary blob in a string most likely corrupts the binary. To base64 decode a binary blob, + use the ``base64`` command and pipe the encoded data through standard input. + For example, in the ansible.builtin.shell`` module, ``cmd="base64 --decode > myfile.bin" stdin="{{ encoded }}"``. positional: _input options: _input: diff --git a/lib/ansible/plugins/lookup/fileglob.py b/lib/ansible/plugins/lookup/fileglob.py index b1ee05a2..abf8202e 100644 --- a/lib/ansible/plugins/lookup/fileglob.py +++ b/lib/ansible/plugins/lookup/fileglob.py @@ -18,6 +18,7 @@ DOCUMENTATION = """ required: True notes: - Patterns are only supported on files, not directory/paths. + - See R(Ansible task paths,playbook_task_paths) to understand how file lookup occurs with paths. - Matching is against local system files on the Ansible controller. To iterate a list of files on a remote node, use the M(ansible.builtin.find) module. - Returns a string list of paths joined by commas, or an empty list if no files match. For a 'true list' pass C(wantlist=True) to the lookup. diff --git a/lib/ansible/release.py b/lib/ansible/release.py index 1562b704..a38538f5 100644 --- a/lib/ansible/release.py +++ b/lib/ansible/release.py @@ -19,6 +19,6 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -__version__ = '2.14.0' +__version__ = '2.14.1' __author__ = 'Ansible, Inc.' __codename__ = "C'mon Everybody" diff --git a/lib/ansible/template/native_helpers.py b/lib/ansible/template/native_helpers.py index b6fc37b5..343e10c7 100644 --- a/lib/ansible/template/native_helpers.py +++ b/lib/ansible/template/native_helpers.py @@ -128,7 +128,7 @@ def ansible_native_concat(nodes): out = ''.join([to_text(v) for v in nodes]) try: - return ast.literal_eval( + evaled = ast.literal_eval( # In Python 3.10+ ast.literal_eval removes leading spaces/tabs # from the given string. For backwards compatibility we need to # parse the string ourselves without removing leading spaces/tabs. @@ -136,3 +136,9 @@ def ansible_native_concat(nodes): ) except (ValueError, SyntaxError, MemoryError): return out + + if isinstance(evaled, string_types): + quote = out[0] + return f'{quote}{evaled}{quote}' + + return evaled diff --git a/lib/ansible/utils/display.py b/lib/ansible/utils/display.py index c3a5de98..e521f2a4 100644 --- a/lib/ansible/utils/display.py +++ b/lib/ansible/utils/display.py @@ -41,6 +41,7 @@ from ansible.utils.color import stringc from ansible.utils.multiprocessing import context as multiprocessing_context from ansible.utils.singleton import Singleton from ansible.utils.unsafe_proxy import wrap_var +from functools import wraps _LIBC = ctypes.cdll.LoadLibrary(ctypes.util.find_library('c')) @@ -163,12 +164,33 @@ b_COW_PATHS = ( ) +def _synchronize_textiowrapper(tio, lock): + # Ensure that a background thread can't hold the internal buffer lock on a file object + # during a fork, which causes forked children to hang. We're using display's existing lock for + # convenience (and entering the lock before a fork). + def _wrap_with_lock(f, lock): + @wraps(f) + def locking_wrapper(*args, **kwargs): + with lock: + return f(*args, **kwargs) + + return locking_wrapper + + buffer = tio.buffer + + # monkeypatching the underlying file-like object isn't great, but likely safer than subclassing + buffer.write = _wrap_with_lock(buffer.write, lock) + buffer.flush = _wrap_with_lock(buffer.flush, lock) + + class Display(metaclass=Singleton): def __init__(self, verbosity=0): self._final_q = None + # NB: this lock is used to both prevent intermingled output between threads and to block writes during forks. + # Do not change the type of this lock or upgrade to a shared lock (eg multiprocessing.RLock). self._lock = threading.RLock() self.columns = None @@ -199,6 +221,13 @@ class Display(metaclass=Singleton): self._set_column_width() + try: + # NB: we're relying on the display singleton behavior to ensure this only runs once + _synchronize_textiowrapper(sys.stdout, self._lock) + _synchronize_textiowrapper(sys.stderr, self._lock) + except Exception as ex: + self.warning(f"failed to patch stdout/stderr for fork-safety: {ex}") + def set_queue(self, queue): """Set the _final_q on Display, so that we know to proxy display over the queue instead of directly writing to stdout/stderr from forks diff --git a/lib/ansible_core.egg-info/PKG-INFO b/lib/ansible_core.egg-info/PKG-INFO index 7ecd0088..373b0ae4 100644 --- a/lib/ansible_core.egg-info/PKG-INFO +++ b/lib/ansible_core.egg-info/PKG-INFO @@ -1,6 +1,6 @@ Metadata-Version: 2.1 Name: ansible-core -Version: 2.14.0 +Version: 2.14.1 Summary: Radically simple IT automation Home-page: https://ansible.com/ Author: Ansible, Inc. diff --git a/lib/ansible_core.egg-info/SOURCES.txt b/lib/ansible_core.egg-info/SOURCES.txt index 0a4290ed..e97472c7 100644 --- a/lib/ansible_core.egg-info/SOURCES.txt +++ b/lib/ansible_core.egg-info/SOURCES.txt @@ -39,6 +39,7 @@ docs/docsite/ansible_5.inv docs/docsite/ansible_6.inv docs/docsite/collection-plugins.yml docs/docsite/jinja2.inv +docs/docsite/known_good_reqs.txt docs/docsite/modules.js docs/docsite/python2.inv docs/docsite/python3.inv @@ -2283,6 +2284,7 @@ test/integration/targets/copy/tasks/no_log.yml test/integration/targets/copy/tasks/selinux.yml test/integration/targets/copy/tasks/src_file_dest_file_in_non_existent_dir.yml test/integration/targets/copy/tasks/src_file_dest_file_in_non_existent_dir_remote_src.yml +test/integration/targets/copy/tasks/src_remote_file_is_not_file.yml test/integration/targets/copy/tasks/tests.yml test/integration/targets/cron/aliases test/integration/targets/cron/defaults/main.yml @@ -2468,6 +2470,13 @@ test/integration/targets/find/files/a.txt test/integration/targets/find/files/log.txt test/integration/targets/find/meta/main.yml test/integration/targets/find/tasks/main.yml +test/integration/targets/fork_safe_stdio/aliases +test/integration/targets/fork_safe_stdio/hosts +test/integration/targets/fork_safe_stdio/run-with-pty.py +test/integration/targets/fork_safe_stdio/runme.sh +test/integration/targets/fork_safe_stdio/test.yml +test/integration/targets/fork_safe_stdio/vendored_pty.py +test/integration/targets/fork_safe_stdio/callback_plugins/spewstdio.py test/integration/targets/gathering/aliases test/integration/targets/gathering/explicit.yml test/integration/targets/gathering/implicit.yml @@ -3027,6 +3036,7 @@ test/integration/targets/jinja2_native_types/test_concatentation.yml test/integration/targets/jinja2_native_types/test_dunder.yml test/integration/targets/jinja2_native_types/test_hostvars.yml test/integration/targets/jinja2_native_types/test_none.yml +test/integration/targets/jinja2_native_types/test_preserving_quotes.yml test/integration/targets/jinja2_native_types/test_template.yml test/integration/targets/jinja2_native_types/test_template_newlines.j2 test/integration/targets/jinja2_native_types/test_types.yml diff --git a/test/integration/targets/ansible-galaxy-role/tasks/main.yml b/test/integration/targets/ansible-galaxy-role/tasks/main.yml index e49e4e29..03d0b3c2 100644 --- a/test/integration/targets/ansible-galaxy-role/tasks/main.yml +++ b/test/integration/targets/ansible-galaxy-role/tasks/main.yml @@ -1,3 +1,6 @@ +- name: Install role from Galaxy (should not fail with AttributeError) + command: ansible-galaxy role install ansible.nope -vvvv --ignore-errors + - name: Archive directories file: state: directory diff --git a/test/integration/targets/ansible-galaxy/runme.sh b/test/integration/targets/ansible-galaxy/runme.sh index 4005531a..7d966e29 100755 --- a/test/integration/targets/ansible-galaxy/runme.sh +++ b/test/integration/targets/ansible-galaxy/runme.sh @@ -103,7 +103,11 @@ f_ansible_galaxy_status "install of local git repo" mkdir -p "${galaxy_testdir}" pushd "${galaxy_testdir}" - ansible-galaxy install git+file:///"${galaxy_local_test_role_git_repo}" "$@" + # minimum verbosity is hardcoded to include calls to Galaxy + ansible-galaxy install git+file:///"${galaxy_local_test_role_git_repo}" "$@" -vvvv 2>&1 | tee out.txt + + # Test no initial call is made to Galaxy + grep out.txt -e "https://galaxy.ansible.com" && cat out.txt && exit 1 # Test that the role was installed to the expected directory [[ -d "${HOME}/.ansible/roles/${galaxy_local_test_role}" ]] diff --git a/test/integration/targets/copy/tasks/main.yml b/test/integration/targets/copy/tasks/main.yml index 817fe0a1..b86c56ac 100644 --- a/test/integration/targets/copy/tasks/main.yml +++ b/test/integration/targets/copy/tasks/main.yml @@ -96,6 +96,9 @@ - 'diff_output.diff[0].before == ""' - '"Ansible managed" in diff_output.diff[0].after' + - name: tests with remote_src and non files + import_tasks: src_remote_file_is_not_file.yml + always: - name: Cleaning file: diff --git a/test/integration/targets/copy/tasks/src_remote_file_is_not_file.yml b/test/integration/targets/copy/tasks/src_remote_file_is_not_file.yml new file mode 100644 index 00000000..2cda7d37 --- /dev/null +++ b/test/integration/targets/copy/tasks/src_remote_file_is_not_file.yml @@ -0,0 +1,39 @@ +- name: test remote src non files + vars: + destfile: '{{remote_dir}}/whocares' + block: + - name: mess with dev/null + copy: + src: /dev/null + dest: "{{destfile}}" + remote_src: true + become: true + register: dev_null_fail + ignore_errors: true + + - name: ensure we failed + assert: + that: + - dev_null_fail is failed + - "'not a file' in dev_null_fail.msg" + + - name: now with file existing + file: state=touch path="{{destfile}}" + + - name: mess with dev/null again + copy: + src: /dev/null + dest: "{{destfile}}" + remote_src: true + become: true + register: dev_null_fail + ignore_errors: true + + - name: ensure we failed, again + assert: + that: + - dev_null_fail is failed + - "'not a file' in dev_null_fail.msg" + always: + - name: cleanup + file: state=absent path="{{destfile}}" diff --git a/test/integration/targets/fork_safe_stdio/aliases b/test/integration/targets/fork_safe_stdio/aliases new file mode 100644 index 00000000..e968db72 --- /dev/null +++ b/test/integration/targets/fork_safe_stdio/aliases @@ -0,0 +1,3 @@ +shippable/posix/group3 +context/controller +skip/macos diff --git a/test/integration/targets/fork_safe_stdio/callback_plugins/spewstdio.py b/test/integration/targets/fork_safe_stdio/callback_plugins/spewstdio.py new file mode 100644 index 00000000..6ed6ef34 --- /dev/null +++ b/test/integration/targets/fork_safe_stdio/callback_plugins/spewstdio.py @@ -0,0 +1,58 @@ +import atexit +import os +import sys + +from ansible.plugins.callback import CallbackBase +from ansible.utils.display import Display +from threading import Thread + +# This callback plugin reliably triggers the deadlock from https://github.com/ansible/ansible-runner/issues/1164 when +# run on a TTY/PTY. It starts a thread in the controller that spews unprintable characters to stdout as fast as +# possible, while causing forked children to write directly to the inherited stdout immediately post-fork. If a fork +# occurs while the spew thread holds stdout's internal BufferedIOWriter lock, the lock will be orphaned in the child, +# and attempts to write to stdout there will hang forever. + +# Any mechanism that ensures non-main threads do not hold locks before forking should allow this test to pass. + +# ref: https://docs.python.org/3/library/io.html#multi-threading +# ref: https://github.com/python/cpython/blob/0547a981ae413248b21a6bb0cb62dda7d236fe45/Modules/_io/bufferedio.c#L268 + + +class CallbackModule(CallbackBase): + CALLBACK_VERSION = 2.0 + CALLBACK_NAME = 'spewstdio' + + def __init__(self): + super().__init__() + self.display = Display() + + if os.environ.get('SPEWSTDIO_ENABLED', '0') != '1': + self.display.warning('spewstdio test plugin loaded but disabled; set SPEWSTDIO_ENABLED=1 to enable') + return + + self.display = Display() + self._keep_spewing = True + + # cause the child to write directly to stdout immediately post-fork + os.register_at_fork(after_in_child=lambda: print(f"hi from forked child pid {os.getpid()}")) + + # in passing cases, stop spewing when the controller is exiting to prevent fatal errors on final flush + atexit.register(self.stop_spew) + + self._spew_thread = Thread(target=self.spew, daemon=True) + self._spew_thread.start() + + def stop_spew(self): + self._keep_spewing = False + + def spew(self): + # dump a message so we know the callback thread has started + self.display.warning("spewstdio STARTING NONPRINTING SPEW ON BACKGROUND THREAD") + + while self._keep_spewing: + # dump a non-printing control character directly to stdout to avoid junking up the screen while still + # doing lots of writes and flushes. + sys.stdout.write('\x1b[K') + sys.stdout.flush() + + self.display.warning("spewstdio STOPPING SPEW") diff --git a/test/integration/targets/fork_safe_stdio/hosts b/test/integration/targets/fork_safe_stdio/hosts new file mode 100644 index 00000000..675e82ad --- /dev/null +++ b/test/integration/targets/fork_safe_stdio/hosts @@ -0,0 +1,5 @@ +[all] +local-[1:10] + +[all:vars] +ansible_connection=local diff --git a/test/integration/targets/fork_safe_stdio/run-with-pty.py b/test/integration/targets/fork_safe_stdio/run-with-pty.py new file mode 100755 index 00000000..46391528 --- /dev/null +++ b/test/integration/targets/fork_safe_stdio/run-with-pty.py @@ -0,0 +1,11 @@ +#!/usr/bin/env python +"""Run a command using a PTY.""" + +import sys + +if sys.version_info < (3, 10): + import vendored_pty as pty +else: + import pty + +sys.exit(1 if pty.spawn(sys.argv[1:]) else 0) diff --git a/test/integration/targets/fork_safe_stdio/runme.sh b/test/integration/targets/fork_safe_stdio/runme.sh new file mode 100755 index 00000000..4438c3fe --- /dev/null +++ b/test/integration/targets/fork_safe_stdio/runme.sh @@ -0,0 +1,20 @@ +#!/usr/bin/env bash + +set -eu + +echo "testing for stdio deadlock on forked workers (10s timeout)..." + +# Enable a callback that trips deadlocks on forked-child stdout, time out after 10s; forces running +# in a pty, since that tends to be much slower than raw file I/O and thus more likely to trigger the deadlock. +# Redirect stdout to /dev/null since it's full of non-printable garbage we don't want to display unless it failed +ANSIBLE_CALLBACKS_ENABLED=spewstdio SPEWSTDIO_ENABLED=1 python run-with-pty.py timeout 10s ansible-playbook -i hosts -f 5 test.yml > stdout.txt && RC=$? || RC=$? + +if [ $RC != 0 ]; then + echo "failed; likely stdout deadlock. dumping raw output (may be very large)" + cat stdout.txt + exit 1 +fi + +grep -q -e "spewstdio STARTING NONPRINTING SPEW ON BACKGROUND THREAD" stdout.txt || (echo "spewstdio callback was not enabled"; exit 1) + +echo "PASS" diff --git a/test/integration/targets/fork_safe_stdio/test.yml b/test/integration/targets/fork_safe_stdio/test.yml new file mode 100644 index 00000000..d60f0715 --- /dev/null +++ b/test/integration/targets/fork_safe_stdio/test.yml @@ -0,0 +1,5 @@ +- hosts: all + gather_facts: no + tasks: + - debug: + msg: yo diff --git a/test/integration/targets/fork_safe_stdio/vendored_pty.py b/test/integration/targets/fork_safe_stdio/vendored_pty.py new file mode 100644 index 00000000..bc70803b --- /dev/null +++ b/test/integration/targets/fork_safe_stdio/vendored_pty.py @@ -0,0 +1,189 @@ +# Vendored copy of https://github.com/python/cpython/blob/3680ebed7f3e529d01996dd0318601f9f0d02b4b/Lib/pty.py +# PSF License (see licenses/PSF-license.txt or https://opensource.org/licenses/Python-2.0) +"""Pseudo terminal utilities.""" + +# Bugs: No signal handling. Doesn't set slave termios and window size. +# Only tested on Linux, FreeBSD, and macOS. +# See: W. Richard Stevens. 1992. Advanced Programming in the +# UNIX Environment. Chapter 19. +# Author: Steen Lumholt -- with additions by Guido. + +from select import select +import os +import sys +import tty + +# names imported directly for test mocking purposes +from os import close, waitpid +from tty import setraw, tcgetattr, tcsetattr + +__all__ = ["openpty", "fork", "spawn"] + +STDIN_FILENO = 0 +STDOUT_FILENO = 1 +STDERR_FILENO = 2 + +CHILD = 0 + +def openpty(): + """openpty() -> (master_fd, slave_fd) + Open a pty master/slave pair, using os.openpty() if possible.""" + + try: + return os.openpty() + except (AttributeError, OSError): + pass + master_fd, slave_name = _open_terminal() + slave_fd = slave_open(slave_name) + return master_fd, slave_fd + +def master_open(): + """master_open() -> (master_fd, slave_name) + Open a pty master and return the fd, and the filename of the slave end. + Deprecated, use openpty() instead.""" + + try: + master_fd, slave_fd = os.openpty() + except (AttributeError, OSError): + pass + else: + slave_name = os.ttyname(slave_fd) + os.close(slave_fd) + return master_fd, slave_name + + return _open_terminal() + +def _open_terminal(): + """Open pty master and return (master_fd, tty_name).""" + for x in 'pqrstuvwxyzPQRST': + for y in '0123456789abcdef': + pty_name = '/dev/pty' + x + y + try: + fd = os.open(pty_name, os.O_RDWR) + except OSError: + continue + return (fd, '/dev/tty' + x + y) + raise OSError('out of pty devices') + +def slave_open(tty_name): + """slave_open(tty_name) -> slave_fd + Open the pty slave and acquire the controlling terminal, returning + opened filedescriptor. + Deprecated, use openpty() instead.""" + + result = os.open(tty_name, os.O_RDWR) + try: + from fcntl import ioctl, I_PUSH + except ImportError: + return result + try: + ioctl(result, I_PUSH, "ptem") + ioctl(result, I_PUSH, "ldterm") + except OSError: + pass + return result + +def fork(): + """fork() -> (pid, master_fd) + Fork and make the child a session leader with a controlling terminal.""" + + try: + pid, fd = os.forkpty() + except (AttributeError, OSError): + pass + else: + if pid == CHILD: + try: + os.setsid() + except OSError: + # os.forkpty() already set us session leader + pass + return pid, fd + + master_fd, slave_fd = openpty() + pid = os.fork() + if pid == CHILD: + # Establish a new session. + os.setsid() + os.close(master_fd) + + # Slave becomes stdin/stdout/stderr of child. + os.dup2(slave_fd, STDIN_FILENO) + os.dup2(slave_fd, STDOUT_FILENO) + os.dup2(slave_fd, STDERR_FILENO) + if slave_fd > STDERR_FILENO: + os.close(slave_fd) + + # Explicitly open the tty to make it become a controlling tty. + tmp_fd = os.open(os.ttyname(STDOUT_FILENO), os.O_RDWR) + os.close(tmp_fd) + else: + os.close(slave_fd) + + # Parent and child process. + return pid, master_fd + +def _writen(fd, data): + """Write all the data to a descriptor.""" + while data: + n = os.write(fd, data) + data = data[n:] + +def _read(fd): + """Default read function.""" + return os.read(fd, 1024) + +def _copy(master_fd, master_read=_read, stdin_read=_read): + """Parent copy loop. + Copies + pty master -> standard output (master_read) + standard input -> pty master (stdin_read)""" + fds = [master_fd, STDIN_FILENO] + while fds: + rfds, _wfds, _xfds = select(fds, [], []) + + if master_fd in rfds: + # Some OSes signal EOF by returning an empty byte string, + # some throw OSErrors. + try: + data = master_read(master_fd) + except OSError: + data = b"" + if not data: # Reached EOF. + return # Assume the child process has exited and is + # unreachable, so we clean up. + else: + os.write(STDOUT_FILENO, data) + + if STDIN_FILENO in rfds: + data = stdin_read(STDIN_FILENO) + if not data: + fds.remove(STDIN_FILENO) + else: + _writen(master_fd, data) + +def spawn(argv, master_read=_read, stdin_read=_read): + """Create a spawned process.""" + if isinstance(argv, str): + argv = (argv,) + sys.audit('pty.spawn', argv) + + pid, master_fd = fork() + if pid == CHILD: + os.execlp(argv[0], *argv) + + try: + mode = tcgetattr(STDIN_FILENO) + setraw(STDIN_FILENO) + restore = True + except tty.error: # This is the same as termios.error + restore = False + + try: + _copy(master_fd, master_read, stdin_read) + finally: + if restore: + tcsetattr(STDIN_FILENO, tty.TCSAFLUSH, mode) + + close(master_fd) + return waitpid(pid, 0)[1] diff --git a/test/integration/targets/jinja2_native_types/runme.sh b/test/integration/targets/jinja2_native_types/runme.sh index f648f875..a6c2befa 100755 --- a/test/integration/targets/jinja2_native_types/runme.sh +++ b/test/integration/targets/jinja2_native_types/runme.sh @@ -7,4 +7,5 @@ ansible-playbook runtests.yml -v "$@" ansible-playbook --vault-password-file test_vault_pass test_vault.yml -v "$@" ansible-playbook test_hostvars.yml -v "$@" ansible-playbook nested_undefined.yml -v "$@" +ansible-playbook test_preserving_quotes.yml -v "$@" unset ANSIBLE_JINJA2_NATIVE diff --git a/test/integration/targets/jinja2_native_types/test_casting.yml b/test/integration/targets/jinja2_native_types/test_casting.yml index 8627a056..5e9c76d6 100644 --- a/test/integration/targets/jinja2_native_types/test_casting.yml +++ b/test/integration/targets/jinja2_native_types/test_casting.yml @@ -13,7 +13,7 @@ - assert: that: - - 'int_to_str == "2"' + - int_to_str == "'2'" - 'int_to_str|type_debug in ["str", "unicode"]' - 'int_to_str2 == "2"' - 'int_to_str2|type_debug in ["NativeJinjaText"]' diff --git a/test/integration/targets/jinja2_native_types/test_concatentation.yml b/test/integration/targets/jinja2_native_types/test_concatentation.yml index 8a8077b6..24a90381 100644 --- a/test/integration/targets/jinja2_native_types/test_concatentation.yml +++ b/test/integration/targets/jinja2_native_types/test_concatentation.yml @@ -22,7 +22,7 @@ - assert: that: - - 'string_sum == "12"' + - string_sum == "'12'" - 'string_sum|type_debug in ["str", "unicode"]' - name: add two lists diff --git a/test/integration/targets/jinja2_native_types/test_preserving_quotes.yml b/test/integration/targets/jinja2_native_types/test_preserving_quotes.yml new file mode 100644 index 00000000..d6fea10e --- /dev/null +++ b/test/integration/targets/jinja2_native_types/test_preserving_quotes.yml @@ -0,0 +1,14 @@ +- hosts: localhost + gather_facts: false + tasks: + - assert: + that: + - quoted_str == '"hello"' + - empty_quoted_str == '""' + vars: + third_nested_lvl: '"hello"' + second_nested_lvl: "{{ third_nested_lvl }}" + first_nested_lvl: "{{ second_nested_lvl }}" + quoted_str: "{{ first_nested_lvl }}" + empty_quoted_str: "{{ empty_str }}" + empty_str: '""' diff --git a/test/integration/targets/jinja_plugins/tasks/main.yml b/test/integration/targets/jinja_plugins/tasks/main.yml index 824e8306..d3d6e2e8 100644 --- a/test/integration/targets/jinja_plugins/tasks/main.yml +++ b/test/integration/targets/jinja_plugins/tasks/main.yml @@ -1,4 +1,6 @@ - shell: ansible-playbook {{ verbosity }} playbook.yml + environment: + ANSIBLE_FORCE_COLOR: no args: chdir: '{{ role_path }}' vars: @@ -8,10 +10,14 @@ - debug: var: result +- set_fact: + # NOTE: This will cram words together that were manually wrapped, which should be OK for this test. + stderr: "{{ result.stderr | replace('\n', '') }}" + - assert: that: - - '"[WARNING]: Skipping filter plugin" in result.stderr' - - '"[WARNING]: Skipping test plugin" in result.stderr' - - result.stderr|regex_findall('bad_collection_filter')|length == 3 - - result.stderr|regex_findall('bad_collection_filter2')|length == 1 - - result.stderr|regex_findall('bad_collection_test')|length == 2 + - '"[WARNING]: Skipping filter plugin" in stderr' + - '"[WARNING]: Skipping test plugin" in stderr' + - stderr|regex_findall('bad_collection_filter')|length == 3 + - stderr|regex_findall('bad_collection_filter2')|length == 1 + - stderr|regex_findall('bad_collection_test')|length == 2 diff --git a/test/lib/ansible_test/_internal/commands/sanity/pylint.py b/test/lib/ansible_test/_internal/commands/sanity/pylint.py index 4723c13d..cd5a8350 100644 --- a/test/lib/ansible_test/_internal/commands/sanity/pylint.py +++ b/test/lib/ansible_test/_internal/commands/sanity/pylint.py @@ -226,7 +226,7 @@ class PylintTest(SanitySingleVersion): '--max-complexity', '20', '--rcfile', rcfile, '--output-format', 'json', - '--load-plugins', ','.join(load_plugins), + '--load-plugins', ','.join(sorted(load_plugins)), ] + paths if data_context().content.collection: diff --git a/test/lib/ansible_test/_util/target/sanity/import/importer.py b/test/lib/ansible_test/_util/target/sanity/import/importer.py index 3dcb8bf9..3180530c 100644 --- a/test/lib/ansible_test/_util/target/sanity/import/importer.py +++ b/test/lib/ansible_test/_util/target/sanity/import/importer.py @@ -48,11 +48,7 @@ def main(): __import__(name) return sys.modules[name] - try: - # noinspection PyCompatibility - from StringIO import StringIO - except ImportError: - from io import StringIO + from io import BytesIO, TextIOWrapper try: from importlib.util import spec_from_loader, module_from_spec @@ -436,8 +432,9 @@ def main(): class Capture: """Captured output and/or exception.""" def __init__(self): - self.stdout = StringIO() - self.stderr = StringIO() + # use buffered IO to simulate StringIO; allows Ansible's stream patching to behave without warnings + self.stdout = TextIOWrapper(BytesIO()) + self.stderr = TextIOWrapper(BytesIO()) def capture_report(path, capture, messages): """Report on captured output. @@ -445,12 +442,17 @@ def main(): :type capture: Capture :type messages: set[str] """ - if capture.stdout.getvalue(): - first = capture.stdout.getvalue().strip().splitlines()[0].strip() + # since we're using buffered IO, flush before checking for data + capture.stdout.flush() + capture.stderr.flush() + stdout_value = capture.stdout.buffer.getvalue() + if stdout_value: + first = stdout_value.decode().strip().splitlines()[0].strip() report_message(path, 0, 0, 'stdout', first, messages) - if capture.stderr.getvalue(): - first = capture.stderr.getvalue().strip().splitlines()[0].strip() + stderr_value = capture.stderr.buffer.getvalue() + if stderr_value: + first = stderr_value.decode().strip().splitlines()[0].strip() report_message(path, 0, 0, 'stderr', first, messages) def report_message(path, line, column, code, message, messages): diff --git a/test/sanity/ignore.txt b/test/sanity/ignore.txt index e9ea871d..660628fc 100644 --- a/test/sanity/ignore.txt +++ b/test/sanity/ignore.txt @@ -133,6 +133,7 @@ test/integration/targets/ansible-test-docker/ansible_collections/ns/col/tests/un test/integration/targets/ansible-test-no-tty/ansible_collections/ns/col/vendored_pty.py pep8!skip # vendored code test/integration/targets/collections_relative_imports/collection_root/ansible_collections/my_ns/my_col/plugins/modules/my_module.py pylint:relative-beyond-top-level test/integration/targets/collections_relative_imports/collection_root/ansible_collections/my_ns/my_col/plugins/module_utils/my_util2.py pylint:relative-beyond-top-level +test/integration/targets/fork_safe_stdio/vendored_pty.py pep8!skip # vendored code test/integration/targets/gathering_facts/library/bogus_facts shebang test/integration/targets/gathering_facts/library/facts_one shebang test/integration/targets/gathering_facts/library/facts_two shebang diff --git a/test/units/plugins/action/test_action.py b/test/units/plugins/action/test_action.py index 74b08e38..f2bbe194 100644 --- a/test/units/plugins/action/test_action.py +++ b/test/units/plugins/action/test_action.py @@ -427,7 +427,7 @@ class TestActionBase(unittest.TestCase): 'stderr': '', } assertThrowRegex( - 'Failed to set file mode on remote temporary file', + 'Failed to set file mode or acl on remote temporary files', execute=True) action_base._remote_chmod.return_value = { 'rc': 0, |