Feat/molecule-testing

.gitignore

@@ -8,6 +8,7 @@ playbooks/test.yml
 roles/test
 context/
 particle/.vagrant
+extensions/molecule/**/*.retry
 
 # mkdocs documentation
 /docs/CHANGELOG.md

CONTRIBUTING.md

@@ -704,6 +704,63 @@ Some files under `plugins/modules/` are not authored by Linuxfabrik but vendored
     * Drop when: LFOps raises its minimum ansible-core to >= 2.18; switch to `community.general.lvm_pv` and update `roles/lvm` accordingly.
 
 
+### Testing
+
+Molecule is used as the framework to test the LFOps playbooks (*not roles*). The test scenarios and configurations live in `extension/molecule` and are structured as follows:
+
+```
+extensions
+└── molecule
+    ├── apps -- test scenario, named after the playbook name
+    │   ├── install -- if needed, sub-scenario
+    │   │   ├── converge.yml
+    │   │   ├── inventory -- scenario-specific inventory with variables that are needed for the playbook under test and optionally additional hosts (e.g. for a cluster test setup). Overwrites the shared inventory (extensions/molecule/inventory)
+    │   │   │   ├── group_vars
+    │   │   │   │   └── systems_under_test.yml
+    │   │   │   └── hosts.yml
+    │   │   ├── molecule.yml -- scenario marker; required even if empty. Can also be used to overwrite, which playbooks are used by Molecule (e.g. to switch between VM and container provisioning playbooks)
+    │   │   └── verify.yml
+    │   └── remove -- additional sub-scenario
+    │       └── ...
+    ├── config.yml -- valid for all scenarios, can be overwritten in each scenario's molecule.yml (same content and structure)
+    ├── default -- we are not using the "default" scenario, but molecule needs this to run at all. could be used to share config (e.g. prepare.yml) across *all* scenarios
+    │   └── molecule.yml
+    ├── inventory -- shared inventory across all scenarios and therefore available in all scenarios. Contains a basic set of VMs/containers that are commonly used.
+    │   ├── hosts.yml -- Required, even if empty, that Ansible can detect this inventory
+    │   └── host_vars
+    │       ├── debian11-container.yml
+    │       ├── debian11-vm.yml
+    │       └── ...
+    ├── monitoring_plugins -- scenario with no sub-scenarios
+    │   ├── converge.yml
+    │   ├── inventory
+    │   │   └── ...
+    │   ├── molecule.yml
+    │   └── verify.yml
+    ├── playbooks -- shared playbooks used by Molecule for running the scenarios
+    │   ├── create-container.yml
+    │   ├── destroy-container.yml
+    │   └── ...
+    └── requirements.yml
+```
+
+Tests can be run against a subset of targets by providing them as a comma-separated list via the project-specific `LFOPS_TEST_TARGETS` environment variable:
+
+```shell
+# for VMs (the hypervisor host needs to be included as well; here `localhost`)
+LFOPS_TEST_TARGETS='localhost,rocky*' molecule test --scenario-name apps/install
+
+# for containers
+LFOPS_TEST_TARGETS='rocky*' molecule test --scenario-name apps/install
+```
+
+
+Known Limitations:
+
+* VM-based testing currently requires passwordless sudo on the Ansible controller.
+* Ansible Navigator does not work out of the box.
+
+
 ### Credits
 
 * <https://github.com/whitecloud/ansible-styleguide>

extensions/molecule/apps/install/converge.yml

@@ -0,0 +1,2 @@
+- name: 'Converge apps playbook'
+  ansible.builtin.import_playbook: 'linuxfabrik.lfops.apps'

extensions/molecule/apps/install/inventory/group_vars/systems_under_test.yml

@@ -0,0 +1,3 @@
+apps__apps__group_var:
+  - name: 'zsh'
+    state: 'present'

extensions/molecule/apps/install/inventory/hosts.yml

@@ -0,0 +1,15 @@
+lfops_apps:
+  children:
+    systems_under_test:
+
+systems_under_test:
+  hosts:
+    debian11-vm:
+    debian12-vm:
+    debian13-vm:
+    rocky8-vm:
+    rocky9-vm:
+    rocky10-vm:
+    ubuntu2004-vm:
+    ubuntu2204-vm:
+    ubuntu2404-vm:

extensions/molecule/apps/install/molecule.yml

@@ -0,0 +1 @@
+# Molecule scenario marker

extensions/molecule/apps/install/verify.yml

@@ -0,0 +1,11 @@
+- name: 'Verify apps are installed'
+  hosts: 'systems_under_test'
+  gather_facts: false
+  tasks:
+    - name: 'Gather the package facts'
+      ansible.builtin.package_facts:
+        manager: 'auto'
+
+    - name: 'Assert'
+      ansible.builtin.assert:
+        that: '"zsh" in ansible_facts.packages'

extensions/molecule/apps/remove/converge.yml

@@ -0,0 +1,2 @@
+- name: 'Converge apps playbook'
+  ansible.builtin.import_playbook: 'linuxfabrik.lfops.apps'

extensions/molecule/apps/remove/inventory/group_vars/systems_under_test.yml

@@ -0,0 +1,3 @@
+apps__apps__group_var:
+  - name: 'less'
+    state: 'absent'

extensions/molecule/apps/remove/inventory/hosts.yml

@@ -0,0 +1,15 @@
+lfops_apps:
+  children:
+    systems_under_test:
+
+systems_under_test:
+  hosts:
+    debian11-vm:
+    debian12-vm:
+    debian13-vm:
+    rocky8-vm:
+    rocky9-vm:
+    rocky10-vm:
+    ubuntu2004-vm:
+    ubuntu2204-vm:
+    ubuntu2404-vm:

extensions/molecule/apps/remove/molecule.yml

@@ -0,0 +1 @@
+# Molecule scenario marker

extensions/molecule/apps/remove/verify.yml

@@ -0,0 +1,11 @@
+- name: 'Verify apps are not installed'
+  hosts: 'systems_under_test'
+  gather_facts: true
+  tasks:
+    - name: 'Gather the package facts'
+      ansible.builtin.package_facts:
+        manager: 'auto'
+
+    - name: 'Assert'
+      ansible.builtin.assert:
+        that: '"less" not in ansible_facts.packages'

extensions/molecule/config.yml

@@ -0,0 +1,65 @@
+dependency:
+  name: 'galaxy'
+  options:
+    requirements-file: '${MOLECULE_PROJECT_DIRECTORY}/extensions/molecule/requirements.yml'
+
+ansible:
+  cfg:
+    defaults:
+      accelerate_timeout: 5
+      ansible_managed: 'This file is managed by Ansible - do not edit'
+      callbacks_enabled: 'profile_tasks'
+      fact_caching: 'jsonfile'
+      fact_caching_connection: '${MOLECULE_EPHEMERAL_DIRECTORY}/.ansible_cache'
+      fact_caching_timeout: 86400
+      forks: 30
+      gathering: 'smart'
+      host_key_checking: false
+      inventory: 'hosts'
+      nocows: 1
+      retry_files_enabled: true
+      timeout: 60
+      log_path: '${MOLECULE_EPHEMERAL_DIRECTORY}/ansible.log'
+      inventory_ignore_extensions:
+        - '~'
+        - '.orig'
+        - '.bak'
+        - '.ini'
+        - '.cfg'
+        - '.retry'
+        - '.pyc'
+        - '.pyo'
+        - '.csv'
+        - '.md'
+      inventory_ignore_patterns: '(host|group)_files'
+      stdout_callback: 'yaml'
+    ssh_connections:
+      pipelining: true
+      ssh_args: '-o ControlMaster=auto -o ControlPersist=60s'
+  executor:
+    backend: 'ansible-playbook' # or 'ansible-navigator'
+    args:
+      ansible_navigator:
+        - '--inventory=${MOLECULE_PROJECT_DIRECTORY}/extensions/molecule/inventory/'
+        - '--inventory=${MOLECULE_SCENARIO_DIRECTORY}/inventory/'
+        - '--limit=${LFOPS_TEST_TARGETS}'
+      ansible_playbook:
+        - '--inventory=${MOLECULE_PROJECT_DIRECTORY}/extensions/molecule/inventory/'
+        - '--inventory=${MOLECULE_SCENARIO_DIRECTORY}/inventory/'
+        - '--limit=${LFOPS_TEST_TARGETS}'
+
+provisioner:
+  playbooks:
+    create: '${MOLECULE_PROJECT_DIRECTORY}/extensions/molecule/playbooks/create-vm.yml'
+    destroy: '${MOLECULE_PROJECT_DIRECTORY}/extensions/molecule/playbooks/destroy-vm.yml'
+    prepare: '${MOLECULE_PROJECT_DIRECTORY}/extensions/molecule/playbooks/prepare-vm.yml'
+
+scenario:
+  test_sequence:
+    - 'create'
+    - 'prepare'
+    - 'converge'
+    - 'verify'
+    - 'idempotence'
+    - 'verify'
+    - 'destroy'

extensions/molecule/default/molecule.yml

@@ -0,0 +1 @@
+# Molecule scenario marker

extensions/molecule/inventory/host_vars/debian11-container.yml

@@ -0,0 +1,6 @@
+ansible_connection: 'containers.podman.podman'
+ansible_host: 'debian11-container'
+
+container_command: 'sleep 1d'
+container_image: 'docker.io/library/debian:11'
+container_privileged: false

extensions/molecule/inventory/host_vars/debian11-vm.yml

@@ -0,0 +1,17 @@
+ansible_connection: 'ssh'
+ansible_user: 'root'
+
+vm_image_url: 'https://cloud.debian.org/images/cloud/bullseye/latest/debian-11-genericcloud-amd64.qcow2'
+
+kvm_vm__autostart: false
+kvm_vm__base_image: 'debian-11-genericcloud-amd64.qcow2'
+kvm_vm__boot_disk_size: '20G'
+kvm_vm__host: 'localhost'
+kvm_vm__memory: 4096
+kvm_vm__network_connections:
+  - name: 'enp1s0'
+    network_name: 'default'
+    dhcp4: true
+kvm_vm__osinfo: 'debian11'
+kvm_vm__packages: []
+kvm_vm__vcpus: 2

extensions/molecule/inventory/host_vars/debian12-container.yml

@@ -0,0 +1,6 @@
+ansible_connection: 'containers.podman.podman'
+ansible_host: 'debian12-container'
+
+container_command: 'sleep 1d'
+container_image: 'docker.io/library/debian:12'
+container_privileged: false

extensions/molecule/inventory/host_vars/debian12-vm.yml

@@ -0,0 +1,17 @@
+ansible_connection: 'ssh'
+ansible_user: 'root'
+
+vm_image_url: 'https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2'
+
+kvm_vm__autostart: false
+kvm_vm__base_image: 'debian-12-genericcloud-amd64.qcow2'
+kvm_vm__boot_disk_size: '20G'
+kvm_vm__host: 'localhost'
+kvm_vm__memory: 4096
+kvm_vm__network_connections:
+  - name: 'enp1s0'
+    network_name: 'default'
+    dhcp4: true
+kvm_vm__osinfo: 'debian12'
+kvm_vm__packages: []
+kvm_vm__vcpus: 2

extensions/molecule/inventory/host_vars/debian13-container.yml

@@ -0,0 +1,6 @@
+ansible_connection: 'containers.podman.podman'
+ansible_host: 'debian13-container'
+
+container_command: 'sleep 1d'
+container_image: 'docker.io/library/debian:13'
+container_privileged: false

extensions/molecule/inventory/host_vars/debian13-vm.yml

@@ -0,0 +1,17 @@
+ansible_connection: 'ssh'
+ansible_user: 'root'
+
+vm_image_url: 'https://cloud.debian.org/images/cloud/trixie/latest/debian-13-genericcloud-amd64.qcow2'
+
+kvm_vm__autostart: false
+kvm_vm__base_image: 'debian-13-genericcloud-amd64.qcow2'
+kvm_vm__boot_disk_size: '20G'
+kvm_vm__host: 'localhost'
+kvm_vm__memory: 4096
+kvm_vm__network_connections:
+  - name: 'enp1s0'
+    network_name: 'default'
+    dhcp4: true
+kvm_vm__osinfo: 'debian13'
+kvm_vm__packages: []
+kvm_vm__vcpus: 2

extensions/molecule/inventory/host_vars/rocky10-container.yml

@@ -0,0 +1,7 @@
+ansible_connection: 'containers.podman.podman'
+ansible_host: 'rocky10-container'
+
+container_command: '/usr/sbin/init'
+container_image: 'docker.io/rockylinux/rockylinux:10-ubi-init'
+container_privileged: false
+container_systemd: true

extensions/molecule/inventory/host_vars/rocky10-vm.yml

@@ -0,0 +1,17 @@
+ansible_connection: 'ssh'
+ansible_user: 'root'
+
+vm_image_url: 'https://dl.rockylinux.org/pub/rocky/10/images/x86_64/Rocky-10-GenericCloud-Base.latest.x86_64.qcow2'
+
+kvm_vm__autostart: false
+kvm_vm__base_image: 'Rocky-10-GenericCloud-Base.latest.x86_64.qcow2'
+kvm_vm__boot_disk_size: '20G'
+kvm_vm__host: 'localhost'
+kvm_vm__memory: 4096
+kvm_vm__network_connections:
+  - name: 'enp1s0'
+    network_name: 'default'
+    dhcp4: true
+kvm_vm__osinfo: 'rocky10'
+kvm_vm__packages: []
+kvm_vm__vcpus: 2

extensions/molecule/inventory/host_vars/rocky8-container.yml

@@ -0,0 +1,7 @@
+ansible_connection: 'containers.podman.podman'
+ansible_host: 'rocky8-container'
+
+container_command: '/usr/sbin/init'
+container_image: 'docker.io/rockylinux/rockylinux:8-ubi-init'
+container_privileged: false
+container_systemd: true

extensions/molecule/inventory/host_vars/rocky8-vm.yml

@@ -0,0 +1,17 @@
+ansible_connection: 'ssh'
+ansible_user: 'root'
+
+vm_image_url: 'https://dl.rockylinux.org/pub/rocky/8/images/x86_64/Rocky-8-GenericCloud-Base.latest.x86_64.qcow2'
+
+kvm_vm__autostart: false
+kvm_vm__base_image: 'Rocky-8-GenericCloud-Base.latest.x86_64.qcow2'
+kvm_vm__boot_disk_size: '20G'
+kvm_vm__host: 'localhost'
+kvm_vm__memory: 4096
+kvm_vm__network_connections:
+  - name: 'enp1s0'
+    network_name: 'default'
+    dhcp4: true
+kvm_vm__osinfo: 'rocky8'
+kvm_vm__packages: []
+kvm_vm__vcpus: 2

extensions/molecule/inventory/host_vars/rocky9-container.yml

@@ -0,0 +1,7 @@
+ansible_connection: 'containers.podman.podman'
+ansible_host: 'rocky9-container'
+
+container_command: '/usr/sbin/init'
+container_image: 'docker.io/rockylinux/rockylinux:9-ubi-init'
+container_privileged: false
+container_systemd: true

extensions/molecule/inventory/host_vars/rocky9-vm.yml

@@ -0,0 +1,17 @@
+ansible_connection: 'ssh'
+ansible_user: 'root'
+
+vm_image_url: 'https://dl.rockylinux.org/pub/rocky/9/images/x86_64/Rocky-9-GenericCloud-Base.latest.x86_64.qcow2'
+
+kvm_vm__autostart: false
+kvm_vm__base_image: 'Rocky-9-GenericCloud-Base.latest.x86_64.qcow2'
+kvm_vm__boot_disk_size: '20G'
+kvm_vm__host: 'localhost'
+kvm_vm__memory: 4096
+kvm_vm__network_connections:
+  - name: 'enp1s0'
+    network_name: 'default'
+    dhcp4: true
+kvm_vm__osinfo: 'rocky9'
+kvm_vm__packages: []
+kvm_vm__vcpus: 2

extensions/molecule/inventory/host_vars/ubuntu2004-container.yml

@@ -0,0 +1,6 @@
+ansible_connection: 'containers.podman.podman'
+ansible_host: 'ubuntu2004-container'
+
+container_command: 'sleep 1d'
+container_image: 'docker.io/library/ubuntu:20.04'
+container_privileged: false

extensions/molecule/inventory/host_vars/ubuntu2004-vm.yml

@@ -0,0 +1,17 @@
+ansible_connection: 'ssh'
+ansible_user: 'root'
+
+vm_image_url: 'https://cloud-images.ubuntu.com/focal/current/focal-server-cloudimg-amd64.img'
+
+kvm_vm__autostart: false
+kvm_vm__base_image: 'focal-server-cloudimg-amd64.img'
+kvm_vm__boot_disk_size: '20G'
+kvm_vm__host: 'localhost'
+kvm_vm__memory: 4096
+kvm_vm__network_connections:
+  - name: 'enp1s0'
+    network_name: 'default'
+    dhcp4: true
+kvm_vm__osinfo: 'ubuntu20.04'
+kvm_vm__packages: []
+kvm_vm__vcpus: 2

extensions/molecule/inventory/host_vars/ubuntu2204-container.yml

@@ -0,0 +1,6 @@
+ansible_connection: 'containers.podman.podman'
+ansible_host: 'ubuntu2204-container'
+
+container_command: 'sleep 1d'
+container_image: 'docker.io/library/ubuntu:22.04'
+container_privileged: false