mirror of
https://github.com/ansible-collections/kubernetes.core.git
synced 2026-11-21 14:48:37 +00:00
* fix(meta): add missing modules to helm and k8s action groups
`helm_plugin` and `helm_plugin_info` both build their argument spec from
`HELM_AUTH_ARG_SPEC`, and `k8s_taint` builds its own from `AUTH_ARG_SPEC`,
but none of the three were listed in the action groups. Anyone setting
`module_defaults` on `group/kubernetes.core.helm` or
`group/kubernetes.core.k8s` silently got no defaults for them.
Deliberately left out of the groups, since they do not accept the shared
authentication options and would make `module_defaults` fail for every
user of the group:
- `helm_pull` and `helm_template` take only `binary_path`
- `helm_registry_auth` takes `binary_path` plus its own required `host`,
which is an OCI registry URL rather than a Kubernetes API server
- `kubeconfig` writes a kubeconfig file locally and takes no cluster
connection options
Also documents both action groups in the scenario guide, including the
exclusions above and the distinction from the legacy `k8s` group that
ansible-core defines, which is a different group and does not cover this
collection's modules.
Closes #577
* test(meta): guard action group membership against argspec drift
The action groups in `meta/runtime.yml` were maintained by hand, so
`helm_plugin`, `helm_plugin_info` and `k8s_taint` were able to inherit the
shared authentication arg specs without anyone adding them to a group.
Nothing failed, users just silently got no `module_defaults`.
Asserts the invariant in both directions: a module belongs to a group if
and only if it builds its argument spec from that group's shared constant.
The reverse direction matters too, since a member that does not accept the
shared options makes `module_defaults` fail with "Unsupported parameters"
for every user of the group.
Membership is read statically with `ast`, so the test needs no imports and
runs without a cluster or the `kubernetes` package.
The four modules that are deliberately excluded are listed with their
reasons, so restoring one has to be a decision rather than an oversight.
* fix(tests): satisfy pylint disallowed-name and set an explicit license
ansible-test's pylint profile rejects `_` as a name, which the sanity job
flagged three times. Rather than renaming the throwaways, give the entries
in SHARED_ARG_SPECS named keys so there is nothing to discard when reading
them back.
The header was copied from a sibling test that carries Apache-2.0 because
it derives from kubernetes/kubernetes, so it named the wrong copyright
holder. It now names the author, and keeps Apache-2.0 deliberately: the
collection requirements allow code outside plugins/ that imports no
GPL-3.0-or-later code to use any GPL-3.0-compatible license, and this file
imports only ast, os, pytest and yaml, since it reads group membership
statically rather than importing the modules. A comment records that
reasoning so the constraint is visible if an import is ever added.
* fix(doc): update changelog fragment with the manintainer suggestion
* fix(doc): show helm group defaults in the action group example
abikouo asked for the module_defaults example to cover the helm action
group as well, with tasks that actually consume those defaults. Set
binary_path, kubeconfig and context on group/kubernetes.core.helm and
add helm_repository, helm and helm_info tasks that rely on them; the
namespace in the k8s tasks now matches the release namespace so the
playbook reads as one flow.
---------
(cherry picked from commit 0bc99117af)
Co-authored-by: Yuriy Novostavskiy <yuriy@novostavskiy.kyiv.ua>
Co-authored-by: Bikouo Aubin <79859644+abikouo@users.noreply.github.com>
This commit is contained in:
co-authored by
Yuriy Novostavskiy
Bikouo Aubin
parent
5c06a554a8
commit
c3f7a453fd
@@ -0,0 +1,3 @@
|
||||
---
|
||||
minor_changes:
|
||||
- meta - Add ``helm_plugin`` and ``helm_plugin_info`` to the ``helm`` action group, and ``k8s_taint`` to the ``k8s`` action group, so that ``module_defaults`` set on those groups applies to them (https://github.com/ansible-collections/kubernetes.core/pull/1216).
|
||||
@@ -42,6 +42,92 @@ Basic authentication is also supported using the ``username`` and ``password`` o
|
||||
|
||||
To disable SSL certificate verification, set ``verify_ssl`` to false.
|
||||
|
||||
Sharing options across tasks with action groups
|
||||
===============================================
|
||||
|
||||
Repeating the same authentication options on every task gets verbose quickly. The collection
|
||||
defines two `action groups <https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_module_defaults.html#module-defaults-groups>`_
|
||||
so you can set them once with ``module_defaults``:
|
||||
|
||||
``kubernetes.core.k8s``
|
||||
Modules that talk to the Kubernetes API and accept the standard authentication options
|
||||
(``kubeconfig``, ``context``, ``host``, ``api_key``, ``validate_certs``, and so on):
|
||||
``k8s``, ``k8s_cluster_info``, ``k8s_cp``, ``k8s_drain``, ``k8s_exec``, ``k8s_info``,
|
||||
``k8s_json_patch``, ``k8s_log``, ``k8s_rollback``, ``k8s_scale``, ``k8s_service``, and
|
||||
``k8s_taint``.
|
||||
|
||||
``kubernetes.core.helm``
|
||||
Modules that shell out to the ``helm`` binary and accept its shared authentication
|
||||
options (``binary_path``, ``kubeconfig``, ``context``, ``host``, ``api_key``,
|
||||
``ca_cert``, ``validate_certs``): ``helm``, ``helm_info``, ``helm_plugin``,
|
||||
``helm_plugin_info``, and ``helm_repository``.
|
||||
|
||||
Prefix the group name with ``group/`` to use it:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
- hosts: localhost
|
||||
module_defaults:
|
||||
group/kubernetes.core.k8s:
|
||||
kubeconfig: /path/to/kubeconfig
|
||||
context: staging
|
||||
group/kubernetes.core.helm:
|
||||
binary_path: /path/to/helm
|
||||
kubeconfig: /path/to/kubeconfig
|
||||
context: staging
|
||||
tasks:
|
||||
- name: Create a namespace
|
||||
kubernetes.core.k8s:
|
||||
definition:
|
||||
apiVersion: v1
|
||||
kind: Namespace
|
||||
metadata:
|
||||
name: monitoring
|
||||
|
||||
- name: Read it back
|
||||
kubernetes.core.k8s_info:
|
||||
kind: Namespace
|
||||
name: monitoring
|
||||
|
||||
- name: Add the prometheus chart repository
|
||||
kubernetes.core.helm_repository:
|
||||
name: prometheus-community
|
||||
repo_url: https://prometheus-community.github.io/helm-charts
|
||||
|
||||
- name: Deploy the kube-prometheus-stack chart
|
||||
kubernetes.core.helm:
|
||||
name: kube-prometheus-stack
|
||||
chart_ref: prometheus-community/kube-prometheus-stack
|
||||
release_namespace: monitoring
|
||||
|
||||
- name: Collect the releases in that namespace
|
||||
kubernetes.core.helm_info:
|
||||
name: kube-prometheus-stack
|
||||
release_namespace: monitoring
|
||||
|
||||
Every task picks up ``kubeconfig`` and ``context`` from its group without repeating them, the
|
||||
``helm`` modules additionally pick up ``binary_path``, and an option set on an individual task
|
||||
still wins over the group default.
|
||||
|
||||
.. note::
|
||||
|
||||
Always write the group name fully qualified as ``group/kubernetes.core.k8s``. A bare
|
||||
``group/k8s`` refers to the legacy ``k8s`` group that ansible-core defined back when the
|
||||
Kubernetes modules shipped in core itself. The two are not the same group, and the legacy
|
||||
one does not cover the modules in this collection.
|
||||
|
||||
Some modules are deliberately **not** in these groups because they do not accept the shared
|
||||
authentication options, and including them would make ``module_defaults`` fail for everyone
|
||||
using the group:
|
||||
|
||||
- ``helm_pull`` and ``helm_template`` accept only ``binary_path``.
|
||||
- ``helm_registry_auth`` accepts ``binary_path`` and its own ``host``, which is an OCI
|
||||
registry URL rather than a Kubernetes API server.
|
||||
- ``kubeconfig`` writes a kubeconfig file locally and takes no cluster connection options.
|
||||
|
||||
Pass options to those modules directly, or give them their own per-module ``module_defaults``
|
||||
entry.
|
||||
|
||||
Reporting an issue
|
||||
==================
|
||||
|
||||
|
||||
@@ -1,10 +1,17 @@
|
||||
---
|
||||
requires_ansible: '>=2.16.0'
|
||||
|
||||
# Only modules that accept the shared authentication options belong in these
|
||||
# groups: HELM_AUTH_ARG_SPEC for helm, AUTH_ARG_SPEC for k8s. Adding a module
|
||||
# that does not accept them makes module_defaults fail for every user of the
|
||||
# group. This excludes helm_pull, helm_registry_auth, helm_template and
|
||||
# kubeconfig, which only take a subset (or none) of those options.
|
||||
action_groups:
|
||||
helm:
|
||||
- helm
|
||||
- helm_info
|
||||
- helm_plugin
|
||||
- helm_plugin_info
|
||||
- helm_repository
|
||||
k8s:
|
||||
- k8s
|
||||
@@ -18,6 +25,7 @@ action_groups:
|
||||
- k8s_rollback
|
||||
- k8s_scale
|
||||
- k8s_service
|
||||
- k8s_taint
|
||||
|
||||
plugin_routing:
|
||||
inventory:
|
||||
|
||||
@@ -0,0 +1,156 @@
|
||||
# Copyright (c) 2026 Yuriy Novostavskiy
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
# implied. See the License for the specific language governing
|
||||
# permissions and limitations under the License.
|
||||
#
|
||||
# This file is licensed permissively rather than under the collection's
|
||||
# GPL-3.0-or-later because it lives outside plugins/ and imports no
|
||||
# GPL-licensed code: membership is read statically with ast, so nothing from
|
||||
# ansible-core or plugins/ is imported. See the collection requirements,
|
||||
# "Licensing" section.
|
||||
|
||||
# Guards the action groups declared in meta/runtime.yml.
|
||||
#
|
||||
# A module belongs in an action group if and only if it accepts that group's
|
||||
# shared authentication options, because module_defaults set on a group is
|
||||
# applied to every member. A member that does not accept the options fails with
|
||||
# "Unsupported parameters"; a non-member that does accept them silently ignores
|
||||
# the defaults the user set. Both directions are bugs, so both are asserted.
|
||||
#
|
||||
# Membership is derived from whether a module builds its argument spec from the
|
||||
# shared constant, which is how every module in the collection does it today.
|
||||
|
||||
import ast
|
||||
import os
|
||||
|
||||
import pytest
|
||||
import yaml
|
||||
|
||||
COLLECTION_ROOT = os.path.dirname(
|
||||
os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
)
|
||||
MODULES_DIR = os.path.join(COLLECTION_ROOT, "plugins", "modules")
|
||||
RUNTIME_YML = os.path.join(COLLECTION_ROOT, "meta", "runtime.yml")
|
||||
|
||||
# action group -> the module_utils file defining its shared spec, and the constant name
|
||||
SHARED_ARG_SPECS = {
|
||||
"k8s": {"module_utils": "args_common", "constant": "AUTH_ARG_SPEC"},
|
||||
"helm": {"module_utils": "helm_args_common", "constant": "HELM_AUTH_ARG_SPEC"},
|
||||
}
|
||||
|
||||
# Modules that intentionally stay out of the groups, with the reason. Listed
|
||||
# explicitly so that adding one back is a deliberate decision rather than an
|
||||
# oversight. See https://github.com/ansible-collections/kubernetes.core/issues/577
|
||||
EXCLUDED_FROM_GROUPS = {
|
||||
"helm_pull": "accepts only binary_path, not the shared helm auth options",
|
||||
"helm_template": "accepts only binary_path, not the shared helm auth options",
|
||||
"helm_registry_auth": "its 'host' is an OCI registry URL, not a Kubernetes API server",
|
||||
"kubeconfig": "writes a kubeconfig file locally, takes no cluster connection options",
|
||||
}
|
||||
|
||||
|
||||
def _module_names():
|
||||
return sorted(
|
||||
name[:-3]
|
||||
for name in os.listdir(MODULES_DIR)
|
||||
if name.endswith(".py") and name != "__init__.py"
|
||||
)
|
||||
|
||||
|
||||
def _shared_specs_used_by(module_name):
|
||||
"""Return the shared arg-spec constants a module imports."""
|
||||
path = os.path.join(MODULES_DIR, module_name + ".py")
|
||||
with open(path, "rb") as handle:
|
||||
tree = ast.parse(handle.read(), filename=path)
|
||||
|
||||
group_of_constant = {
|
||||
spec["constant"]: group for group, spec in SHARED_ARG_SPECS.items()
|
||||
}
|
||||
modules_of_interest = {spec["module_utils"] for spec in SHARED_ARG_SPECS.values()}
|
||||
|
||||
used = set()
|
||||
for node in ast.walk(tree):
|
||||
if not isinstance(node, ast.ImportFrom) or not node.module:
|
||||
continue
|
||||
if node.module.rsplit(".", 1)[-1] not in modules_of_interest:
|
||||
continue
|
||||
for alias in node.names:
|
||||
if alias.name in group_of_constant:
|
||||
used.add(group_of_constant[alias.name])
|
||||
return used
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def action_groups():
|
||||
with open(RUNTIME_YML) as handle:
|
||||
return yaml.safe_load(handle)["action_groups"]
|
||||
|
||||
|
||||
def test_runtime_declares_expected_action_groups(action_groups):
|
||||
assert set(action_groups) == set(SHARED_ARG_SPECS), (
|
||||
"meta/runtime.yml declares action groups this test does not know about. "
|
||||
"Add the new group and its shared arg-spec constant to SHARED_ARG_SPECS."
|
||||
)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("group", sorted(SHARED_ARG_SPECS))
|
||||
def test_action_group_members_exist(action_groups, group):
|
||||
known = set(_module_names())
|
||||
missing = sorted(set(action_groups[group]) - known)
|
||||
assert not missing, (
|
||||
"meta/runtime.yml lists modules in the '%s' action group that do not exist "
|
||||
"under plugins/modules/: %s" % (group, ", ".join(missing))
|
||||
)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("group", sorted(SHARED_ARG_SPECS))
|
||||
def test_action_group_matches_shared_arg_spec_users(action_groups, group):
|
||||
constant = SHARED_ARG_SPECS[group]["constant"]
|
||||
declared = set(action_groups[group])
|
||||
actual = {name for name in _module_names() if group in _shared_specs_used_by(name)}
|
||||
|
||||
missing_from_group = sorted(actual - declared)
|
||||
assert not missing_from_group, (
|
||||
"%s build their argument spec from %s but are not listed in the '%s' action "
|
||||
"group, so module_defaults set on that group silently does not reach them. "
|
||||
"Add them to meta/runtime.yml."
|
||||
% (", ".join(missing_from_group), constant, group)
|
||||
)
|
||||
|
||||
not_shared = sorted(declared - actual)
|
||||
assert not not_shared, (
|
||||
"%s are listed in the '%s' action group but do not build their argument spec "
|
||||
"from %s, so module_defaults set on that group will fail for them with "
|
||||
"'Unsupported parameters'. Remove them from meta/runtime.yml."
|
||||
% (", ".join(not_shared), group, constant)
|
||||
)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("module_name,reason", sorted(EXCLUDED_FROM_GROUPS.items()))
|
||||
def test_excluded_modules_stay_out_of_action_groups(action_groups, module_name, reason):
|
||||
assert module_name in _module_names(), (
|
||||
"%s is listed in EXCLUDED_FROM_GROUPS but no longer exists; drop the entry."
|
||||
% module_name
|
||||
)
|
||||
|
||||
for group, members in action_groups.items():
|
||||
assert module_name not in members, (
|
||||
"%s was added to the '%s' action group, but it %s. If it now accepts the "
|
||||
"group's shared authentication options, remove it from EXCLUDED_FROM_GROUPS "
|
||||
"in this test as well." % (module_name, group, reason)
|
||||
)
|
||||
|
||||
assert not _shared_specs_used_by(module_name), (
|
||||
"%s now builds its argument spec from a shared auth spec, so the reason it was "
|
||||
"excluded (%s) no longer holds. Add it to the matching action group and remove "
|
||||
"it from EXCLUDED_FROM_GROUPS." % (module_name, reason)
|
||||
)
|
||||
Reference in New Issue
Block a user