Files
kubernetes.core/plugins/lookup/k8s.py
T
1016f80aee Add ansible-core version check to k8s lookup turbo mode (#1253) (#1254)
* feat(lookup): add ansible-core version check for turbo mode in k8s lookup

Add ansible-core version checking to the k8s lookup plugin to match the
behavior already implemented in module_utils/ansiblemodule.py.

When ENABLE_TURBO_MODE is set and ansible-core >= 2.19.0:
- Emit deprecation warning for ENABLE_TURBO_MODE
- Emit version warning explaining turbo mode is unsupported
- Disable turbo mode and fall back to standard LookupBase

This prevents confusing tracebacks when cloud.common (which declares
requires_ansible '>=2.15.0,<2.19') is used on newer ansible-core versions
where it is not fully compatible.

Changes:
- Import ansible_version and LooseVersion
- Add TURBO_UNSUPPORTED_CORE = "2.19.0" constant
- Check version before enabling turbo mode
- Disable turbo mode and warn if version >= 2.19.0

Addresses reviewer feedback on PR #1251 to add version testing to the
lookup plugin matching the module implementation.



* test(lookup): add unit tests for k8s turbo mode version check

Add comprehensive unit tests for the ansible-core version checking logic
in the k8s lookup plugin's turbo mode handling.

Tests validate that when ENABLE_TURBO_MODE is set:
- Turbo mode is disabled on ansible-core >= 2.19.0 (tests 2.19.0 and 2.21.4)
- Turbo mode is enabled on ansible-core < 2.19.0 (tests 2.18.0)
- Appropriate deprecation and version warnings are shown
- Standard LookupBase is used when turbo mode is disabled

Tests also verify that when ENABLE_TURBO_MODE is not set:
- No deprecation or warning messages are shown
- Turbo mode remains disabled
- Standard LookupBase is used

Implementation follows pytest best practices:
- Autouse fixture for module cleanup between tests
- Parametrized tests to avoid duplication (2.19.0 and 2.21.4 share logic)
- Mock assertion methods (assert_called, assert_not_called)
- Module-level import of StandardLookupBase to avoid repetition

Simplified and maintainable: 71 lines vs initial 139-line implementation
(49% reduction through deduplication and better abstractions).



* style: format with black

* fixup! test(lookup): add unit tests for k8s turbo mode version check

* docs: add changelog fragment for k8s lookup turbo version check

Add changelog entry documenting that the k8s lookup plugin now ignores
ENABLE_TURBO_MODE on ansible-core >= 2.19.0 and falls back to standard
LookupBase instead of failing with a traceback.

This complements the existing deprecate-enable-turbo-mode.yml fragment
which covers the module implementation, by documenting the lookup plugin
fix specifically.



* fixup! fixup! test(lookup): add unit tests for k8s turbo mode version check

* fixup! fixup! fixup! test(lookup): add unit tests for k8s turbo mode version check

---------


(cherry picked from commit c46180bb6f)

Co-authored-by: Don Naro <dnaro@redhat.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-09-15 16:42:50 +01:00

369 lines
15 KiB
Python

#
# Copyright 2018 Red Hat | Ansible
#
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = """
name: k8s
short_description: Query the K8s API
author:
- Chris Houseknecht (@chouseknecht)
- Fabian von Feilitzsch (@fabianvf)
description:
- Uses the Kubernetes Python client to fetch a specific object by name, all matching objects within a
namespace, or all matching objects for all namespaces, as well as information about the cluster.
- Provides access the full range of K8s APIs.
- Enables authentication via config file, certificates, password or token.
notes:
- While querying, please use C(query) or C(lookup) format with C(wantlist=True) to provide an easier and more
consistent interface. For more details, see
U(https://docs.ansible.com/ansible/latest/plugins/lookup.html#forcing-lookups-to-return-lists-query-and-wantlist-true).
options:
cluster_info:
description:
- Use to specify the type of cluster information you are attempting to retrieve. Will take priority
over all the other options.
api_version:
description:
- Use to specify the API version. If I(resource definition) is provided, the I(apiVersion) from the
I(resource_definition) will override this option.
default: v1
kind:
description:
- Use to specify an object model. If I(resource definition) is provided, the I(kind) from a
I(resource_definition) will override this option.
required: true
resource_name:
description:
- Fetch a specific object by name. If I(resource definition) is provided, the I(metadata.name) value
from the I(resource_definition) will override this option.
namespace:
description:
- Limit the objects returned to a specific namespace. If I(resource definition) is provided, the
I(metadata.namespace) value from the I(resource_definition) will override this option.
label_selector:
description:
- Additional labels to include in the query. Ignored when I(resource_name) is provided.
field_selector:
description:
- Specific fields on which to query. Ignored when I(resource_name) is provided.
resource_definition:
description:
- "Provide a YAML configuration for an object. NOTE: I(kind), I(api_version), I(resource_name),
and I(namespace) will be overwritten by corresponding values found in the provided I(resource_definition)."
src:
description:
- "Provide a path to a file containing a valid YAML definition of an object dated. Mutually
exclusive with I(resource_definition). NOTE: I(kind), I(api_version), I(resource_name), and I(namespace)
will be overwritten by corresponding values found in the configuration read in from the I(src) file."
- Reads from the local file system. To read from the Ansible controller's file system, use the file lookup
plugin or template lookup plugin, combined with the from_yaml filter, and pass the result to
I(resource_definition). See Examples below.
host:
description:
- Provide a URL for accessing the API. Can also be specified via K8S_AUTH_HOST environment variable.
api_key:
description:
- Token used to authenticate with the API. Can also be specified via K8S_AUTH_API_KEY environment variable.
kubeconfig:
description:
- Path to an existing Kubernetes config file. If not provided, and no other connection
options are provided, the Kubernetes client will attempt to load the default
configuration file from I(~/.kube/config). Can also be specified via K8S_AUTH_KUBECONFIG environment
variable.
context:
description:
- The name of a context found in the config file. Can also be specified via K8S_AUTH_CONTEXT environment
variable.
username:
description:
- Provide a username for authenticating with the API. Can also be specified via K8S_AUTH_USERNAME environment
variable.
no_proxy:
description:
- The comma separated list of hosts/domains/IP/CIDR that shouldn't go through proxy.
Can also be specified via K8S_AUTH_NO_PROXY environment variable.
- Please note that this module does not pick up typical proxy settings from the environment (e.g. NO_PROXY).
- This feature requires kubernetes>=19.15.0.
When kubernetes library is less than 19.15.0, it fails even if no_proxy is set correctly.
type: str
password:
description:
- Provide a password for authenticating with the API. Can also be specified via K8S_AUTH_PASSWORD environment
variable.
proxy:
description:
- The URL of an HTTP proxy to use for the connection. Can also be specified via K8S_AUTH_PROXY environment variable.
- Please note that this module does not pick up typical proxy settings from the environment (e.g. HTTP_PROXY).
type: str
proxy_headers:
description:
- The Header used for the HTTP proxy.
- Documentation can be found here
U(https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html?highlight=proxy_headers#urllib3.util.make_headers).
type: dict
suboptions:
proxy_basic_auth:
type: str
description:
- Colon-separated username:password for proxy basic authentication header.
- Can also be specified via K8S_AUTH_PROXY_HEADERS_PROXY_BASIC_AUTH environment.
basic_auth:
type: str
description:
- Colon-separated username:password for basic authentication header.
- Can also be specified via K8S_AUTH_PROXY_HEADERS_BASIC_AUTH environment.
user_agent:
type: str
description:
- String representing the user-agent you want, such as foo/1.0.
- Can also be specified via K8S_AUTH_PROXY_HEADERS_USER_AGENT environment.
client_cert:
description:
- Path to a certificate used to authenticate with the API. Can also be specified via K8S_AUTH_CERT_FILE environment
variable.
aliases: [ cert_file ]
client_key:
description:
- Path to a key file used to authenticate with the API. Can also be specified via K8S_AUTH_KEY_FILE environment
variable.
aliases: [ key_file ]
ca_cert:
description:
- Path to a CA certificate used to authenticate with the API. Can also be specified via K8S_AUTH_SSL_CA_CERT
environment variable.
aliases: [ ssl_ca_cert ]
validate_certs:
description:
- Whether or not to verify the API server's SSL certificates. Can also be specified via K8S_AUTH_VERIFY_SSL
environment variable.
type: bool
aliases: [ verify_ssl ]
requirements:
- "python >= 3.9"
- "kubernetes >= 24.2.0"
- "PyYAML >= 3.11"
"""
EXAMPLES = """
- name: Fetch a list of namespaces
set_fact:
projects: "{{ query('kubernetes.core.k8s', api_version='v1', kind='Namespace') }}"
- name: Fetch all deployments
set_fact:
deployments: "{{ query('kubernetes.core.k8s', kind='Deployment') }}"
- name: Fetch all deployments in a namespace
set_fact:
deployments: "{{ query('kubernetes.core.k8s', kind='Deployment', namespace='testing') }}"
- name: Fetch a specific deployment by name
set_fact:
deployments: "{{ query('kubernetes.core.k8s', kind='Deployment', namespace='testing', resource_name='elastic') }}"
- name: Fetch with label selector
set_fact:
service: "{{ query('kubernetes.core.k8s', kind='Service', label_selector='app=galaxy') }}"
# Use parameters from a YAML config
- name: Load config from the Ansible controller filesystem
set_fact:
config: "{{ lookup('file', 'service.yml') | from_yaml }}"
- name: Using the config (loaded from a file in prior task), fetch the latest version of the object
set_fact:
service: "{{ query('kubernetes.core.k8s', resource_definition=config) }}"
- name: Use a config from the local filesystem
set_fact:
service: "{{ query('kubernetes.core.k8s', src='service.yml') }}"
"""
RETURN = """
_list:
description:
- One ore more object definitions returned from the API.
type: list
elements: dict
sample:
- kind: ConfigMap
apiVersion: v1
metadata:
creationTimestamp: "2022-03-04T13:59:49Z"
name: my-config-map
namespace: default
resourceVersion: "418"
uid: 5714b011-d090-4eac-8272-a0ea82ec0abd
data:
key1: val1
"""
import os
from collections.abc import KeysView
from ansible.errors import AnsibleError
from ansible.module_utils.ansible_release import __version__ as ansible_version
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,
)
from ansible_collections.kubernetes.core.plugins.module_utils.k8s.resource import (
create_definitions,
)
from ansible_collections.kubernetes.core.plugins.module_utils.version import (
LooseVersion,
)
display = Display()
# 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:
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",
)
if LooseVersion(ansible_version) >= LooseVersion(TURBO_UNSUPPORTED_CORE):
display.warning(
"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.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
try:
from kubernetes.dynamic.exceptions import NotFoundError
HAS_K8S_MODULE_HELPER = True
k8s_import_exception = None
except ImportError as e:
HAS_K8S_MODULE_HELPER = False
k8s_import_exception = e
class KubernetesLookup(object):
def __init__(self):
if not HAS_K8S_MODULE_HELPER:
raise Exception(
"Requires the Kubernetes Python client. Try `pip install kubernetes`. Detail: {0}".format(
k8s_import_exception
)
)
self.kind = None
self.name = None
self.namespace = None
self.api_version = None
self.label_selector = None
self.field_selector = None
self.include_uninitialized = None
self.resource_definition = None
self.helper = None
self.connection = {}
def fail(self, msg=None):
raise AnsibleError(msg)
def run(self, terms, variables=None, **kwargs):
self.params = kwargs
self.client = get_api_client(**kwargs)
cluster_info = kwargs.get("cluster_info")
if cluster_info == "version":
return [self.client.client.version]
if cluster_info == "api_groups":
if isinstance(self.client.resources.api_groups, KeysView):
return [list(self.client.resources.api_groups)]
return [self.client.resources.api_groups]
self.kind = kwargs.get("kind")
self.name = kwargs.get("resource_name")
self.namespace = kwargs.get("namespace")
self.api_version = kwargs.get("api_version", "v1")
self.label_selector = kwargs.get("label_selector")
self.field_selector = kwargs.get("field_selector")
self.include_uninitialized = kwargs.get("include_uninitialized", False)
resource_definition = kwargs.get("resource_definition")
src = kwargs.get("src")
if src:
definitions = create_definitions(params=dict(src=src))
if definitions:
self.kind = definitions[0].kind
self.name = definitions[0].name
self.namespace = definitions[0].namespace
self.api_version = definitions[0].api_version or "v1"
if resource_definition:
self.kind = resource_definition.get("kind", self.kind)
self.api_version = resource_definition.get("apiVersion", self.api_version)
self.name = resource_definition.get("metadata", {}).get("name", self.name)
self.namespace = resource_definition.get("metadata", {}).get(
"namespace", self.namespace
)
if not self.kind:
raise AnsibleError(
"Error: no Kind specified. Use the 'kind' parameter, or provide an object YAML configuration "
"using the 'resource_definition' parameter."
)
resource = self.client.resource(self.kind, self.api_version)
try:
params = dict(
name=self.name,
namespace=self.namespace,
label_selector=self.label_selector,
field_selector=self.field_selector,
)
k8s_obj = self.client.get(resource, **params)
except NotFoundError:
return []
if self.name:
return [k8s_obj.to_dict()]
return k8s_obj.to_dict().get("items")
class LookupModule(LookupBase):
def _run(self, terms, variables=None, **kwargs):
return KubernetesLookup().run(terms, variables=variables, **kwargs)
run = _run if not hasattr(LookupBase, "run_on_daemon") else LookupBase.run_on_daemon