anthony.wen/cds-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

cdsmcp: add direct ESX VM hardware workflow guide

Browse Source 
Add a dedicated ESX VM guide for read-first hardware change workflows,
including disk creation, datastore VMDK attachment, and PCI passthrough
assignment.

Update the existing lookup/assignment runbook and top-level docs to
reference the new guide and require explicit reporting of VM name
mismatches and missing datastore directories before any change.
This commit is contained in:
anthony.wen
2026-04-24 11:09:13 -04:00
parent 2e25c2ae2b
commit a02227fbe5
4 changed files with 62 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
cdsmcp/AGENTS.md
View File

@@ -7,6 +7,8 @@ This folder contains the VMware/vCenter + MigrateOps runbook for CDS MCP workflo
- top-level navigation
- `docs/vmware-migrateops-guide.md`
- authoritative VMware compute migration workflow
- `docs/esxvm-guide.md`
- direct vCenter VM hardware review/change workflow
- `docs/vm-lookup-and-assignment.md`
- VM lookup, datastore reporting, and FC/disk assignment workflow
- `docs/cmc-install-reference.md`
@@ -20,6 +22,7 @@ This folder contains the VMware/vCenter + MigrateOps runbook for CDS MCP workflo
## Source Of Truth
- Use `docs/vmware-migrateops-guide.md` for how to execute VMware compute migration runs.
- Use `docs/esxvm-guide.md` for direct vCenter VM hardware changes such as new disks, existing-disk attach, and PCI passthrough assignment.
- Use `docs/vm-lookup-and-assignment.md` for VM lookup responses and FC/disk assignment requests.
- Use `docs/cmc-install-reference.md` for CMC install/uninstall commands and fallback reinstall notes.
- Use `templates/vmw.yaml` as the starting operation template.
@@ -49,6 +52,7 @@ This folder contains the VMware/vCenter + MigrateOps runbook for CDS MCP workflo
## Update Rules
- Update `docs/vmware-migrateops-guide.md` only when migration workflow/default behavior changes.
- Update `docs/esxvm-guide.md` only when direct vCenter hardware workflow/default behavior changes.
- Update `docs/vm-lookup-and-assignment.md` only when lookup/assignment workflow behavior changes.
- Update `docs/cmc-install-reference.md` only when install or reinstall reference behavior changes.
- Update `docs/run-learnings.md` only when a run reveals a new learning/failure pattern/required check.

2
cdsmcp/README.md
View File

@@ -5,6 +5,8 @@ This folder contains the VMware/vCenter and MigrateOps runbook material used for
## Start Here
- VMware compute migration workflow:
- `docs/vmware-migrateops-guide.md`
- Direct vCenter VM hardware review/change workflow:
- `docs/esxvm-guide.md`
- VM lookup and FC/disk assignment workflow:
- `docs/vm-lookup-and-assignment.md`
- CMC install and uninstall reference:

53
cdsmcp/docs/esxvm-guide.md Normal file
View File

@@ -0,0 +1,53 @@
# ESX VM Guide
This file covers read-only review and approval rules for direct vCenter VM hardware changes.
## Scope
- Use this guide for direct vCenter VM hardware work such as:
- creating a new VM disk
- attaching existing datastore VMDKs
- assigning PCI passthrough devices
## vCenter Access
- Always log into vCenter `192.168.0.201`.
- Source `/home/aw/code/cds/.env.credentials.local` and use `VCENTER_USER` plus `VCENTER_PASSWORD`.
- Standard CLI path: `/home/aw/.local/bin/govc`
- Default datacenter: `CDSHQ-Eng`
## Review-First Rule
- Treat direct VM hardware changes as a two-step workflow:
- first gather and report findings
- then wait for explicit operator approval before making any change
- Never create, attach, remove, or reassign hardware until the operator explicitly approves after seeing the summary.
## VM Identification Rule
- When the requested VM name is not present exactly as given, search for the closest live inventory name and report the mismatch before planning any change.
- Do not act on a guessed VM silently.
## Host And Datastore Checks
- Find the specified VM and verify the ESXi host it is currently running on.
- Default expected ESXi host is `192.168.1.165`, but always verify live placement before planning changes.
- Always identify and report the datastore where the VM is stored before planning disk work.
## New Disk Creation Rule
- When asked to create a new disk for a VM:
- inspect the VM's current controller layout first
- prefer the existing SCSI controller already backing the VM disks unless the operator explicitly asks for a different controller
- report the controller label, controller type, and the next free unit number before proposing the change
- report the target datastore and requested size before proposing the change
- if the VM has snapshots, include that fact in the review summary before the operator approves
## Existing Disk And FC Assignment Rule
- For existing-disk and FC-passthrough requests, use the workflow in `vm-lookup-and-assignment.md`.
- If the specified devices or disk files cannot be found exactly as requested, do nothing.
## Summary Requirement
- Before any direct VM hardware change, always report:
- VM name found
- guest hostname when available
- ESXi host
- datastore
- current controller layout relevant to the request
- snapshot state when relevant
- exactly what would be changed
- any blockers that mean nothing will be changed

3
cdsmcp/docs/vm-lookup-and-assignment.md
View File

@@ -26,6 +26,7 @@ This file covers vCenter VM lookup responses and the workflow for assigning exis
- then wait for explicit approval before making any changes
- Always log into vCenter `192.168.0.201`.
- Find the specified VM and verify the ESXi host it is currently running on.
- If the requested VM name is not present exactly as given, search for the closest live inventory name and report the mismatch before planning any change.
- Default expected ESXi host is `192.168.1.165`, but always verify live placement before planning changes.
- Always identify and report the datastore where the VM is stored before planning disk attachment.
- Unless the operator explicitly specifies alternatives, default to these PCI passthrough FC adapters:
@@ -37,8 +38,10 @@ This file covers vCenter VM lookup responses and the workflow for assigning exis
- `atvm-DISK_2.vmdk`
- Do not substitute any other disks if either default or operator-specified disk cannot be found.
- If the specified adapters or specified disks cannot be found, do nothing and report that nothing will be assigned.
- For these requests, never substitute a different datastore directory when `atvm-DISKS` is missing.
- Before any assignment action, always provide a summary of:
- the VM found
- any name mismatch between requested VM name and live inventory VM name
- the ESXi host
- the datastore
- whether `vmhba7` and `vmhba8` were found and are usable