From 0bc99117af1c20e4e393bdc8673333e349482f64 Mon Sep 17 00:00:00 2001 From: Yuriy Novostavskiy Date: Fri, 14 Aug 2026 21:36:02 +0200 Subject: [PATCH] fix(meta): add missing modules to helm and k8s action groups, document them (#1216) * 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. Co-Authored-By: Bikouo Aubin <79859644+abikouo@users.noreply.github.com> --------- Co-authored-by: Bikouo Aubin <79859644+abikouo@users.noreply.github.com> --- .../fragments/20260812-action-groups.yaml | 3 + .../rst/kubernetes_scenarios/k8s_intro.rst | 86 ++++++++++ meta/runtime.yml | 8 + tests/unit/test_action_groups.py | 156 ++++++++++++++++++ 4 files changed, 253 insertions(+) create mode 100644 changelogs/fragments/20260812-action-groups.yaml create mode 100644 tests/unit/test_action_groups.py diff --git a/changelogs/fragments/20260812-action-groups.yaml b/changelogs/fragments/20260812-action-groups.yaml new file mode 100644 index 00000000..bba10ffe --- /dev/null +++ b/changelogs/fragments/20260812-action-groups.yaml @@ -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). diff --git a/docs/docsite/rst/kubernetes_scenarios/k8s_intro.rst b/docs/docsite/rst/kubernetes_scenarios/k8s_intro.rst index 00dfcb3f..490f0ef8 100644 --- a/docs/docsite/rst/kubernetes_scenarios/k8s_intro.rst +++ b/docs/docsite/rst/kubernetes_scenarios/k8s_intro.rst @@ -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 `_ +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 ================== diff --git a/meta/runtime.yml b/meta/runtime.yml index 6dce54a3..5732fb1f 100644 --- a/meta/runtime.yml +++ b/meta/runtime.yml @@ -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: diff --git a/tests/unit/test_action_groups.py b/tests/unit/test_action_groups.py new file mode 100644 index 00000000..bd5bb1be --- /dev/null +++ b/tests/unit/test_action_groups.py @@ -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) + )