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, 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>
This commit is contained in:
co-authored by
Bikouo Aubin
parent
c643719085
commit
0bc99117af
@@ -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
|
||||
==================
|
||||
|
||||
|
||||
Reference in New Issue
Block a user