Files
kubernetes.core/plugins/lookup/k8s.py
T
8c0de50fb8 **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 031bc475fa)

Co-authored-by: Mandar Kulkarni <mandkulk@redhat.com>
2026-09-15 15:31:27 +01:00

351 lines
14 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 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,
)
from ansible_collections.kubernetes.core.plugins.module_utils.k8s.resource import (
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
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