Merge branch 'devel' into feature_parents_attribute

.github/workflows/label-issues.yaml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: "Label Issues."
-      uses: github/issue-labeler@v3.3
+      uses: github/issue-labeler@v3.4
       with:
         configuration-path: .github/labels-issues.yml
         include-title: 1

.github/workflows/release.yaml

@@ -99,16 +99,14 @@ jobs:
         run: antsibull-docs collection --use-current --squash-hierarchy --fail-on-error --dest-dir ./docs/ ${{env.NAMESPACE}}.${{env.COLLECTION_NAME}}
 
       - name: Create Pull Request for docs and changelog against devel branch
-        uses: peter-evans/create-pull-request@v5
+        uses: peter-evans/create-pull-request@v6
         with:
-          commit-message: Update Docs and Changelogs
-          committer: GitHub <[email protected]>
-          author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
+          commit-message: Update Docs and Changelogs upon Release
           signoff: false
           branch: changelogs-docs-update-devel
           base: devel
           delete-branch: true
-          title: '[Auto] Update changelogs and docs'
+          title: '[Auto] Update changelogs and docs upon release'
           body: |
             Changelogs and docs updated during *${{ steps.current_version.outputs.version }}* release.
           assignees: robin-checkmk
@@ -146,7 +144,7 @@ jobs:
             # Ansible Collection: ${{env.NAMESPACE}}.${{env.COLLECTION_NAME}}
 
             For information about this collection and how to install it, refer to the [README](https://github.com/Checkmk/ansible-collection-checkmk.general/blob/main/README.md).
-            
+
             For a detailed changelog, refer to the [CHANGELOG](https://github.com/Checkmk/ansible-collection-checkmk.general/blob/main/CHANGELOG.rst).
 
       - name: Publish Ansible Collection to the Galaxy

CONTRIBUTING.md

@@ -106,7 +106,7 @@ We urge you to run the following tests locally as applicable, so the turnaround
 ### Sanity
 
 [Ansible Sanity Tests](https://docs.ansible.com/ansible/latest/dev_guide/testing_sanity.html) enforce Ansible coding standards and requirements facilitating static code analysis. The `ansible-test` tool typically comes along with your Ansible installation (e.g. if you use the `requirements.txt` of this project).
-We recommend using the `--docker` option, so you get the best results, as that uses a Docker image crafted and maintained by the Ansible project.  
+We recommend using the `--docker` option, so you get the best results, as that uses a Docker image crafted and maintained by the Ansible project.
 **Caution**: By default, Docker containers cannot be run as an unprivileged user! Depending on your setup you need to allow your user to run containers, or run `ansible-test` with `sudo`. Keep in mind, that with the latter you are running in another environment and might need to take care of installing the Python requirements for Ansible.
 
 To run the tests locally, use the following command in the project root:
@@ -120,7 +120,7 @@ You can also run a subset by mentioning them as follows. See `ansible-test sanit
 ### Integration
 
 [Ansible Integration Tests](https://docs.ansible.com/ansible/latest/dev_guide/testing_integration.html) run test cases created by the maintainers of this project, to ensure the collection actually does what is intended. The `ansible-test` tool typically comes along with your Ansible installation (e.g. if you use the `requirements.txt` of this project).
-We strongly recommend using the `--docker` option, so you do not modify your local system with these tests.  
+We strongly recommend using the `--docker` option, so you do not modify your local system with these tests.
 **Caution**: By default, Docker containers cannot be run as an unprivileged user! Depending on your setup you need to allow your user to run containers, or run `ansible-test` with `sudo`. Keep in mind, that with the latter you are running in another environment and might need to take care of installing the Python requirements for Ansible.
 
 To run all tests locally, use the following command in the project root:
@@ -149,16 +149,20 @@ Releasing this collection is automated using GitHub Actions.
 Before running the action `Release Collection` against the `main` branch, the
 following needs to be done:
 
-1. Update the collection version in `galaxy.yml` and `requirements.yml`. Look for `version:`.
-2. Check the integration and molecule tests for up-to-date Checkmk versions.
+1. Create a pull request from `devel` into `main` with the following naming scheme: `Release X.Y.Z`.
+2. Choose and note which feature pull request you want to include in this release.
 3. Check the GitHub Workflows for [EOL Ansible and Python versions and add new releases](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix).
-4. Update the compatibility matrix in `SUPPORT.md` accordingly.
+4. The following tasks are automated in `scripts/release.sh`. Feel free to use the script, but double-check the result!
+    1. Update the collection version in `galaxy.yml` and `requirements.yml`. Look for the string `version:`.
+    2. Check the integration and molecule tests for up-to-date Checkmk versions and update if necessary.
+    3. Update the compatibility matrix in `SUPPORT.md` accordingly.
 5. Double check `changelogs/fragments` if all changes have a changelog.
 6. After all changes have been performed, merge them into the `main` branch.
 7. Release the collection by running the action `Release Collection` against the `main` branch.
 8. Merge the automatically created pull request into `devel` and then update the `main` branch from `devel`.
 
-Some of these steps can already be checked and done with `scripts/release.sh`. This is a work in progress and should be used carefully.
+Some of these steps can already be checked and done with `scripts/release.sh`.
+This is a work in progress and should be used carefully.
 You should definitely check the resulting changes thoroughly before committing.
 
 ## Code of Conduct

Makefile

@@ -2,18 +2,22 @@ SHELL=/bin/bash
 
 VERSION := $$(grep 'version:' galaxy.yml | cut -d ' ' -f 2)
 
+COLLECTION_ROOT="/home/vagrant/ansible_collections/checkmk/general"
+CONTAINER_BUILD_ROOT="$(COLLECTION_ROOT)/tests/container"
+CONTAINER_NAME="ansible-checkmk-test"
+
 help:
-	@echo "setup           - Run all setup target at once."
+	@echo "setup           				- Run all setup target at once."
 	@echo ""
-	@echo "setup-python    - Prepare the system for development with Python."
+	@echo "setup-python    				- Prepare the system for development with Python."
 	@echo ""
-	@echo "setup-kvm       - Install and enable KVM and prepare Vagrant."
+	@echo "setup-kvm       				- Install and enable KVM and prepare Vagrant."
 	@echo ""
-	@echo "kvm             - Only copy the correct Vagrantfile for use with KVM."
+	@echo "kvm             				- Only copy the correct Vagrantfile for use with KVM."
 	@echo ""
-	@echo "setup-vbox      - Copy the correct Vagrantfile for use with VirtualBox."
+	@echo "setup-vbox 	     			- Copy the correct Vagrantfile for use with VirtualBox."
 	@echo ""
-	@echo "vbox            - Copy the correct Vagrantfile for use with VirtualBox."
+	@echo "vbox 	           			- Copy the correct Vagrantfile for use with VirtualBox."
 	@echo ""
 	@echo "vm              - Create a virtual development environment."
 	@echo "molecule        - Create a virtual environment for molecule tests."
@@ -22,23 +26,34 @@ help:
 	@echo "vms-redhat 	   - Create a virtual environment with all RedHat family OSes."
 	@echo "vms-suse 	   - Create a virtual environment with all Suse family OSes."
 	@echo ""
-	@echo "clean           - Clean up several things"
-	@echo "clean-vm        - Clean up virtual development environment."
+	@echo "container       				- Create a customized container image for testing."
+	@echo ""
+	@echo "tests	       				- Run all available tests."
+	@echo "tests-sanity    				- Run sanity tests."
+	@echo "tests-integration    		- Run all integration tests."
+	@echo "tests-integration-custom		- Run all integration tests using a custom built image."
 	@echo ""
-	@echo "version         - Update collection version"
+	@echo "clean           				- Clean up several things"
+	@echo "clean-vm        				- Clean up virtual development environment."
+	@echo ""
+	@echo "version         				- Update collection version"
 	@echo ""
 	@echo "Publishing:"
 	@echo ""
-	@echo "  release       - Build, upload, publish, announce and tag a release"
-	@echo "  announce      - Announce the release"
-	@echo "  publish       - Make files available, update git and announce"
+	@echo "  release       				- Build, upload, publish, announce and tag a release"
+	@echo "  announce      				- Announce the release"
+	@echo "  publish       				- Make files available, update git and announce"
 	@echo ""
 
-release:
-
-publish:
+release: version
+	# gh workflow run release.yaml --ref main  # https://cli.github.com/manual/gh_workflow_run
 
 announce:
+	# See cma scripts announce
+
+version:
+	@newversion=$$(dialog --stdout --inputbox "New Version:" 0 0 "$(VERSION)") ; \
+	if [ -n "$$newversion" ] ; then ./scripts/release.sh -s "$(VERSION)" -t $$newversion ; fi
 
 setup: setup-python setup-kvm
 
@@ -66,9 +81,7 @@ setup-kvm: kvm
 		qemu-kvm \
 		libvirt-clients \
 		libvirt-daemon-system \
-		bridge-utils \
-		virtinst \
-		libguestfs-tools \
+		bridge-utils \--build-arg DL_PW=$$(cat .secret)
 		libvirt-daemon\
 		libvirt-dev \
 		libxslt-dev \
@@ -85,10 +98,6 @@ vbox:
 
 setup-vbox: vbox
 
-version:
-	@newversion=$$(dialog --stdout --inputbox "New Version:" 0 0 "$(VERSION)") ; \
-	if [ -n "$$newversion" ] ; then ./scripts/release.sh -s "$(VERSION)" -t $$newversion ; fi
-
 clean: clean-vm
 
 clean-vm:
@@ -114,3 +123,28 @@ vms-suse:
 
 vms-windows:
 	@vagrant up ansidows
+
+container: molecule
+	vagrant ssh molecule -c "\
+	docker build -t $(CONTAINER_NAME) $(CONTAINER_BUILD_ROOT) --build-arg DL_PW=$$(cat .secret) && \
+	docker save $(CONTAINER_NAME):latest > $(COLLECTION_ROOT)/$(CONTAINER_NAME)-latest-image.tar.gz"
+
+tests: tests-sanity tests-integration
+
+tests-sanity: vm
+	@vagrant ssh collection -c "\
+	cd $(COLLECTION_ROOT) && \
+	ansible-test sanity --docker"
+
+tests-integration: vm
+	@vagrant ssh collection -c "\
+	cd $(COLLECTION_ROOT) && \
+	ansible-test integration --docker"
+
+tests-integration-custom: vm container
+	@vagrant ssh collection -c "\
+	cd $(COLLECTION_ROOT) && \
+	docker load -i ansible-checkmk-test-latest-image.tar.gz && \
+	ansible-test integration --docker-privileged --python 3.10 --docker ansible-checkmk-test && \
+	ansible-test integration --docker-privileged --python 3.11 --docker ansible-checkmk-test && \
+	ansible-test integration --docker-privileged --python 3.12 --docker ansible-checkmk-test"

plugins/lookup/bakery.py

@@ -9,27 +9,71 @@
     name: bakery
     author: Max Sickora (@max-checkmk)
     version_added: "4.0.0"
+
     short_description: Get the bakery status of a Checkmk server
+
     description:
       - Returns the bakery status of a Checkmk server as a string, e.g. 'running'
+
     options:
+
       server_url:
         description: URL of the Checkmk server
         required: True
+        vars:
+          - name: ansible_lookup_checkmk_server_url
+        env:
+          - name: ANSIBLE_LOOKUP_CHECKMK_SERVER_URL
+        ini:
+          - section: checkmk_lookup
+            key: server_url
+
       site:
-        description: site name
+        description: Site name.
         required: True
+        vars:
+          - name: ansible_lookup_checkmk_site
+        env:
+          - name: ANSIBLE_LOOKUP_CHECKMK_SITE
+        ini:
+          - section: checkmk_lookup
+            key: site
+
       automation_user:
-        description: automation user for the REST API access
+        description: Automation user for the REST API access.
         required: True
+        vars:
+          - name: ansible_lookup_checkmk_automation_user
+        env:
+          - name: ANSIBLE_LOOKUP_CHECKMK_AUTOMATION_USER
+        ini:
+          - section: checkmk_lookup
+            key: automation_user
+
       automation_secret:
-        description: automation secret for the REST API access
+        description: Automation secret for the REST API access.
         required: True
+        vars:
+          - name: ansible_lookup_checkmk_automation_secret
+        env:
+          - name: ANSIBLE_LOOKUP_CHECKMK_AUTOMATION_SECRET
+        ini:
+          - section: checkmk_lookup
+            key: automation_secret
+
       validate_certs:
-        description: Wether or not to validate TLS certificates
+        description: Whether or not to validate TLS certificates.
         type: boolean
         required: False
         default: True
+        vars:
+          - name: ansible_lookup_checkmk_validate_certs
+        env:
+          - name: ANSIBLE_LOOKUP_CHECKMK_VALIDATE_CERTS
+        ini:
+          - section: checkmk_lookup
+            key: validate_certs
+
     notes:
       - Like all lookups, this runs on the Ansible controller and is unaffected by other keywords such as 'become'.
         If you need to use different permissions, you must change the command or run Ansible as another user.

plugins/lookup/folder.py

@@ -9,30 +9,80 @@
     name: folder
     author: Lars Getwan (@lgetwan)
     version_added: "3.3.0"
+
     short_description: Get folder attributes
+
     description:
       - Returns the attributes of a folder
+
     options:
+
       _terms:
         description: complete folder path using tilde as a delimiter
         required: True
+
       server_url:
         description: URL of the Checkmk server
         required: True
+        vars:
+          - name: ansible_lookup_checkmk_server_url
+        env:
+          - name: ANSIBLE_LOOKUP_CHECKMK_SERVER_URL
+        ini:
+          - section: checkmk_lookup
+            key: server_url
+
       site:
-        description: site name
+        description: Site name.
         required: True
+        vars:
+          - name: ansible_lookup_checkmk_site
+        env:
+          - name: ANSIBLE_LOOKUP_CHECKMK_SITE
+        ini:
+          - section: checkmk_lookup
+            key: site
+
       automation_user:
-        description: automation user for the REST API access
+        description: Automation user for the REST API access.
         required: True
+        vars:
+          - name: ansible_lookup_checkmk_automation_user
+        env:
+          - name: ANSIBLE_LOOKUP_CHECKMK_AUTOMATION_USER
+        ini:
+          - section: checkmk_lookup
+            key: automation_user
+
       automation_secret:
-        description: automation secret for the REST API access
+        description: Automation secret for the REST API access.
         required: True
+        vars:
+          - name: ansible_lookup_checkmk_automation_secret
+        env:
+          - name: ANSIBLE_LOOKUP_CHECKMK_AUTOMATION_SECRET
+        ini:
+          - section: checkmk_lookup
+            key: automation_secret
+
       validate_certs:
-        description: Wether or not to validate TLS certificates
+        description: Whether or not to validate TLS certificates.
         type: boolean
         required: False
         default: True
+        vars:
+          - name: ansible_lookup_checkmk_validate_certs
+        env:
+          - name: ANSIBLE_LOOKUP_CHECKMK_VALIDATE_CERTS
+        ini:
+          - section: checkmk_lookup
+            key: validate_certs
+
+    notes:
+      - Like all lookups, this runs on the Ansible controller and is unaffected by other keywords such as 'become'.
+        If you need to use different permissions, you must change the command or run Ansible as another user.
+      - Alternatively, you can use a shell/command task that runs against localhost and registers the result.
+      - The directory of the play is used as the current working directory.
 """
 
 EXAMPLES = """