Extend the `vsphere-clone` builder to support using local OVF and OVA files as clone sources

[tenthirtyam]

Overview

Extend the vsphere-clone builder to support using local OVF and OVA files as clone sources, in addition to the current support for standard virtual machine templates. Local OVF/OVA support enables users to clone virtual machines directly from OVF/OVA files stored on the local file system where Packer is running.

Requirements

Requirement 1

User Story: As a user of the Packer plugin for vSphere, I want to clone virtual machines from local OVF files stored on my file system, so that I can use OVF templates directly.

Acceptance Criteria

1. WHEN a user specifies a local OVF file path as the clone source THEN the system SHALL successfully read and clone from that OVF file.
2. WHEN a local OVF source is specified THEN the system SHALL support both absolute and relative file paths.
3. WHEN a local OVF file path uses relative paths THEN the system SHALL resolve them relative to the configuration file location.
4. IF a local OVF file is not accessible or does not exist THEN the Prepare() method SHALL return an error early with a clear message indicating the file path and access issue.

Requirement 2

User Story: As a user of the Packer plugin for vSphere, I want to clone virtual machines from local OVA files stored on my file system, so that I can use single-file OVA templates locally.

Acceptance Criteria

1. WHEN a user specifies a local OVA file path as the clone source THEN the system SHALL successfully read and clone from that OVA file.
2. WHEN a local OVA file is specified THEN the system SHALL handle the single-file OVA format appropriately.
3. IF an OVA file is corrupted or invalid THEN the Prepare() method SHALL return an error early with a clear message about file integrity issues.

Requirement 3

User Story: As a user of the Packer plugin for vSphere, I want the local OVF/OVA source configuration to be intuitive and consistent with other source specification patterns, so that I can easily configure local sources.

Acceptance Criteria

1. WHEN configuring a local OVF/OVA source THEN the user SHALL be able to specify it using a local_source field with a direct string path value.

   HCL Examples:

   # Absolute path to OVF file
   source "vsphere-clone" "example" {
     local_source = "/home/user/templates/linux-ubuntu-24.04-lts.ovf"
   }
   
   # Relative path to OVA file (relative to config file)
   source "vsphere-clone" "example" {
     local_source = "./templates/linux-ubuntu-24.04-lts.ova"
   }
   
   # Using variables for file paths
   variable "template_path" {
     type = string
   }
   
   source "vsphere-clone" "example" {
     local_source = var.template_path
   }
   
   # Using environment variables in path
   source "vsphere-clone" "example" {
     local_source = "${env("TEMPLATE_DIR")}/linux-ubuntu-24.04-lts.ovf"
   }
   
   # Windows path example
   source "vsphere-clone" "example" {
     local_source = "C:\\Templates\\linux-ubuntu-24.04-lts.ova"
   }
   
   # Invalid: Cannot use multiple source types
   source "vsphere-clone" "example" {
     template = "linux-ubuntu-24.04-lts"
     local_source = "./templates/linux-ubuntu-24.04-lts.ovf"  # ERROR
   }

2. WHEN both template field and local_source field are specified THEN the Prepare() method SHALL return an error message "cannot specify both 'template' and 'local_source' - choose one source type".

3. WHEN multiple source types are specified THEN the Prepare() method SHALL validate mutual exclusivity among all source types.

4. WHEN designing the local source configuration THEN it SHALL use a simple string field for ease of use and consistency with similar Packer patterns.

Requirement 4

User Story: As a user of the Packer plugin for vSphere, I want flexible file path handling for local OVF/OVA sources, so that I can organize my templates in various directory structures and reference them easily.

Acceptance Criteria

1. WHEN using absolute file paths THEN the system SHALL access files directly using the provided absolute path.
2. WHEN using relative file paths THEN the system SHALL resolve them relative to the directory containing the configuration file.
3. WHEN file paths contain environment variables THEN the system SHALL expand environment variables before accessing the file.
4. WHEN file paths contain variables THEN the system SHALL interpolate variables before accessing the file.
5. WHEN file paths contain special characters or spaces THEN the system SHALL handle them correctly across different operating systems.
6. WHEN accessing files on different operating systems THEN the system SHALL handle path separators appropriately (forward slash on Unix-like systems, backslash on Windows).

Requirement 5

User Story: As a user of the Packer plugin for vSphere, I want comprehensive error handling and validation for local OVF/OVA operations, so that I can troubleshoot issues effectively when local files are not accessible or invalid.

Acceptance Criteria

1. WHEN a local OVF/OVA file does not exist THEN the Prepare() method SHALL return an error early with a clear message indicating the file path and that the file was not found.
2. WHEN a local OVF/OVA file exists but is not readable THEN the Prepare() method SHALL return an error early with a clear message about file permissions or access issues.
3. WHEN a local OVF/OVA file is corrupted or has invalid format THEN the Prepare() method SHALL perform basic validation and return an error early with specific messages about what validation checks failed.
4. WHEN local OVF/OVA operations succeed THEN the system SHALL log successful file reading and cloning progress with file size information.
5. WHEN file path resolution fails THEN the Prepare() method SHALL return an error early with clear messages about path resolution issues.

Requirement 6

User Story: As a user of the Packer plugin for vSphere, I want support for vApp properties and OVF-specific configurations when cloning from local OVF/OVA sources, so that I can fully utilize OVF template capabilities.

Acceptance Criteria

1. WHEN a local OVF source defines vApp properties THEN the system SHALL support configuration of those properties through the existing vApp configuration block.
2. WHEN an OVF file requires specific clone parameters THEN the system SHALL handle those parameters appropriately during cloning.
3. WHEN OVF clone options are available THEN the system SHALL support configuration of clone options such as network mapping and storage policies.
4. IF required OVF clone parameters are missing THEN the system SHALL provide clear error messages about which parameters are required.

Requirement 7

User Story: As a user of the Packer plugin for vSphere, I want backward compatibility with existing vsphere-clone configurations, so that the current template pattern continues to work without modification when local OVF/OVA support is added.

Acceptance Criteria

1. WHEN existing configurations use the template field with standard virtual machine templates THEN they SHALL continue to work without changes.
2. WHEN new local source fields are added THEN they SHALL not affect existing template-based configurations.
3. WHEN the plugin loads existing configurations THEN no breaking changes SHALL be introduced to the configuration schema.
4. WHEN documentation is updated THEN it SHALL clearly explain all available source types.

Requirement 8

User Story: As a user of the Packer plugin for vSphere, I want the local OVF/OVA cloning to use vSphere's native APIs without requiring external tools, so that I don't need to install and manage additional dependencies.

Acceptance Criteria

1. WHEN cloning from local OVF/OVA files THEN the system SHALL use vSphere's native OVF deployment APIs through the govmomi library.
2. WHEN the system processes OVF/OVA files THEN it SHALL NOT require any external tools (e.g., VMware OVFTool) to be installed.
3. WHEN OVF cloning is performed THEN the system SHALL leverage the existing vSphere API client connection used by other vsphere-clone operations.
4. IF vSphere's native OVF APIs cannot handle a specific OVF/OVA file THEN the system SHALL provide a clear error message about the incompatibility.

Requirement 9

User Story: As a user of the Packer plugin for vSphere, I want reliable handling of local OVA/OVF files during cloning, so that the process works consistently regardless of file size.

Acceptance Criteria

1. WHEN local file operations are performed THEN the system SHALL validate basic file accessibility and format before attempting cloning to vSphere.
2. WHEN OVF/OVA cloning is in progress THEN the system SHALL provide basic status logging consistent with other vsphere-clone operations.
3. IF local file processing or cloning fails THEN the system SHALL provide clear error messages about the failure and cleanup any partial operations.