cds-ai/atvm/docs/automation/atvm-prep-reference.md

ATVM Prep Script Reference

This document summarizes the behavior of the controller-local prep script:

• Host: atvm-cypress-vm-1 (192.168.3.190)
• Path: /root/atvm_prep/atvm_prep.py
• Execution rule: run all atvm_prep.py commands on 192.168.3.190 (ATVM Cypress controller).

Use this as a quick runbook when ATVM datastore/lun prep is requested.

Purpose

atvm_prep.py orchestrates DGS and VMware actions around a target DGS LUN name for ATVM test environments. It handles clone lifecycle cleanup, snapshot clone assignment, datastore mount/unmount operations, and optional VM register/unregister workflows.

Primary Modes

The script supports these operation modes:

1. -A / --automated_testing

• Prepare environment for automated testing.
• Cleans up prior assigned clone/lun state, creates a new clone from snapshot, assigns it, and force-mounts unresolved VMFS.

2. -M / --maintenance

• Prepare for maintenance against the specified DGS LUN.
• Cleans clone state, reassigns original/gold volume, rescans storage, and mounts the datastore.

3. -R / --register

• Register VMs only for the LUN currently assigned to the target client.
• Scans VMX files on datastore and registers missing VMs.

4. -U / --unregister

• Power off and unregister VMs only for the LUN currently assigned to the target client.

5. -rvgd / --rollback_vm_gold_disk

• Roll back target volume to a selected snapshot, then assign/mount for use.

Main Inputs

Notable arguments:

• -n / --dgs_lun_name (required): target DGS LUN base name
• -s / --snapshot_name: optional snapshot name; latest used when omitted
• -c / --client_name: defaults to CDS1-ESX165
• -vi / --vcenter_ip: defaults to 192.168.0.201
• -vu / --vcenter_username
• -vp / --vcenter_password
• -e / --esx_host_ip: defaults to 192.168.1.165

Workspace Shorthand Mapping

For requests in this workspace, operator shorthand may be expanded as follows:

1. Datastore/LUN shorthand for -n

• Gold -> AutomatedTest-VMBootImg-Gold
• Gold2 -> AutomatedTest-VMBootImg-Gold-2
• ComputeMigration (or compute migration) -> AutomatedTest-VMBootImgComputeMigration-Gold

2. Client/ESXi pairing (-c with -e)

• CDS1-ESX165 <-> 192.168.1.165
• CDS1-ESX166 <-> 192.168.1.166

3. Inference rules

• If only one side of the pair is supplied (-c or -e), auto-fill the other side from this mapping.
• If both are supplied but conflict, stop and confirm before execution.

4. Approval rule

• Always show the exact planned atvm_prep.py command and wait for explicit operator approval before execution.

Operational Flow

High-level behavior across modes:

1. Resolve DGS client and volume/policy IDs.
2. Resolve currently assigned volume for the target client where relevant.
3. If cleanup is required:

• Find datastore from LUN GUID.
• Power off VMs on that datastore.
• Unregister VMs.
• Unmount datastore on ESXi.
• Unassign and optionally delete clone on DGS.

4. Execute mode-specific action:

• create clone and assign (-A)
• assign gold and mount (-M)
• register only (-R)
• power off/unregister only (-U)
• rollback and reassign (-rvgd)

VMware Helpers In Script

Reusable functions implemented in atvm_prep.py include:

• datastore discovery from DGS LUN GUID
• force-mount unresolved VMFS volume
• datastore mount/unmount
• VM power-off by datastore membership
• VM unregister by datastore membership
• VMX discovery on datastore for registration

Safety Traits

The script intentionally exits on ambiguous or unsafe states, including:

• snapshot not found or duplicate snapshot names
• missing client/volume/datastore
• multiple datastores matching same GUID

For some operations (register, unregister, rollback) it prompts for explicit confirmation ([y/n]) before acting.

Known Caveats

1. Default credentials are hardcoded in script arguments.

• Treat these as legacy behavior and prefer supplying credentials explicitly in runtime usage.

2. main() contains this condition:

• if not is_register or not is_unregister:
• This is effectively true for almost all normal runs and likely intended as and.
• Do not change behavior blindly during operations; patch only with explicit operator approval.

3. Registration steps in -A, -M, and -rvgd paths are currently commented out.

• Datastore prep/mount occurs, but VM registration is not automatically performed in those paths unless script is modified.

Logging

• Script log directory: /root/atvm_prep/log
• Main log file: /root/atvm_prep/log/atvm_prep.log
• Rotating log handler is enabled in script.

Practical Usage Notes

• Prefer dry validation of target LUN/client/snapshot before destructive modes.
• Use -U for scoped VM power-off/unregister tied to LUN GUID mapping.
• Use -R after datastore mount when VM registration is required and safe.