fix(meta): add missing modules to helm and k8s action groups, document them (#1216) (#1221)

* 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:
patchback[bot]
2026-09-10 17:24:42 +01:00
committed by GitHub
co-authored by Yuriy Novostavskiy Bikouo Aubin
parent 5c06a554a8
commit c3f7a453fd
4 changed files with 253 additions and 0 deletions
@@ -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
==================
+8
View File
@@ -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:
+156
View File
@@ -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)
)