From b988ba07febc949ebdf4865f0c96a9f0b195555f Mon Sep 17 00:00:00 2001 From: "anthony.wen" Date: Mon, 11 May 2026 10:13:39 -0400 Subject: [PATCH] docs(atvm): add atvm_prep reference and workspace guardrail --- AGENTS.md | 4 + atvm/docs/automation/atvm-prep-reference.md | 98 +++++++++++++++++++++ 2 files changed, 102 insertions(+) create mode 100644 atvm/docs/automation/atvm-prep-reference.md diff --git a/AGENTS.md b/AGENTS.md index f92150b..81a9e5e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,3 +10,7 @@ Always let the user review the proposed commit scope and commit message first, a - Never commit or push to the nested `galaxy-complete` repo under `/home/aw/code/cds/galaxy-complete` without the user's explicit approval. - Never assume work in `/home/aw/code/cds` should be pushed to `rnd.cdsi.us.com`. + +## ATVM Prep Script Guardrail + +- Do not run `/root/atvm_prep/atvm_prep.py` unless the operator explicitly asks for an `atvm_prep` task. diff --git a/atvm/docs/automation/atvm-prep-reference.md b/atvm/docs/automation/atvm-prep-reference.md new file mode 100644 index 0000000..c7b4ced --- /dev/null +++ b/atvm/docs/automation/atvm-prep-reference.md @@ -0,0 +1,98 @@ +# 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.