Feature Overview (mandatory - Complete while in New status)
The VMware Migration Kit requires a mechanism to customize virtual machine guest operating systems during and after migration to OpenStack. Script Hooks provide users the ability to inject custom scripts at two critical points in the migration workflow: during the V2V conversion process (runscript) and at the first boot of the migrated VM in OpenStack (bootscript). This feature enables network reconfiguration, driver updates, application adjustments, and any guest-level changes necessary to ensure VMs operate correctly in their new OpenStack environment—reducing migration failures and post-migration manual intervention.

Goals (mandatory - Complete while in New status)

• Cloud Migration Engineers: Can automate guest OS customizations during migration without manual intervention

• System Administrators: Can ensure consistent network configuration and driver setup across all migrated VMs
• Operations Teams: Reduce post-migration troubleshooting by addressing OS-level changes proactively

Requirements (mandatory -_ Complete while in Refinement status):

Done - Acceptance Criteria (mandatory - Complete while in Refinement status):

AC1: When runscript is provided, the script executes during V2V conversion for Linux guests and the migration completes successfully

AC2: When bootscript is provided, the script is configured to run on first boot of the migrated VM in OpenStack

AC3: If runscript or bootscript path does not exist, the migration fails with a clear error message

AC4: Default network_config.sh is auto-generated from template using MAC addresses extracted from VMware metadata

AC5: Generated udev rules correctly map VMware MAC addresses to interface names, supporting:

• NetworkManager system connections
• sysconfig ifcfg-* files
• Netplan YAML configurations

AC6: Scripts are not executed for Windows guests (runscript only applies to Linux)

AC7: Documentation covers script hook usage with examples for common use cases

Use Cases - i.e. User Experience & Workflow: (Initial completion while in Refinement status):

Use Case 1: Network Interface Preservation

Actor: Migration EngineerScenario: Migrating a Linux VM with multiple network interfacesFlow:

1. Export VM metadata from VMware (includes MAC addresses)
2. Migration workflow auto-generates network_config.sh from template
3. During V2V conversion, runscript creates udev rules mapping MACs to interface names
4. VM boots in OpenStack with preserved network configuration

Use Case 2: Custom First-Boot Configuration

Actor: System AdministratorScenario: Installing cloud-init compatible agents on first bootFlow:

1. Admin provides custom bootscript path via import_workloads_boot_script_path variable
2. Bootscript is injected into VM during V2V conversion
3. On first boot in OpenStack, bootscript executes (e.g., configures monitoring agents, registers with management systems)

Use Case 3: Advanced V2V Options

Actor: Advanced UserScenario: Migrating encrypted LUKS volumesFlow:

1. User provides extraopts: "--key LUKS" parameter
2. Combined with scripts, V2V handles encrypted disk conversion
3. Scripts handle any post-decryption configuration

Out of Scope _{}(Initial completion while in Refinement status):{_}

• Windows guest runscript execution (Windows VMs are powered off before snapshot; bootscript may still apply)

Documentation Considerations _{}(Initial completion while in Refinement status):{_}

1. How to use runscript, bootscript, and extraopts
2. Template customization guide for network_config.sh.j2
3. Troubleshooting guide for script-related migration failures
4. Examples for common customization scenarios:
   1. Network interface remapping
   2. Cloud-init configuration
   3. Driver installation
   4. Application reconfiguration

Questions to Answer _{}(Initial completion while in Refinement status):{_}

1. Should we provide a library of pre-built bootscript templates for common scenarios (cloud-init setup, monitoring agent installation)?
2. Is there a need for Windows-specific first-boot customization using sysprep or similar mechanisms?
3. Should script execution results be captured and returned in module output for debugging?
4. Do we need rollback capabilities if script execution fails?
5. Should scripts be validated (syntax check) before migration starts?

Background and Strategic Fit (Initial completion while in Refinement status):
Script Hooks are a core component of the VMware-to-OpenStack migration workflow within the os_migrate.vmware_migration_kit Ansible collection. They leverage virt-v2v-in-place capabilities to modify guest filesystems during the conversion process. This aligns with the collection's goal of providing automated, repeatable migrations with minimal manual intervention.

Customer Considerations _{}(Initial completion while in Refinement status):{_}

1. Script Security: Scripts execute with elevated privileges inside the guest; customers should review scripts for security implications
2. Testing Requirements: Scripts should be tested on representative VMs before large-scale migrations
3. Network Complexity: Environments with VLANs, bonds, or complex network configurations may require custom script modifications
4. OS Support Matrix: Template supports RHEL, CentOS, Ubuntu (NetworkManager, sysconfig, netplan); other distributions may require custom templates
5. Failure Handling: Script failures will cause migration to fail; customers should have rollback procedures

Team Sign Off (Completion while in Planning status)

• All required Epics (known at the time) are linked to the this Feature
• All required Stories, Tasks (known at the time) for the most immediate Epics have been created and estimated
• Add - Reviewers name, Team Name
• Acceptance == Feature as “Ready” - well understood and scope is clear - Acceptance Criteria (scope) is elaborated, well defined, and understood
• Note: Only set FixVersion/s: on a Feature if the delivery team agrees they have the capacity and have committed that capability for that milestone

• …