From 98a9f7cc7ead9cbb33804b27007e9734278ef2ae Mon Sep 17 00:00:00 2001 From: Ryan Johnson Date: Sun, 7 Jul 2024 23:13:22 -0400 Subject: [PATCH] chore: update run config - Updates comments for more streamlined documentation. - Removes the use of "magic" numbers and defines constants. Signed-off-by: Ryan Johnson --- .web-docs/components/builder/iso/README.md | 80 +++++++++-------- .web-docs/components/builder/vmx/README.md | 80 +++++++++-------- builder/vmware/common/run_config.go | 89 +++++++++++-------- builder/vmware/common/run_config_test.go | 25 +++--- .../vmware/common/RunConfig-not-required.mdx | 79 ++++++++-------- .../builder/vmware/common/RunConfig.mdx | 5 -- docs/builders/iso.mdx | 2 - docs/builders/vmx.mdx | 2 - 8 files changed, 190 insertions(+), 172 deletions(-) delete mode 100644 docs-partials/builder/vmware/common/RunConfig.mdx diff --git a/.web-docs/components/builder/iso/README.md b/.web-docs/components/builder/iso/README.md index cc078734..b1a096b5 100644 --- 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 - - -~> **Note:** If [vnc_over_websocket](#vnc_over_websocket) is set to true, any other VNC configuration will be ignored. +#### Optional: - + +- `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`. - +- `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`. diff --git a/.web-docs/components/builder/vmx/README.md b/.web-docs/components/builder/vmx/README.md index 725e18ba..44e1d4e9 100644 --- a/.web-docs/components/builder/vmx/README.md +++ b/.web-docs/components/builder/vmx/README.md @@ -468,52 +468,54 @@ boot time. ### Run configuration - - -~> **Note:** If [vnc_over_websocket](#vnc_over_websocket) is set to true, any other VNC configuration will be ignored. +#### Optional: - + +- `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`. - +- `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`. diff --git a/builder/vmware/common/run_config.go b/builder/vmware/common/run_config.go index 15bff871..f95178b1 100644 --- 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 index 27d01edf..b8e3dfd5 100644 --- 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."}, }, } diff --git a/docs-partials/builder/vmware/common/RunConfig-not-required.mdx b/docs-partials/builder/vmware/common/RunConfig-not-required.mdx index ed189129..2c4c92d7 100644 --- a/docs-partials/builder/vmware/common/RunConfig-not-required.mdx +++ b/docs-partials/builder/vmware/common/RunConfig-not-required.mdx @@ -1,39 +1,48 @@ -- `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_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. - -- `insecure_connection` (bool) - Do not validate VNC over websocket server's TLS certificate. Defaults to `false`. +- `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`. + +- `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`. + +- `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`. + +- `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) - 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 TLS certificate when connecting to VNC over a websocket + connection. Defaults to `false`. diff --git a/docs-partials/builder/vmware/common/RunConfig.mdx b/docs-partials/builder/vmware/common/RunConfig.mdx deleted file mode 100644 index 0727ccdc..00000000 --- a/docs-partials/builder/vmware/common/RunConfig.mdx +++ /dev/null @@ -1,5 +0,0 @@ - - -~> **Note:** If [vnc_over_websocket](#vnc_over_websocket) is set to true, any other VNC configuration will be ignored. - - diff --git a/docs/builders/iso.mdx b/docs/builders/iso.mdx index 81108d4f..499775c7 100644 --- a/docs/builders/iso.mdx +++ b/docs/builders/iso.mdx @@ -157,8 +157,6 @@ necessary for this build to succeed and can be found further down the page. ### Run configuration -@include 'builder/vmware/common/RunConfig.mdx' - #### Optional: @include 'builder/vmware/common/RunConfig-not-required.mdx' diff --git a/docs/builders/vmx.mdx b/docs/builders/vmx.mdx index ea02a4b7..20493898 100644 --- a/docs/builders/vmx.mdx +++ b/docs/builders/vmx.mdx @@ -138,8 +138,6 @@ necessary for this build to succeed and can be found further down the page. ### Run configuration -@include 'builder/vmware/common/RunConfig.mdx' - #### Optional: @include 'builder/vmware/common/RunConfig-not-required.mdx'