From 2417d6c8631b9f8604dc621051307f409a80687c Mon Sep 17 00:00:00 2001 From: Ryan Johnson Date: Thu, 15 Aug 2024 10:37:17 -0400 Subject: [PATCH] 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 --- .web-docs/components/builder/iso/README.md | 58 +++++++------- .web-docs/components/builder/vmx/README.md | 58 +++++++------- builder/vmware/common/driver_config.go | 75 +++++++++++-------- builder/vmware/common/driver_config_test.go | 6 +- .../common/DriverConfig-not-required.mdx | 58 +++++++------- 5 files changed, 139 insertions(+), 116 deletions(-) diff --git a/.web-docs/components/builder/iso/README.md b/.web-docs/components/builder/iso/README.md index 1a514934..7e7492aa 100644 --- a/.web-docs/components/builder/iso/README.md +++ b/.web-docs/components/builder/iso/README.md @@ -723,44 +723,48 @@ wget http://{{ .HTTPIP }}:{{ .HTTPPort }}/foo/bar/preseed.cfg -- `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`. diff --git a/.web-docs/components/builder/vmx/README.md b/.web-docs/components/builder/vmx/README.md index f52db8e5..5b204084 100644 --- a/.web-docs/components/builder/vmx/README.md +++ b/.web-docs/components/builder/vmx/README.md @@ -495,44 +495,48 @@ wget http://{{ .HTTPIP }}:{{ .HTTPPort }}/foo/bar/preseed.cfg -- `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`. diff --git a/builder/vmware/common/driver_config.go b/builder/vmware/common/driver_config.go index b56514c6..f1766c98 100644 --- a/builder/vmware/common/driver_config.go +++ b/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,21 +64,27 @@ 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 } @@ -82,12 +92,12 @@ func (c *DriverConfig) Prepare(ctx *interpolate.Context) []error { 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 diff --git a/builder/vmware/common/driver_config_test.go b/builder/vmware/common/driver_config_test.go index bd9d98e0..2e64c41b 100644 --- a/builder/vmware/common/driver_config_test.go +++ b/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,7 +57,7 @@ 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", @@ -65,7 +65,7 @@ func TestDriverConfigPrepare(t *testing.T) { 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")}, }, } diff --git a/docs-partials/builder/vmware/common/DriverConfig-not-required.mdx b/docs-partials/builder/vmware/common/DriverConfig-not-required.mdx index dd2e13c3..cb0471a1 100644 --- a/docs-partials/builder/vmware/common/DriverConfig-not-required.mdx +++ b/docs-partials/builder/vmware/common/DriverConfig-not-required.mdx @@ -1,42 +1,46 @@ -- `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`.