Skip to content

Commit 8a457f8

Browse files
MarioRobresprisorue
MarioRobres
and
prisorue
authored
F OpenNebula/one#7299: Add new API calls to execute commands on a Virtual Machine (#436)
Co-authored-by: Priscill Orue <[email protected]>
1 parent dfc634d commit 8a457f8

File tree

5 files changed

+124
-3
lines changed

5 files changed

+124
-3
lines changed

‎assets/images/vm_exec_architecture.png‎

21.5 KB
Loading

‎content/product/cloud_system_administration/resource_monitoring/monitoring_system.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ For a quick view of any changes in configuration file options in maintenance rel
6060
| `SYSTEM_HOST` | Time in seconds to send Host static/configuration information | |
6161
| `MONITOR_HOST` | Time in seconds to send Host variable information | |
6262
| `STATE_VM` | Time in seconds to send VM status (ie. running, error, stopped…) | |
63+
| `EXEC_VM` | Time in seconds to send VM command execution result | |
6364
| `MONITOR_VM` | Time in seconds to send VM resource usage metrics | |
6465
| `SYNC_STATE_VM` | Send a complete VM report if probes stopped more than `SYNC_STATE_VM` seconds | |
6566

@@ -273,6 +274,9 @@ Probes are structured in different directories that determine the frequency in w
273274
| |-- monitor_ds_vm.rb
274275
| |-- ...
275276
|
277+
|-- execution
278+
| |-- exec.rb
279+
|
276280
`-- status
277281
`-- state.rb
278282
```
@@ -286,6 +290,7 @@ The purpose of each directory is described in the following table:
286290
| `host/system` | General quasi-static info. about Host (e.g. NUMA nodes) stored in `HOST/TEMPLATE` and `HOST/SHARE` | `SYSTEM_HOST` (600s) |
287291
| `vm/monitor` | Monitor information (variable) (e.g. used cpu, network usage) stored in `VM/MONITORING` | `MONITOR_VM` (30s) |
288292
| `vm/state` | State change notification, only send when a change is detected | `STATE_VM` (30s) |
293+
| `vm/execution` | Retrieve results from the command executed inside the VMs | `EXEC_VM` (5s) |
289294

290295
If you need to add custom metrics, the procedure is:
291296

‎content/product/integration_references/system_interfaces/api.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,9 @@ Commands with marked with \* are asynchronous. The success response for these co
122122
| pci-attach | one.vm.attachpci | VM:MANAGE |
123123
| pci-detach | one.vm.detachpci | VM:MANAGE |
124124
| restore | one.vm.restore | VM:MANAGE |
125+
| exec | one.vm.exec | VM:MANAGE |
126+
| exec-retry | one.vm.retryexec | VM:MANAGE |
127+
| exec-cancel | one.vm.cancelexec | VM:MANAGE |
125128

126129
{{< alert title="Note" color="success" >}}
127130
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:
13841387
| OUT | Int/String | The VM ID / The error string. |
13851388
| OUT | Int | Error code. |
13861389

1390+
### one.vm.exec
1391+
1392+
- **Description**: Executes a command inside a Virtual Machine. The VM needs to be in RUNNING state.
1393+
- **Parameters**
1394+
1395+
| Type | Data Type | Description |
1396+
|--------|-------------|----------------------------------------------------|
1397+
| IN | Int | The VM ID. |
1398+
| IN | String | The command to be run inside the VM. |
1399+
| OUT | Boolean | `true` or `false` whenever it is successful or not |
1400+
| OUT | Int/String | The VM ID / The error string. |
1401+
| OUT | Int | Error code. |
1402+
1403+
### one.vm.retryexec
1404+
1405+
- **Description**: Attempts to run the last command executed inside a Virtual Machine. The VM needs to be in RUNNING state.
1406+
- **Parameters**
1407+
1408+
| Type | Data Type | Description |
1409+
|--------|-------------|-------------------------------------------------|
1410+
| IN | Int | The VM ID. |
1411+
| OUT | Boolean | `true` or `false` whenever is successful or not |
1412+
| OUT | Int/String | The VM ID / The error string. |
1413+
| OUT | Int | Error code. |
1414+
1415+
### one.vm.cancelexec
1416+
1417+
- **Description**: Cancels the execution of last command inside a Virtual Machine. The VM needs to be in RUNNING state.
1418+
- **Parameters**
1419+
1420+
| Type | Data Type | Description |
1421+
|--------|-------------|-------------------------------------------------|
1422+
| IN | Int | The VM ID. |
1423+
| OUT | Boolean | `true` or `false` whenever is successful or not |
1424+
| OUT | Int/String | The VM ID / The error string. |
1425+
| OUT | Int | Error code. |
1426+
13871427
### one.vmpool.info
13881428

13891429
{{< alert title="Note" color="success" >}}

‎content/product/virtual_machines_operation/virtual_machines/vm_instances.md‎

Lines changed: 77 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -757,6 +757,82 @@ In this example, the first argument would be the disk and the second the snapsho
757757
{{< alert title="Note" color="success" >}}
758758
The arguments are mandatory. If you use the CLI or Sunstone they are generated automatically for the actions.{{< /alert >}}
759759

760+
## Command Execution Inside the Virtual Machine
761+
Prerequisites:
762+
* Running commands within a VM rely on the QEMU Guest Agent, which must be installed and running on the VM.
763+
* The VM must be in the `RUNNING` state.
764+
765+
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:
766+
767+
![Architecture Outlining How Command Execution Operates Within the VM](/images/vm_exec_architecture.png)
768+
769+
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).
770+
771+
{{< alert title="Warning" color="warning" >}}
772+
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 >}}
773+
774+
### Options
775+
The `QEMU_GA_EXEC` section in the VM template contains the following fields:
776+
777+
| Field | Description |
778+
|---------------|-----------------------------------------------------------------|
779+
| `COMMAND` | The command to be executed in the VM. |
780+
| `STDIN` | Stdin data to pass to the command executed on the VM |
781+
| `PID` | (Hypervisor-side) PID handling the exec request. |
782+
| `RETURN_CODE` | Numeric exit code produced by the command (e.g. `0` = success). |
783+
| `STATUS` | Execution state: `EXECUTING`, `CANCELLED`, `DONE` or `ERROR`. |
784+
| `STDOUT` | Command standard output (base64-encoded). |
785+
| `STDERR` | Command standard error (base64-encoded). |
786+
787+
788+
### Executing a command from the CLI
789+
790+
To execute a command inside a VM, use the `onevm exec` command. For example, to list files in the home directory of VM 0:
791+
```bash
792+
$ onevm exec 0 'ls -l'
793+
```
794+
795+
Check the status of the command with:
796+
```bash
797+
$ onevm show 0
798+
```
799+
800+
When still executing:
801+
802+
```bash
803+
VIRTUAL MACHINE TEMPLATE
804+
...
805+
QEMU_GA_EXEC=[
806+
COMMAND="ls -l",
807+
STDIN="",
808+
STATUS="EXECUTING" ]
809+
```
810+
811+
After the execution is complete, details are updated:
812+
813+
```bash
814+
VIRTUAL MACHINE TEMPLATE
815+
...
816+
QEMU_GA_EXEC=[
817+
COMMAND="ls -l",
818+
STDIN="",
819+
PID="3864",
820+
RETURN_CODE="0",
821+
STATUS="DONE",
822+
STDERR="",
823+
STDOUT="dG90Y..." ]
824+
```
825+
826+
To retry the execution of the last command executed, use `onevm exec-retry`:
827+
```bash
828+
$ onevm exec-retry 0
829+
```
830+
831+
To cancel the command being executed, use `onevm exec-cancel`:
832+
```bash
833+
$ onevm exec-cancel 0
834+
```
835+
760836
<a id="vm-life-cycle-and-states"></a>
761837

762838
## Virtual Machine States
@@ -775,7 +851,7 @@ Note that this is a simplified version. If you are a developer you may want to t
775851
| `boot` | `Boot` | OpenNebula is waiting for the hypervisor to create the VM. |
776852
| `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. |
777853
| `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). |
778-
| `hotp` | `Hotplug` | A disk attach/detach, nic attach/detach, save as or resize operation is in process. |
854+
| `hotp` | `Hotplug` | A disk attach/detach, nic attach/detach, save as, resize or exec operation is in process. |
779855
| `snap` | `Snapshot` | A system snapshot is being taken. |
780856
| `save` | `Save` | The system is saving the VM files after a migration, stop, or suspend operation. |
781857
| `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. |

‎content/software/release_information/release_notes_72/whats_new.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ We encourage you to review the [Known Issues]({{% relref "known_issues" %}}) and
3232
## Monitoring
3333
<!--keeping some examples-->
3434
- [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.
35+
- [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)
3536

3637
## Scheduler
3738
<!--keeping some examples-->
@@ -59,6 +60,7 @@ We encourage you to review the [Known Issues]({{% relref "known_issues" %}}) and
5960
## API and CLI
6061
<!--keeping some examples-->
6162
- [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).
63+
- [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)
6264
- The output of `onemarketapp list` list now contains 2 extra columns displaying **HYPERVISOR** and **ARCHITECTURE**.
6365
- [Add automatic VM index for multiple persistent VM instantiation](../../../product/virtual_machines_operation/virtual_machines/vm_instances.md#instantiate-to-persistent)
6466

@@ -68,10 +70,8 @@ We encourage you to review the [Known Issues]({{% relref "known_issues" %}}) and
6870
- [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.
6971

7072
## LXC
71-
7273
- NIC Hotplugging, recontextualization and NIC PCI passthrough are now available [driver features](../../../product/operation_references/hypervisor_configuration/lxc_driver.md).
7374

74-
7575
## OpenNebula Flow
7676
<!--keeping some examples-->
7777
- [Oneflow clients include content-type header to make them work with Sinatra 4.0.0](https://github.com/OpenNebula/one/issues/6508).

0 commit comments

Comments
 (0)