From e2e5b4e3441f46fbaef36751c6e5a6d1bc5ad671 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oto=20Pet=C5=99=C3=ADk?= Date: Tue, 31 Oct 2023 02:10:34 +0100 Subject: [PATCH] fix(docs): document qemu-guest-agent behavior (#670) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit fix(docs): Document qemu-guest-agent behavior Modify example to start with disabled guest agent. Signed-off-by: Oto Petřík --- docs/resources/virtual_environment_vm.md | 41 +++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/docs/resources/virtual_environment_vm.md b/docs/resources/virtual_environment_vm.md index aba96266..33d56cf9 100644 --- a/docs/resources/virtual_environment_vm.md +++ b/docs/resources/virtual_environment_vm.md @@ -23,7 +23,8 @@ resource "proxmox_virtual_environment_vm" "ubuntu_vm" { vm_id = 4321 agent { - enabled = true + # read 'Qemu guest agent' section, change to true only when ready + enabled = false } startup { @@ -498,6 +499,44 @@ output "ubuntu_vm_public_key" { - `network_interface_names` - The network interface names published by the QEMU agent (empty list when `agent.enabled` is `false`) +## Qemu guest agent + +Qemu-guest-agent is an application which can be installed inside guest VM, see +[Proxmox Wiki](https://pve.proxmox.com/wiki/Qemu-guest-agent) and [Proxmox +Documentation](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#qm_qemu_agent) + +For VM with `agent.enabled = false`, Proxmox uses ACPI for `Shutdown` and +`Reboot`, and `qemu-guest-agent` is not needed inside the VM. + +Setting `agent.enabled = true` informs Proxmox that the guest agent is expected +to be *running* inside the VM. Proxmox then uses `qemu-guest-agent` instead of +ACPI to control the VM. If the agent is not running, Proxmox operations +`Shutdown` and `Reboot` time out and fail. The failing operation gets a lock on +the VM, and until the operation times out, other operations like `Stop` and +`Reboot` cannot be used. + +Do **not** run VM with `agent.enabled = true`, unless the VM is configured to +automatically **start** `qemu-guest-agent` at some point. + +"Monitor" tab in Proxmox GUI can be used to send low-level commands to `qemu`. +See the [documentation](https://www.qemu.org/docs/master/system/monitor.html). +Commands `system_powerdown` and `quit` have proven useful in shutting down VMs +with `agent.enabled = true` and no agent running. + +Cloud images usually do not have `qemu-guest-agent` installed. It is possible to +install and *start* it using cloud-init, e.g. using custom `user_data_file_id` +file. + +This provider requires `agent.enabled = true` to populate `ipv4_addresses`, +`ipv6_addresses` and `network_interface_names` output attributes. + +Setting `agent.enabled = true` without running `qemu-guest-agent` in the VM will +also result in long timeouts when using the provider, both when creating VMs, +and when refreshing resources. The provider has no way to distinguish between +"qemu-guest-agent not installed" and "very long boot due to a disk check", it +trusts the user to set `agent.enabled` correctly and waits for +`qemu-guest-agent` to start. + ## Important Notes When cloning an existing virtual machine, whether it's a template or not, the