common: add qemu agent settings block

- Extend QEMU agent handling by introducing qemu_quest_agent block, deprecating qemu_agent bool - Enable setting the agent type - Enable toggling freeze/thaw filesystems on backup - Enable toggling fstrim after disk move or VM migration - Each added setting defaults to Proxmox's backend defaults when not configured.
hashicorp · Oct 4, 2024 · 3703ff3 · 3703ff3
1 parent 07788d3
commit 3703ff3
Show file tree

Hide file tree

Showing 15 changed files with 403 additions and 17 deletions.
diff --git a/.web-docs/components/builder/clone/README.md b/.web-docs/components/builder/clone/README.md
@@ -243,10 +243,13 @@ boot time.
     ]
     ```
 
-- `qemu_agent` (boolean) - Enables QEMU Agent option for this VM. When enabled,
+- `qemu_agent` (boolean) - DEPRECATED. Define QEMU Guest Agent settings in a `qemu_guest_agent` block instead.
+  Enables QEMU Agent option for this VM. When enabled,
   then `qemu-guest-agent` must be installed on the guest. When disabled, then
   `ssh_host` should be used. Defaults to `true`.
 
+- `qemu_guest_agent` (agentConfig) - QEMU Guest Agent configuration. See [QEMU Guest Agent](#qemu-guest-agent)
+
 - `scsi_controller` (string) - The SCSI controller model to emulate. Can be `lsi`,
   `lsi53c810`, `virtio-scsi-pci`, `virtio-scsi-single`, `megasas`, or `pvscsi`.
   Defaults to `lsi`.
@@ -826,6 +829,57 @@ Usage example (JSON):
 <!-- End of code generated from the comments of the efiConfig struct in builder/proxmox/common/config.go; -->
 
 
+### QEMU Guest Agent
+
+<!-- Code generated from the comments of the agentConfig struct in builder/proxmox/common/config.go; DO NOT EDIT MANUALLY -->
+
+Set the QEMU Guest Agent options.
+
+JSON Example:
+
+```json
+
+	"qemu_guest_agent": {
+			  "enabled": true,
+			  "type": "isa",
+			  "freeze": false,
+			  "fstrim": false
+	}
+
+```
+HCL2 example:
+
+```hcl
+
+	qemu_guest_agent {
+	  enabled = true
+	  type = "isa"
+	  freeze = false
+	  fstrim = false
+	}
+
+```
+
+<!-- End of code generated from the comments of the agentConfig struct in builder/proxmox/common/config.go; -->
+
+
+#### Optional:
+
+<!-- Code generated from the comments of the agentConfig struct in builder/proxmox/common/config.go; DO NOT EDIT MANUALLY -->
+
+- `enabled` (boolean) - Enable QEMU Agent option for this VM. When enabled
+  `qemu-guest-agent` must be installed on the guest. When disabled
+  `ssh_host` should be used. Defaults to `true`.
+
+- `type` (string) - Sets the Agent Type. Must be `isa` or `virtio`. Defaults to `virtio`
+
+- `freeze` (boolean) - Enable freeze/thaw of guest filesystem on backup. Defaults to `true`
+
+- `fstrim` (bool) - Run guest-trim after a disk move or VM migration. Defaults to `false`
+
+<!-- End of code generated from the comments of the agentConfig struct in builder/proxmox/common/config.go; -->
+
+
 ### VirtIO RNG device
 
 <!-- Code generated from the comments of the rng0Config struct in builder/proxmox/common/config.go; DO NOT EDIT MANUALLY -->

diff --git a/.web-docs/components/builder/iso/README.md b/.web-docs/components/builder/iso/README.md
@@ -178,10 +178,13 @@ in the image's Cloud-Init settings for provisioning.
     ]
     ```
 
-- `qemu_agent` (boolean) - Enables QEMU Agent option for this VM. When enabled,
+- `qemu_agent` (boolean) - DEPRECATED. Define QEMU Guest Agent settings in a `qemu_guest_agent` block instead.
+  Enables QEMU Agent option for this VM. When enabled,
   then `qemu-guest-agent` must be installed on the guest. When disabled, then
   `ssh_host` should be used. Defaults to `true`.
 
+- `qemu_guest_agent` (agentConfig) - QEMU Guest Agent configuration. See [QEMU Guest Agent](#qemu-guest-agent)
+
 - `scsi_controller` (string) - The SCSI controller model to emulate. Can be `lsi`,
   `lsi53c810`, `virtio-scsi-pci`, `virtio-scsi-single`, `megasas`, or `pvscsi`.
   Defaults to `lsi`.
@@ -667,6 +670,57 @@ Usage example (JSON):
 <!-- End of code generated from the comments of the efiConfig struct in builder/proxmox/common/config.go; -->
 
 
+### QEMU Guest Agent
+
+<!-- Code generated from the comments of the agentConfig struct in builder/proxmox/common/config.go; DO NOT EDIT MANUALLY -->
+
+Set the QEMU Guest Agent options.
+
+JSON Example:
+
+```json
+
+	"qemu_guest_agent": {
+			  "enabled": true,
+			  "type": "isa",
+			  "freeze": false,
+			  "fstrim": false
+	}
+
+```
+HCL2 example:
+
+```hcl
+
+	qemu_guest_agent {
+	  enabled = true
+	  type = "isa"
+	  freeze = false
+	  fstrim = false
+	}
+
+```
+
+<!-- End of code generated from the comments of the agentConfig struct in builder/proxmox/common/config.go; -->
+
+
+#### Optional:
+
+<!-- Code generated from the comments of the agentConfig struct in builder/proxmox/common/config.go; DO NOT EDIT MANUALLY -->
+
+- `enabled` (boolean) - Enable QEMU Agent option for this VM. When enabled
+  `qemu-guest-agent` must be installed on the guest. When disabled
+  `ssh_host` should be used. Defaults to `true`.
+
+- `type` (string) - Sets the Agent Type. Must be `isa` or `virtio`. Defaults to `virtio`
+
+- `freeze` (boolean) - Enable freeze/thaw of guest filesystem on backup. Defaults to `true`
+
+- `fstrim` (bool) - Run guest-trim after a disk move or VM migration. Defaults to `false`
+
+<!-- End of code generated from the comments of the agentConfig struct in builder/proxmox/common/config.go; -->
+
+
 ### VirtIO RNG device
 
 <!-- Code generated from the comments of the rng0Config struct in builder/proxmox/common/config.go; DO NOT EDIT MANUALLY -->

diff --git a/builder/proxmox/clone/config.hcl2spec.go b/builder/proxmox/clone/config.hcl2spec.go
diff --git a/builder/proxmox/common/config.go b/builder/proxmox/common/config.go
@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MPL-2.0
 
 //go:generate packer-sdc struct-markdown
-//go:generate packer-sdc mapstructure-to-hcl2 -type Config,NICConfig,diskConfig,rng0Config,pciDeviceConfig,vgaConfig,ISOsConfig,efiConfig,tpmConfig
+//go:generate packer-sdc mapstructure-to-hcl2 -type Config,NICConfig,diskConfig,rng0Config,pciDeviceConfig,vgaConfig,ISOsConfig,efiConfig,tpmConfig,agentConfig
 
 package proxmox
 
@@ -158,10 +158,13 @@ type Config struct {
 	//   ]
 	//   ```
 	Serials []string `mapstructure:"serials"`
+	// DEPRECATED. Define QEMU Guest Agent settings in a `qemu_guest_agent` block instead.
 	// Enables QEMU Agent option for this VM. When enabled,
 	// then `qemu-guest-agent` must be installed on the guest. When disabled, then
 	// `ssh_host` should be used. Defaults to `true`.
 	Agent config.Trilean `mapstructure:"qemu_agent"`
+	// QEMU Guest Agent configuration. See [QEMU Guest Agent](#qemu-guest-agent)
+	GuestAgent agentConfig `mapstructure:"qemu_guest_agent"`
 	// The SCSI controller model to emulate. Can be `lsi`,
 	// `lsi53c810`, `virtio-scsi-pci`, `virtio-scsi-single`, `megasas`, or `pvscsi`.
 	// Defaults to `lsi`.
@@ -207,6 +210,45 @@ type Config struct {
 	Ctx interpolate.Context `mapstructure-to-hcl2:",skip"`
 }
 
+// Set the QEMU Guest Agent options.
+//
+// JSON Example:
+//
+// ```json
+//
+//	"qemu_guest_agent": {
+//			  "enabled": true,
+//			  "type": "isa",
+//			  "freeze": false,
+//			  "fstrim": false
+//	}
+//
+// ```
+// HCL2 example:
+//
+// ```hcl
+//
+//	qemu_guest_agent {
+//	  enabled = true
+//	  type = "isa"
+//	  freeze = false
+//	  fstrim = false
+//	}
+//
+// ```
+type agentConfig struct {
+	// Enable QEMU Agent option for this VM. When enabled
+	// `qemu-guest-agent` must be installed on the guest. When disabled
+	// `ssh_host` should be used. Defaults to `true`.
+	Enabled config.Trilean `mapstructure:"enabled"`
+	// Sets the Agent Type. Must be `isa` or `virtio`. Defaults to `virtio`
+	Type string `mapstructure:"type"`
+	// Enable freeze/thaw of guest filesystem on backup. Defaults to `true`
+	Freeze config.Trilean `mapstructure:"freeze"`
+	// Run guest-trim after a disk move or VM migration. Defaults to `false`
+	FsTrim bool `mapstructure:"fstrim"`
+}
+
 // ISO files attached to the virtual machine.
 //
 // JSON Example:
@@ -606,7 +648,27 @@ func (c *Config) Prepare(upper interface{}, raws ...interface{}) ([]string, []st
 
 	// Default qemu_agent to true
 	if c.Agent != config.TriFalse {
-		c.Agent = config.TriTrue
+		warnings = append(warnings, "qemu_agent is deprecated and will be removed in a future release. define QEMU agent settings in a qemu_guest_agent block instead")
+		// convert to qemu_guest_agent block value
+		c.GuestAgent.Enabled = config.TriTrue
+	}
+
+	// Default qemu_guest_agent.enable to true
+	if c.GuestAgent.Enabled != config.TriFalse {
+		c.GuestAgent.Enabled = config.TriTrue
+	}
+	// Default qemu_guest_agent.freeze to true
+	if c.GuestAgent.Freeze != config.TriFalse {
+		c.GuestAgent.Freeze = config.TriTrue
+	}
+
+	switch c.GuestAgent.Type {
+	case "virtio", "isa":
+	case "":
+		log.Printf("qemu_guest_agent type not specified, defaulting to `virtio`")
+		c.GuestAgent.Type = "virtio"
+	default:
+		errs = packersdk.MultiErrorAppend(errs, errors.New("qemu_guest_agent type field must be `virtio` or `isa`"))
 	}
 
 	packersdk.LogSecretFilter.Set(c.Password)

diff --git a/builder/proxmox/common/config.hcl2spec.go b/builder/proxmox/common/config.hcl2spec.go
diff --git a/builder/proxmox/common/config_test.go b/builder/proxmox/common/config_test.go
@@ -63,6 +63,22 @@ func TestAgentSetToFalse(t *testing.T) {
 	}
 }
 
+func TestQemuAgentInvalidType(t *testing.T) {
+	cfg := mandatoryConfig(t)
+
+	agentCfg := make(map[string]interface{})
+	agentCfg["type"] = "qwerty"
+
+	cfg["qemu_guest_agent"] = agentCfg
+
+	var c Config
+	_, _, err := c.Prepare(&c, cfg)
+	// expect error, if none returned fail test
+	if err == nil {
+		t.Error("expected config preparation to fail, but no error occured")
+	}
+}
+
 func TestPacketQueueSupportForNetworkAdapters(t *testing.T) {
 	drivertests := []struct {
 		expectedToFail bool

diff --git a/builder/proxmox/common/step_start_vm.go b/builder/proxmox/common/step_start_vm.go
@@ -15,7 +15,6 @@ import (
 	"github.com/Telmate/proxmox-api-go/proxmox"
 	"github.com/hashicorp/packer-plugin-sdk/multistep"
 	packersdk "github.com/hashicorp/packer-plugin-sdk/packer"
-	"github.com/hashicorp/packer-plugin-sdk/template/config"
 )
 
 // stepStartVM takes the given configuration and starts a VM on the given Proxmox node.
@@ -121,7 +120,7 @@ func (s *stepStartVM) Run(ctx context.Context, state multistep.StateBag) multist
 
 	config := proxmox.ConfigQemu{
 		Name:           c.VMName,
-		Agent:          generateAgentConfig(c.Agent),
+		Agent:          generateAgentConfig(c.GuestAgent),
 		QemuKVM:        &kvm,
 		Tags:           generateTags(c.Tags),
 		Boot:           c.Boot, // Boot priority, example: "order=virtio0;ide2;net0", virtio0:Disk0 -> ide0:CDROM -> net0:Network
@@ -250,16 +249,18 @@ func (s *stepStartVM) Run(ctx context.Context, state multistep.StateBag) multist
 	return multistep.ActionContinue
 }
 
-func generateAgentConfig(agent config.Trilean) *proxmox.QemuGuestAgent {
-	var enableAgent bool
+func generateAgentConfig(agent agentConfig) *proxmox.QemuGuestAgent {
+	var agentCfg proxmox.QemuGuestAgent
 
-	if agent.True() {
-		enableAgent = true
-	}
+	agentCfg.Enable = agent.Enabled.ToBoolPointer()
+	agentCfg.Freeze = agent.Freeze.ToBoolPointer()
 
-	return &proxmox.QemuGuestAgent{
-		Enable: &enableAgent,
-	}
+	agentType := proxmox.QemuGuestAgentType(agent.Type)
+	agentCfg.Type = &agentType
+
+	agentCfg.FsTrim = &agent.FsTrim
+
+	return &agentCfg
 }
 
 func generateTags(rawTags string) *[]proxmox.Tag {