From ba133a9591278e92e65ecbc878e8c9dabb2c7e4d Mon Sep 17 00:00:00 2001 From: Jordan Borean Date: Tue, 29 Oct 2024 05:15:39 +1000 Subject: [PATCH 1/3] Added 2.18 porting guide --- .../porting_guides/core_porting_guides.rst | 1 + .../porting_guide_core_2.18.rst | 123 ++++++++++++++++++ 2 files changed, 124 insertions(+) create mode 100644 docs/docsite/rst/porting_guides/porting_guide_core_2.18.rst diff --git a/docs/docsite/rst/porting_guides/core_porting_guides.rst b/docs/docsite/rst/porting_guides/core_porting_guides.rst index 4bfd206aeac..9facb790f74 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.18 porting_guide_core_2.17 porting_guide_core_2.16 porting_guide_core_2.15 diff --git a/docs/docsite/rst/porting_guides/porting_guide_core_2.18.rst b/docs/docsite/rst/porting_guides/porting_guide_core_2.18.rst new file mode 100644 index 00000000000..c13e8d619ac --- /dev/null +++ b/docs/docsite/rst/porting_guides/porting_guide_core_2.18.rst @@ -0,0 +1,123 @@ + +.. _porting_2.18_guide_core: + +******************************* +Ansible-core 2.18 Porting Guide +******************************* + +This section discusses the behavioral changes between ``ansible-core`` 2.17 and ``ansible-core`` 2.18. + +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. + +We suggest you read this page along with `ansible-core Changelog for 2.18 `_ to understand what updates you may need to make. + +This document is part of a collection on porting. The complete list of porting guides can be found at :ref:`porting guides `. + +.. contents:: Topics + + +Playbook +======== + +* Conditionals - due to mitigation of security issue CVE-2023-5764 in ansible-core 2.16.1, + conditional expressions with embedded template blocks can fail with the message + "``Conditional is marked as unsafe, and cannot be evaluated.``" when an embedded template + consults data from untrusted sources like module results or vars marked ``!unsafe``. + Conditionals with embedded templates can be a source of malicious template injection when + referencing untrusted data, and can nearly always be rewritten without embedded + templates. Playbook task conditional keywords such as ``when`` and ``until`` have long + displayed warnings discouraging use of embedded templates in conditionals; this warning + has been expanded to non-task conditionals as well, such as the ``assert`` action. + + .. code-block:: yaml + + - name: task with a module result (always untrusted by Ansible) + shell: echo "hi mom" + register: untrusted_result + + # don't do it this way... + # - name: insecure conditional with embedded template consulting untrusted data + # assert: + # that: '"hi mom" is in {{ untrusted_result.stdout }}' + + - name: securely access untrusted values directly as Jinja variables instead + assert: + that: '"hi mom" is in untrusted_result.stdout' + + + +Command Line +============ + +* Python 3.10 is a no longer supported control node version. Python 3.11+ is now required for running Ansible. +* Python 3.7 is a no longer supported remote version. Python 3.8+ is now required for target execution. + + +Deprecated +========== + +No notable changes + + +Modules +======= + +No notable changes + + +Modules removed +--------------- + +The following modules no longer exist: + +* No notable changes + + +Deprecation notices +------------------- + +No notable changes + + +Noteworthy module changes +------------------------- + +No notable changes + + +Plugins +======= + +* The ``ssh`` connection plugin now officially supports targeting Windows hosts. A + breaking change has been made as part of this official support is the low level command + execution done by plugins like ``ansible.builtin.raw`` and action plugins calling + ``_low_level_execute_command`` is no longer wrapped with a ``powershell.exe`` wrapped + invocation. These commands will now be executed directly on the target host using + the default shell configuration set on the Windows host. This change is done to + simplify the configuration required on the Ansible side, make module execution more + efficient, and to remove the need to decode stderr CLIXML output. A consequence of this + change is that ``ansible.builtin.raw`` commands are no longer be guaranteed to be + run through a PowerShell shell and with the output encoding of UTF-8. To run a command + through PowerShell and with UTF-8 output support, use the ``ansible.windows.win_shell`` + or ``ansible.windows.win_powershell`` module instead. + + .. code-block:: yaml + + - name: Run with win_shell + ansible.windows.win_shell: Write-Host "Hello, Café" + + - name: Run with win_powershell + ansible.windows.win_powershell: + script: Write-Host "Hello, Café" + + +Porting custom scripts +====================== + +No notable changes + + +Networking +========== + +No notable changes From 2c6e389da932ee33428bbbb51b802edc0f539e65 Mon Sep 17 00:00:00 2001 From: Jordan Borean Date: Tue, 29 Oct 2024 07:51:09 +1000 Subject: [PATCH 2/3] Removed assertion change from porting guide --- .../porting_guide_core_2.18.rst | 26 +------------------ 1 file changed, 1 insertion(+), 25 deletions(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_core_2.18.rst b/docs/docsite/rst/porting_guides/porting_guide_core_2.18.rst index c13e8d619ac..ea53c439faa 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_core_2.18.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_core_2.18.rst @@ -19,31 +19,7 @@ This document is part of a collection on porting. The complete list of porting g Playbook ======== -* Conditionals - due to mitigation of security issue CVE-2023-5764 in ansible-core 2.16.1, - conditional expressions with embedded template blocks can fail with the message - "``Conditional is marked as unsafe, and cannot be evaluated.``" when an embedded template - consults data from untrusted sources like module results or vars marked ``!unsafe``. - Conditionals with embedded templates can be a source of malicious template injection when - referencing untrusted data, and can nearly always be rewritten without embedded - templates. Playbook task conditional keywords such as ``when`` and ``until`` have long - displayed warnings discouraging use of embedded templates in conditionals; this warning - has been expanded to non-task conditionals as well, such as the ``assert`` action. - - .. code-block:: yaml - - - name: task with a module result (always untrusted by Ansible) - shell: echo "hi mom" - register: untrusted_result - - # don't do it this way... - # - name: insecure conditional with embedded template consulting untrusted data - # assert: - # that: '"hi mom" is in {{ untrusted_result.stdout }}' - - - name: securely access untrusted values directly as Jinja variables instead - assert: - that: '"hi mom" is in untrusted_result.stdout' - +No notable changed Command Line From 2524c64950c21a4fbbc67f3fd95926e41fc6eda5 Mon Sep 17 00:00:00 2001 From: Jordan Borean Date: Wed, 30 Oct 2024 05:56:15 +1000 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Sandra McCann --- docs/docsite/rst/porting_guides/porting_guide_core_2.18.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_core_2.18.rst b/docs/docsite/rst/porting_guides/porting_guide_core_2.18.rst index ea53c439faa..faacb97bfc6 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_core_2.18.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_core_2.18.rst @@ -65,14 +65,14 @@ Plugins ======= * The ``ssh`` connection plugin now officially supports targeting Windows hosts. A - breaking change has been made as part of this official support is the low level command + breaking change that has been made as part of this official support is the low level command execution done by plugins like ``ansible.builtin.raw`` and action plugins calling ``_low_level_execute_command`` is no longer wrapped with a ``powershell.exe`` wrapped invocation. These commands will now be executed directly on the target host using the default shell configuration set on the Windows host. This change is done to simplify the configuration required on the Ansible side, make module execution more efficient, and to remove the need to decode stderr CLIXML output. A consequence of this - change is that ``ansible.builtin.raw`` commands are no longer be guaranteed to be + change is that ``ansible.builtin.raw`` commands are no longer guaranteed to be run through a PowerShell shell and with the output encoding of UTF-8. To run a command through PowerShell and with UTF-8 output support, use the ``ansible.windows.win_shell`` or ``ansible.windows.win_powershell`` module instead.