diff --git a/assets/images/vm_exec_architecture.png b/assets/images/vm_exec_architecture.png new file mode 100644 index 000000000..3a016cfe4 Binary files /dev/null and b/assets/images/vm_exec_architecture.png differ diff --git a/content/product/cloud_system_administration/resource_monitoring/monitoring_system.md b/content/product/cloud_system_administration/resource_monitoring/monitoring_system.md index 357bab42b..4e6da2812 100644 --- a/content/product/cloud_system_administration/resource_monitoring/monitoring_system.md +++ b/content/product/cloud_system_administration/resource_monitoring/monitoring_system.md @@ -60,6 +60,7 @@ For a quick view of any changes in configuration file options in maintenance rel | `SYSTEM_HOST` | Time in seconds to send Host static/configuration information | | | `MONITOR_HOST` | Time in seconds to send Host variable information | | | `STATE_VM` | Time in seconds to send VM status (ie. running, error, stopped…) | | +| `EXEC_VM` | Time in seconds to send VM command execution result | | | `MONITOR_VM` | Time in seconds to send VM resource usage metrics | | | `SYNC_STATE_VM` | Send a complete VM report if probes stopped more than `SYNC_STATE_VM` seconds | | @@ -273,6 +274,9 @@ Probes are structured in different directories that determine the frequency in w | |-- monitor_ds_vm.rb | |-- ... | + |-- execution + | |-- exec.rb + | `-- status `-- state.rb ``` @@ -286,6 +290,7 @@ The purpose of each directory is described in the following table: | `host/system` | General quasi-static info. about Host (e.g. NUMA nodes) stored in `HOST/TEMPLATE` and `HOST/SHARE` | `SYSTEM_HOST` (600s) | | `vm/monitor` | Monitor information (variable) (e.g. used cpu, network usage) stored in `VM/MONITORING` | `MONITOR_VM` (30s) | | `vm/state` | State change notification, only send when a change is detected | `STATE_VM` (30s) | +| `vm/execution` | Retrieve results from the command executed inside the VMs | `EXEC_VM` (5s) | If you need to add custom metrics, the procedure is: diff --git a/content/product/integration_references/system_interfaces/api.md b/content/product/integration_references/system_interfaces/api.md index 0c7de59f2..7babc2784 100644 --- a/content/product/integration_references/system_interfaces/api.md +++ b/content/product/integration_references/system_interfaces/api.md @@ -122,6 +122,9 @@ Commands with marked with \* are asynchronous. The success response for these co | pci-attach | one.vm.attachpci | VM:MANAGE | | pci-detach | one.vm.detachpci | VM:MANAGE | | restore | one.vm.restore | VM:MANAGE | +| exec | one.vm.exec | VM:MANAGE | +| exec-retry | one.vm.retryexec | VM:MANAGE | +| exec-cancel | one.vm.cancelexec | VM:MANAGE | {{< alert title="Note" color="success" >}} The **deploy** action requires the user issuing the command to have VM:ADMIN rights. This user will usually be the scheduler with the oneadmin credentials. @@ -1384,6 +1387,43 @@ For example: | OUT | Int/String | The VM ID / The error string. | | OUT | Int | Error code. | +### one.vm.exec + +- **Description**: Executes a command inside a Virtual Machine. The VM needs to be in RUNNING state. +- **Parameters** + +| Type | Data Type | Description | +|--------|-------------|----------------------------------------------------| +| IN | Int | The VM ID. | +| IN | String | The command to be run inside the VM. | +| OUT | Boolean | `true` or `false` whenever it is successful or not | +| OUT | Int/String | The VM ID / The error string. | +| OUT | Int | Error code. | + +### one.vm.retryexec + +- **Description**: Attempts to run the last command executed inside a Virtual Machine. The VM needs to be in RUNNING state. +- **Parameters** + +| Type | Data Type | Description | +|--------|-------------|-------------------------------------------------| +| IN | Int | The VM ID. | +| OUT | Boolean | `true` or `false` whenever is successful or not | +| OUT | Int/String | The VM ID / The error string. | +| OUT | Int | Error code. | + +### one.vm.cancelexec + +- **Description**: Cancels the execution of last command inside a Virtual Machine. The VM needs to be in RUNNING state. +- **Parameters** + +| Type | Data Type | Description | +|--------|-------------|-------------------------------------------------| +| IN | Int | The VM ID. | +| OUT | Boolean | `true` or `false` whenever is successful or not | +| OUT | Int/String | The VM ID / The error string. | +| OUT | Int | Error code. | + ### one.vmpool.info {{< alert title="Note" color="success" >}} diff --git a/content/product/virtual_machines_operation/virtual_machines/vm_instances.md b/content/product/virtual_machines_operation/virtual_machines/vm_instances.md index d1afc984a..9e79e0354 100644 --- a/content/product/virtual_machines_operation/virtual_machines/vm_instances.md +++ b/content/product/virtual_machines_operation/virtual_machines/vm_instances.md @@ -757,6 +757,82 @@ In this example, the first argument would be the disk and the second the snapsho {{< alert title="Note" color="success" >}} The arguments are mandatory. If you use the CLI or Sunstone they are generated automatically for the actions.{{< /alert >}} +## Command Execution Inside the Virtual Machine +Prerequisites: +* Running commands within a VM rely on the QEMU Guest Agent, which must be installed and running on the VM. +* The VM must be in the `RUNNING` state. + +With OpenNebula, run commands inside a Virtual Machine. Commands are sent to the VM through the QEMU Guest Agent, and results are stored in the VM template under `QEMU_GA_EXEC`. The following diagram depicts how commands are executed within a VM: + +![Architecture Outlining How Command Execution Operates Within the VM](/images/vm_exec_architecture.png) + +The `VM_EXEC` monitor probe collects the results and updates the `QEMU_GA_EXEC` block. To find more details on configuring the monitor probe, refer to [Monitoring System](../../../product/cloud_system_administration/resource_monitoring/monitoring_system.md). + +{{< alert title="Warning" color="warning" >}} +Run only one command at a time for every Virtual Machine. If a current command is still in `EXECUTING` status, even if finished but not yet updated by the monitor probe, new commands will not be executed until the current one is fully completed.{{< /alert >}} + +### Options +The `QEMU_GA_EXEC` section in the VM template contains the following fields: + +| Field | Description | +|---------------|-----------------------------------------------------------------| +| `COMMAND` | The command to be executed in the VM. | +| `STDIN` | Stdin data to pass to the command executed on the VM | +| `PID` | (Hypervisor-side) PID handling the exec request. | +| `RETURN_CODE` | Numeric exit code produced by the command (e.g. `0` = success). | +| `STATUS` | Execution state: `EXECUTING`, `CANCELLED`, `DONE` or `ERROR`. | +| `STDOUT` | Command standard output (base64-encoded). | +| `STDERR` | Command standard error (base64-encoded). | + + +### Executing a command from the CLI + +To execute a command inside a VM, use the `onevm exec` command. For example, to list files in the home directory of VM 0: +```bash +$ onevm exec 0 'ls -l' +``` + +Check the status of the command with: +```bash +$ onevm show 0 +``` + +When still executing: + +```bash +VIRTUAL MACHINE TEMPLATE +... +QEMU_GA_EXEC=[ + COMMAND="ls -l", + STDIN="", + STATUS="EXECUTING" ] +``` + +After the execution is complete, details are updated: + +```bash +VIRTUAL MACHINE TEMPLATE +... +QEMU_GA_EXEC=[ + COMMAND="ls -l", + STDIN="", + PID="3864", + RETURN_CODE="0", + STATUS="DONE", + STDERR="", + STDOUT="dG90Y..." ] +``` + +To retry the execution of the last command executed, use `onevm exec-retry`: +```bash +$ onevm exec-retry 0 +``` + +To cancel the command being executed, use `onevm exec-cancel`: +```bash +$ onevm exec-cancel 0 +``` + ## Virtual Machine States @@ -775,7 +851,7 @@ Note that this is a simplified version. If you are a developer you may want to t | `boot` | `Boot` | OpenNebula is waiting for the hypervisor to create the VM. | | `runn` | `Running` | The VM is running (note that this stage includes the internal virtualized machine booting and shutting down phases). In this state, the virtualization driver will periodically monitor it. | | `migr` | `Migrate` | The VM is migrating from one resource to another. This can be a life migration or cold migration (the VM is saved, powered off or powered off hard and VM files are transferred to the new resource). | -| `hotp` | `Hotplug` | A disk attach/detach, nic attach/detach, save as or resize operation is in process. | +| `hotp` | `Hotplug` | A disk attach/detach, nic attach/detach, save as, resize or exec operation is in process. | | `snap` | `Snapshot` | A system snapshot is being taken. | | `save` | `Save` | The system is saving the VM files after a migration, stop, or suspend operation. | | `epil` | `Epilog` | In this phase the system cleans up the Host used to virtualize the VM, and additionally disk images to be saved are copied back to the system datastore. | diff --git a/content/software/release_information/release_notes_72/whats_new.md b/content/software/release_information/release_notes_72/whats_new.md index 15def56bd..32db8cf44 100644 --- a/content/software/release_information/release_notes_72/whats_new.md +++ b/content/software/release_information/release_notes_72/whats_new.md @@ -32,6 +32,7 @@ We encourage you to review the [Known Issues]({{% relref "known_issues" %}}) and ## Monitoring - [Resource Usage Forecast](../../../product/cloud_system_administration/resource_monitoring/forecast/): Introduces predictive analytics for Host and VM resource consumption, enabling proactive infrastructure management. By analyzing trends in CPU, memory, disk, and network usage, OpenNebula 7.0 supports improved capacity planning, optimized workload scheduling, and early detection of performance bottlenecks. +- [New monitor message `EXEC_VM`to retrieve the result of commands executed inside a Virtual Machine](../../../product/cloud_system_administration/resource_monitoring/monitoring_system.md) ## Scheduler @@ -59,6 +60,7 @@ We encourage you to review the [Known Issues]({{% relref "known_issues" %}}) and ## API and CLI - [The `onedb purge-history` command now removes history records only within the specified `–start`, `–end` range for the `–id`, instead of deleting all records](https://github.com/OpenNebula/one/issues/6699). +- [New API calls (`one.vm.exec`, `one.vm.retryexec` and `one.vm.cancelexec`) to execute commands on a Virtual Machine](../../../product/virtual_machines_operation/virtual_machines/vm_instances.md#execute-commands-inside-the-virtual-machine) - The output of `onemarketapp list` list now contains 2 extra columns displaying **HYPERVISOR** and **ARCHITECTURE**. - [Add automatic VM index for multiple persistent VM instantiation](../../../product/virtual_machines_operation/virtual_machines/vm_instances.md#instantiate-to-persistent) @@ -68,10 +70,8 @@ We encourage you to review the [Known Issues]({{% relref "known_issues" %}}) and - [Virtual Machine memory encryption](../../../product/virtual_machines_operation/virtual_machines/vm_templates#memory-encryption) allows VM workloads whose memory cannot be read by the hypervisor. ## LXC - - NIC Hotplugging, recontextualization and NIC PCI passthrough are now available [driver features](../../../product/operation_references/hypervisor_configuration/lxc_driver.md). - ## OpenNebula Flow - [Oneflow clients include content-type header to make them work with Sinatra 4.0.0](https://github.com/OpenNebula/one/issues/6508).