From 8c0de50fb8e5a3df57f8ba0e53b11497c3fe5e5d Mon Sep 17 00:00:00 2001 From: Yuriy Novostavskiy Date: Tue, 15 Sep 2026 16:31:27 +0200 Subject: [PATCH] **This is a manual backport of PR #1242 as merged into main ([031bc47](https://github.com/ansible-collections/kubernetes.core/commit/031bc475fadd0fcf8152d3c9083e22a77e3d870d)).** (#1251) Emit an explicit deprecation warning when users enable Ansible Turbo mode via `ENABLE_TURBO_MODE`, and stop turbo mode from being used on ansible-core versions where `cloud.common` is not supported. Turbo mode depends on `cloud.common`, which is being retired. PR #1120 already deprecated the `cloud.common` dependency; without this change, removing that dependency later would cause `ENABLE_TURBO_MODE` to stop working silently. This PR warns users at runtime so they can migrate before support is removed in `kubernetes.core` 8.0.0. Changes: * Modules: emit the deprecation at import time via the module-level `deprecate()` in `plugins/module_utils/ansiblemodule.py`. `AnsibleTurboModule.__init__()` ends in `run_on_daemon()`, which calls `exit_json()` and exits the process, so a `deprecate()` call tied to instance construction is never reached. * Modules: skip turbo mode on ansible-core >= 2.19.0 and fall back to the standard `AnsibleModule`, emitting a warning. `cloud.common` declares `requires_ansible '>=2.15.0,<2.19'`, but that is only enforced at collection load time and the turbo import itself still succeeds on newer cores, so turbo mode would otherwise fail later with `byte indices must be integers or slices, not str`. * Modules and lookup: warn instead of silently falling back when `ENABLE_TURBO_MODE` is set but `cloud.common` is not installed. * Lookup: call `Display.deprecated()` in the `k8s` lookup when turbo mode is enabled. The lookup path still works on >= 2.19, so it keeps using turbo and is not version-gated. * Docs: add deprecation notices to `README.md` and `docs/ansible_turbo_mode.rst`. * Changelog: add `deprecated_features`, `bugfixes`, and `minor_changes` fragment entries. On ansible-core < 2.19 with `cloud.common` installed, turbo mode continues to work exactly as before and only gains a deprecation warning. On ansible-core >= 2.19 turbo mode is now deliberately bypassed, which replaces a confusing traceback with a clear warning. * Bugfix Pull Request * Docs Pull Request `ENABLE_TURBO_MODE` / Ansible Turbo mode On a supported ansible-core (< 2.19) with `cloud.common` installed, turbo mode stays active and users see: ``` [DEPRECATION WARNING]: ENABLE_TURBO_MODE is deprecated, as it relies on the cloud.common collection which is being retired. Setting this environment variable will have no effect once support is removed. This feature will be removed from kubernetes.core in version 8.0.0. ``` On ansible-core >= 2.19.0, turbo mode is bypassed and an additional warning is emitted: ``` [WARNING]: ENABLE_TURBO_MODE is ignored on ansible-core 2.21.4: Ansible Turbo mode requires the cloud.common collection, which supports ansible-core < 2.19.0 only. Continuing without Turbo mode. ``` Warnings are emitted from: * `plugins/module_utils/ansiblemodule.py` for collection modules * `plugins/lookup/k8s.py` for the `k8s` lookup plugin To verify locally: ```shell export ENABLE_TURBO_MODE=1 ansible localhost -m kubernetes.core.k8s_info -a "kind=Namespace" 2>&1 | grep -iE "deprecat|warning" ``` Integration tests that run with `ENABLE_TURBO_MODE=true` use ansible-core 2.18, where turbo mode remains enabled, so turbo behaviour there is unchanged. Thanks to @yurnov for diagnosing the unreachable deprecation and for the suggested fix in [mandar242#1](https://github.com/mandar242/kubernetes.core/pull/1). (cherry picked from commit 031bc475fadd0fcf8152d3c9083e22a77e3d870d) Co-authored-by: Mandar Kulkarni --- README.md | 6 +++- .../fragments/deprecate-enable-turbo-mode.yml | 7 +++++ docs/ansible_turbo_mode.rst | 14 +++++++++ plugins/lookup/k8s.py | 14 +++++++++ plugins/module_utils/ansiblemodule.py | 30 +++++++++++++++++++ 5 files changed, 70 insertions(+), 1 deletion(-) create mode 100644 changelogs/fragments/deprecate-enable-turbo-mode.yml diff --git a/README.md b/README.md index 96492d7b..b1dc6828 100644 --- a/README.md +++ b/README.md @@ -187,7 +187,11 @@ For documentation on how to use individual modules and other content included in ## Ansible Turbo Mode Tech Preview -The ``kubernetes.core`` collection supports Ansible Turbo mode as a tech preview via the ``cloud.common`` collection. By default, this feature is disabled. To enable Turbo mode for modules, set the environment variable `ENABLE_TURBO_MODE=1` on the managed node. For example: +> **Deprecated:** Ansible Turbo mode (`ENABLE_TURBO_MODE`) is deprecated and will be removed in a future major release (planned for 8.0.0), since it depends on the `cloud.common` collection, which is being retired. Setting `ENABLE_TURBO_MODE` will keep emitting a deprecation warning until support is removed, at which point the variable will have no effect. + +> **Note:** Ansible Turbo mode is supported only with ``ansible-core`` versions **lower than 2.19**. Starting from ``ansible-core`` 2.19, the ``cloud.common`` collection is no longer supported, and therefore Ansible Turbo mode is also not supported in ``kubernetes.core``. If ``ENABLE_TURBO_MODE`` is set to ``1`` (or any truthy value) with ``ansible-core >= 2.19.0``, Turbo mode is ignored and a warning is emitted; modules run without it. + +The ``kubernetes.core`` collection supports Ansible Turbo mode as a tech preview via the ``cloud.common`` collection (requires `ansible-core < 2.19`). By default, this feature is disabled. To enable Turbo mode for modules, set the environment variable `ENABLE_TURBO_MODE=1` on the managed node. For example: ```yaml --- diff --git a/changelogs/fragments/deprecate-enable-turbo-mode.yml b/changelogs/fragments/deprecate-enable-turbo-mode.yml new file mode 100644 index 00000000..d25854cc --- /dev/null +++ b/changelogs/fragments/deprecate-enable-turbo-mode.yml @@ -0,0 +1,7 @@ +--- +deprecated_features: + - Ansible Turbo mode (``ENABLE_TURBO_MODE``) has been deprecated and will be removed in release 8.0.0, as it depends on the ``cloud.common`` collection, which is being retired (https://github.com/ansible-collections/kubernetes.core/pull/1242). +bugfixes: + - Ansible Turbo mode - ignore ``ENABLE_TURBO_MODE`` on ansible-core 2.19.0 and later, where the ``cloud.common`` collection is not supported, and fall back to the standard ``AnsibleModule`` instead of failing with ``byte indices must be integers or slices, not str`` (https://github.com/ansible-collections/kubernetes.core/pull/1242). +minor_changes: + - k8s lookup - warn when ``ENABLE_TURBO_MODE`` is set but the ``cloud.common`` collection is not installed, instead of silently falling back to the standard lookup base (https://github.com/ansible-collections/kubernetes.core/pull/1242). diff --git a/docs/ansible_turbo_mode.rst b/docs/ansible_turbo_mode.rst index 6e0c990e..1e998e11 100644 --- a/docs/ansible_turbo_mode.rst +++ b/docs/ansible_turbo_mode.rst @@ -12,6 +12,20 @@ Following document provides overview of Ansible Turbo mode in ``kubernetes.core` :depth: 1 +.. warning:: + Ansible Turbo mode is **deprecated** and will be removed in a future major release + (planned for 8.0.0), as it depends on the ``cloud.common`` collection, which is being + retired. Setting ``ENABLE_TURBO_MODE`` now emits a deprecation warning; once support is + removed, the variable will have no effect. Start planning your migration away from + Turbo mode. + +.. warning:: + Ansible Turbo mode is supported only with ``ansible-core`` versions **lower than 2.19**. + Starting from ``ansible-core`` 2.19, the ``cloud.common`` collection is no longer supported, + and therefore Ansible Turbo mode is also not supported in ``kubernetes.core``. + If ``ENABLE_TURBO_MODE`` is set to ``1`` (or any truthy value) with ``ansible-core >= 2.19.0``, + Turbo mode is ignored and a warning is emitted; modules run without it. + Synopsis -------- - A brief introduction about Ansible Turbo mode in ``kuberentes.core`` collection. diff --git a/plugins/lookup/k8s.py b/plugins/lookup/k8s.py index ec9fc0c6..1f508082 100644 --- a/plugins/lookup/k8s.py +++ b/plugins/lookup/k8s.py @@ -213,6 +213,7 @@ import os from ansible.errors import AnsibleError from ansible.module_utils.common._collections_compat import KeysView from ansible.module_utils.common.validation import check_type_bool +from ansible.utils.display import Display from ansible_collections.kubernetes.core.plugins.module_utils.k8s.client import ( get_api_client, ) @@ -220,17 +221,30 @@ from ansible_collections.kubernetes.core.plugins.module_utils.k8s.resource impor create_definitions, ) +display = Display() + try: enable_turbo_mode = check_type_bool(os.environ.get("ENABLE_TURBO_MODE")) except TypeError: enable_turbo_mode = False if enable_turbo_mode: + display.deprecated( + "ENABLE_TURBO_MODE is deprecated, as it relies on the cloud.common " + "collection which is being retired. Setting this environment " + "variable will have no effect once support is removed.", + version="8.0.0", + collection_name="kubernetes.core", + ) try: from ansible_collections.cloud.common.plugins.plugin_utils.turbo.lookup import ( TurboLookupBase as LookupBase, ) except ImportError: + display.warning( + "ENABLE_TURBO_MODE is set but the cloud.common collection is not installed. " + "Continuing without Turbo mode." + ) from ansible.plugins.lookup import LookupBase # noqa: F401 else: from ansible.plugins.lookup import LookupBase # noqa: F401 diff --git a/plugins/module_utils/ansiblemodule.py b/plugins/module_utils/ansiblemodule.py index d3eba8df..1792a2d8 100644 --- a/plugins/module_utils/ansiblemodule.py +++ b/plugins/module_utils/ansiblemodule.py @@ -5,13 +5,39 @@ __metaclass__ = type import os +from ansible.module_utils.ansible_release import __version__ as ansible_version from ansible.module_utils.common.validation import check_type_bool +from ansible.module_utils.common.warnings import deprecate, warn +from ansible_collections.kubernetes.core.plugins.module_utils.version import ( + LooseVersion, +) + +# cloud.common declares requires_ansible '>=2.15.0,<2.19'. On newer ansible-core the +# import still succeeds, so the version has to be checked explicitly: relying on +# ImportError alone lets turbo mode fail later with an unrelated traceback. +TURBO_UNSUPPORTED_CORE = "2.19.0" try: enable_turbo_mode = check_type_bool(os.environ.get("ENABLE_TURBO_MODE")) except TypeError: enable_turbo_mode = False +if enable_turbo_mode: + deprecate( + "ENABLE_TURBO_MODE is deprecated, as it relies on the cloud.common collection " + "which is being retired. Setting this environment variable will have no effect " + "once support is removed.", + version="8.0.0", + collection_name="kubernetes.core", + ) + if LooseVersion(ansible_version) >= LooseVersion(TURBO_UNSUPPORTED_CORE): + warn( + "ENABLE_TURBO_MODE is ignored on ansible-core %s: Ansible Turbo mode requires " + "the cloud.common collection, which supports ansible-core < %s only. " + "Continuing without Turbo mode." % (ansible_version, TURBO_UNSUPPORTED_CORE) + ) + enable_turbo_mode = False + if enable_turbo_mode: try: from ansible_collections.cloud.common.plugins.module_utils.turbo.module import ( # noqa: F401 @@ -20,6 +46,10 @@ if enable_turbo_mode: AnsibleModule.collection_name = "kubernetes.core" except ImportError: + warn( + "ENABLE_TURBO_MODE is set but the cloud.common collection is not installed. " + "Continuing without Turbo mode." + ) from ansible.module_utils.basic import AnsibleModule # noqa: F401 else: from ansible.module_utils.basic import AnsibleModule # noqa: F401