DTT1 - Iteration 3 - Test module - Module documentation

[QU3B1M]

Epic #4848

Description

This issue aims to generate usage and technical documentation for the module

Tasks

• Usage documentation
• Technical documentation (including class/flow diagrams)

[pro-akim]

Testing Module

User documentation

The test module runs tests on the different components of Wazuh.
It is designed so that you can perform installations, actions on components and uninstallations, performing validations at each step.
This module must receive allocated and provisioned infrastructure. (From Allocation and Provision modules)

This module can be executed as follows:
A. Installing and using Workflow engine
B. Direct execution

A. Installing and using Workflow engine

The execution of the workflow is done through the installation of its library.

Initially, Python libraries must be installed. we recommended the use of virtual environments. Follow the technical documentation at https://docs.python.org/3/library/venv.html.

1. Create the python environment:

   python3 -m venv {environment_name}

2. Activate the environment:

    source {venv directory}/bin/activate

3. Clone the wazuh-qa repository:

   Navigate to the project directory and switch to the project branch:

   https://github.com/wazuh/wazuh-qa.git
   cd wazuh-qa
   git checkout {project-branch}

4. Install requirements:

   pip3 install -r deployability/deps/requirements.txt

5. Install the Workflow engine library and its launcher:

   While in wazuh-qa:

   cd modules
   pip3 uninstall -y workflow_engine && pip3 install .

Run the module by doing the following steps:

6. Test fixture to execute:

   It will be necessary to create a fixture (YAML file) where the infrastructure, provisioning, and tests to be executed will be declared.

   Note: It is possible to find some fixture examples in 'deployability/modules/workflow_engine/examples/'

   Example:

   version: 0.1
   description: This workflow is used to test agents deployment por DDT1 PoC
   variables:
     agents-os:
       - linux-ubuntu-22.04-amd64
     manager-os: 
       - linux-redhat-8-amd64
     infra-provider: vagrant
     working-dir: /tmp/dtt1-poc
   
   tasks:
     # Generic agent test task
     - task: "run-agent-tests"
       description: "Run tests install for the agent."
       do:
         this: process
         with:
           path: python3
           args:
             - modules/testing/main.py
             - targets:
               - wazuh-1: "{working-dir}/manager-linux-ubuntu-22.04-amd64/inventory.yaml"
               - agent-1: "{working-dir}/agent-linux-redhat-8-amd64/inventory.yaml"
             - tests: "install,registration,restart,stop,uninstall"
             - component: "agent"
             - wazuh-version: "4.7.1"
             - wazuh-revision: "40709"
             - live: "True"
       depends-on:
         - "allocate-{agent}"
         - "allocate-manager"
   
     # Unique manager allocate task
     - task: "allocate-manager"
       description: "Allocate resources for the manager."
       do:
         this: process
         with:
           path: python3
           args:
             - modules/allocation/main.py
             - action: create
             - provider: "{infra-provider}"
             - size: large
             - composite-name: "{manager-os}"
             - inventory-output: "{working-dir}/manager-{manager-os}/inventory.yaml"
             - track-output: "{working-dir}/manager-{manager-os}/track.yaml"
       cleanup:
         this: process
         with:
           path: python3
           args:
             - modules/allocation/main.py
             - action: delete
             - track-output: "{working-dir}/manager-{manager-os}/track.yaml"
   
     # Generic agent allocate task
     - task: "allocate-{agent}"
       description: "Allocate resources for the {agent} agent."
       do:
         this: process
         with:
           path: python3
           args:
             - modules/allocation/main.py
             - action: create
             - provider: "{infra-provider}"
             - size: small
             - composite-name: "{agent}"
             - inventory-output: "{working-dir}/agent-{agent}/inventory.yaml"
             - track-output: "{working-dir}/agent-{agent}/track.yaml"
       cleanup:
         this: process
         with:
           path: python3
           args:
             - modules/allocation/main.py
             - action: delete
             - track-output: "{working-dir}/agent-{agent}/track.yaml"
       foreach:
         - variable: agents-os
           as: agent

   Following the schema of the example:

   Configure the following parameters depending on your test case:

   variables/agent-os
   variables/manager-os
   infra-provider
   working-dir
   tasks

   Pay attention to the tasks:

   args
   depends-on

   Note: In args, configure the launcher's path correctly (main.py files in each module), and to fill depends-on, consider the steps of your test (allocation, provision, and test)

7. Command execution (local):

   Execute the command by referencing the parameters required by the library (launcher).

   python3 -m workflow_engine {.yaml fixture path} 

   Example

   python3 -m workflow_engine modules/workflow_engine/examples/dtt1-agents-poc.yaml

B. Direct execution

To execute the testing module without installing the Workflow engine, it can be done by using the launcher ('module/testing/main.py'):

1. Execution

While in 'wazuh-qa/deployability'

python3  modules/testing/main.py --wazuh-revision '{{ wazuh_revision }}' --wazuh-version '{{ wazuh_version }}' --component {{ component }} --tests 'install,restart,stop,uninstall' --targets '{"wazuh-1":"{{ inventory }}"}' --targets '{"wazuh-2":"{{ inventory }}"}' --live 'True'

Examples:

python3  modules/testing/main.py --wazuh-revision '40714' --wazuh-version '4.7.3' --component 'manager' --tests 'install,restart,stop,uninstall' --targets '{"wazuh-1":"/tmp/dtt1-poc/manager-linux-ubuntu-22.04-amd64/inventory.yml"}' --targets '{"wazuh-2":"/tmp/dtt1-poc/manager-linux-redhat-8-amd64/inventory.yml"}' --live 'True'

python3  modules/testing/main.py --wazuh-revision '40714' --wazuh-version '4.7.3' --component 'agent' --tests 'install,registration,restart,stop,uninstall' --targets '{"wazuh-1":"/tmp/dtt1-poc/manager-linux-ubuntu-22.04-amd64/inventory.yml"}' --targets '{"agent-1":"/tmp/dtt1-poc/agent-linux-redhat-8-amd64/inventory.yml"}' --targets '{"agent-2":"/tmp/dtt1-poc/agent-linux-redhat-9-amd64/inventory.yml"}' --targets '{"agent-3":"/tmp/dtt1-poc/agent-linux-centos-7-amd64/inventory.yml"}' --live 'True'

To be considered:

wazuh-1: This is the master node
wazuh-{number}: They are the workers
agent-{number}: They are the agents

If the manager component is tested, 'wazuh-' components must be entered in target.
If the agent component is tested, there must be a master and the rest must be 'agent-'s

---

Technical documentation

The testing module allows the execution of tests on agents and central components.

Instructions can be received from the fixture and executed through the Workflow Engine or run through commands on an already provisioned infrastructure.

In both cases, the following information will be required:

  - task: "run-agent-tests"
    description: "Run tests install for the agent."
    do:
      this: process
      with:
        path: python3
        args:
          - modules/testing/main.py
          - targets:
            - wazuh-1: "{working-dir}/manager-linux-ubuntu-22.04-amd64/inventory.yaml"
            - agent-1: "{working-dir}/agent-linux-redhat-8-amd64/inventory.yaml"
          - tests: "install,registration,restart,stop,uninstall"
          - component: "agent"
          - wazuh-version: "4.7.3"
          - wazuh-revision: "40714"
          - live: "True"
    depends-on:
      - "allocate-{agent}"
      - "allocate-manager"

In the exposed fixture fragment, the execution of the testing module launcher (testing/main.py), it is necessary to provide the inventory, dependencies, component, tests to execute, Wazuh version, Wazuh revision, and whether the repository is live or not (if not, it will look for information in packages-dev pre-release).

For manual execution, an example command would be:

python3  modules/testing/main.py --wazuh-revision '40714' --wazuh-version '4.7.3' --component 'agent' --tests 'install,registration,restart,stop,uninstall' --targets '{"wazuh-1":"/tmp/dtt1-poc/manager-linux-ubuntu-22.04-amd64/inventory.yml"}' --targets '{"agent-1":"/tmp/dtt1-poc/agent-linux-redhat-8-amd64/inventory.yml"}' --live 'True'

The module is composed of:

• Launcher ('/wazuh-qa/deployability/modules/testing/main.py'): Entry point for the workflow or the user who wishes to execute a test.

• Parameter validator ('/wazuh-qa/deployability/modules/testing/models.py'): Validator for parameters entered by the Workflow or the user.

• Module functions ('/wazuh-qa/deployability/modules/testing/testing.py'): Module-specific functions responsible for triggering the test.

• Executor ('/wazuh-qa/deployability/modules/provision/actions.py'): Executes the provision using Actions in the generic module.

• Playbooks ('/wazuh-qa/deployability/modules/tests/playbooks'): Contains setup, execution, and post-test cleanup playbooks.

• Tests ('/wazuh-qa/deployability/modules/tests'): Contains the test_agent and test_manager directories where the tests to be executed are located.

• Helpers ('/wazuh-qa/deployability/modules/tests/helpers'): Contains files that enable the execution of the test.

• Conftest ('/wazuh-qa/deployability/modules/tests/conftest.py'): Contains information that will be transferred from the parameter validator to the tests.

The testing module receives the infrastructure generated and provisioned by the allocation and provision modules. The module has the ability to execute actions on the hosts as well as perform the necessary validation.

Testing.drawio.zip

The test module must recieve the infrastructure generated and provisioned by the allocation and provision modules. The module can execute actions on the hosts as well as perform the necessary validation.

Testing of the manager component includes:
install, restart, stop and uninstall
Install should come at the beginning and uninstall at the end, other tests can change their order

Testing of the agent component includes:
install, registration, restart, stop and uninstall
Install must come at the beginning followed by registration Uninstall must come at the end and the other tests can change their order

License

WAZUH Copyright (C) 2015 Wazuh Inc. (License GPLv2)

[QU3B1M]

Required discussion with @fcaffieri about how generic or specific this documentation must be.

[pro-akim]

Update

The documentation will be moved to General documentation.
The test documentation will be written after a POC presentation

[fcaffieri]

We need to adapt the documentation with these recommendations:

• We could have a short introduction about testing module in the User documentation section. In the tech documentation section under it, we can see a short intro about the allocation module but nothing similar for the user doc above.
• Styles using passive voice are vague. We could change to active voice instead. For example, "You must install Python libraries. We recommend using virtual environments" rather than "... must be installed..." and "... is recommended to use...".
• Maybe creating some subsections with subtitles to separate topics like one for setting up the repository and environment, another one for using the workflow library, another for manually running it, and so on.
• Paths could use links to easily check files content in Github. For example: Module functions /wazuh-qa/deployability/modules/testing/test.py: Module-specific functions responsible for triggering the testing.
• If required, we could review phrasing as well as expanding some topics.

[pro-akim]

Update:

Sample has been updated in #4850 (comment) following the standards mentioned at #4850 (comment).

[pro-akim]

Update

Some fixes were done.
Readme of Workflow was incorrectly modified.

[rauldpm]

LGTM