chore: update run config (#223)

- Updates comments for more streamlined documentation. - Removes the use of "magic" numbers and defines constants. Signed-off-by: Ryan Johnson <[email protected]>
hashicorp · Jul 17, 2024 · 7fa57d8 · 7fa57d8
1 parent d00e38f
commit 7fa57d8
Show file tree

Hide file tree

Showing 8 changed files with 190 additions and 172 deletions.
diff --git a/.web-docs/components/builder/iso/README.md b/.web-docs/components/builder/iso/README.md
@@ -709,52 +709,54 @@ provisioner](/packer/docs/provisioner/file).
 
 ### Run configuration
 
-<!-- Code generated from the comments of the RunConfig struct in builder/vmware/common/run_config.go; DO NOT EDIT MANUALLY -->
-
-~> **Note:** If [vnc_over_websocket](#vnc_over_websocket) is set to true, any other VNC configuration will be ignored.
+#### Optional:
 
-<!-- End of code generated from the comments of the RunConfig struct in builder/vmware/common/run_config.go; -->
+<!-- Code generated from the comments of the RunConfig struct in builder/vmware/common/run_config.go; DO NOT EDIT MANUALLY -->
 
+- `headless` (bool) - The plugin defaults to building virtual machines by launching the
+  desktop hypervisor's graphical user interface (GUI) to display the
+  console of the virtual machine being built. When this value is set to
+  `true`, the virtual machine will start without a console; however, the
+  plugin will output VNC connection information in case you need to connect
+  to the console to debug the build process. Defaults to `false`.
+
+  ~> **Note:** Some users have experienced issues where Packer cannot
+  properly connect to a virtual machine when using `headless`. This is
+  often attributed to the use of an evaluation license for VMware desktop
+  hypervisors. It is recommended to launch the product and accept the
+  evaluation license to resolve this if you encounter an issue with this
+  option.
+
+- `vnc_bind_address` (string) - The IP address to use for VNC access to the virtual machine. Defaults to
+  `127.0.0.1`.
+
+  ~> **Note:** To bind to all interfaces use `0.0.0.0`.
 
-#### Optional:
+- `vnc_port_min` (int) - The minimum port number to use for VNC access to the virtual machine.
+  The plugin uses VNC to type the `boot_command`. Defaults to `5900`.
 
-<!-- Code generated from the comments of the RunConfig struct in builder/vmware/common/run_config.go; DO NOT EDIT MANUALLY -->
+- `vnc_port_max` (int) - The maximum port number to use for VNC access to the virtual machine.
+  The plugin uses VNC to type the `boot_command`. Defaults to `6000`.
+
+  ~> **Note:** The plugin randomly selects port within the inclusive range
+  specified by `vnc_port_min` and `vnc_port_max`.
 
-- `headless` (bool) - Packer defaults to building VMware virtual machines
-  by launching a GUI that shows the console of the machine being built. When
-  this value is set to true, the machine will start without a console. For
-  VMware machines, Packer will output VNC connection information in case you
-  need to connect to the console to debug the build process.
-  Some users have experienced issues where Packer cannot properly connect
-  to a VM if it is headless; this appears to be a result of not ever having
-  launched the VMware GUI and accepting the evaluation license, or
-  supplying a real license. If you experience this, launching VMware and
-  accepting the license should resolve your problem.
-
-- `vnc_bind_address` (string) - The IP address that should be
-  binded to for VNC. By default packer will use 127.0.0.1 for this. If you
-  wish to bind to all interfaces use 0.0.0.0.
-
-- `vnc_port_min` (int) - The minimum and maximum port
-  to use for VNC access to the virtual machine. The builder uses VNC to type
-  the initial boot_command. Because Packer generally runs in parallel,
-  Packer uses a randomly chosen port in this range that appears available. By
-  default this is 5900 to 6000. The minimum and maximum ports are
-  inclusive.
-
-- `vnc_port_max` (int) - VNC Port Max
-
-- `vnc_disable_password` (bool) - Don't auto-generate a VNC password that
-  is used to secure the VNC communication with the VM. This must be set to
-  true if building on ESXi 6.5 and 6.7 with VNC enabled. Defaults to
-  false.
+- `vnc_disable_password` (bool) - Disables the auto-generation of a VNC password that is used to secure the
+  VNC communication with the virtual machine. Defaults to `false`.
+
+  ~> **Important:** Must be set to `true` for remote hypervisor builds with
+  VNC enabled.
 
-- `vnc_over_websocket` (bool) - When set to true, Packer will connect to the remote VNC server over a websocket connection
-  and any other VNC configuration option will be ignored.
-  Remote builds using ESXi 6.7+ allows to connect to the VNC server only over websocket,
-  for these the `vnc_over_websocket` must be set to true.
+- `vnc_over_websocket` (bool) - Connect to VNC over a websocket connection. Defaults to `false`.
+
+  ~> **Note:** When set to `true`, any other VNC configuration options will
+  be ignored.
+
+  ~> **Important:** Must be set to `true` for remote hypervisor builds with
+  VNC enabled.
 
-- `insecure_connection` (bool) - Do not validate VNC over websocket server's TLS certificate. Defaults to `false`.
+- `insecure_connection` (bool) - Do not validate TLS certificate when connecting to VNC over a websocket
+  connection. Defaults to `false`.
 
 <!-- End of code generated from the comments of the RunConfig struct in builder/vmware/common/run_config.go; -->
 

diff --git a/.web-docs/components/builder/vmx/README.md b/.web-docs/components/builder/vmx/README.md
@@ -468,52 +468,54 @@ boot time.
 
 ### Run configuration
 
-<!-- Code generated from the comments of the RunConfig struct in builder/vmware/common/run_config.go; DO NOT EDIT MANUALLY -->
-
-~> **Note:** If [vnc_over_websocket](#vnc_over_websocket) is set to true, any other VNC configuration will be ignored.
+#### Optional:
 
-<!-- End of code generated from the comments of the RunConfig struct in builder/vmware/common/run_config.go; -->
+<!-- Code generated from the comments of the RunConfig struct in builder/vmware/common/run_config.go; DO NOT EDIT MANUALLY -->
 
+- `headless` (bool) - The plugin defaults to building virtual machines by launching the
+  desktop hypervisor's graphical user interface (GUI) to display the
+  console of the virtual machine being built. When this value is set to
+  `true`, the virtual machine will start without a console; however, the
+  plugin will output VNC connection information in case you need to connect
+  to the console to debug the build process. Defaults to `false`.
+
+  ~> **Note:** Some users have experienced issues where Packer cannot
+  properly connect to a virtual machine when using `headless`. This is
+  often attributed to the use of an evaluation license for VMware desktop
+  hypervisors. It is recommended to launch the product and accept the
+  evaluation license to resolve this if you encounter an issue with this
+  option.
+
+- `vnc_bind_address` (string) - The IP address to use for VNC access to the virtual machine. Defaults to
+  `127.0.0.1`.
+
+  ~> **Note:** To bind to all interfaces use `0.0.0.0`.
 
-#### Optional:
+- `vnc_port_min` (int) - The minimum port number to use for VNC access to the virtual machine.
+  The plugin uses VNC to type the `boot_command`. Defaults to `5900`.
 
-<!-- Code generated from the comments of the RunConfig struct in builder/vmware/common/run_config.go; DO NOT EDIT MANUALLY -->
+- `vnc_port_max` (int) - The maximum port number to use for VNC access to the virtual machine.
+  The plugin uses VNC to type the `boot_command`. Defaults to `6000`.
+
+  ~> **Note:** The plugin randomly selects port within the inclusive range
+  specified by `vnc_port_min` and `vnc_port_max`.
 
-- `headless` (bool) - Packer defaults to building VMware virtual machines
-  by launching a GUI that shows the console of the machine being built. When
-  this value is set to true, the machine will start without a console. For
-  VMware machines, Packer will output VNC connection information in case you
-  need to connect to the console to debug the build process.
-  Some users have experienced issues where Packer cannot properly connect
-  to a VM if it is headless; this appears to be a result of not ever having
-  launched the VMware GUI and accepting the evaluation license, or
-  supplying a real license. If you experience this, launching VMware and
-  accepting the license should resolve your problem.
-
-- `vnc_bind_address` (string) - The IP address that should be
-  binded to for VNC. By default packer will use 127.0.0.1 for this. If you
-  wish to bind to all interfaces use 0.0.0.0.
-
-- `vnc_port_min` (int) - The minimum and maximum port
-  to use for VNC access to the virtual machine. The builder uses VNC to type
-  the initial boot_command. Because Packer generally runs in parallel,
-  Packer uses a randomly chosen port in this range that appears available. By
-  default this is 5900 to 6000. The minimum and maximum ports are
-  inclusive.
-
-- `vnc_port_max` (int) - VNC Port Max
-
-- `vnc_disable_password` (bool) - Don't auto-generate a VNC password that
-  is used to secure the VNC communication with the VM. This must be set to
-  true if building on ESXi 6.5 and 6.7 with VNC enabled. Defaults to
-  false.
+- `vnc_disable_password` (bool) - Disables the auto-generation of a VNC password that is used to secure the
+  VNC communication with the virtual machine. Defaults to `false`.
+
+  ~> **Important:** Must be set to `true` for remote hypervisor builds with
+  VNC enabled.
 
-- `vnc_over_websocket` (bool) - When set to true, Packer will connect to the remote VNC server over a websocket connection
-  and any other VNC configuration option will be ignored.
-  Remote builds using ESXi 6.7+ allows to connect to the VNC server only over websocket,
-  for these the `vnc_over_websocket` must be set to true.
+- `vnc_over_websocket` (bool) - Connect to VNC over a websocket connection. Defaults to `false`.
+
+  ~> **Note:** When set to `true`, any other VNC configuration options will
+  be ignored.
+
+  ~> **Important:** Must be set to `true` for remote hypervisor builds with
+  VNC enabled.
 
-- `insecure_connection` (bool) - Do not validate VNC over websocket server's TLS certificate. Defaults to `false`.
+- `insecure_connection` (bool) - Do not validate TLS certificate when connecting to VNC over a websocket
+  connection. Defaults to `false`.
 
 <!-- End of code generated from the comments of the RunConfig struct in builder/vmware/common/run_config.go; -->
 

diff --git a/builder/vmware/common/run_config.go b/builder/vmware/common/run_config.go
@@ -11,75 +11,90 @@ import (
 	"github.com/hashicorp/packer-plugin-sdk/template/interpolate"
 )
 
-// ~> **Note:** If [vnc_over_websocket](#vnc_over_websocket) is set to true, any other VNC configuration will be ignored.
+const (
+	defaultVNCPortMin     = 5900
+	defaultVNCPortMax     = 6000
+	defaultVNCBindAddress = "127.0.0.1"
+)
+
 type RunConfig struct {
-	// Packer defaults to building VMware virtual machines
-	// by launching a GUI that shows the console of the machine being built. When
-	// this value is set to true, the machine will start without a console. For
-	// VMware machines, Packer will output VNC connection information in case you
-	// need to connect to the console to debug the build process.
-	// Some users have experienced issues where Packer cannot properly connect
-	// to a VM if it is headless; this appears to be a result of not ever having
-	// launched the VMware GUI and accepting the evaluation license, or
-	// supplying a real license. If you experience this, launching VMware and
-	// accepting the license should resolve your problem.
+	// The plugin defaults to building virtual machines by launching the
+	// desktop hypervisor's graphical user interface (GUI) to display the
+	// console of the virtual machine being built. When this value is set to
+	// `true`, the virtual machine will start without a console; however, the
+	// plugin will output VNC connection information in case you need to connect
+	// to the console to debug the build process. Defaults to `false`.
+	//
+	// ~> **Note:** Some users have experienced issues where Packer cannot
+	// properly connect to a virtual machine when using `headless`. This is
+	// often attributed to the use of an evaluation license for VMware desktop
+	// hypervisors. It is recommended to launch the product and accept the
+	// evaluation license to resolve this if you encounter an issue with this
+	// option.
 	Headless bool `mapstructure:"headless" required:"false"`
-	// The IP address that should be
-	// binded to for VNC. By default packer will use 127.0.0.1 for this. If you
-	// wish to bind to all interfaces use 0.0.0.0.
+	// The IP address to use for VNC access to the virtual machine. Defaults to
+	// `127.0.0.1`.
+	//
+	// ~> **Note:** To bind to all interfaces use `0.0.0.0`.
 	VNCBindAddress string `mapstructure:"vnc_bind_address" required:"false"`
-	// The minimum and maximum port
-	// to use for VNC access to the virtual machine. The builder uses VNC to type
-	// the initial boot_command. Because Packer generally runs in parallel,
-	// Packer uses a randomly chosen port in this range that appears available. By
-	// default this is 5900 to 6000. The minimum and maximum ports are
-	// inclusive.
+	// The minimum port number to use for VNC access to the virtual machine.
+	// The plugin uses VNC to type the `boot_command`. Defaults to `5900`.
 	VNCPortMin int `mapstructure:"vnc_port_min" required:"false"`
+	// The maximum port number to use for VNC access to the virtual machine.
+	// The plugin uses VNC to type the `boot_command`. Defaults to `6000`.
+	//
+	// ~> **Note:** The plugin randomly selects port within the inclusive range
+	// specified by `vnc_port_min` and `vnc_port_max`.
 	VNCPortMax int `mapstructure:"vnc_port_max"`
-	// Don't auto-generate a VNC password that
-	// is used to secure the VNC communication with the VM. This must be set to
-	// true if building on ESXi 6.5 and 6.7 with VNC enabled. Defaults to
-	// false.
+	// Disables the auto-generation of a VNC password that is used to secure the
+	// VNC communication with the virtual machine. Defaults to `false`.
+	//
+	// ~> **Important:** Must be set to `true` for remote hypervisor builds with
+	// VNC enabled.
 	VNCDisablePassword bool `mapstructure:"vnc_disable_password" required:"false"`
-	// When set to true, Packer will connect to the remote VNC server over a websocket connection
-	// and any other VNC configuration option will be ignored.
-	// Remote builds using ESXi 6.7+ allows to connect to the VNC server only over websocket,
-	// for these the `vnc_over_websocket` must be set to true.
+	// Connect to VNC over a websocket connection. Defaults to `false`.
+	//
+	// ~> **Note:** When set to `true`, any other VNC configuration options will
+	// be ignored.
+	//
+	// ~> **Important:** Must be set to `true` for remote hypervisor builds with
+	// VNC enabled.
 	VNCOverWebsocket bool `mapstructure:"vnc_over_websocket" required:"false"`
-	// Do not validate VNC over websocket server's TLS certificate. Defaults to `false`.
+	// Do not validate TLS certificate when connecting to VNC over a websocket
+	// connection. Defaults to `false`.
 	InsecureConnection bool `mapstructure:"insecure_connection" required:"false"`
 }
 
 func (c *RunConfig) Prepare(_ *interpolate.Context, driverConfig *DriverConfig) (warnings []string, errs []error) {
 	if c.VNCOverWebsocket {
 		if driverConfig.RemoteType == "" {
-			errs = append(errs, fmt.Errorf("'vnc_over_websocket' can only be used with remote builds"))
+			errs = append(errs, fmt.Errorf("'vnc_over_websocket' can only be used with remote hypervisor builds"))
 			return
 		}
 		if c.VNCPortMin != 0 || c.VNCPortMax != 0 || c.VNCBindAddress != "" || c.VNCDisablePassword {
-			warnings = append(warnings, "[WARN] When 'vnc_over_websocket' is set "+
-				"any other VNC configuration will be ignored.")
+			warnings = append(warnings, "[WARN] 'vnc_over_websocket' enabled, any other VNC configuration will be ignored.")
 		}
 		return
 	}
 
 	if c.VNCPortMin == 0 {
-		c.VNCPortMin = 5900
+		c.VNCPortMin = defaultVNCPortMin
 	}
 
 	if c.VNCPortMax == 0 {
-		c.VNCPortMax = 6000
+		c.VNCPortMax = defaultVNCPortMax
 	}
 
 	if c.VNCBindAddress == "" {
-		c.VNCBindAddress = "127.0.0.1"
+		c.VNCBindAddress = defaultVNCBindAddress
 	}
 
 	if c.VNCPortMin > c.VNCPortMax {
-		errs = append(errs, fmt.Errorf("vnc_port_min must be less than vnc_port_max"))
+		errs = append(errs, fmt.Errorf("'vnc_port_min' must be less than 'vnc_port_max'"))
 	}
+
 	if c.VNCPortMin < 0 {
-		errs = append(errs, fmt.Errorf("vnc_port_min must be positive"))
+		errs = append(errs, fmt.Errorf("'vnc_port_min' must be positive"))
 	}
 
 	return

diff --git a/builder/vmware/common/run_config_test.go b/builder/vmware/common/run_config_test.go
@@ -23,7 +23,7 @@ func TestRunConfig_Prepare(t *testing.T) {
 		warnings       []string
 	}{
 		{
-			name:   "VNC defaults",
+			name:   "Default configuration.",
 			config: &RunConfig{},
 			expectedConfig: &RunConfig{
 				VNCPortMin:     5900,
@@ -35,7 +35,7 @@ func TestRunConfig_Prepare(t *testing.T) {
 			warnings: nil,
 		},
 		{
-			name: "VNC port min less than vnc port max",
+			name: "Minimum port less than maximum port.",
 			config: &RunConfig{
 				VNCPortMin: 5000,
 				VNCPortMax: 5900,
@@ -50,38 +50,38 @@ func TestRunConfig_Prepare(t *testing.T) {
 			warnings: nil,
 		},
 		{
-			name: "VNC port min bigger than vnc port max",
+			name: "Minimum port greater than maximum port.",
 			config: &RunConfig{
 				VNCPortMin: 5900,
 				VNCPortMax: 5000,
 			},
 			expectedConfig: nil,
 			driver:         new(DriverConfig),
-			errs:           []error{fmt.Errorf("vnc_port_min must be less than vnc_port_max")},
+			errs:           []error{fmt.Errorf("'vnc_port_min' must be less than 'vnc_port_max'")},
 			warnings:       nil,
 		},
 		{
-			name: "VNC port min must be positive",
+			name: "Minimum port must be positive.",
 			config: &RunConfig{
 				VNCPortMin: -1,
 			},
 			expectedConfig: nil,
 			driver:         new(DriverConfig),
-			errs:           []error{fmt.Errorf("vnc_port_min must be positive")},
+			errs:           []error{fmt.Errorf("'vnc_port_min' must be positive")},
 			warnings:       nil,
 		},
 		{
-			name: "fail when vnc_over_websocket set when remote_type is not set",
+			name: "If a remote hypervisor build, 'vnc_over_websocket' must be enabled.",
 			config: &RunConfig{
 				VNCOverWebsocket: true,
 			},
 			expectedConfig: nil,
 			driver:         new(DriverConfig),
-			errs:           []error{fmt.Errorf("'vnc_over_websocket' can only be used with remote builds")},
+			errs:           []error{fmt.Errorf("'vnc_over_websocket' can only be used with remote hypervisor builds")},
 			warnings:       nil,
 		},
 		{
-			name: "warn about ignored vnc configuration",
+			name: "Return warnings when 'vnc_over_websocket' is enabled.",
 			config: &RunConfig{
 				VNCOverWebsocket: true,
 				VNCPortMin:       5000,
@@ -92,10 +92,9 @@ func TestRunConfig_Prepare(t *testing.T) {
 				VNCPortMin:       5000,
 				VNCPortMax:       5900,
 			},
-			driver: &DriverConfig{RemoteType: "esxi"},
-			errs:   nil,
-			warnings: []string{"[WARN] When 'vnc_over_websocket' is set " +
-				"any other VNC configuration will be ignored."},
+			driver:   &DriverConfig{RemoteType: "esx5"},
+			errs:     nil,
+			warnings: []string{"[WARN] 'vnc_over_websocket' enabled, any other VNC configuration will be ignored."},
 		},
 	}