Description

This pull request introduces a new mechanism for providing VMware Tools to virtual machines, adding support for explicit modes (upload, attach, and disable) and refactoring the configuration and implementation accordingly. It also adds robust logic for attaching VMware Tools ISO as a CD-ROM device, including slot detection and device management, and updates documentation to reflect these changes.

• Added explicit tools_mode configuration supporting three modes: upload (uploads ISO), attach (attaches ISO as CD-ROM), and disable (no ISO provided). This change is reflected in both documentation files (.web-docs/components/builder/iso/README.md and .web-docs/components/builder/vmx/README.md) and in code constants (builder/vmware/common/driver.go). [1] [2] [3] [4]
• Added new utility functions in cdrom_utils.go to find the next available CD-ROM slot, attach, and detach CD-ROM devices in VMX configuration data, supporting IDE, SATA, and SCSI adapters.
• Implemented StepAttachToolsCDROM, a new build step that attaches the VMware Tools ISO as a CD-ROM device based on configuration, handling device slot selection, error cases, and state management.
• Added comprehensive unit tests for the new step, covering all major scenarios: skipping when not in attach mode, handling missing ISO, successful attachment, conflict resolution, default adapter type usage, VMX read errors, and cleanup.
• Updated documentation for both ISO and VMX builders to describe the new tools_mode and clarify the usage and restrictions of related configuration options. [1] [2]

Valid Configurations

1. Upload Mode with Flavor

source "vmware-iso" "example" {
  # ... other configuration ...

  tools_mode          = "upload"
  tools_upload_flavor = "linux"
  tools_upload_path   = "/tmp/vmware-tools.iso"
}

2. Upload Mode with Flavor and Default Path

source "vmware-iso" "example" {
  # ... other configuration ...

  tools_mode          = "upload"
  tools_upload_flavor = "windows"
}

3. Upload Mode with Custom ISO File

source "vmware-iso" "example" {
  # ... other configuration ...

  tools_mode        = "upload"
  tools_source_path = "/path/to/vmware-tools.iso"
  tools_upload_path = "/tmp/custom-tools.iso"
}

4. Attach Mode with Local ISO

source "vmware-iso" "example" {
  # ... other configuration ...

  tools_mode        = "attach"
  tools_source_path = "/path/to/vmware-tools.iso"
}

5. Disabled Tools

source "vmware-iso" "example" {
  # ... other configuration ...

  tools_mode = "disable"
}

6. Upload Mode with Template Path

source "vmware-iso" "example" {
  # ... other configuration ...

  tools_mode          = "upload"
  tools_upload_flavor = "windows"
  tools_upload_path   = "/Users/packer/Downloads/{{ .Flavor }}-vmware-tools.iso"
}

Invalid Configurations

1. Missing tools_mode (when using tools config)

# ❌ INVALID: tools_mode must be explicitly specified
source "vmware-iso" "example" {
  # ... other configuration ...

  tools_upload_flavor = "windows"  # Error: requires tools_mode
}

Error: 'tools_mode' must be explicitly specified when using any tools configuration

2. Invalid tools_mode value

# ❌ INVALID: invalid tools_mode
source "vmware-iso" "example" {
  # ... other configuration ...

  tools_mode = "invalid_mode"
}

Error: invalid 'tools_mode' specified: invalid_mode; must be one of upload, attach, disable

3. Invalid tools_upload_flavor

# ❌ INVALID: invalid flavor
source "vmware-iso" "example" {
  # ... other configuration ...

  tools_mode          = "upload"
  tools_upload_flavor = "invalid_os"
}

Error: invalid 'tools_upload_flavor' specified: invalid_os; must be one of darwin, linux, windows

4. Conflicting upload configuration

# ❌ INVALID: cannot use both flavor and source path
source "vmware-iso" "example" {
  # ... other configuration ...

  tools_mode          = "upload"
  tools_upload_flavor = "linux"
  tools_source_path   = "/path/to/tools.iso"  # Conflict!
}

Error: 'tools_upload_flavor' and 'tools_source_path' cannot both be specified - use one or the other

5. Upload mode without source

# ❌ INVALID: upload mode needs either flavor or source path
source "vmware-iso" "example" {
  # ... other configuration ...

  tools_mode = "upload"
  # Missing: tools_upload_flavor OR tools_source_path
}

Error: 'tools_mode="upload"' requires either 'tools_upload_flavor' or 'tools_source_path'

6. Attach mode without source path

# ❌ INVALID: attach mode requires source path
source "vmware-iso" "example" {
  # ... other configuration ...

  tools_mode = "attach"
  # Missing: tools_source_path
}

Error: 'tools_source_path' is required when 'tools_mode="attach"'

7. Upload path with attach mode

# ❌ INVALID: upload path only works with upload mode
source "vmware-iso" "example" {
  # ... other configuration ...

  tools_mode        = "attach"
  tools_source_path = "/path/to/tools.iso"
  tools_upload_path = "/tmp/tools.iso"  # Invalid with attach mode
}

Error: 'tools_upload_path' can only be used with 'tools_mode="upload"', not 'tools_mode="attach"'

8. Non-existent source path

# ❌ INVALID: source file doesn't exist
source "vmware-iso" "example" {
  # ... other configuration ...

  tools_mode        = "attach"
  tools_source_path = "/nonexistent/path/tools.iso"
}

Error: tools source path does not exist: /nonexistent/path/tools.iso

9. Relative path (not absolute)

# ❌ INVALID: path must be absolute
source "vmware-iso" "example" {
  # ... other configuration ...

  tools_mode        = "attach"
  tools_source_path = "relative/path/tools.iso"
}

Error: tools source path must be absolute, got relative path: relative/path/tools.iso

10. Directory instead of file

# ❌ INVALID: source path points to directory
source "vmware-iso" "example" {
  # ... other configuration ...

  tools_mode        = "attach"
  tools_source_path = "/Applications/VMware Fusion.app"  # Directory, not file
}

Error: tools source path must be a file, not a directory: /Applications/VMware Fusion.app

Warnings

1. Ignored configuration with disabled mode

# ⚠️ WARNING: extra config ignored
source "vmware-iso" "example" {
  # ... other configuration ...

  tools_mode          = "disable"
  tools_upload_flavor = "linux"      # Ignored
  tools_upload_path   = "/tmp/tools"  # Ignored
  tools_source_path   = "/path/tools" # Ignored
}

Warnings:

• 'tools_upload_flavor' is ignored when 'tools_mode="disable"'
• 'tools_upload_path' is ignored when 'tools_mode="disable"'
• 'tools_source_path' is ignored when 'tools_mode="disable"'

Resolved Issues

Closes #281

Rollback Plan

Revert commit.

Changes to Security Controls

None.