mirrors/terraform-provider-proxmox
0
0
Fork 0
mirror of https://github.com/bpg/terraform-provider-proxmox.git synced 2025-06-30 18:42:58 +00:00
Code

fix(docs): document qemu-guest-agent behavior (#670)

Browse Source 
fix(docs): Document qemu-guest-agent behavior

Modify example to start with disabled guest agent.

Signed-off-by: Oto Petřík <oto.petrik@gmail.com>
This commit is contained in:
Oto Petřík 2023-10-31 02:10:34 +01:00 committed by GitHub
parent 6ab1d5fffb
commit e2e5b4e344
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 40 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
docs/resources/virtual_environment_vm.md
View File

@ -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