From 74bf2bf792963a0d9eb8785b45f01f0f60a516d7 Mon Sep 17 00:00:00 2001 From: Ryan Johnson Date: Sun, 3 Mar 2024 22:51:41 -0500 Subject: [PATCH] docs: `vsphere-clone` customize - Updates documentation for `vsphere-clone` customization. - Updates all VMware vSphere references to vSphere 8.0. Signed-off-by: Ryan Johnson --- .../builder/vsphere-clone/README.md | 77 ++++++------ .../components/builder/vsphere-iso/README.md | 6 +- builder/vsphere/clone/step_customize.go | 111 +++++++++--------- builder/vsphere/common/step_hardware.go | 4 +- builder/vsphere/common/storage_config.go | 2 +- .../clone/CustomizeConfig-not-required.mdx | 23 ++-- .../builder/vsphere/clone/CustomizeConfig.mdx | 10 +- .../clone/GlobalDnsSettings-not-required.mdx | 4 +- .../vsphere/clone/GlobalDnsSettings.mdx | 4 +- .../GlobalRoutingSettings-not-required.mdx | 4 +- .../vsphere/clone/GlobalRoutingSettings.mdx | 2 +- .../clone/LinuxOptions-not-required.mdx | 8 +- .../clone/NetworkInterface-not-required.mdx | 16 +-- .../clone/WindowsOptions-not-required.mdx | 24 ++-- .../common/HardwareConfig-not-required.mdx | 4 +- .../common/StorageConfig-not-required.mdx | 2 +- 16 files changed, 151 insertions(+), 150 deletions(-) diff --git a/.web-docs/components/builder/vsphere-clone/README.md b/.web-docs/components/builder/vsphere-clone/README.md index e12774e93..0b6e579bf 100644 --- a/.web-docs/components/builder/vsphere-clone/README.md +++ b/.web-docs/components/builder/vsphere-clone/README.md @@ -82,7 +82,7 @@ necessary for this build to succeed and can be found further down the page. - `disk_controller_type` ([]string) - Set VM disk controller type. Example `lsilogic`, `lsilogic-sas`, `pvscsi`, `nvme`, or `scsi`. Use a list to define additional controllers. Defaults to `lsilogic`. See - [SCSI, SATA, and NVMe Storage Controller Conditions, Limitations, and Compatibility](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-5872D173-A076-42FE-8D0B-9DB0EB0E7362.html#GUID-5872D173-A076-42FE-8D0B-9DB0EB0E7362) + [SCSI, SATA, and NVMe Storage Controller Conditions, Limitations, and Compatibility](https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-5872D173-A076-42FE-8D0B-9DB0EB0E7362.html) for additional details. - `storage` ([]DiskConfig) - Configures a collection of one or more disks to be provisioned along with the VM. See the [Storage Configuration](#storage-configuration). @@ -264,37 +264,40 @@ can be done via environment variable: -A cloned virtual machine can be [customized](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-58E346FF-83AE-42B8-BE58-253641D257BC.html) +A cloned virtual machine can be [customized](https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-58E346FF-83AE-42B8-BE58-253641D257BC.html) to configure host, network, or licensing settings. To perform virtual machine customization as a part of the clone process, specify the customize block with the respective customization options. Windows guests are customized using Sysprep, which will result in the machine SID being reset. -Before using customization, check that your source VM meets the [requirements](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-E63B6FAA-8D35-428D-B40C-744769845906.html) -for guest OS customization on vSphere. -See the [customization example](#customization-example) for a usage synopsis. +Before using customization, check that your source virtual machine meets the +[requirements](https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-E63B6FAA-8D35-428D-B40C-744769845906.html) +for guest OS customization on vSphere. Refer to the [customization example](#customization-example) for a usage synopsis. -The settings for customize are as follows: +The settings for guest customization include: -- `linux_options` (\*LinuxOptions) - Settings to Linux guest OS customization. See [Linux customization settings](#linux-customization-settings). +- `linux_options` (\*LinuxOptions) - Settings for the guest customization of Linux operating systems. Refer to the [Linux options](#linux-options) section for additional details. -- `windows_options` (\*WindowsOptions) - Settings to Windows guest OS customization. +- `windows_options` (\*WindowsOptions) - Settings for the guest customization of Windows operating systems. Refer to the [Windows options](#windows-options) section for additional details. -- `windows_sysprep_file` (string) - Provide a sysprep.xml file to allow control of the customization process independent of vSphere. This option is deprecated, please use windows_sysprep_text. +- `windows_sysprep_file` (string) - Provide a `sysprep.xml` file to allow control of the customization process independent of vSphere. This option is deprecated, please use `windows_sysprep_text`. -- `windows_sysprep_text` (string) - Provide the text for the sysprep.xml content to allow control of the customization process independent of vSphere. This option is intended to be used with HCL templates. +- `windows_sysprep_text` (string) - Provide the text for the `sysprep.xml` content to allow control of the customization process independent of vSphere. This option is intended to be used with HCL templates. + + Example usage: + + In HCL2: - **Example usage:** - **In HCL2:** ```hcl customize { windows_sysprep_text = file("") } - ```` + ``` + ```hcl customize { windows_sysprep_text = templatefile("", { @@ -304,9 +307,9 @@ The settings for customize are as follows: } ``` -- `network_interface` (NetworkInterfaces) - Configure network interfaces on a per-interface basis that should matched up to the network adapters present in the VM. - To use DHCP, declare an empty network_interface for each adapter being configured. This field is required. - See [Network interface settings](#network-interface-settings). +- `network_interface` (NetworkInterfaces) - Set up network interfaces individually to correspond with the network adapters on the virtual machine. + To use DHCP, specify an empty `network_interface` for each configured adapter. This field is mandatory. + Refer to the [network interface](#network-interface-settings) section for additional details. @@ -315,19 +318,19 @@ The settings for customize are as follows: -- `dns_server_list` ([]string) - Network interface-specific DNS server settings for Windows operating systems. - Ignored on Linux and possibly other operating systems - for those systems, please see the [global DNS settings](#global-dns-settings) section. +- `dns_server_list` ([]string) - Specifies the DNS servers for a specific network interface on a Windows guest operating system. + Ignored on Linux. Refer to the [global DNS settings](#global-dns-settings) section for additional details. -- `dns_domain` (string) - Network interface-specific DNS search domain for Windows operating systems. - Ignored on Linux and possibly other operating systems - for those systems, please see the [global DNS settings](#global-dns-settings) section. +- `dns_domain` (string) - Specifies the DNS search domain for a specific network interface on a Windows guest operating system. + Ignored on Linux. Refer to the [global DNS settings](#global-dns-settings) section for additional details. -- `ipv4_address` (string) - The IPv4 address assigned to this network adapter. If left blank or not included, DHCP is used. +- `ipv4_address` (string) - Specifies the IPv4 address assigned to the network adapter. If left blank or not included, DHCP is used. -- `ipv4_netmask` (int) - The IPv4 subnet mask, in bits (example: 24 for 255.255.255.0). +- `ipv4_netmask` (int) - Specifies the IPv4 subnet mask, in bits, for the network adapter. For example, `24` for a `/24` subnet. -- `ipv6_address` (string) - The IPv6 address assigned to this network adapter. If left blank or not included, auto-configuration is used. +- `ipv6_address` (string) - Specifies the IPv6 address assigned to the network adapter. If left blank or not included, auto-configuration is used. -- `ipv6_netmask` (int) - The IPv6 subnet mask, in bits (example: 32). +- `ipv6_netmask` (int) - Specifies the IPv6 subnet mask, in bits, for the network adapter. For example, `64` for a `/64` subnet. @@ -336,16 +339,16 @@ The settings for customize are as follows: -The settings here must match the IP/mask of at least one network_interface supplied to customization. +The settings must match the IP address and subnet mask of at least one `network_interface` for the customization. -- `ipv4_gateway` (string) - The IPv4 default gateway when using network_interface customization on the virtual machine. +- `ipv4_gateway` (string) - Specifies the IPv4 default gateway when using `network_interface` customization. -- `ipv6_gateway` (string) - The IPv6 default gateway when using network_interface customization on the virtual machine. +- `ipv6_gateway` (string) - Specifies the IPv6 default gateway when using `network_interface` customization. @@ -354,17 +357,17 @@ The settings here must match the IP/mask of at least one network_interface suppl -The following settings configure DNS globally, generally for Linux systems. For Windows systems, -this is done per-interface, see [network interface](#network_interface) settings. +The following settings configure DNS globally for Linux guest operating systems. +For Windows guest operating systems, this is set for each network interface. Refer to the [network interface](#network_interface) section for additional details. -- `dns_server_list` ([]string) - The list of DNS servers to configure on a virtual machine. +- `dns_server_list` ([]string) - Specifies a list of DNS servers to configure on the guest operating system. -- `dns_suffix_list` ([]string) - A list of DNS search domains to add to the DNS configuration on the virtual machine. +- `dns_suffix_list` ([]string) - Specifies a list of DNS search domains to add to the DNS configuration on the guest operating system. @@ -373,13 +376,13 @@ this is done per-interface, see [network interface](#network_interface) settings -- `domain` (string) - The domain name for this machine. This, along with [host_name](#host_name), make up the FQDN of this virtual machine. +- `domain` (string) - Specifies the domain name for the guest operating system. Used with [host_name](#host_name) to construct the fully qualified domain name (FQDN). -- `host_name` (string) - The host name for this machine. This, along with [domain](#domain), make up the FQDN of this virtual machine. +- `host_name` (string) - Specifies the hostname for the guest operating system. Used with [domain](#domain) to construct the fully qualified domain name (FQDN). -- `hw_clock_utc` (boolean) - Tells the operating system that the hardware clock is set to UTC. Default: true. +- `hw_clock_utc` (boolean) - Specifies whether the hardware clock is set to Coordinated Universal Time (UTC). Defaults to `true`. -- `time_zone` (string) - Sets the time zone. The default is UTC. +- `time_zone` (string) - Specifies the time zone for the guest operating system. @@ -732,10 +735,10 @@ wget http://{{ .HTTPIP }}:{{ .HTTPPort }}/foo/bar/preseed.cfg - `RAM_hot_plug` (bool) - Enable RAM hot plug setting for virtual machine. Defaults to `false`. -- `video_ram` (int64) - Amount of video memory in KB. See [vSphere documentation](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-789C3913-1053-4850-A0F0-E29C3D32B6DA.html) +- `video_ram` (int64) - Amount of video memory in KB. See [vSphere documentation](https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-789C3913-1053-4850-A0F0-E29C3D32B6DA.html) for supported maximums. Defaults to 4096 KB. -- `displays` (int32) - Number of video displays. See [vSphere documentation](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-789C3913-1053-4850-A0F0-E29C3D32B6DA.html) +- `displays` (int32) - Number of video displays. See [vSphere documentation](https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-789C3913-1053-4850-A0F0-E29C3D32B6DA.html) for supported maximums. Defaults to 1. - `vgpu_profile` (string) - vGPU profile for accelerated graphics. See [NVIDIA GRID vGPU documentation](https://docs.nvidia.com/grid/latest/grid-vgpu-user-guide/index.html#configure-vmware-vsphere-vm-with-vgpu) diff --git a/.web-docs/components/builder/vsphere-iso/README.md b/.web-docs/components/builder/vsphere-iso/README.md index eaa4bc0f3..86cada257 100644 --- a/.web-docs/components/builder/vsphere-iso/README.md +++ b/.web-docs/components/builder/vsphere-iso/README.md @@ -389,10 +389,10 @@ wget http://{{ .HTTPIP }}:{{ .HTTPPort }}/foo/bar/preseed.cfg - `RAM_hot_plug` (bool) - Enable RAM hot plug setting for virtual machine. Defaults to `false`. -- `video_ram` (int64) - Amount of video memory in KB. See [vSphere documentation](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-789C3913-1053-4850-A0F0-E29C3D32B6DA.html) +- `video_ram` (int64) - Amount of video memory in KB. See [vSphere documentation](https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-789C3913-1053-4850-A0F0-E29C3D32B6DA.html) for supported maximums. Defaults to 4096 KB. -- `displays` (int32) - Number of video displays. See [vSphere documentation](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-789C3913-1053-4850-A0F0-E29C3D32B6DA.html) +- `displays` (int32) - Number of video displays. See [vSphere documentation](https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-789C3913-1053-4850-A0F0-E29C3D32B6DA.html) for supported maximums. Defaults to 1. - `vgpu_profile` (string) - vGPU profile for accelerated graphics. See [NVIDIA GRID vGPU documentation](https://docs.nvidia.com/grid/latest/grid-vgpu-user-guide/index.html#configure-vmware-vsphere-vm-with-vgpu) @@ -812,7 +812,7 @@ boot time. - `disk_controller_type` ([]string) - Set VM disk controller type. Example `lsilogic`, `lsilogic-sas`, `pvscsi`, `nvme`, or `scsi`. Use a list to define additional controllers. Defaults to `lsilogic`. See - [SCSI, SATA, and NVMe Storage Controller Conditions, Limitations, and Compatibility](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-5872D173-A076-42FE-8D0B-9DB0EB0E7362.html#GUID-5872D173-A076-42FE-8D0B-9DB0EB0E7362) + [SCSI, SATA, and NVMe Storage Controller Conditions, Limitations, and Compatibility](https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-5872D173-A076-42FE-8D0B-9DB0EB0E7362.html) for additional details. - `storage` ([]DiskConfig) - Configures a collection of one or more disks to be provisioned along with the VM. See the [Storage Configuration](#storage-configuration). diff --git a/builder/vsphere/clone/step_customize.go b/builder/vsphere/clone/step_customize.go index f653ab4ff..243035a00 100644 --- a/builder/vsphere/clone/step_customize.go +++ b/builder/vsphere/clone/step_customize.go @@ -23,120 +23,119 @@ var ( windowsSysprepFileDeprecatedMessage = "`windows_sysprep_file` is deprecated and will be removed in a future release. please use `windows_sysprep_text`." ) -// A cloned virtual machine can be [customized](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-58E346FF-83AE-42B8-BE58-253641D257BC.html) +// A cloned virtual machine can be [customized](https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-58E346FF-83AE-42B8-BE58-253641D257BC.html) // to configure host, network, or licensing settings. // // To perform virtual machine customization as a part of the clone process, specify the customize block with the // respective customization options. Windows guests are customized using Sysprep, which will result in the machine SID being reset. -// Before using customization, check that your source VM meets the [requirements](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-E63B6FAA-8D35-428D-B40C-744769845906.html) -// for guest OS customization on vSphere. -// See the [customization example](#customization-example) for a usage synopsis. +// Before using customization, check that your source virtual machine meets the +// [requirements](https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-E63B6FAA-8D35-428D-B40C-744769845906.html) +// for guest OS customization on vSphere. Refer to the [customization example](#customization-example) for a usage synopsis. // -// The settings for customize are as follows: +// The settings for guest customization include: type CustomizeConfig struct { - // Settings to Linux guest OS customization. See [Linux customization settings](#linux-customization-settings). + // Settings for the guest customization of Linux operating systems. Refer to the [Linux options](#linux-options) section for additional details. LinuxOptions *LinuxOptions `mapstructure:"linux_options"` - // Settings to Windows guest OS customization. + // Settings for the guest customization of Windows operating systems. Refer to the [Windows options](#windows-options) section for additional details. WindowsOptions *WindowsOptions `mapstructure:"windows_options"` - // Provide a sysprep.xml file to allow control of the customization process independent of vSphere. This option is deprecated, please use windows_sysprep_text. + // Provide a `sysprep.xml` file to allow control of the customization process independent of vSphere. This option is deprecated, please use `windows_sysprep_text`. WindowsSysPrepFile string `mapstructure:"windows_sysprep_file"` - // Provide the text for the sysprep.xml content to allow control of the customization process independent of vSphere. This option is intended to be used with HCL templates. + // Provide the text for the `sysprep.xml` content to allow control of the customization process independent of vSphere. This option is intended to be used with HCL templates. + // + // Example usage: + // + // In HCL2: // - // **Example usage:** - // **In HCL2:** // ```hcl - //customize { + // customize { // windows_sysprep_text = file("") - //} - // ```` + // } + // ``` + // // ```hcl - //customize { + // customize { // windows_sysprep_text = templatefile("", { // var1="example" // var2="example-2" // }) - //} + // } // ``` WindowsSysPrepText string `mapstructure:"windows_sysprep_text"` - // Configure network interfaces on a per-interface basis that should matched up to the network adapters present in the VM. - // To use DHCP, declare an empty network_interface for each adapter being configured. This field is required. - // See [Network interface settings](#network-interface-settings). + // Set up network interfaces individually to correspond with the network adapters on the virtual machine. + // To use DHCP, specify an empty `network_interface` for each configured adapter. This field is mandatory. + // Refer to the [network interface](#network-interface-settings) section for additional details. NetworkInterfaces NetworkInterfaces `mapstructure:"network_interface"` GlobalRoutingSettings `mapstructure:",squash"` GlobalDnsSettings `mapstructure:",squash"` } type LinuxOptions struct { - // The domain name for this machine. This, along with [host_name](#host_name), make up the FQDN of this virtual machine. + // Specifies the domain name for the guest operating system. Used with [host_name](#host_name) to construct the fully qualified domain name (FQDN). Domain string `mapstructure:"domain"` - // The host name for this machine. This, along with [domain](#domain), make up the FQDN of this virtual machine. + // Specifies the hostname for the guest operating system. Used with [domain](#domain) to construct the fully qualified domain name (FQDN). Hostname string `mapstructure:"host_name"` - // Tells the operating system that the hardware clock is set to UTC. Default: true. + // Specifies whether the hardware clock is set to Coordinated Universal Time (UTC). Defaults to `true`. HWClockUTC config.Trilean `mapstructure:"hw_clock_utc"` - // Sets the time zone. The default is UTC. + // Specifies the time zone for the guest operating system. Timezone string `mapstructure:"time_zone"` } type WindowsOptions struct { - // CustomizationGuiRunOnce - // A list of commands to run at first user logon, after guest customization. + // Specifies a list of commands to run at first logon after the guest operating system is customized. RunOnceCommandList *[]string `mapstructure:"run_once_command_list"` - // CustomizationGuiUnattended - // Specifies whether or not the VM automatically logs on as Administrator. + // Specifies whether the guest operating system automatically logs on as Administrator. AutoLogon *bool `mapstructure:"auto_logon"` - // Specifies how many times the VM should auto-logon the Administrator account when auto_logon is true. Default 1 + // Specifies how many times the guest operating system should auto-logon the Administrator account when `auto_logon` is set to `true`. Default:s to `1`. AutoLogonCount *int32 `mapstructure:"auto_logon_count"` - // The new administrator password for this virtual machine. + // Specifies the password for the guest operating system's Administrator account. AdminPassword *string `mapstructure:"admin_password"` - // The new time zone for the virtual machine. This is a sysprep-dictated timezone code. Default 85 (GMT) + // Specifies the time zone for the guest operating system. Default to `85` (Pacific Time). TimeZone *int32 `mapstructure:"time_zone"` - // CustomizationIdentification - // The workgroup for this virtual machine - AD Join is not supported + // Specifies the workgroup for the guest operating system. Joining an Active Directory domain is not supported. Workgroup string `mapstructure:"workgroup"` - // CustomizationUserData - // The host name for this virtual machine. + // Specifies the hostname for the guest operating system. ComputerName string `mapstructure:"computer_name"` - // The full name of the user of this virtual machine. Default: "Administrator" + // Specifies the full name for the guest operating system's Administrator account. Defaults to `Administrator`. FullName string `mapstructure:"full_name"` - // The organization name this virtual machine is being installed for. Default: "Managed by Packer" + // Specifies the organization name for the guest operating system. Defaults to `Built by Packer`. OrganizationName string `mapstructure:"organization_name"` - // The product key for this virtual machine. + // Specifies the product key for the guest operating system. ProductKey string `mapstructure:"product_key"` } type NetworkInterface struct { - // Network interface-specific DNS server settings for Windows operating systems. - // Ignored on Linux and possibly other operating systems - for those systems, please see the [global DNS settings](#global-dns-settings) section. + // Specifies the DNS servers for a specific network interface on a Windows guest operating system. + // Ignored on Linux. Refer to the [global DNS settings](#global-dns-settings) section for additional details. DnsServerList []string `mapstructure:"dns_server_list"` - // Network interface-specific DNS search domain for Windows operating systems. - // Ignored on Linux and possibly other operating systems - for those systems, please see the [global DNS settings](#global-dns-settings) section. + // Specifies the DNS search domain for a specific network interface on a Windows guest operating system. + // Ignored on Linux. Refer to the [global DNS settings](#global-dns-settings) section for additional details. DnsDomain string `mapstructure:"dns_domain"` - // The IPv4 address assigned to this network adapter. If left blank or not included, DHCP is used. + // Specifies the IPv4 address assigned to the network adapter. If left blank or not included, DHCP is used. Ipv4Address string `mapstructure:"ipv4_address"` - // The IPv4 subnet mask, in bits (example: 24 for 255.255.255.0). + // Specifies the IPv4 subnet mask, in bits, for the network adapter. For example, `24` for a `/24` subnet. Ipv4NetMask int `mapstructure:"ipv4_netmask"` - // The IPv6 address assigned to this network adapter. If left blank or not included, auto-configuration is used. + // Specifies the IPv6 address assigned to the network adapter. If left blank or not included, auto-configuration is used. Ipv6Address string `mapstructure:"ipv6_address"` - // The IPv6 subnet mask, in bits (example: 32). + // Specifies the IPv6 subnet mask, in bits, for the network adapter. For example, `64` for a `/64` subnet. Ipv6NetMask int `mapstructure:"ipv6_netmask"` } type NetworkInterfaces []NetworkInterface -// The settings here must match the IP/mask of at least one network_interface supplied to customization. +// The settings must match the IP address and subnet mask of at least one `network_interface` for the customization. type GlobalRoutingSettings struct { - // The IPv4 default gateway when using network_interface customization on the virtual machine. + // Specifies the IPv4 default gateway when using `network_interface` customization. Ipv4Gateway string `mapstructure:"ipv4_gateway"` - // The IPv6 default gateway when using network_interface customization on the virtual machine. + // Specifies the IPv6 default gateway when using `network_interface` customization. Ipv6Gateway string `mapstructure:"ipv6_gateway"` } -// The following settings configure DNS globally, generally for Linux systems. For Windows systems, -// this is done per-interface, see [network interface](#network_interface) settings. +// The following settings configure DNS globally for Linux guest operating systems. +// For Windows guest operating systems, this is set for each network interface. Refer to the [network interface](#network_interface) section for additional details. type GlobalDnsSettings struct { - // The list of DNS servers to configure on a virtual machine. + // Specifies a list of DNS servers to configure on the guest operating system. DnsServerList []string `mapstructure:"dns_server_list"` - // A list of DNS search domains to add to the DNS configuration on the virtual machine. + // Specifies a list of DNS search domains to add to the DNS configuration on the guest operating system. DnsSuffixList []string `mapstructure:"dns_suffix_list"` } @@ -170,7 +169,7 @@ func (c *CustomizeConfig) Prepare() ([]string, []error) { if options_number > 1 { errs = append(errs, errCustomizeOptionMutualExclusive) } else if options_number == 0 { - errs = append(errs, fmt.Errorf("One of `linux_options`, `windows_options`, `windows_sysprep_file` must be set")) + errs = append(errs, fmt.Errorf("one of `linux_options`, `windows_options`, `windows_sysprep_file` must be set")) } if c.LinuxOptions != nil { @@ -339,10 +338,10 @@ func (s *StepCustomize) globalIpSettings() types.CustomizationGlobalIPSettings { func (l *LinuxOptions) prepare(errs []error) []error { if l.Hostname == "" { - errs = append(errs, fmt.Errorf("linux options `host_name` is empty")) + errs = append(errs, fmt.Errorf("linux options: `host_name` is required")) } if l.Domain == "" { - errs = append(errs, fmt.Errorf("linux options `domain` is empty")) + errs = append(errs, fmt.Errorf("linux options: `domain` is required")) } if l.HWClockUTC == config.TriUnset { @@ -368,7 +367,7 @@ func (l *LinuxOptions) linuxPrep() *types.CustomizationLinuxPrep { func (w *WindowsOptions) prepare(errs []error) []error { if w.ComputerName == "" { - errs = append(errs, fmt.Errorf("The `computer_name` is required")) + errs = append(errs, fmt.Errorf("windows options: `computer_name` is required")) } if w.FullName == "" { w.FullName = "Administrator" diff --git a/builder/vsphere/common/step_hardware.go b/builder/vsphere/common/step_hardware.go index 7b6764379..fe7438d4a 100644 --- a/builder/vsphere/common/step_hardware.go +++ b/builder/vsphere/common/step_hardware.go @@ -35,10 +35,10 @@ type HardwareConfig struct { RAMReserveAll bool `mapstructure:"RAM_reserve_all"` // Enable RAM hot plug setting for virtual machine. Defaults to `false`. MemoryHotAddEnabled bool `mapstructure:"RAM_hot_plug"` - // Amount of video memory in KB. See [vSphere documentation](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-789C3913-1053-4850-A0F0-E29C3D32B6DA.html) + // Amount of video memory in KB. See [vSphere documentation](https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-789C3913-1053-4850-A0F0-E29C3D32B6DA.html) // for supported maximums. Defaults to 4096 KB. VideoRAM int64 `mapstructure:"video_ram"` - // Number of video displays. See [vSphere documentation](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-789C3913-1053-4850-A0F0-E29C3D32B6DA.html) + // Number of video displays. See [vSphere documentation](https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-789C3913-1053-4850-A0F0-E29C3D32B6DA.html) // for supported maximums. Defaults to 1. Displays int32 `mapstructure:"displays"` // vGPU profile for accelerated graphics. See [NVIDIA GRID vGPU documentation](https://docs.nvidia.com/grid/latest/grid-vgpu-user-guide/index.html#configure-vmware-vsphere-vm-with-vgpu) diff --git a/builder/vsphere/common/storage_config.go b/builder/vsphere/common/storage_config.go index 8b795c74b..dbebe8e9c 100644 --- a/builder/vsphere/common/storage_config.go +++ b/builder/vsphere/common/storage_config.go @@ -104,7 +104,7 @@ type DiskConfig struct { type StorageConfig struct { // Set VM disk controller type. Example `lsilogic`, `lsilogic-sas`, `pvscsi`, `nvme`, or `scsi`. Use a list to define additional controllers. // Defaults to `lsilogic`. See - // [SCSI, SATA, and NVMe Storage Controller Conditions, Limitations, and Compatibility](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-5872D173-A076-42FE-8D0B-9DB0EB0E7362.html#GUID-5872D173-A076-42FE-8D0B-9DB0EB0E7362) + // [SCSI, SATA, and NVMe Storage Controller Conditions, Limitations, and Compatibility](https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-5872D173-A076-42FE-8D0B-9DB0EB0E7362.html) // for additional details. DiskControllerType []string `mapstructure:"disk_controller_type"` // Configures a collection of one or more disks to be provisioned along with the VM. See the [Storage Configuration](#storage-configuration). diff --git a/docs-partials/builder/vsphere/clone/CustomizeConfig-not-required.mdx b/docs-partials/builder/vsphere/clone/CustomizeConfig-not-required.mdx index 102dd0d32..d134b71c9 100644 --- a/docs-partials/builder/vsphere/clone/CustomizeConfig-not-required.mdx +++ b/docs-partials/builder/vsphere/clone/CustomizeConfig-not-required.mdx @@ -1,20 +1,23 @@ -- `linux_options` (\*LinuxOptions) - Settings to Linux guest OS customization. See [Linux customization settings](#linux-customization-settings). +- `linux_options` (\*LinuxOptions) - Settings for the guest customization of Linux operating systems. Refer to the [Linux options](#linux-options) section for additional details. -- `windows_options` (\*WindowsOptions) - Settings to Windows guest OS customization. +- `windows_options` (\*WindowsOptions) - Settings for the guest customization of Windows operating systems. Refer to the [Windows options](#windows-options) section for additional details. -- `windows_sysprep_file` (string) - Provide a sysprep.xml file to allow control of the customization process independent of vSphere. This option is deprecated, please use windows_sysprep_text. +- `windows_sysprep_file` (string) - Provide a `sysprep.xml` file to allow control of the customization process independent of vSphere. This option is deprecated, please use `windows_sysprep_text`. -- `windows_sysprep_text` (string) - Provide the text for the sysprep.xml content to allow control of the customization process independent of vSphere. This option is intended to be used with HCL templates. +- `windows_sysprep_text` (string) - Provide the text for the `sysprep.xml` content to allow control of the customization process independent of vSphere. This option is intended to be used with HCL templates. + + Example usage: + + In HCL2: - **Example usage:** - **In HCL2:** ```hcl customize { windows_sysprep_text = file("") } - ```` + ``` + ```hcl customize { windows_sysprep_text = templatefile("", { @@ -24,8 +27,8 @@ } ``` -- `network_interface` (NetworkInterfaces) - Configure network interfaces on a per-interface basis that should matched up to the network adapters present in the VM. - To use DHCP, declare an empty network_interface for each adapter being configured. This field is required. - See [Network interface settings](#network-interface-settings). +- `network_interface` (NetworkInterfaces) - Set up network interfaces individually to correspond with the network adapters on the virtual machine. + To use DHCP, specify an empty `network_interface` for each configured adapter. This field is mandatory. + Refer to the [network interface](#network-interface-settings) section for additional details. diff --git a/docs-partials/builder/vsphere/clone/CustomizeConfig.mdx b/docs-partials/builder/vsphere/clone/CustomizeConfig.mdx index e159ec065..c696ceccf 100644 --- a/docs-partials/builder/vsphere/clone/CustomizeConfig.mdx +++ b/docs-partials/builder/vsphere/clone/CustomizeConfig.mdx @@ -1,14 +1,14 @@ -A cloned virtual machine can be [customized](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-58E346FF-83AE-42B8-BE58-253641D257BC.html) +A cloned virtual machine can be [customized](https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-58E346FF-83AE-42B8-BE58-253641D257BC.html) to configure host, network, or licensing settings. To perform virtual machine customization as a part of the clone process, specify the customize block with the respective customization options. Windows guests are customized using Sysprep, which will result in the machine SID being reset. -Before using customization, check that your source VM meets the [requirements](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-E63B6FAA-8D35-428D-B40C-744769845906.html) -for guest OS customization on vSphere. -See the [customization example](#customization-example) for a usage synopsis. +Before using customization, check that your source virtual machine meets the +[requirements](https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-E63B6FAA-8D35-428D-B40C-744769845906.html) +for guest OS customization on vSphere. Refer to the [customization example](#customization-example) for a usage synopsis. -The settings for customize are as follows: +The settings for guest customization include: diff --git a/docs-partials/builder/vsphere/clone/GlobalDnsSettings-not-required.mdx b/docs-partials/builder/vsphere/clone/GlobalDnsSettings-not-required.mdx index 072fa1b77..7115f39fa 100644 --- a/docs-partials/builder/vsphere/clone/GlobalDnsSettings-not-required.mdx +++ b/docs-partials/builder/vsphere/clone/GlobalDnsSettings-not-required.mdx @@ -1,7 +1,7 @@ -- `dns_server_list` ([]string) - The list of DNS servers to configure on a virtual machine. +- `dns_server_list` ([]string) - Specifies a list of DNS servers to configure on the guest operating system. -- `dns_suffix_list` ([]string) - A list of DNS search domains to add to the DNS configuration on the virtual machine. +- `dns_suffix_list` ([]string) - Specifies a list of DNS search domains to add to the DNS configuration on the guest operating system. diff --git a/docs-partials/builder/vsphere/clone/GlobalDnsSettings.mdx b/docs-partials/builder/vsphere/clone/GlobalDnsSettings.mdx index fe86c5ad2..2b01d2856 100644 --- a/docs-partials/builder/vsphere/clone/GlobalDnsSettings.mdx +++ b/docs-partials/builder/vsphere/clone/GlobalDnsSettings.mdx @@ -1,6 +1,6 @@ -The following settings configure DNS globally, generally for Linux systems. For Windows systems, -this is done per-interface, see [network interface](#network_interface) settings. +The following settings configure DNS globally for Linux guest operating systems. +For Windows guest operating systems, this is set for each network interface. Refer to the [network interface](#network_interface) section for additional details. diff --git a/docs-partials/builder/vsphere/clone/GlobalRoutingSettings-not-required.mdx b/docs-partials/builder/vsphere/clone/GlobalRoutingSettings-not-required.mdx index 6fad61b45..24b7a43fa 100644 --- a/docs-partials/builder/vsphere/clone/GlobalRoutingSettings-not-required.mdx +++ b/docs-partials/builder/vsphere/clone/GlobalRoutingSettings-not-required.mdx @@ -1,7 +1,7 @@ -- `ipv4_gateway` (string) - The IPv4 default gateway when using network_interface customization on the virtual machine. +- `ipv4_gateway` (string) - Specifies the IPv4 default gateway when using `network_interface` customization. -- `ipv6_gateway` (string) - The IPv6 default gateway when using network_interface customization on the virtual machine. +- `ipv6_gateway` (string) - Specifies the IPv6 default gateway when using `network_interface` customization. diff --git a/docs-partials/builder/vsphere/clone/GlobalRoutingSettings.mdx b/docs-partials/builder/vsphere/clone/GlobalRoutingSettings.mdx index 43f1a3683..ba78b169f 100644 --- a/docs-partials/builder/vsphere/clone/GlobalRoutingSettings.mdx +++ b/docs-partials/builder/vsphere/clone/GlobalRoutingSettings.mdx @@ -1,5 +1,5 @@ -The settings here must match the IP/mask of at least one network_interface supplied to customization. +The settings must match the IP address and subnet mask of at least one `network_interface` for the customization. diff --git a/docs-partials/builder/vsphere/clone/LinuxOptions-not-required.mdx b/docs-partials/builder/vsphere/clone/LinuxOptions-not-required.mdx index a11b96cd5..12911147e 100644 --- a/docs-partials/builder/vsphere/clone/LinuxOptions-not-required.mdx +++ b/docs-partials/builder/vsphere/clone/LinuxOptions-not-required.mdx @@ -1,11 +1,11 @@ -- `domain` (string) - The domain name for this machine. This, along with [host_name](#host_name), make up the FQDN of this virtual machine. +- `domain` (string) - Specifies the domain name for the guest operating system. Used with [host_name](#host_name) to construct the fully qualified domain name (FQDN). -- `host_name` (string) - The host name for this machine. This, along with [domain](#domain), make up the FQDN of this virtual machine. +- `host_name` (string) - Specifies the hostname for the guest operating system. Used with [domain](#domain) to construct the fully qualified domain name (FQDN). -- `hw_clock_utc` (boolean) - Tells the operating system that the hardware clock is set to UTC. Default: true. +- `hw_clock_utc` (boolean) - Specifies whether the hardware clock is set to Coordinated Universal Time (UTC). Defaults to `true`. -- `time_zone` (string) - Sets the time zone. The default is UTC. +- `time_zone` (string) - Specifies the time zone for the guest operating system. diff --git a/docs-partials/builder/vsphere/clone/NetworkInterface-not-required.mdx b/docs-partials/builder/vsphere/clone/NetworkInterface-not-required.mdx index b5ab78b1d..608a32c3f 100644 --- a/docs-partials/builder/vsphere/clone/NetworkInterface-not-required.mdx +++ b/docs-partials/builder/vsphere/clone/NetworkInterface-not-required.mdx @@ -1,17 +1,17 @@ -- `dns_server_list` ([]string) - Network interface-specific DNS server settings for Windows operating systems. - Ignored on Linux and possibly other operating systems - for those systems, please see the [global DNS settings](#global-dns-settings) section. +- `dns_server_list` ([]string) - Specifies the DNS servers for a specific network interface on a Windows guest operating system. + Ignored on Linux. Refer to the [global DNS settings](#global-dns-settings) section for additional details. -- `dns_domain` (string) - Network interface-specific DNS search domain for Windows operating systems. - Ignored on Linux and possibly other operating systems - for those systems, please see the [global DNS settings](#global-dns-settings) section. +- `dns_domain` (string) - Specifies the DNS search domain for a specific network interface on a Windows guest operating system. + Ignored on Linux. Refer to the [global DNS settings](#global-dns-settings) section for additional details. -- `ipv4_address` (string) - The IPv4 address assigned to this network adapter. If left blank or not included, DHCP is used. +- `ipv4_address` (string) - Specifies the IPv4 address assigned to the network adapter. If left blank or not included, DHCP is used. -- `ipv4_netmask` (int) - The IPv4 subnet mask, in bits (example: 24 for 255.255.255.0). +- `ipv4_netmask` (int) - Specifies the IPv4 subnet mask, in bits, for the network adapter. For example, `24` for a `/24` subnet. -- `ipv6_address` (string) - The IPv6 address assigned to this network adapter. If left blank or not included, auto-configuration is used. +- `ipv6_address` (string) - Specifies the IPv6 address assigned to the network adapter. If left blank or not included, auto-configuration is used. -- `ipv6_netmask` (int) - The IPv6 subnet mask, in bits (example: 32). +- `ipv6_netmask` (int) - Specifies the IPv6 subnet mask, in bits, for the network adapter. For example, `64` for a `/64` subnet. diff --git a/docs-partials/builder/vsphere/clone/WindowsOptions-not-required.mdx b/docs-partials/builder/vsphere/clone/WindowsOptions-not-required.mdx index 023e57dcf..7dbf6d1a4 100644 --- a/docs-partials/builder/vsphere/clone/WindowsOptions-not-required.mdx +++ b/docs-partials/builder/vsphere/clone/WindowsOptions-not-required.mdx @@ -1,27 +1,23 @@ -- `run_once_command_list` (\*[]string) - CustomizationGuiRunOnce - A list of commands to run at first user logon, after guest customization. +- `run_once_command_list` (\*[]string) - Specifies a list of commands to run at first logon after the guest operating system is customized. -- `auto_logon` (\*bool) - CustomizationGuiUnattended - Specifies whether or not the VM automatically logs on as Administrator. +- `auto_logon` (\*bool) - Specifies whether the guest operating system automatically logs on as Administrator. -- `auto_logon_count` (\*int32) - Specifies how many times the VM should auto-logon the Administrator account when auto_logon is true. Default 1 +- `auto_logon_count` (\*int32) - Specifies how many times the guest operating system should auto-logon the Administrator account when `auto_logon` is set to `true`. Default:s to `1`. -- `admin_password` (\*string) - The new administrator password for this virtual machine. +- `admin_password` (\*string) - Specifies the password for the guest operating system's Administrator account. -- `time_zone` (\*int32) - The new time zone for the virtual machine. This is a sysprep-dictated timezone code. Default 85 (GMT) +- `time_zone` (\*int32) - Specifies the time zone for the guest operating system. Default to `85` (Pacific Time). -- `workgroup` (string) - CustomizationIdentification - The workgroup for this virtual machine - AD Join is not supported +- `workgroup` (string) - Specifies the workgroup for the guest operating system. Joining an Active Directory domain is not supported. -- `computer_name` (string) - CustomizationUserData - The host name for this virtual machine. +- `computer_name` (string) - Specifies the hostname for the guest operating system. -- `full_name` (string) - The full name of the user of this virtual machine. Default: "Administrator" +- `full_name` (string) - Specifies the full name for the guest operating system's Administrator account. Defaults to `Administrator`. -- `organization_name` (string) - The organization name this virtual machine is being installed for. Default: "Managed by Packer" +- `organization_name` (string) - Specifies the organization name for the guest operating system. Defaults to `Built by Packer`. -- `product_key` (string) - The product key for this virtual machine. +- `product_key` (string) - Specifies the product key for the guest operating system. diff --git a/docs-partials/builder/vsphere/common/HardwareConfig-not-required.mdx b/docs-partials/builder/vsphere/common/HardwareConfig-not-required.mdx index e5b2c27cd..177cc9a79 100644 --- a/docs-partials/builder/vsphere/common/HardwareConfig-not-required.mdx +++ b/docs-partials/builder/vsphere/common/HardwareConfig-not-required.mdx @@ -19,10 +19,10 @@ - `RAM_hot_plug` (bool) - Enable RAM hot plug setting for virtual machine. Defaults to `false`. -- `video_ram` (int64) - Amount of video memory in KB. See [vSphere documentation](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-789C3913-1053-4850-A0F0-E29C3D32B6DA.html) +- `video_ram` (int64) - Amount of video memory in KB. See [vSphere documentation](https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-789C3913-1053-4850-A0F0-E29C3D32B6DA.html) for supported maximums. Defaults to 4096 KB. -- `displays` (int32) - Number of video displays. See [vSphere documentation](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-789C3913-1053-4850-A0F0-E29C3D32B6DA.html) +- `displays` (int32) - Number of video displays. See [vSphere documentation](https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-789C3913-1053-4850-A0F0-E29C3D32B6DA.html) for supported maximums. Defaults to 1. - `vgpu_profile` (string) - vGPU profile for accelerated graphics. See [NVIDIA GRID vGPU documentation](https://docs.nvidia.com/grid/latest/grid-vgpu-user-guide/index.html#configure-vmware-vsphere-vm-with-vgpu) diff --git a/docs-partials/builder/vsphere/common/StorageConfig-not-required.mdx b/docs-partials/builder/vsphere/common/StorageConfig-not-required.mdx index 4881cdb7f..d5825473e 100644 --- a/docs-partials/builder/vsphere/common/StorageConfig-not-required.mdx +++ b/docs-partials/builder/vsphere/common/StorageConfig-not-required.mdx @@ -2,7 +2,7 @@ - `disk_controller_type` ([]string) - Set VM disk controller type. Example `lsilogic`, `lsilogic-sas`, `pvscsi`, `nvme`, or `scsi`. Use a list to define additional controllers. Defaults to `lsilogic`. See - [SCSI, SATA, and NVMe Storage Controller Conditions, Limitations, and Compatibility](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-5872D173-A076-42FE-8D0B-9DB0EB0E7362.html#GUID-5872D173-A076-42FE-8D0B-9DB0EB0E7362) + [SCSI, SATA, and NVMe Storage Controller Conditions, Limitations, and Compatibility](https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-5872D173-A076-42FE-8D0B-9DB0EB0E7362.html) for additional details. - `storage` ([]DiskConfig) - Configures a collection of one or more disks to be provisioned along with the VM. See the [Storage Configuration](#storage-configuration).