# 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`

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`

## 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.