Prepare release 3.2.0 (#746)

SUMMARY
Prepare version 3.2.0
ISSUE TYPE

New Version Pull Request

ADDITIONAL INFORMATION
The current version of a major Ansible (Ansible 10) includes a collection version 3.1.0, meaning that the minor version (i.e. Ansible 10.1) will pick versions from the stable-3 branch. Hence, a recent documentation update will not be in Ansible and Ansible documentation site/kubernetes.core collection chapter until a new minor version released from stable-3 branch.
This PR also includes changes in README.md and Makefile that were missed in 3.1.0

Reviewed-by: Mike Graves <mgraves@redhat.com>

.ansible-lint-ignore

@@ -0,0 +1,2 @@
+# no-changed-when is not requried for examples
+plugins/connection/kubectl.py no-changed-when

.github/workflows/integration-tests-kubevirt.yaml

@@ -0,0 +1,127 @@
+name: Integration tests Kubevirt
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+    branches:
+      - main
+      - stable-*
+
+jobs:
+  splitter:
+    continue-on-error: true
+    env:
+      kubernetes: "./kubernetes"
+      kubevirt: "./kubevirt"
+      py_version: 3.9
+    runs-on: ubuntu-latest
+    outputs:
+      test_targets: ${{ steps.splitter.outputs.kubevirt_targets }}
+    steps:
+      - name: Checkout kubernetes.core repository
+        uses: actions/checkout@v3
+        with:
+          path: ${{ env.kubernetes }}
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Checkout the kubevirt.core collection
+        uses: actions/checkout@v3
+        with:
+          repository: kubevirt/kubevirt.core
+          path: ${{ env.kubevirt }}
+
+      - name: "Set up Python ${{ env.py_version }}"
+        uses: actions/setup-python@v4
+        with:
+          python-version: "${{ env.py_version }}"
+
+      - name: List targets from kubevirt.core collection
+        id: splitter
+        run: python ${{ env.kubernetes }}/tools/kubevirt_list_targets.py ${{ env.kubevirt }}
+        shell: bash
+
+  integration:
+    if: ${{ needs.splitter.outputs.test_targets != '' }}
+    name: "integration-kubevirt-${{ matrix.test-target }}"
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    needs:
+      - splitter
+    env:
+      kubernetes: "./kubernetes"
+      kubevirt: "./kubevirt"
+      ansible_version: milestone
+      python_version: 3.12
+    strategy:
+      fail-fast: false
+      matrix:
+        test-target: ${{ fromJson(needs.splitter.outputs.test_targets) }}
+    steps:
+      - name: Checkout kubernetes.core repository
+        uses: actions/checkout@v4
+        with:
+          path: ${{ env.kubernetes }}
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Checkout kubevirt.core repository
+        uses: actions/checkout@v4
+        with:
+          repository: kubevirt/kubevirt.core
+          path: ${{ env.kubevirt }}
+          ref: main
+
+      # Install ansible
+      - name: Install ansible-core (${{ env.ansible_version }})
+        run: >-
+          python3 -m pip install
+          https://github.com/ansible/ansible/archive/${{ env.ansible_version }}.tar.gz
+          --disable-pip-version-check
+        shell: bash
+
+      - name: Build and install kubevirt.core collection
+        id: install-kubevirt
+        uses: ansible-network/github_actions/.github/actions/build_install_collection@main
+        with:
+          install_python_dependencies: true
+          source_path: ${{ env.kubevirt }}
+
+      - name: Build and install kubernetes.core collection
+        id: install-kubernetes
+        uses: ansible-network/github_actions/.github/actions/build_install_collection@main
+        with:
+          install_python_dependencies: true
+          source_path: ${{ env.kubernetes }}
+
+      - name: Install kind / kubectl
+        uses: helm/kind-action@v1.9.0
+        with:
+          version: v0.22.0
+          install_only: true
+
+      - name: Deploy kubevirt
+        run: >-
+          ${{ env.kubevirt }}/hack/e2e-setup.sh \
+            -v \
+            --configure-inotify-limits \
+            --configure-secondary-network \
+            --deploy-kubevirt \
+            --deploy-kubevirt-cdi \
+            --deploy-kubevirt-common-instancetypes \
+            --deploy-cnao \
+            --create-cluster \
+            --create-nad
+        env:
+          KIND: kind
+          KUBECTL: kubectl
+
+      - name: Run integration tests
+        uses: ansible-network/github_actions/.github/actions/ansible_test_integration@main
+        with:
+          collection_path: ${{ steps.install-kubevirt.outputs.collection_path }}
+          python_version: ${{ env.python_version }}
+          ansible_version: ${{ env.ansible_version }}
+          ansible_test_targets: ${{ matrix.test-target }}
+        env:
+          ANSIBLE_COLLECTIONS_PATHS: /home/runner/collections

CHANGELOG.rst

@@ -4,6 +4,19 @@ Kubernetes Collection Release Notes
 
 .. contents:: Topics
 
+v3.2.0
+======
+
+Release Summary
+---------------
+This release comes with documentation updates.
+
+Minor Changes
+-------------
+
+- inventory/k8s.py - Defer removal of k8s inventory plugin to version 6.0.0 (https://github.com/ansible-collections/kubernetes.core/pull/734).
+- connection/kubectl.py - Added an example of using the kubectl connection plugin to the documentation (https://github.com/ansible-collections/kubernetes.core/pull/741).
+
 v3.1.0
 ======
 

Makefile

@@ -1,5 +1,5 @@
 # Also needs to be updated in galaxy.yml
-VERSION = 3.0.0
+VERSION = 3.2.0
 
 TEST_ARGS ?= ""
 PYTHON_VERSION ?= `python -c 'import platform; print(".".join(platform.python_version_tuple()[0:2]))'`

README.md

@@ -93,7 +93,7 @@ You can also include it in a `requirements.yml` file and install it via `ansible
 ---
 collections:
   - name: kubernetes.core
-    version: 3.0.0
+    version: 3.2.0
 ```
 
 ### Installing the Kubernetes Python Library

changelogs/changelog.yaml

@@ -854,3 +854,14 @@ releases:
     - 652-fix-json-patch-action.yml
     - 654-helm-expand-user.yml
     release_date: '2024-05-16'
+  3.2.0:
+    changes:
+      minor_changes:
+      - inventory/k8s.py - Defer removal of k8s inventory plugin to version 6.0.0 (https://github.com/ansible-collections/kubernetes.core/pull/734).
+      - connection/kubectl.py - Added an example of using the kubectl connection plugin to the documentation (https://github.com/ansible-collections/kubernetes.core/pull/741).
+      release_summary: This release comes with documentation updates.
+    fragments:
+    - 20240530-defer-removal-and-ansible-core-support-update.yaml
+    - 20240601-doc-example-of-using-kubectl.yaml
+    - 3.2.0.yml
+    release_date: '2024-06-14'

changelogs/fragments/20240530-ansible-core-support-update.yaml

@@ -0,0 +1,3 @@
+---
+minor_changes:
+  - inventory/k8s.py - Defer removal of k8s inventory plugin to version 6.0.0 (https://github.com/ansible-collections/kubernetes.core/pull/734).

changelogs/fragments/inventory-update_removal_date.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - inventory/k8s.py - Defer removal of k8s inventory plugin to version 5.0 (https://github.com/ansible-collections/kubernetes.core/pull/723).

docs/kubernetes.core.k8s_inventory.rst

@@ -17,7 +17,7 @@ DEPRECATED
 ----------
 :Removed in collection release after 
 :Why: As discussed in https://github.com/ansible-collections/kubernetes.core/issues/31, we decided to
-remove the k8s inventory plugin in release 4.0.0.
+remove the k8s inventory plugin in release 6.0.0.
 
 :Alternative: Use :ref:`kubernetes.core.k8s_info <kubernetes.core.k8s_info_module>` and :ref:`ansible.builtin.add_host <ansible.builtin.add_host_module>` instead.
 
@@ -357,7 +357,7 @@ Status
 ------
 
 
-- This inventory will be removed in version 4.0.0. *[deprecated]*
+- This inventory will be removed in version 6.0.0. *[deprecated]*
 - For more information see `DEPRECATED`_.
 
 

docs/kubernetes.core.kubectl_connection.rst

@@ -365,6 +365,82 @@ Parameters
 
 
 
+Examples
+--------
+
+.. code-block:: yaml
+
+    - name: Run a command in a pod using local kubectl with kubeconfig file ~/.kube/config
+      hosts: localhost
+      gather_facts: no
+      vars:
+        ansible_connection: kubernetes.core.kubectl
+        ansible_kubectl_namespace: my-namespace
+        ansible_kubectl_pod: my-pod
+        ansible_kubectl_container: my-container
+      tasks:
+        # be aware that the command is executed as the user that started the container
+        # and requires python to be installed in the image
+        - name: Run a command in a pod
+          ansible.builtin.command: echo "Hello, World!"
+
+    - name: Run a command in a pod using local kubectl with inventory variables
+      # Example inventory:
+      # k8s:
+      #   hosts:
+      #     foo.example.com:
+      #       ansible_connection: kubernetes.core.kubectl
+      #       ansible_kubectl_kubeconfig: /root/.kube/foo.example.com.config
+      #       ansible_kubectl_pod: my-foo-pod
+      #       ansible_kubectl_container: my-foo-container
+      #       ansible_kubectl_namespace: my-foo-namespace
+      #     bar.example.com:
+      #       ansible_connection: kubernetes.core.kubectl
+      #       ansible_kubectl_kubeconfig: /root/.kube/bar.example.com.config
+      #       ansible_kubectl_pod: my-bar-pod
+      #       ansible_kubectl_container: my-bar-container
+      #       ansible_kubectl_namespace: my-bar-namespace
+      hosts: k8s
+      gather_facts: no
+      tasks:
+        # be aware that the command is executed as the user that started the container
+        # and requires python to be installed in the image
+        - name: Run a command in a pod
+          ansible.builtin.command: echo "Hello, World!"
+
+    - name: Run a command in a pod using dynamic inventory
+      hosts: localhost
+      gather_facts: no
+      vars:
+        kubeconfig: /root/.kube/config
+        namespace: my-namespace
+        my_app: my-app
+      tasks:
+        - name: Get My App pod info based on label
+          kubernetes.core.k8s_info:
+            kubeconfig: "{{ kubeconfig }}"
+            namespace: "{{ namespace }}"
+            kind: Pod
+            label_selectors: app.kubernetes.io/name = "{{ my_app }}"
+          register: my_app_pod
+
+        - name: Get My App pod name
+          ansible.builtin.set_fact:
+            my_app_pod_name: "{{ my_app_pod.resources[0].metadata.name }}"
+
+        - name: Add My App pod to inventory
+          ansible.builtin.add_host:
+            name: "{{ my_app_pod_name }}"
+            ansible_connection: kubernetes.core.kubectl
+            ansible_kubectl_kubeconfig: "{{ kubeconfig }}"
+            ansible_kubectl_pod: "{{ my_app_pod_name }}"
+            ansible_kubectl_namespace: "{{ namespace }}"
+
+        - name: Run a command in My App pod
+          # be aware that the command is executed as the user that started the container
+          # and requires python to be installed in the image
+          ansible.builtin.command: echo "Hello, World!"
+          delegate_to: "{{ my_app_pod_name }}"
 
 
 

galaxy.yml

@@ -25,7 +25,7 @@ tags:
   - openshift
   - okd
   - cluster
-version: 3.1.0
+version: 3.2.0
 build_ignore:
   - .DS_Store
   - "*.tar.gz"

meta/runtime.yml

@@ -22,10 +22,10 @@ plugin_routing:
       redirect: community.okd.openshift
     k8s:
       deprecation:
-        removal_version: 4.0.0
+        removal_version: 6.0.0
         warning_text: >-
           The k8s inventory plugin has been deprecated and
-          will be removed in release 4.0.0.
+          will be removed in release 6.0.0.
   modules:
     k8s_auth:
       redirect: community.okd.k8s_auth

plugins/connection/kubectl.py

@@ -181,6 +181,81 @@ DOCUMENTATION = r"""
         aliases: [ kubectl_verify_ssl ]
 """
 
+EXAMPLES = r"""
+
+- name: Run a command in a pod using local kubectl with kubeconfig file ~/.kube/config
+  hosts: localhost
+  gather_facts: no
+  vars:
+    ansible_connection: kubernetes.core.kubectl
+    ansible_kubectl_namespace: my-namespace
+    ansible_kubectl_pod: my-pod
+    ansible_kubectl_container: my-container
+  tasks:
+    # be aware that the command is executed as the user that started the container
+    # and requires python to be installed in the image
+    - name: Run a command in a pod
+      ansible.builtin.command: echo "Hello, World!"
+
+- name: Run a command in a pod using local kubectl with inventory variables
+  # Example inventory:
+  # k8s:
+  #   hosts:
+  #     foo.example.com:
+  #       ansible_connection: kubernetes.core.kubectl
+  #       ansible_kubectl_kubeconfig: /root/.kube/foo.example.com.config
+  #       ansible_kubectl_pod: my-foo-pod
+  #       ansible_kubectl_container: my-foo-container
+  #       ansible_kubectl_namespace: my-foo-namespace
+  #     bar.example.com:
+  #       ansible_connection: kubernetes.core.kubectl
+  #       ansible_kubectl_kubeconfig: /root/.kube/bar.example.com.config
+  #       ansible_kubectl_pod: my-bar-pod
+  #       ansible_kubectl_container: my-bar-container
+  #       ansible_kubectl_namespace: my-bar-namespace
+  hosts: k8s
+  gather_facts: no
+  tasks:
+    # be aware that the command is executed as the user that started the container
+    # and requires python to be installed in the image
+    - name: Run a command in a pod
+      ansible.builtin.command: echo "Hello, World!"
+
+- name: Run a command in a pod using dynamic inventory
+  hosts: localhost
+  gather_facts: no
+  vars:
+    kubeconfig: /root/.kube/config
+    namespace: my-namespace
+    my_app: my-app
+  tasks:
+    - name: Get My App pod info based on label
+      kubernetes.core.k8s_info:
+        kubeconfig: "{{ kubeconfig }}"
+        namespace: "{{ namespace }}"
+        kind: Pod
+        label_selectors: app.kubernetes.io/name = "{{ my_app }}"
+      register: my_app_pod
+
+    - name: Get My App pod name
+      ansible.builtin.set_fact:
+        my_app_pod_name: "{{ my_app_pod.resources[0].metadata.name }}"
+
+    - name: Add My App pod to inventory
+      ansible.builtin.add_host:
+        name: "{{ my_app_pod_name }}"
+        ansible_connection: kubernetes.core.kubectl
+        ansible_kubectl_kubeconfig: "{{ kubeconfig }}"
+        ansible_kubectl_pod: "{{ my_app_pod_name }}"
+        ansible_kubectl_namespace: "{{ namespace }}"
+
+    - name: Run a command in My App pod
+      # be aware that the command is executed as the user that started the container
+      # and requires python to be installed in the image
+      ansible.builtin.command: echo "Hello, World!"
+      delegate_to: "{{ my_app_pod_name }}"
+"""
+
 import json
 import os
 import os.path

plugins/inventory/k8s.py

@@ -20,10 +20,10 @@ DOCUMENTATION = """
       - Uses k8s.(yml|yaml) YAML configuration file to set parameter values.
 
     deprecated:
-      removed_in: 4.0.0
+      removed_in: 6.0.0
       why: |
         As discussed in U(https://github.com/ansible-collections/kubernetes.core/issues/31), we decided to
-        remove the k8s inventory plugin in release 4.0.0.
+        remove the k8s inventory plugin in release 6.0.0.
       alternative: "Use M(kubernetes.core.k8s_info) and M(ansible.builtin.add_host) instead."
 
     options:
@@ -164,8 +164,8 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
         super(InventoryModule, self).parse(inventory, loader, path)
 
         self.display.deprecated(
-            "The 'k8s' inventory plugin has been deprecated and will be removed in release 4.0.0",
+            "The 'k8s' inventory plugin has been deprecated and will be removed in release 6.0.0",
-            version="4.0.0",
+            version="6.0.0",
             collection_name="kubernetes.core",
         )
         cache_key = self._get_cache_prefix(path)

tools/kubevirt_list_targets.py

@@ -0,0 +1,22 @@
+import os
+import sys
+from pathlib import PosixPath
+
+
+def main():
+
+    src = sys.argv[1]
+    path = PosixPath(src) / PosixPath("tests/integration/targets/")
+
+    def _is_disable(path):
+        flags = ("unsupported", "disabled", "unstable", "hidden")
+        aliases_path = path / PosixPath("aliases")
+        return (aliases_path.exists() and any((d.startswith(flags) for d in aliases_path.read_text().split("\n"))))
+
+    targets = [i.stem for i in path.glob("*") if i.is_dir() and not _is_disable(i)]
+    with open(os.environ.get("GITHUB_OUTPUT"), "a", encoding="utf-8") as fw:
+        fw.write(f"kubevirt_targets={targets}\n")
+
+
+if __name__ == "__main__":
+    main()