[Feature] Add Apis -- Exec and Get Command Output

[wu5bocheng]

API Design Document

Overview

This document outlines the design and implementation of the new APIs for executing commands on virtual machines (VMs) and retrieving their output. These APIs are part of the TopoMojo project and are intended to enhance the functionality of VM management.

API Endpoints

1. Execute VM Command

• Endpoint: POST /api/vm/{id}/exec
• Description: Starts the execution of a command on a specified VM.
• Parameters:
  • id (string): The ID of the VM.
  • commandList (array of strings): The list of commands to execute.
• Response:
  • 200 OK: Returns the process ID (pid) of the started command execution.
  • 403 Forbidden: If the user is not authorized to manage the VM.
  • 400 Bad Request: If there is an error in executing the command.
• Example Request:

  {
    "commandList": ["ls", "pwd"]
  }

• Example Response:

  {
    "pid": 1234
  }

2. Get VM Command Output

• Endpoint: GET /api/vm/{id}/exec/{pid}
• Description: Retrieves the output of a previously executed command on a specified VM.
• Parameters:
  • id (string): The ID of the VM.
  • pid (integer): The process ID of the command execution.
• Response:
  • 200 OK: Returns the output of the command execution.
  • 403 Forbidden: If the user is not authorized to manage the VM.
  • 400 Bad Request: If there is an error in retrieving the command output.
• Example Response:

  {
    "outData": "output of the command",
    "errData": "error output if any",
    "exitCode": 0,
    "exited": true
  }

Implementation Details

VM Controller

• File: src/TopoMojo.Api/Features/Vm/VmController.cs
• Methods:
  • ExecVmCommand: Handles the execution of commands on VMs.
  • GetVmCommandOutput: Retrieves the output of executed commands.

Hypervisor Service

• File: src/TopoMojo.Hypervisor/IHypervisorService.cs
• Methods:
  • ExecCommand: Executes commands on the VM.
  • GetCommandOutput: Retrieves the output of executed commands.

Proxmox Client

• File: src/TopoMojo.Hypervisor/Proxmox/ProxmoxClient.cs
• Methods:
  • ExecCommand: Implements the command execution logic.
  • GetCommandOutput: Implements the logic to retrieve command output.

Mock Hypervisor Service

• File: src/TopoMojo.Hypervisor/vMock/MockHypervisorService.cs
• Methods:
  • ExecCommand: Mock implementation for command execution.
  • GetCommandOutput: Mock implementation for retrieving command output.

Conclusion

These new APIs provide a robust mechanism for executing commands on VMs and retrieving their output, enhancing the overall functionality of the TopoMojo project. The implementation details ensure that the APIs are well-integrated with the existing system architecture.

[wu5bocheng]

@sei-aschlackman Dear Andrew, we have already finished the draft version of the command execution api for topomojo, please review.