From ece629fcd12d3e3fc72b153b28246531528365c6 Mon Sep 17 00:00:00 2001 From: Matt Martz Date: Wed, 15 Oct 2025 12:32:31 -0500 Subject: [PATCH] Add 2.20 porting guide --- .../porting_guides/core_porting_guides.rst | 1 + .../porting_guide_core_2.20.rst | 201 ++++++++++++++++++ 2 files changed, 202 insertions(+) create mode 100644 docs/docsite/rst/porting_guides/porting_guide_core_2.20.rst diff --git a/docs/docsite/rst/porting_guides/core_porting_guides.rst b/docs/docsite/rst/porting_guides/core_porting_guides.rst index e6bdaf43680..5ba85bdb966 100644 --- a/docs/docsite/rst/porting_guides/core_porting_guides.rst +++ b/docs/docsite/rst/porting_guides/core_porting_guides.rst @@ -12,6 +12,7 @@ Please note that this is not a complete list. If you believe any extra informati :maxdepth: 1 :glob: + porting_guide_core_2.20 porting_guide_core_2.19 porting_guide_core_2.18 porting_guide_core_2.17 diff --git a/docs/docsite/rst/porting_guides/porting_guide_core_2.20.rst b/docs/docsite/rst/porting_guides/porting_guide_core_2.20.rst new file mode 100644 index 00000000000..e5abdc25530 --- /dev/null +++ b/docs/docsite/rst/porting_guides/porting_guide_core_2.20.rst @@ -0,0 +1,201 @@ + +.. _porting_2.20_guide_core: + +******************************* +Ansible-core 2.20 Porting Guide +******************************* + +This section discusses the behavioral changes between ``ansible-core`` 2.19 and ``ansible-core`` 2.20. + +It is intended to assist in updating your playbooks, plugins, +and other parts of your Ansible infrastructure so they will work with this version of Ansible. + +Review this page and the +`ansible-core Changelog for 2.20 `_ +to understand necessary changes. + +This document is part of a collection on porting. +The complete list of porting guides can be found at :ref:`porting guides `. + +.. contents:: Topics + +.. _2.20_introduction: + +Introduction +============ + +No notable changes + +.. _2.20_playbook: + +Playbook +======== + +Removed quote stripping in PowerShell operations +------------------------------------------------- + +The PowerShell module utilities no longer attempt to remove quotes from paths when performing Windows operations like copying and fetching files. This should not affect normal playbooks unless a value is quoted too many times. If you have playbooks that rely on this automatic quote removal, you will need to adjust your path formatting. + +.. _2.20_engine: + +Engine +====== + +No notable changes + +.. _2.20_plugin_api: + +Plugin API +========== + +Removed Features +---------------- + +The following previously deprecated features have been removed: + +* The ``DEFAULT_TRANSPORT`` configuration option no longer supports the ``smart`` value that selected the default transport as either ``ssh`` or ``paramiko`` based on the underlying platform configuration. +* The ``vault`` and ``unvault`` filters no longer accept the deprecated ``vaultid`` parameter. +* The ``ansible-galaxy`` command no longer supports the v2 Galaxy server API. Galaxy servers hosting collections must support v3. +* The ``dnf`` and ``dnf5`` modules no longer support the deprecated ``install_repoquery`` option. +* The ``encrypt`` module utility no longer includes the deprecated ``passlib_or_crypt`` API. +* The ``paramiko`` connection plugin no longer supports the ``PARAMIKO_HOST_KEY_AUTO_ADD`` and ``PARAMIKO_LOOK_FOR_KEYS`` configuration keys, which were previously deprecated. +* The ``py3compat.environ`` call has been removed. +* Vars plugins that do not inherit from ``BaseVarsPlugin`` and define a ``get_vars`` method can no longer use the deprecated ``get_host_vars`` or ``get_group_vars`` fallback. +* The ``yum_repository`` module no longer supports the deprecated ``keepcache`` option. + +Behavioral Changes +------------------ + +* The ``DataLoader.get_basedir`` method now returns an absolute path instead of a relative path. Plugin code that relies on relative paths may need adjustment. +* Argument spec validation now treats ``None`` values as empty strings for the ``str`` type for better consistency with pre-2.19 templating conversions. +* When using ``failed_when`` to suppress an error, the ``exception`` key in the result is now renamed to ``failed_when_suppressed_exception``. This prevents the error from being displayed by callbacks after being suppressed. If you have playbooks that check for the exception in the result, update them as follows: + +.. code-block:: yaml+jinja + + # Before + - command: /bin/false + register: result + failed_when: false + + - debug: + msg: "Exception was: {{ result.exception }}" + when: result.exception is defined + + # After + - command: /bin/false + register: result + failed_when: false + + - debug: + msg: "Exception was: {{ result.failed_when_suppressed_exception }}" + when: result.failed_when_suppressed_exception is defined + +.. _2.20_command_line: + +Command Line +============ + +* Python 3.11 is no longer a supported control node version. Python 3.12+ is now required for running Ansible. +* Python 3.8 is no longer a supported remote version. Python 3.9+ is now required for target execution. + +.. _2.20_deprecated: + +Deprecated +========== + +INJECT_FACTS_AS_VARS +-------------------- + +The ``INJECT_FACTS_AS_VARS`` configuration currently defaults to ``True``, but this is now deprecated and it will switch to ``False`` in Ansible 2.24. + +When enabled, facts are available both inside the ``ansible_facts`` dictionary and as individual variables in the main namespace. In the ``ansible_facts`` dictionary, the ``ansible_`` prefix is removed from fact names. + +You will receive deprecation warnings if you are accessing 'injected' facts. To prepare for the future default: + +**Update your playbooks to use the ansible_facts dictionary:** + +.. code-block:: yaml+jinja + + # Deprecated - will stop working in 2.24 + - debug: + msg: "OS: {{ ansible_os_distribution }}" + + # Recommended - works in all versions + - debug: + msg: "OS: {{ ansible_facts['distribution'] }}" + # Note: 'ansible_' prefix is removed inside ansible_facts + +**Or explicitly enable the current behavior in your configuration:** + +In your ``ansible.cfg`` file: + +.. code-block:: ini + + [defaults] + inject_facts_as_vars = True + +By exporting an environment variable: + +.. code-block:: shell + + export ANSIBLE_INJECT_FACT_VARS=True + +Other Deprecations +------------------ + +* The ``vars`` internal variable cache will be removed in 2.24. This cache, once used internally, exposes variables in inconsistent states. The ``vars`` and ``varnames`` lookups should be used instead. +* Specifying ``ignore_files`` as a string in the ``include_vars`` module is deprecated. Use a list instead: + +.. code-block:: yaml + + # Deprecated + - include_vars: + dir: vars/ + ignore_files: ".gitkeep" + + # Correct + - include_vars: + dir: vars/ + ignore_files: [".gitkeep"] + +.. _2.20_modules: + +Modules +======= + +Modules removed +--------------- + +The following modules no longer exist: + +* No notable changes + +Deprecation notices +------------------- + +No notable changes + +Noteworthy module changes +------------------------- + +* The ``include_vars`` module now raises an error if the ``extensions`` parameter is not specified as a list. Previously, non-list values were silently accepted. +* The ``include_vars`` module now raises an error if the ``ignore_files`` parameter is not specified as a list. Previously, string values were accepted but are now deprecated. +* The ``replace`` module now reads and writes files in text-mode as unicode characters instead of as bytes, and switches regex matching to unicode characters instead of bytes. This may affect playbooks that rely on byte-level operations. + +Plugins +======= + +Noteworthy plugin changes +------------------------- + +No notable changes + +Porting custom scripts +====================== + +No notable changes + +Networking +========== + +No notable changes