Kubeconfig module improvement (#1123)

* Add kubeconfig module for managing Kubernetes config files

* Remove unnecessary requirement & Change version

* Move functions to module_utils

* Add unit tests

* Add kubeconfig module for managing Kubernetes config files

* Remove unnecessary requirement & Change version

* Move functions to module_utils

* Add unit tests

* Avoid linter errors

* Improve documentation clarity

* Redact sensitive kubeconfig information

* Imprvoe verbosity

* Move import statement for to_native to avoid linters check failure

* Fix linting error

* Add remove behavior

* Add tests for remove behavior

* Imporve documentation

* Add changelog

---------

Co-authored-by: Bianca Henderson <bianca@redhat.com>

tests/integration/targets/kubeconfig/tasks/main.yml

@@ -102,7 +102,7 @@
   assert:
     that:
       - update_result is changed
-      - update_result.kubeconfig.clusters[0].cluster.server == "https://updated.example.com:6443"
+      - update_result.kubeconfig.clusters | selectattr('name', 'equalto', test_cluster_name) | map(attribute='cluster') | map(attribute='server') | first == "https://updated.example.com:6443"
 
 # Test 5: Check mode
 - name: Test check mode
@@ -115,8 +115,72 @@
   check_mode: true
   register: check_mode_result
 
-- name: Verify check mode didn't write
+- name: Verify check mode reports change but does not write
   assert:
     that:
       - check_mode_result is changed
-      - check_mode_result.kubeconfig.clusters | length == 3 # Includes new cluster in output
+      - check_mode_result.kubeconfig.clusters | length == 3
+
+- name: Verify check mode cluster was not actually written to disk
+  kubernetes.core.kubeconfig:
+    path: "{{ test_config_path }}"
+  register: after_check_mode
+
+- name: Confirm check-mode-cluster is absent from disk
+  assert:
+    that:
+      - after_check_mode.kubeconfig.clusters | selectattr('name', 'equalto', 'check-mode-cluster') | list | length == 0
+
+# Test 6: Remove behavior
+- name: Remove cluster-2, user-2, and context-2
+  kubernetes.core.kubeconfig:
+    path: "{{ test_config_path }}"
+    clusters:
+      - name: cluster-2
+        behavior: remove
+    users:
+      - name: user-2
+        behavior: remove
+    contexts:
+      - name: context-2
+        behavior: remove
+  register: remove_result
+
+- name: Verify entries were removed
+  assert:
+    that:
+      - remove_result is changed
+      - remove_result.kubeconfig.clusters | selectattr('name', 'equalto', 'cluster-2') | list | length == 0
+      - remove_result.kubeconfig.users | selectattr('name', 'equalto', 'user-2') | list | length == 0
+      - remove_result.kubeconfig.contexts | selectattr('name', 'equalto', 'context-2') | list | length == 0
+
+# Test 7: Remove behavior is idempotent when entry does not exist
+- name: Remove already-absent entry
+  kubernetes.core.kubeconfig:
+    path: "{{ test_config_path }}"
+    clusters:
+      - name: cluster-2
+        behavior: remove
+  register: remove_idempotent_result
+
+- name: Verify no change when removing nonexistent entry
+  assert:
+    that:
+      - remove_idempotent_result is not changed
+
+# Test 8: Keep behavior protects existing entry
+- name: Attempt to overwrite protected cluster
+  kubernetes.core.kubeconfig:
+    path: "{{ test_config_path }}"
+    clusters:
+      - name: "{{ test_cluster_name }}"
+        behavior: keep
+        cluster:
+          server: https://should-not-apply.example.com:6443
+  register: keep_result
+
+- name: Verify keep behavior left existing entry unchanged
+  assert:
+    that:
+      - keep_result is not changed
+      - keep_result.kubeconfig.clusters | selectattr('name', 'equalto', test_cluster_name) | map(attribute='cluster') | map(attribute='server') | first == "https://updated.example.com:6443"

tests/unit/module_utils/test_kubeconfig.py

@@ -141,6 +141,39 @@ def test_merge_by_name_keep_behavior_preserves_existing():
     assert result[0]["cluster"]["server"] == "https://old.com"
 
 
+def test_merge_by_name_remove_behavior_removes_existing_entry():
+    existing = [{"name": "cluster-a", "cluster": {"server": "https://a.com"}}]
+    new = [{"name": "cluster-a", "behavior": "remove"}]
+    result = merge_by_name(existing, new)
+    assert result == []
+
+
+def test_merge_by_name_remove_behavior_only_removes_target_entry():
+    existing = [
+        {"name": "cluster-a", "cluster": {"server": "https://a.com"}},
+        {"name": "cluster-b", "cluster": {"server": "https://b.com"}},
+    ]
+    new = [{"name": "cluster-a", "behavior": "remove"}]
+    result = merge_by_name(existing, new)
+    assert len(result) == 1
+    assert result[0]["name"] == "cluster-b"
+
+
+def test_merge_by_name_remove_behavior_silently_skips_nonexistent_entry():
+    existing = [{"name": "cluster-a", "cluster": {"server": "https://a.com"}}]
+    new = [{"name": "cluster-nonexistent", "behavior": "remove"}]
+    result = merge_by_name(existing, new)
+    assert len(result) == 1
+    assert result[0]["name"] == "cluster-a"
+
+
+def test_merge_by_name_remove_behavior_on_empty_existing():
+    existing = []
+    new = [{"name": "cluster-a", "behavior": "remove"}]
+    result = merge_by_name(existing, new)
+    assert result == []
+
+
 def test_merge_by_name_behavior_key_not_in_output():
     existing = []
     new = [