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

[tenthirtyam]

Overview

Extend the vsphere-clone builder to support using remote OVF and OVA files as clone sources, in addition to the current support for standard virtual machine templates. Remote OVF/OVA support enables users to deploy virtual machines directly from OVF/OVA files accessible via HTTP/HTTPS URLs using vSphere's native OVF Manager capabilities available in the govmomi SDK.

Requirements

Requirement 1

User Story: As a user of the Packer plugin for vSphere, I want to deploy VMs from remote OVF files accessible via HTTP/HTTPS, so that I can use OVF templates from remote sources.

Acceptance Criteria

1. WHEN a user specifies a remote OVF URL as the clone source THEN the system SHALL successfully deploy from that OVF file using vSphere's OVF Manager via govmomi SDK.
2. WHEN a remote OVF source is specified THEN the system SHALL support HTTP and HTTPS protocols for file access.
3. WHEN a remote OVF source requires authentication THEN the system SHALL support basic authentication (username/password) as supported by vSphere's OVF Manager via govmomi SDK.
4. IF a remote OVF source is not accessible or deployment fails THEN the system SHALL return a clear error message indicating the URL and failure reason.

Requirement 2

User Story: As a user of the Packer plugin for vSphere, I want to deploy VMs from remote OVA files accessible via HTTP/HTTPS, so that I can use single-file OVA templates from remote sources.

Acceptance Criteria

1. WHEN a user specifies a remote OVA file URL as the clone source THEN the system SHALL successfully deploy from that OVA file using vSphere's OVF Manager via govmomi SDK.
2. WHEN a remote OVA file is specified THEN the system SHALL handle the single-file OVA format appropriately.
3. WHEN an OVA file is large THEN the system SHALL provide progress feedback during deployment by monitoring vSphere task progress.
4. IF an OVA file is corrupted or invalid THEN the system SHALL return a clear error message about file integrity issues.

Requirement 3

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

Acceptance Criteria

1. WHEN configuring a remote OVF/OVA source THEN the user SHALL be able to specify it using a remote_source block with url and optional authentication fields.

   HCL Examples:

   # Anonymous access (HTTP)
   source "vsphere-clone" "example" {
     remote_source = {
       url = "http://packages.example.com/templates/linux-ubuntu-24.04-lts.ovf"
     }
   }
   
   # Anonymous access (HTTPS)
   source "vsphere-clone" "example" {
     remote_source = {
       url = "https://packages.example.com/templates/linux-ubuntu-24.04-lts.ovf"
     }
   }
   
   # Basic authentication
   source "vsphere-clone" "example" {
     remote_source = {
       url      = "https://packages.example.com/artifacts/example.ovf"
       username = "template-user"
       password = "secure-password"
     }
   }
   
   # Using Packer variables for sensitive authentication (recommended)
   variable "ovf_username" {
     type      = string
     sensitive = true
   }
   
   variable "ovf_password" {
     type      = string
     sensitive = true
   }
   
   source "vsphere-clone" "example" {
     remote_source = {
       url      = "https://packages.example.com/artifacts/example.ovf"
       username = var.ovf_username
       password = var.ovf_password
     }
   }
   
   # Invalid: Cannot use multiple source types
   source "vsphere-clone" "example" {
     template = "linux-ubuntu-24.04-lts"
     remote_source = {
       url = "https://example.com/linux-ubuntu-24.04-lts.ovf"
     }  # ERROR
   }

2. WHEN both template field and remote source fields are specified THEN the Prepare() method SHALL return an error message "cannot specify both 'template' and 'remote_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 remote source authentication is required THEN the system SHALL support the following authentication methods as supported by vSphere's OVF Manager via govmomi SDK:

   • Basic authentication using username and password fields.
   • Anonymous access (no authentication required).

5. WHEN designing the remote source configuration THEN it SHALL follow consistent naming patterns with other source configuration blocks.

Requirement 4

User Story: As a user of the Packer plugin for vSphere, I want flexible authentication options for remote OVF/OVA sources, so that I can access templates from various secure endpoints with different authentication requirements.

Acceptance Criteria

1. WHEN using basic authentication THEN the system SHALL support username and password fields and pass these credentials to vSphere's OVF Manager via govmomi SDK.
2. WHEN no authentication is specified THEN the system SHALL attempt anonymous access to the remote URL via vSphere's OVF Manager using govmomi SDK.
3. WHEN accessing HTTPS endpoints THEN the system SHALL support standard TLS connections as handled by vSphere's OVF Manager via govmomi SDK.
4. WHEN authentication credentials are provided THEN the system SHALL not log or expose sensitive authentication information in error messages or debug output.
5. WHEN using sensitive authentication data THEN the system SHALL support Packer variables marked as sensitive = true and environment variable interpolation to avoid hardcoding credentials in configuration files.

Requirement 5

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

Acceptance Criteria

1. WHEN a remote OVF/OVA URL is not accessible THEN the system SHALL log the attempted URL and return a descriptive error message with HTTP status code or network error details.
2. WHEN authentication fails for a remote OVF/OVA source THEN the system SHALL return a clear error message indicating authentication failure without exposing credentials.
3. WHEN a remote OVF/OVA deployment is interrupted THEN the system SHALL provide clear error messages about the interruption and leverage vSphere's built-in retry mechanisms.
4. WHEN remote OVF/OVA operations succeed THEN the system SHALL log successful deployment progress with vSphere task status and completion statistics.
5. WHEN OVF/OVA file validation fails THEN the system SHALL provide specific error messages about what validation checks failed.

Requirement 6

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

Acceptance Criteria

1. WHEN a remote 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 deployment parameters THEN the system SHALL handle those parameters appropriately during deployment.
3. WHEN OVF deployment options are available THEN the system SHALL support configuration of deployment options such as network mapping and storage policies.
4. IF required OVF deployment 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 current templates continue to work without modification when remote OVF support is added.

Acceptance Criteria

1. WHEN existing configurations use the template field with regular VM templates THEN they SHALL continue to work without changes.
2. WHEN new remote 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 (template and remote OVF/OVA).