mirror of
https://github.com/ansible-collections/kubernetes.core.git
synced 2026-11-21 22:50:20 +00:00
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>
351 lines
14 KiB
Python
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
|