Merge pull request #4158 from YongxueHong/multi-host-test-vt-agent

VT Agent: Add agent for remote task execution

Author: richtja

avocado_vt/vt_agent/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=64.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "avocado-vt-agent"
+version = "0.1.0"
+requires-python = ">=3.8"
+authors = [
+    {name = "Yongxue Hong", email = "[email protected]"},
+    {name = "Xu Han", email = "[email protected]"},
+    {name = "Zhenchao Liu", email = "[email protected]"},
+]
+maintainers = [
+    {name = "Yongxue Hong", email = "[email protected]"},
+    {name = "Xu Han", email = "[email protected]"},
+    {name = "Zhenchao Liu", email = "[email protected]"},
+]
+description = "Avocado Agent for Virtualization Testing"
+readme = "README.md"
+
+[project.urls]
+Homepage = "https://avocado-vt.readthedocs.io/en/latest/"
+Documentation = "https://avocado-vt.readthedocs.io/en/latest/index.html#"
+Repository = "https://github.com/avocado-framework/avocado-vt"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["avocado_vt.agent"]

avocado_vt/vt_agent/src/avocado_vt/agent/README.md

@@ -0,0 +1,123 @@
+# Avocado VT Agent
+
+The Avocado VT Agent is a lightweight, extensible RPC agent designed to be installed and run on remote test machines. It allows for the remote execution of predefined functions and custom services, facilitating test automation within the Avocado VT framework.
+
+This agent is packaged as a separate, standalone distribution (`avocado-vt-agent`) that installs itself into the `avocado_vt` namespace.
+
+## Installation
+
+Before running the agent, it must be installed using `pip`. This is typically done on a remote machine where tests will be executed.
+
+### Installing the Agent
+
+To build and install the agent, navigate to its directory (the one containing `pyproject.toml`) and use `pip`:
+
+```bash
+# From the .../avocado-vt/avocado_vt/vt_agent/ directory
+pip install .
+```
+
+This command will build the agent and install it into your Python environment.
+
+## Running the Agent
+
+Once installed, the agent can be started as a module. It's recommended to run it as a background service for continuous operation.
+
+```bash
+python -m avocado_vt.agent --host <address> --port <port> --pid-file /path/to/agent.pid
+```
+
+**Command-line Arguments:**
+
+*   `--host <address>`: The IP address for the agent to listen on. Defaults to `127.0.0.1` (localhost only for security).
+*   `--port <port>`: The port number for the agent to listen on. Defaults to `9999`.
+*   `--pid-file <path>`: (Required) Path to write the agent's Process ID (PID).
+
+**Example:**
+```bash
+python -m avocado_vt.agent --host 0.0.0.0 --port 8001 --pid-file ./vt_agent.pid &
+```
+
+## Features
+
+*   XML-RPC based communication.
+*   Dynamically loads custom services from the `services` directory.
+*   Threaded server to handle multiple client requests concurrently.
+*   Logging for agent operations and service execution.
+
+## Checking Agent Status
+
+You can check if the agent is alive and responsive using an XML-RPC client to call the `core.is_alive` method.
+
+**Example Python client:**
+```python
+import xmlrpc.client
+
+try:
+    # Replace 'localhost' and '8001' with the agent's host and port
+    agent_proxy = xmlrpc.client.ServerProxy("http://localhost:8001/", allow_none=True)
+
+    if agent_proxy.core.is_alive():
+        print("Agent is alive and responding.")
+    else:
+        print("core.is_alive() returned False (unexpected).")
+
+except ConnectionRefusedError:
+    print("Connection refused. Is agent running at the specified address and port?")
+except xmlrpc.client.Fault as fault:
+    print(f"RPC Fault: {fault.faultCode} - {fault.faultString}")
+except Exception as e:
+    print(f"An error occurred: {e}")
+
+# Example of calling an example service method
+try:
+    # Assumes the 'examples.hello' service is loaded
+    print(f"Executing ping to the agent host")
+    greeting = agent_proxy.examples.hello.ping()
+    print(f"Service Response: {greeting}")
+except xmlrpc.client.Fault as fault:
+    print(f"RPC Fault calling service: {fault.faultCode} - {fault.faultString}")
+except Exception as e:
+    print(f"Error calling service: {e}")
+```
+
+## Architecture Overview
+
+*   **Core Agent (`core/`)**: Handles RPC server setup, request dispatching, service loading, logging, and data directory management.
+*   **Application (`app/`)**: Manages command-line arguments and the main execution flow.
+*   **Services (`services/`)**: Contains dynamically loaded service modules. Each `.py` file (not `__init__.py`) in this directory (and its subdirectories) is treated as a service module. Functions within these modules become callable RPC methods, namespaced by their module path (e.g., `examples.hello.say_hello`).
+
+## Developing Services
+
+1.  **Create a Python file** (e.g., `my_service.py`) inside the `src/avocado_vt/agent/services/` directory or a subdirectory.
+2.  **Define functions** within your Python file. These functions will be exposed as RPC methods.
+    *   Example `my_service.py`:
+        ```python
+        import logging
+
+        from avocado_vt.agent.core.logger import DEFAULT_LOG_NAME
+
+        LOG = logging.getLogger(f"{DEFAULT_LOG_NAME}." + __name__)
+
+        def do_something(param1, param2="default"):
+            LOG.info(f"my_service.do_something called with: {param1}, {param2}")
+            result = f"Processed {param1} and {param2}"
+            return {"status": "success", "result": result}
+        ```
+3.  **Logging**: Use `logging.getLogger(f"{DEFAULT_LOG_NAME}." + __name__)` to get a logger instance that integrates with the agent's logging.
+4.  **Naming**: If your file is `services/custom/my_service.py`, its functions will be callable like `custom.my_service.do_something`.
+5.  The agent will automatically discover and load your service when it starts.
+
+## Remote Logging
+
+The agent provides a core API to stream logs from services back to a client:
+*   `core.start_log_redirection(host, port)`: Tells the agent to start sending logs to a socket listener at the specified `host` and `port`.
+*   `core.stop_log_redirection()`: Stops the log streaming.
+
+A corresponding log server/listener needs to be running on the client side to receive these logs.
+
+## Security Considerations
+
+*   **Default Binding**: The agent now defaults to binding on `127.0.0.1` (localhost only) for improved security. To allow external connections, explicitly specify `--host 0.0.0.0`.
+*   **Network Access**: When binding to `0.0.0.0`, ensure proper firewall rules and network security controls are in place.
+*   **Service Loading**: The agent dynamically loads Python modules from the services directory. Only place trusted service modules in this directory.

avocado_vt/vt_agent/src/avocado_vt/agent/__init__.py

@@ -0,0 +1,78 @@
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+#
+# See LICENSE for more details.
+#
+# Copyright: Red Hat Inc. 2025
+# Authors: Yongxue Hong <[email protected]>
+
+import logging
+import os
+import shutil
+
+# pylint: disable=E0611
+from avocado_vt.agent.app.args import init_arguments
+from avocado_vt.agent.app.cmd import run
+from avocado_vt.agent.core import data_dir as core_data_dir
+from avocado_vt.agent.core.logger import DEFAULT_LOG_NAME, init_logger
+
+
+def cleanup_previous_run(dirs):
+    """
+    Clean up directories from previous agent runs.
+
+    :param dirs: Tuple of directory paths to clean up
+    :type dirs: tuple
+    """
+    for directory in dirs:
+        if os.path.exists(directory):
+            try:
+                shutil.rmtree(directory)
+            except OSError:
+                pass
+
+
+def setup_directories(dirs, logger):
+    """
+    Create necessary directories for agent operation.
+
+    :param dirs: Tuple of directory paths to create
+    :type dirs: tuple
+    :param logger: Logger instance for reporting
+    :type logger: logging.Logger
+    """
+    for directory in dirs:
+        try:
+            os.makedirs(directory, exist_ok=True)
+        except OSError as e:
+            logger.error("Failed to create directory %s: %s", directory, e)
+            raise
+
+
+def main():
+    """Main entry point for the agent."""
+    args = init_arguments()
+
+    data_dir = core_data_dir.get_data_dir()
+    log_dir = core_data_dir.get_log_dir()
+    download_dir = core_data_dir.get_download_dir()
+    dirs = (data_dir, log_dir, download_dir)
+
+    cleanup_previous_run(dirs)
+
+    init_logger()
+    logger = logging.getLogger(f"{DEFAULT_LOG_NAME}.__main__")
+
+    setup_directories(dirs, logger)
+
+    run(args.host, args.port, args.pid_file)
+
+
+if __name__ == "__main__":
+    main()

avocado_vt/vt_agent/src/avocado_vt/agent/__main__.py

@@ -0,0 +1,9 @@
+"""
+The `app` package for the Avocado VT Agent.
+
+This package contains modules related to the application setup,
+command-line argument parsing, and main execution command for the agent.
+"""
+
+# pylint: disable=E0611
+from avocado_vt.agent.app import args, cmd