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