Merge pull request #538 from Checkmk/devel

Release 4.3.0

.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"

README.md

@@ -8,7 +8,9 @@ Checkmk and keep your daily operations smooth and efficient.
 ## Here be dragons!
 
 This collection is provided AS IS and we cannot guarantee proper functionality.
+
 Additionally, there is no commercial support whatsoever!
+
 This is an open source endeavour, on which we want to collaborate with the community.
 
 [![Ansible Sanity Tests](https://github.com/Checkmk/ansible-collection-checkmk.general/actions/workflows/ansible-sanity-tests.yaml/badge.svg)](https://github.com/Checkmk/ansible-collection-checkmk.general/actions/workflows/ansible-sanity-tests.yaml)
@@ -42,6 +44,8 @@ Name | Description
 -->
 
 ### Lookup plugins
+Click on the lookup plugin name below, to get detailed documentation about it.
+For more in-depth documentation, see [this README](https://github.com/Checkmk/ansible-collection-checkmk.general/blob/main/plugins/lookup/README.md).
 
 Name | Description | Tests
 --- | --- | ---
@@ -57,6 +61,7 @@ Name | Description | Tests
 [checkmk.general.version](https://github.com/Checkmk/ansible-collection-checkmk.general/blob/main/plugins/lookup/version.py)|Look up version and edition information.|[![Integration Tests for Version Lookup Module](https://github.com/Checkmk/ansible-collection-checkmk.general/actions/workflows/ans-int-test-lkp-version.yaml/badge.svg)](https://github.com/Checkmk/ansible-collection-checkmk.general/actions/workflows/ans-int-test-lkp-version.yaml)
 
 ### Modules
+Click on the module name below, to get detailed documentation about it.
 
 Name | Description | Tests
 --- | --- | ---
@@ -74,6 +79,7 @@ Name | Description | Tests
 [checkmk.general.user](https://github.com/Checkmk/ansible-collection-checkmk.general/blob/main/plugins/modules/user.py)|Manage users.|[![Integration Tests for User Module](https://github.com/Checkmk/ansible-collection-checkmk.general/actions/workflows/ans-int-test-user.yaml/badge.svg)](https://github.com/Checkmk/ansible-collection-checkmk.general/actions/workflows/ans-int-test-user.yaml)
 
 ### Roles
+Click on the role name below, to get documentation about the role.
 
 Name | Description | Tests
 --- | --- | ---

SUPPORT.md

@@ -49,3 +49,4 @@ Collection Version | Checkmk Versions | Ansible Versions | Remarks
 4.0.1 | 2.0.0p39, 2.1.0p36, 2.2.0p16 | 2.14, 2.15, 2.16 | None
 4.1.0 | 2.0.0p39, 2.1.0p37, 2.2.0p17 | 2.14, 2.15, 2.16 | None
 4.2.0 | 2.0.0p39, 2.1.0p38, 2.2.0p19 | 2.14, 2.15, 2.16 | None
+4.3.0 | 2.0.0p39, 2.1.0p39, 2.2.0p22 | 2.14, 2.15, 2.16 | None

Vagrantfile.kvm

@@ -32,6 +32,7 @@ Vagrant.configure("2") do |config|
     apt-get -y install python3-pip ca-certificates curl gnupg lsb-release
     python3 -m pip install pip --upgrade
     python3 -m pip install -r /home/vagrant/ansible_collections/checkmk/general/requirements.txt
+    python3 -m pip install -r /home/vagrant/ansible_collections/checkmk/general/requirements-qa.txt
     sudo -u vagrant ansible-galaxy collection install -f -r /home/vagrant/ansible_collections/checkmk/general/requirements.yml
     mkdir -p /home/vagrant/ansible_collections/checkmk/general
     mkdir -p /etc/apt/keyrings
@@ -72,6 +73,7 @@ Vagrant.configure("2") do |config|
     apt-get -y install python3-pip ca-certificates curl gnupg lsb-release
     python3 -m pip install pip --upgrade
     python3 -m pip install -r /home/vagrant/ansible_collections/checkmk/general/requirements.txt
+    python3 -m pip install -r /home/vagrant/ansible_collections/checkmk/general/requirements-qa.txt
     python3 -m pip install molecule molecule-plugins[docker]
     sudo -u vagrant ansible-galaxy collection install -f -r /home/vagrant/ansible_collections/checkmk/general/requirements.yml
     mkdir -p /home/vagrant/ansible_collections/checkmk/general

Vagrantfile.vbox

@@ -24,6 +24,7 @@ Vagrant.configure("2") do |config|
     apt-get -y install python3-pip ca-certificates curl gnupg lsb-release
     python3 -m pip install pip --upgrade
     python3 -m pip install -r /vagrant/requirements.txt
+    python3 -m pip install -r /vagrant/requirements-qa.txt
     sudo -u vagrant ansible-galaxy collection install -f -r /vagrant/requirements.yml
     mkdir -p /home/vagrant/ansible_collections/checkmk/general
     mkdir -p /etc/apt/keyrings
@@ -55,6 +56,7 @@ Vagrant.configure("2") do |config|
     apt-get -y install python3-pip ca-certificates curl gnupg lsb-release
     python3 -m pip install pip --upgrade
     python3 -m pip install -r /vagrant/requirements.txt
+    python3 -m pip install -r /vagrant/requirements-qa.txt
     python3 -m pip install molecule molecule-plugins[docker]
     sudo -u vagrant ansible-galaxy collection install -f -r /vagrant/requirements.yml
     mkdir -p /home/vagrant/ansible_collections/checkmk/general

changelogs/fragments/fix_folder_module_idempotency.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - Folder module - Fix idempotency when using "attributes" parameter for creating a folder.

changelogs/fragments/folder.yml

@@ -0,0 +1,3 @@
+minor_changes:
+  - Folder module - Extend attribute management. Please refer to the module documentation
+    for more details.

changelogs/fragments/lookups.yml

@@ -0,0 +1,9 @@
+minor_changes:
+  - Lookup modules - Enable usage of ini files, environment and inventory variables
+    to configure basic settings for the lookup plugins, like e.g., the server_url or site
+    alongside the authentication options. Refer to the module documentation for details.
+
+known_issues:
+  - Lookup modules - When using inventory variables to configure e.g., the server_url,
+    it is not possible to assign other variables to these variables.
+    This is a limitation of Ansble itself.

changelogs/fragments/parents.yml

@@ -0,0 +1,5 @@
+bugfixes:
+  - Host module - Parents will be parsed properly now.
+    This means, that parents given as a string will now be parsed as a list of one.
+  - Folder module - Parents will be parsed properly now.
+    This means, that parents given as a string will now be parsed as a list of one.

changelogs/fragments/release_summary.yml

@@ -0,0 +1 @@
+release_summary: "Reworking the CI, enhancing code quality and improving modules."

changelogs/fragments/rule.yml

@@ -0,0 +1,4 @@
+minor_changes:
+  - Rule module - Introduce rule_id to uniquely identify rules.
+    This ID can be retrieved e.g., using the lookup plugin.
+    Refer to the module documentation for further details.

changelogs/fragments/user.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - User module - Fix bug, where an absent user was created, if 'reset_password' was used.

changelogs/template.yml

@@ -21,12 +21,20 @@
 # For changes that are not really scoped (for example, which affect a whole collection), use the following format:
 # - Description starting with an uppercase letter and ending with a dot at the very end. Multiple sentences are allowed.
 
+# Tipps:
+# You can write multi line changelogs like this:
+# - Module name - This is a very long and detailed
+#   changelog line, so we will split it into several
+#   lines, just like this.
+
 ## Possible keys:
 #
 # release_summary
 #     Adds a single line release summary to the changelog.
 # breaking_changes
-#     Changes that break existing playbooks or roles. This includes any change to existing behavior that forces users to update tasks. Displayed in both the changelogs and the Porting Guides.
+#     Changes that break existing playbooks or roles.
+#     This includes any change to existing behavior that forces users to update tasks.
+#     Displayed in both the changelogs and the Porting Guides.
 # major_changes
 #     Major changes to Ansible itself. Generally does not include module or plugin changes. Displayed in both the changelogs and the Porting Guides.
 # minor_changes

galaxy.yml

@@ -10,7 +10,7 @@ name: general
 
 # The version of the collection. Must be compatible with semantic versioning
 
-version: 4.2.0
+version: 4.3.0
 
 # The path to the Markdown (.md) readme file. This path is relative to the root of the collection
 readme: README.md

plugins/doc_fragments/common.py

@@ -7,7 +7,7 @@ class ModuleDocFragment(object):
     DOCUMENTATION = r"""
     options:
         server_url:
-            description: The base url of your Checkmk server.
+            description: The base url of your Checkmk server including the protocol.
             required: true
             type: str
         site: