chore: update driver_config.go

- Updated the docs for the driver configuration.
- Updated the error messages and corresponding tests for clarity and to be more idiomatic.

Signed-off-by: Ryan Johnson <ryan.johnson@broadcom.com>

.web-docs/components/builder/iso/README.md

@@ -723,44 +723,48 @@ wget http://{{ .HTTPIP }}:{{ .HTTPPort }}/foo/bar/preseed.cfg
 
 <!-- Code generated from the comments of the DriverConfig struct in builder/vmware/common/driver_config.go; DO NOT EDIT MANUALLY -->
 
-- `fusion_app_path` (string) - Path to "VMware Fusion.app". By default this is
-  /Applications/VMware Fusion.app but this setting allows you to
-  customize this.
+- `fusion_app_path` (string) - The installation path of the VMware Fusion application. Defaults to
+  `/Applications/VMware Fusion.app`
+
+  ~> **Note:** This is only required if you are using VMware Fusion as a
+  local desktop hypervisor and have installed it in a non-default location.
 
-- `remote_type` (string) - The type of remote machine that will be used to
-  build this VM rather than a local desktop product. The only value accepted
-  for this currently is esx5. If this is not set, a desktop product will
-  be used. By default, this is not set.
+- `remote_type` (string) - The type of remote hypervisor that will be used. If set, the remote
+  hypervisor will be used for the build. If not set, a local desktop
+  hypervisor (VMware Fusion or VMware Workstation) will be used.
+  Available options include `esx5` for VMware ESXi.
 
-- `remote_datastore` (string) - The path to the datastore where the VM will be stored
-  on the ESXi machine.
+- `remote_datastore` (string) - The datastore where the virtual machine will be stored on the ESXi host.
 
-- `remote_cache_datastore` (string) - The path to the datastore where supporting files
-  will be stored during the build on the remote machine.
+- `remote_cache_datastore` (string) - The datastore attached to the remote hypervisor to use for the build.
+  Supporting files such as ISOs and floppies are cached in this datastore
+  during the build. Defaults to `datastore1`.
 
-- `remote_cache_directory` (string) - The path where the ISO and/or floppy files will
-  be stored during the build on the remote machine. The path is relative to
-  the remote_cache_datastore on the remote machine.
+- `remote_cache_directory` (string) - The directory path on the remote cache datastore to use for the build.
+  Supporting files such as ISOs and floppies are cached in this directory,
+  relative to the `remote_cache_datastore`, during the build. Defaults to
+  `packer_cache`.
 
-- `cleanup_remote_cache` (bool) - When set to true, Packer will cleanup the cache folder where the ISO file is stored during the build on the remote machine.
-  By default, this is set to false.
+- `cleanup_remote_cache` (bool) - Remove items added to the remote cache after the build is complete.
+  Defaults to `false`.
 
-- `remote_host` (string) - The host of the remote machine used for access.
-  This is only required if remote_type is enabled.
+- `remote_host` (string) - The fully qualified domain name or IP address of the remote hypervisor
+  where the virtual machine is created.
+
+  ~> **Note:** Required if `remote_type` is set.
 
-- `remote_port` (int) - The SSH port of the remote machine
+- `remote_port` (int) - The SSH port of the remote hypervisor. Defaults to `22`.
 
-- `remote_username` (string) - The SSH username used to access the remote machine.
+- `remote_username` (string) - The SSH username for access to the remote hypervisor. Defaults to `root`.
 
-- `remote_password` (string) - The SSH password for access to the remote machine.
+- `remote_password` (string) - The SSH password for access to the remote hypervisor.
 
-- `remote_private_key_file` (string) - The SSH key for access to the remote machine.
+- `remote_private_key_file` (string) - The SSH key for access to the remote hypervisor.
 
-- `skip_validate_credentials` (bool) - When Packer is preparing to run a
-  remote hypervisor build, and export is not disable, by default it runs a no-op
-  ovftool command to make sure that the remote_username and remote_password
-  given are valid. If you set this flag to true, Packer will skip this
-  validation. Default: false.
+- `skip_validate_credentials` (bool) - Skip the validation of the credentials for access to the remote
+  hypervisor. By default, export is enabled and the plugin will validate
+  the credentials ('remote_username' and 'remote_password'), for use by
+  VMware OVF Tool, before starting the build. Defaults to `false`.
 
 <!-- End of code generated from the comments of the DriverConfig struct in builder/vmware/common/driver_config.go; -->
 

.web-docs/components/builder/vmx/README.md

@@ -495,44 +495,48 @@ wget http://{{ .HTTPIP }}:{{ .HTTPPort }}/foo/bar/preseed.cfg
 
 <!-- Code generated from the comments of the DriverConfig struct in builder/vmware/common/driver_config.go; DO NOT EDIT MANUALLY -->
 
-- `fusion_app_path` (string) - Path to "VMware Fusion.app". By default this is
-  /Applications/VMware Fusion.app but this setting allows you to
-  customize this.
+- `fusion_app_path` (string) - The installation path of the VMware Fusion application. Defaults to
+  `/Applications/VMware Fusion.app`
+
+  ~> **Note:** This is only required if you are using VMware Fusion as a
+  local desktop hypervisor and have installed it in a non-default location.
 
-- `remote_type` (string) - The type of remote machine that will be used to
-  build this VM rather than a local desktop product. The only value accepted
-  for this currently is esx5. If this is not set, a desktop product will
-  be used. By default, this is not set.
+- `remote_type` (string) - The type of remote hypervisor that will be used. If set, the remote
+  hypervisor will be used for the build. If not set, a local desktop
+  hypervisor (VMware Fusion or VMware Workstation) will be used.
+  Available options include `esx5` for VMware ESXi.
 
-- `remote_datastore` (string) - The path to the datastore where the VM will be stored
-  on the ESXi machine.
+- `remote_datastore` (string) - The datastore where the virtual machine will be stored on the ESXi host.
 
-- `remote_cache_datastore` (string) - The path to the datastore where supporting files
-  will be stored during the build on the remote machine.
+- `remote_cache_datastore` (string) - The datastore attached to the remote hypervisor to use for the build.
+  Supporting files such as ISOs and floppies are cached in this datastore
+  during the build. Defaults to `datastore1`.
 
-- `remote_cache_directory` (string) - The path where the ISO and/or floppy files will
-  be stored during the build on the remote machine. The path is relative to
-  the remote_cache_datastore on the remote machine.
+- `remote_cache_directory` (string) - The directory path on the remote cache datastore to use for the build.
+  Supporting files such as ISOs and floppies are cached in this directory,
+  relative to the `remote_cache_datastore`, during the build. Defaults to
+  `packer_cache`.
 
-- `cleanup_remote_cache` (bool) - When set to true, Packer will cleanup the cache folder where the ISO file is stored during the build on the remote machine.
-  By default, this is set to false.
+- `cleanup_remote_cache` (bool) - Remove items added to the remote cache after the build is complete.
+  Defaults to `false`.
 
-- `remote_host` (string) - The host of the remote machine used for access.
-  This is only required if remote_type is enabled.
+- `remote_host` (string) - The fully qualified domain name or IP address of the remote hypervisor
+  where the virtual machine is created.
+
+  ~> **Note:** Required if `remote_type` is set.
 
-- `remote_port` (int) - The SSH port of the remote machine
+- `remote_port` (int) - The SSH port of the remote hypervisor. Defaults to `22`.
 
-- `remote_username` (string) - The SSH username used to access the remote machine.
+- `remote_username` (string) - The SSH username for access to the remote hypervisor. Defaults to `root`.
 
-- `remote_password` (string) - The SSH password for access to the remote machine.
+- `remote_password` (string) - The SSH password for access to the remote hypervisor.
 
-- `remote_private_key_file` (string) - The SSH key for access to the remote machine.
+- `remote_private_key_file` (string) - The SSH key for access to the remote hypervisor.
 
-- `skip_validate_credentials` (bool) - When Packer is preparing to run a
-  remote hypervisor build, and export is not disable, by default it runs a no-op
-  ovftool command to make sure that the remote_username and remote_password
-  given are valid. If you set this flag to true, Packer will skip this
-  validation. Default: false.
+- `skip_validate_credentials` (bool) - Skip the validation of the credentials for access to the remote
+  hypervisor. By default, export is enabled and the plugin will validate
+  the credentials ('remote_username' and 'remote_password'), for use by
+  VMware OVF Tool, before starting the build. Defaults to `false`.
 
 <!-- End of code generated from the comments of the DriverConfig struct in builder/vmware/common/driver_config.go; -->
 

builder/vmware/common/driver_config.go

@@ -6,51 +6,55 @@
 package common
 
 import (
-	"fmt"
+	"errors"
 	"os"
 
 	"github.com/hashicorp/packer-plugin-sdk/template/interpolate"
 )
 
 type DriverConfig struct {
-	// Path to "VMware Fusion.app". By default this is
-	// /Applications/VMware Fusion.app but this setting allows you to
-	// customize this.
+	// The installation path of the VMware Fusion application. Defaults to
+	// `/Applications/VMware Fusion.app`
+	//
+	// ~> **Note:** This is only required if you are using VMware Fusion as a
+	// local desktop hypervisor and have installed it in a non-default location.
 	FusionAppPath string `mapstructure:"fusion_app_path" required:"false"`
-	// The type of remote machine that will be used to
-	// build this VM rather than a local desktop product. The only value accepted
-	// for this currently is esx5. If this is not set, a desktop product will
-	// be used. By default, this is not set.
+	// The type of remote hypervisor that will be used. If set, the remote
+	// hypervisor will be used for the build. If not set, a local desktop
+	// hypervisor (VMware Fusion or VMware Workstation) will be used.
+	// Available options include `esx5` for VMware ESXi.
 	RemoteType string `mapstructure:"remote_type" required:"false"`
-	// The path to the datastore where the VM will be stored
-	// on the ESXi machine.
+	// The datastore where the virtual machine will be stored on the ESXi host.
 	RemoteDatastore string `mapstructure:"remote_datastore" required:"false"`
-	// The path to the datastore where supporting files
-	// will be stored during the build on the remote machine.
+	// The datastore attached to the remote hypervisor to use for the build.
+	// Supporting files such as ISOs and floppies are cached in this datastore
+	// during the build. Defaults to `datastore1`.
 	RemoteCacheDatastore string `mapstructure:"remote_cache_datastore" required:"false"`
-	// The path where the ISO and/or floppy files will
-	// be stored during the build on the remote machine. The path is relative to
-	// the remote_cache_datastore on the remote machine.
+	// The directory path on the remote cache datastore to use for the build.
+	// Supporting files such as ISOs and floppies are cached in this directory,
+	// relative to the `remote_cache_datastore`, during the build. Defaults to
+	// `packer_cache`.
 	RemoteCacheDirectory string `mapstructure:"remote_cache_directory" required:"false"`
-	// When set to true, Packer will cleanup the cache folder where the ISO file is stored during the build on the remote machine.
-	// By default, this is set to false.
+	// Remove items added to the remote cache after the build is complete.
+	// Defaults to `false`.
 	CleanUpRemoteCache bool `mapstructure:"cleanup_remote_cache" required:"false"`
-	// The host of the remote machine used for access.
-	// This is only required if remote_type is enabled.
+	// The fully qualified domain name or IP address of the remote hypervisor
+	// where the virtual machine is created.
+	//
+	// ~> **Note:** Required if `remote_type` is set.
 	RemoteHost string `mapstructure:"remote_host" required:"false"`
-	// The SSH port of the remote machine
+	// The SSH port of the remote hypervisor. Defaults to `22`.
 	RemotePort int `mapstructure:"remote_port" required:"false"`
-	// The SSH username used to access the remote machine.
+	// The SSH username for access to the remote hypervisor. Defaults to `root`.
 	RemoteUser string `mapstructure:"remote_username" required:"false"`
-	// The SSH password for access to the remote machine.
+	// The SSH password for access to the remote hypervisor.
 	RemotePassword string `mapstructure:"remote_password" required:"false"`
-	// The SSH key for access to the remote machine.
+	// The SSH key for access to the remote hypervisor.
 	RemotePrivateKey string `mapstructure:"remote_private_key_file" required:"false"`
-	// When Packer is preparing to run a
-	// remote hypervisor build, and export is not disable, by default it runs a no-op
-	// ovftool command to make sure that the remote_username and remote_password
-	// given are valid. If you set this flag to true, Packer will skip this
-	// validation. Default: false.
+	// Skip the validation of the credentials for access to the remote
+	// hypervisor. By default, export is enabled and the plugin will validate
+	// the credentials ('remote_username' and 'remote_password'), for use by
+	// VMware OVF Tool, before starting the build. Defaults to `false`.
 	SkipValidateCredentials bool `mapstructure:"skip_validate_credentials" required:"false"`
 }
 
@@ -60,34 +64,40 @@ func (c *DriverConfig) Prepare(ctx *interpolate.Context) []error {
 	if c.FusionAppPath == "" {
 		c.FusionAppPath = os.Getenv("FUSION_APP_PATH")
 	}
+
 	if c.FusionAppPath == "" {
 		c.FusionAppPath = "/Applications/VMware Fusion.app"
 	}
+
 	if c.RemoteUser == "" {
 		c.RemoteUser = "root"
 	}
+
 	if c.RemoteDatastore == "" {
 		c.RemoteDatastore = "datastore1"
 	}
+
 	if c.RemoteCacheDatastore == "" {
 		c.RemoteCacheDatastore = c.RemoteDatastore
 	}
+
 	if c.RemoteCacheDirectory == "" {
 		c.RemoteCacheDirectory = "packer_cache"
 	}
+
 	if c.RemotePort == 0 {
 		c.RemotePort = 22
 	}
 
 	if c.RemoteType != "" {
 		if c.RemoteHost == "" {
 			errs = append(errs,
-				fmt.Errorf("remote_host must be specified"))
+				errors.New("'remote_host' must be specified when 'remote_type' is set"))
 		}
 
 		if c.RemoteType != "esx5" {
 			errs = append(errs,
-				fmt.Errorf("only 'esx5' value is accepted for remote_type"))
+				errors.New("only 'esx5' value is accepted for 'remote_type'"))
 		}
 	}
 
@@ -100,8 +110,9 @@ func (c *DriverConfig) Validate(SkipExport bool) error {
 	}
 
 	if c.RemoteType != "" && c.RemotePassword == "" {
-		return fmt.Errorf("exporting the vm from esxi with ovftool requires " +
-			"that you set a value for remote_password")
+		return errors.New(
+			"'remote_password' must be provided when using 'export' with 'remote_type'",
+		)
 	}
 
 	return nil

builder/vmware/common/driver_config_test.go

@@ -4,7 +4,7 @@
 package common
 
 import (
-	"fmt"
+	"errors"
 	"testing"
 
 	"github.com/hashicorp/packer-plugin-sdk/template/interpolate"
@@ -57,15 +57,15 @@ func TestDriverConfigPrepare(t *testing.T) {
 				RemoteHost: "host",
 			},
 			expectedConfig: nil,
-			errs:           []error{fmt.Errorf("only 'esx5' value is accepted for remote_type")},
+			errs:           []error{errors.New("only 'esx5' value is accepted for 'remote_type'")},
 		},
 		{
 			name: "Remote host not set",
 			config: &DriverConfig{
 				RemoteType: "esx5",
 			},
 			expectedConfig: nil,
-			errs:           []error{fmt.Errorf("remote_host must be specified")},
+			errs:           []error{errors.New("'remote_host' must be specified when 'remote_type' is set")},
 		},
 	}
 

docs-partials/builder/vmware/common/DriverConfig-not-required.mdx

@@ -1,42 +1,46 @@
 <!-- Code generated from the comments of the DriverConfig struct in builder/vmware/common/driver_config.go; DO NOT EDIT MANUALLY -->
 
-- `fusion_app_path` (string) - Path to "VMware Fusion.app". By default this is
-  /Applications/VMware Fusion.app but this setting allows you to
-  customize this.
+- `fusion_app_path` (string) - The installation path of the VMware Fusion application. Defaults to
+  `/Applications/VMware Fusion.app`
+
+  ~> **Note:** This is only required if you are using VMware Fusion as a
+  local desktop hypervisor and have installed it in a non-default location.
 
-- `remote_type` (string) - The type of remote machine that will be used to
-  build this VM rather than a local desktop product. The only value accepted
-  for this currently is esx5. If this is not set, a desktop product will
-  be used. By default, this is not set.
+- `remote_type` (string) - The type of remote hypervisor that will be used. If set, the remote
+  hypervisor will be used for the build. If not set, a local desktop
+  hypervisor (VMware Fusion or VMware Workstation) will be used.
+  Available options include `esx5` for VMware ESXi.
 
-- `remote_datastore` (string) - The path to the datastore where the VM will be stored
-  on the ESXi machine.
+- `remote_datastore` (string) - The datastore where the virtual machine will be stored on the ESXi host.
 
-- `remote_cache_datastore` (string) - The path to the datastore where supporting files
-  will be stored during the build on the remote machine.
+- `remote_cache_datastore` (string) - The datastore attached to the remote hypervisor to use for the build.
+  Supporting files such as ISOs and floppies are cached in this datastore
+  during the build. Defaults to `datastore1`.
 
-- `remote_cache_directory` (string) - The path where the ISO and/or floppy files will
-  be stored during the build on the remote machine. The path is relative to
-  the remote_cache_datastore on the remote machine.
+- `remote_cache_directory` (string) - The directory path on the remote cache datastore to use for the build.
+  Supporting files such as ISOs and floppies are cached in this directory,
+  relative to the `remote_cache_datastore`, during the build. Defaults to
+  `packer_cache`.
 
-- `cleanup_remote_cache` (bool) - When set to true, Packer will cleanup the cache folder where the ISO file is stored during the build on the remote machine.
-  By default, this is set to false.
+- `cleanup_remote_cache` (bool) - Remove items added to the remote cache after the build is complete.
+  Defaults to `false`.
 
-- `remote_host` (string) - The host of the remote machine used for access.
-  This is only required if remote_type is enabled.
+- `remote_host` (string) - The fully qualified domain name or IP address of the remote hypervisor
+  where the virtual machine is created.
+
+  ~> **Note:** Required if `remote_type` is set.
 
-- `remote_port` (int) - The SSH port of the remote machine
+- `remote_port` (int) - The SSH port of the remote hypervisor. Defaults to `22`.
 
-- `remote_username` (string) - The SSH username used to access the remote machine.
+- `remote_username` (string) - The SSH username for access to the remote hypervisor. Defaults to `root`.
 
-- `remote_password` (string) - The SSH password for access to the remote machine.
+- `remote_password` (string) - The SSH password for access to the remote hypervisor.
 
-- `remote_private_key_file` (string) - The SSH key for access to the remote machine.
+- `remote_private_key_file` (string) - The SSH key for access to the remote hypervisor.
 
-- `skip_validate_credentials` (bool) - When Packer is preparing to run a
-  remote hypervisor build, and export is not disable, by default it runs a no-op
-  ovftool command to make sure that the remote_username and remote_password
-  given are valid. If you set this flag to true, Packer will skip this
-  validation. Default: false.
+- `skip_validate_credentials` (bool) - Skip the validation of the credentials for access to the remote
+  hypervisor. By default, export is enabled and the plugin will validate
+  the credentials ('remote_username' and 'remote_password'), for use by
+  VMware OVF Tool, before starting the build. Defaults to `false`.
 
 <!-- End of code generated from the comments of the DriverConfig struct in builder/vmware/common/driver_config.go; -->