From a02227fbe524998a70660d3ced9e8d1e54c14928 Mon Sep 17 00:00:00 2001 From: "anthony.wen" Date: Fri, 24 Apr 2026 11:09:13 -0400 Subject: [PATCH] cdsmcp: add direct ESX VM hardware workflow guide 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. --- cdsmcp/AGENTS.md | 4 ++ cdsmcp/README.md | 2 + cdsmcp/docs/esxvm-guide.md | 53 +++++++++++++++++++++++++ cdsmcp/docs/vm-lookup-and-assignment.md | 3 ++ 4 files changed, 62 insertions(+) create mode 100644 cdsmcp/docs/esxvm-guide.md diff --git a/cdsmcp/AGENTS.md b/cdsmcp/AGENTS.md index adafdf1..534bf0d 100644 --- a/cdsmcp/AGENTS.md +++ b/cdsmcp/AGENTS.md @@ -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. diff --git a/cdsmcp/README.md b/cdsmcp/README.md index f2d57df..b71f05c 100644 --- a/cdsmcp/README.md +++ b/cdsmcp/README.md @@ -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: diff --git a/cdsmcp/docs/esxvm-guide.md b/cdsmcp/docs/esxvm-guide.md new file mode 100644 index 0000000..8152b75 --- /dev/null +++ b/cdsmcp/docs/esxvm-guide.md @@ -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 diff --git a/cdsmcp/docs/vm-lookup-and-assignment.md b/cdsmcp/docs/vm-lookup-and-assignment.md index 2671d46..e0b10fb 100644 --- a/cdsmcp/docs/vm-lookup-and-assignment.md +++ b/cdsmcp/docs/vm-lookup-and-assignment.md @@ -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