Upgrade how hooks are defined

There's a need to add single hooks to a list of existing ones, depending
on the scenario we want to run.

Until now, this wasn't possible, since parameters override themselves
and only the last occurrence wins.

This patch introduces a notion of "single hook definition" using crafted
parameters names, consuming specific prefixes.

docs/source/usage/01_usage.md

@@ -71,7 +71,11 @@ The framework is able to leverage hooks located in various locations. Using
 proper parameter name, you may run arbitrary playbook or load custom CRDs at
 specific points in the standard run.
 
-Allowed parameter names are:
+Hooks may be presented in two ways:
+- as a list
+- as a single hook in a parameter
+
+If you want to list multiple hooks, you have to use the following parameter names:
 
 - `pre_infra`: before bootstrapping the infrastructure
 - `post_infra`: after bootstrapping the infrastructure
@@ -89,6 +93,13 @@ Allowed parameter names are:
 - `pre_reporting`: before running reporting
 - `post_reporting`: after running reporting
 
+Since we're already providing hooks as list, you may want to just add one or two hooks
+using your own environment file. Parameter structure is simple: `PREFIX_HOOKNAME: {hook struct}`
+
+PREFIX must match the above parameters (`pre_infra`, `post_reporting` and so on).
+
+The `{hook struct}` is the same as a listed hook, but you'll remove the `name` entry.
+
 Since steps may be skipped, we must ensure proper post/pre exists for specific
 steps.
 

playbooks/02-infra.yml

@@ -1,6 +1,5 @@
 - name: Run pre_infra hooks
   vars:
-    hooks: "{{ pre_infra | default([]) }}"
     step: pre_infra
   ansible.builtin.import_playbook: ./hooks.yml
 
@@ -87,6 +86,5 @@
 
 - name: Run post_infra hooks
   vars:
-    hooks: "{{ post_infra | default([]) }}"
     step: post_infra
   ansible.builtin.import_playbook: ./hooks.yml

playbooks/03-build-packages.yml

@@ -1,6 +1,5 @@
 - name: Run pre_package_build hooks
   vars:
-    hooks: "{{ pre_package_build | default([]) }}"
     step: pre_package_build
   ansible.builtin.import_playbook: ./hooks.yml
 
@@ -22,6 +21,5 @@
 
 - name: Run post_package_build hooks
   vars:
-    hooks: "{{ post_package_build | default([]) }}"
     step: post_package_build
   ansible.builtin.import_playbook: ./hooks.yml

playbooks/04-build-containers.yml

@@ -1,6 +1,5 @@
 - name: Run pre_container_build hooks
   vars:
-    hooks: "{{ pre_container_build | default([]) }}"
     step: pre_container_build
   ansible.builtin.import_playbook: ./hooks.yml
 
@@ -18,6 +17,5 @@
 
 - name: Run post_container_build hooks
   vars:
-    hooks: "{{ post_container_build | default([]) }}"
     step: post_container_build
   ansible.builtin.import_playbook: ./hooks.yml

playbooks/05-build-operators.yml

@@ -1,6 +1,5 @@
 - name: Run pre_operator_build hooks
   vars:
-    hooks: "{{ pre_operator_build | default([]) }}"
     step: pre_operator_build
   ansible.builtin.import_playbook: ./hooks.yml
 
@@ -23,6 +22,5 @@
 
 - name: Run post_operator_build hooks
   vars:
-    hooks: "{{ post_operator_build | default([]) }}"
     step: post_operator_build
   ansible.builtin.import_playbook: ./hooks.yml

playbooks/06-deploy-architecture.yml

@@ -1,7 +1,6 @@
 ---
 - name: Run pre_deploy hooks
   vars:
-    hooks: "{{ pre_deploy | default([]) }}"
     step: pre_deploy
   ansible.builtin.import_playbook: ./hooks.yml
 
@@ -119,6 +118,5 @@
 
 - name: Run post_deploy hooks
   vars:
-    hooks: "{{ post_deploy | default([]) }}"
     step: post_deploy
   ansible.builtin.import_playbook: ./hooks.yml

playbooks/06-deploy-edpm.yml

@@ -1,6 +1,5 @@
 - name: Run pre_deploy hooks
   vars:
-    hooks: "{{ pre_deploy | default([]) }}"
     step: pre_deploy
   ansible.builtin.import_playbook: ./hooks.yml
 
@@ -22,7 +21,6 @@
 
 - name: Run post_ctlplane_deploy hooks
   vars:
-    hooks: "{{ post_ctlplane_deploy | default([]) }}"
     step: post_ctlplane_deploy
   ansible.builtin.import_playbook: ./hooks.yml
 
@@ -107,6 +105,5 @@
 
 - name: Run post_deploy hooks
   vars:
-    hooks: "{{ post_deploy | default([]) }}"
     step: post_deploy
   ansible.builtin.import_playbook: ./hooks.yml

playbooks/07-admin-setup.yml

@@ -1,6 +1,5 @@
 - name: Run pre_admin_setup hooks
   vars:
-    hooks: "{{ pre_admin_setup | default([]) }}"
     step: pre_admin_setup
   ansible.builtin.import_playbook: ./hooks.yml
 
@@ -18,6 +17,5 @@
 
 - name: Run post_admin_setup hooks
   vars:
-    hooks: "{{ post_admin_setup | default([]) }}"
     step: post_admin_setup
   ansible.builtin.import_playbook: ./hooks.yml

playbooks/08-run-tests.yml

@@ -1,6 +1,5 @@
 - name: "Run pre_tests hooks"
   vars:
-    hooks: "{{ pre_tests | default([]) }}"
     step: pre_tests
   ansible.builtin.import_playbook: ./hooks.yml
 
@@ -16,6 +15,5 @@
 
 - name: "Run post_tests hooks"
   vars:
-    hooks: "{{ post_tests | default([]) }}"
     step: post_tests
   ansible.builtin.import_playbook: ./hooks.yml

playbooks/hooks.yml

@@ -1,10 +1,8 @@
+---
 - name: Hook playbook
   hosts: "{{ cifmw_target_host | default('localhost') }}"
   gather_facts: false
   tasks:
     - name: Run hook
-      when:
-        - hooks is defined
-        - hooks | length > 0
       ansible.builtin.import_role:
         name: run_hook

playbooks/update.yml

@@ -1,6 +1,5 @@
 - name: Run pre_update hooks
   vars:
-    hooks: "{{ pre_update | default([]) }}"
     step: pre_update
   ansible.builtin.import_playbook: ./hooks.yml
 
@@ -20,6 +19,5 @@
 
 - name: Run post_update hooks
   vars:
-    hooks: "{{ post_update | default([]) }}"
     step: post_update
   ansible.builtin.import_playbook: ./hooks.yml

roles/kustomize_deploy/tasks/execute_step.yml

@@ -44,7 +44,7 @@
         - stage.pre_stage_run is defined
       vars:
         hooks: "{{ stage.pre_stage_run }}"
-        step: "pre_stage_run_{{ stage_id }}"
+        step: "pre_stage_run"
       ansible.builtin.include_role:
         name: run_hook
 
@@ -188,6 +188,6 @@
         - stage.post_stage_run is defined
       vars:
         hooks: "{{ stage.post_stage_run }}"
-        step: "post_stage_run_{{ stage_id }}"
+        step: "post_stage_run"
       ansible.builtin.include_role:
         name: run_hook

roles/run_hook/README.md

@@ -9,10 +9,31 @@ play has a great chance of failure.
 
 ## Parameters
 * `hooks`: A list of hooks
+* `step`: (String) Prefix for the hooks you want to run. Mandatory.
+
+## Hook sorting
+
+The "name" is taken as a key to sort the various hooks in a selected step.
+
+In case of "single hook in its own parameter", the `name` is computed from the parameter
+name:
+
+* `pre_infra_01_my_hook` will end as `01 my hook`
+* `post_infra_my_hook` will end as `My hook`
 
 ## Hooks expected format
 ### Playbook
-In such a case, the following data can be provided to the hook:
+
+#### Single hook in its own parameter
+* `config_file`: (String) Ansible configuration file. Defaults to `ansible_config_file`.
+* `connection`: (String) Set the connection type for ansible. Defaults to `omit`.
+* `creates`: (String) Refer to the `ansible.builtin.command` "creates" parameter. Defaults to `omit`.
+* `inventory`: (String) Refer to the `--inventory` option for `ansible-playbook`. Defaults to `inventory_file`.
+* `source`: (String) Source of the playbook. If it's a filename, the playbook is expected in `hooks/playbooks`. It can be an absolute path.
+* `type`: (String) Type of the hook. In this case, set it to `playbook`.
+* `extra_vars`: (Dict) Structure listing the extra variables you want to pass down
+
+#### Multiple hooks in a list
 * `config_file`: (String) Ansible configuration file. Defaults to `ansible_config_file`.
 * `connection`: (String) Set the connection type for ansible. Defaults to `omit`.
 * `creates`: (String) Refer to the `ansible.builtin.command` "creates" parameter. Defaults to `omit`.
@@ -52,14 +73,30 @@ pre_deploy:
       type: playbook
       extra_vars:
         UUID: <some generated UUID>
+
+pre_infra_my_nice_hook:
+    source: noop.yml
+    type: playbook
 ```
 
 
 ### CRD
-In such a case, the following data can be provided to the hook:
+
+#### Single hook in its own parameter
+* `type`: (String) Type of the hook. In this case, set it to `crd`.
+* `source`: (String) Source of the CRD. If it's a filename, the CRD is expected in `hooks/crds`. It can be an absolute path.
+* `host`: (String) Cluster API endpoint. Defaults to `https://api.crc.testing:6443`.
+* `username`: (String) Username for authentication against the cluster. Defaults to `kubeadmin`.
+* `password`: (String) Password for authentication against the cluster. Defaults to `12345678`.
+* `state`: (String) State of the service. Can be `present` or `absent`. Defaults to `present`.
+* `validate_certs`: (Boolean) Whether to validate or not the cluster certificates.
+* `wait_condition`: (Dict) Wait condition for the service.
+
+#### Multiple hooks in a list
 * `type`: (String) Type of the hook. In this case, set it to `crd`.
 * `source`: (String) Source of the CRD. If it's a filename, the CRD is expected in `hooks/crds`. It can be an absolute path.
 * `host`: (String) Cluster API endpoint. Defaults to `https://api.crc.testing:6443`.
+* `name`: (String) Describe the hook.
 * `username`: (String) Username for authentication against the cluster. Defaults to `kubeadmin`.
 * `password`: (String) Password for authentication against the cluster. Defaults to `12345678`.
 * `state`: (String) State of the service. Can be `present` or `absent`. Defaults to `present`.

roles/run_hook/molecule/default/converge.yml

@@ -17,25 +17,84 @@
 
 - name: Converge
   hosts: all
-  vars:
-    ansible_user_dir: "{{ lookup('env', 'HOME') }}"
-    step: molecule
-    hooks:
-      - name: Default noop hook
-        source: noop.yml
-        type: playbook
-      - name: With extra-vars
-        source: /tmp/dummy.yml
-        type: playbook
-        extra_vars:
-          foo: bar
-          file: '/tmp/dummy-env.yml'
+  vars_files:
+    - ./resources/vars.yml
   tasks:
-    - name: Hook project provided noop.yml
+    - name: No hook
+      vars:
+        step: no_hook
+      ansible.builtin.include_role:
+        name: run_hook
+
+    - name: Ensure we do not have ceph_uuid
+      ansible.builtin.assert:
+        that:
+          - ceph_uuid is undefined
+
+    - name: Combined hooks
+      vars:
+        step: run_molecule
+      ansible.builtin.include_role:
+        name: run_hook
+
+    - name: Ensure we have the ceph_uuid variable now
+      ansible.builtin.assert:
+        that:
+          - ceph_uuid is defined
+          - ceph_uuid == 'dummy-1.yml'
+
+    - name: Only listed hooks
+      vars:
+        step: list_hooks
+      ansible.builtin.include_role:
+        name: run_hook
+
+    - name: Ensure we have the ceph_uuid variable now
+      ansible.builtin.assert:
+        that:
+          - ceph_uuid is defined
+          - ceph_uuid == 'dummy-3.yml'
+
+    - name: Only filtered hooks
+      vars:
+        step: filtered_hooks
+      ansible.builtin.include_role:
+        name: run_hook
+
+    - name: Ensure we have the ceph_uuid variable now
+      ansible.builtin.assert:
+        that:
+          - ceph_uuid is defined
+          - ceph_uuid == 'dummy-4.yml'
+
+    - name: Direct hooks
+      vars:
+        step: no_hook
+        hooks:
+          - name: Dummy-5
+            source: /tmp/dummy-5.yml
+            type: playbook
+            extra_vars:
+              foo: bar
+              file: '/tmp/dummy-env.yml'
+      ansible.builtin.include_role:
+        name: run_hook
+
+    - name: Ensure we have the ceph_uuid variable now
+      ansible.builtin.assert:
+        that:
+          - ceph_uuid is defined
+          - ceph_uuid == 'dummy-5.yml'
+
+    - name: Direct hooks as param
+      vars:
+        step: no_hook
+        hooks: "{{ my_hook }}"
       ansible.builtin.include_role:
         name: run_hook
 
     - name: Ensure we have the ceph_uuid variable now
       ansible.builtin.assert:
         that:
           - ceph_uuid is defined
+          - ceph_uuid == 'dummy-6.yml'