mirror of
https://github.com/ansible-collections/kubernetes.core.git
synced 2026-11-21 22:50:20 +00:00
* 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. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * 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). Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * 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. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * 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 --------- Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
369 lines
15 KiB
Python
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
|