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

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>

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