# VMware vSphere Phase-1 Execution Plan Last updated: 2026-03-31 Status: ACTIVE Governance surfaces: - `status.json.candidate_lanes.platform-admission-execution` - `status.json.resolved_decisions.vmware-vsphere-vcenter-first-admission-model` ## Intent Pulse now has a locked architecture recommendation for VMware vSphere. This document turns that recommendation into an executable phase-1 plan so implementation can proceed without drifting into a provider-specific island, and so the harness can distinguish real pre-support progress from the final support claim. ## Current Checkpoint Current governed checkpoint: `first-lab-ready`, not `supported`. That means: 1. the architecture and support floor are locked 2. the bounded shared phase-1 implementation floor is landed 3. automated non-live proof covers the shared onboarding, projection, alerts/history, Assistant-read, and exclusion boundaries well enough that the next highest-value step is a real `vCenter` run 4. the remaining blockers to a support claim are live-only facts: privilege floor, supported version floor, and real-signal fidelity This checkpoint is an implementation handoff, not a product support claim. ## Support Decision Pulse should add VMware support, but only in one narrow form: 1. first-class platform id: `vmware-vsphere` 2. supported entry point: `vCenter` only 3. primary ingestion model: `api-backed` 4. phase-1 resource projections: canonical `agent`, `vm`, and `storage` 5. phase-1 product stance: read-first 6. assistant control: `read-only` 7. recovery support: `n/a` Implementation may continue on that basis. If live validation disproves the minimum privilege bundle, supported version floor, or declared support-floor coverage, Pulse should stop at governance and must not widen the support claim. ## Product Sentence Pulse phase-1 VMware support means a shared platform-connections path to `vCenter` that projects ESXi hosts, VMs, and datastores into the canonical Pulse resource model, surfaces alarms and history through the shared product surfaces, and keeps assistant behavior read-only. ## Why This Is A Separate Lane Slice This is not just another provider adapter. It crosses: - platform onboarding and saved-connection health - canonical inventory and identity projection - shared infrastructure, workload, and storage presentation - shared alert and incident surfaces - assistant read classification and action boundaries - support-floor proof before a matrix claim changes That makes VMware a cross-surface admission problem, not a monitoring-only implementation detail. ## Phase-1 Scope Phase 1 should include: 1. `vCenter` onboarding through the shared `Platform connections` workspace 2. host inventory projected as canonical `agent` 3. VM inventory and runtime state projected as canonical `vm` 4. datastore inventory and capacity state projected as canonical `storage` 5. topology metadata for datacenter, cluster, folder, resource-pool, and placement relationships under those shared resources 6. vSphere alarm state, overall health, and related event/task history through shared alert and incident surfaces 7. snapshot-tree visibility and recovery-adjacent VM context as read-side workload detail 8. assistant read on canonical VMware-backed resources through shared read paths only ## Explicit Exclusions Phase 1 should not include: 1. direct `ESXi` onboarding 2. agent-first VMware support 3. `physical-disk`, `system-container`, or `app-container` projections 4. treating vSphere snapshots as Pulse recovery support 5. restore, failover, changed-block recovery, or backup-orchestration claims 6. provider-local VMware pages, top-level resource types, or AI tools 7. assistant or operator control for VM power, snapshot lifecycle, guest operations, host maintenance, or cluster administration ## Execution Slices ### 1. Platform Connection Admission Owners: - `agent-lifecycle` - `api-contracts` Slice contract: - `docs/release-control/v6/internal/VMWARE_VCENTER_PHASE1_ONBOARDING_SPEC.md` - `docs/release-control/v6/internal/VMWARE_VCENTER_PHASE1_API_RUNTIME_SPEC.md` Deliver: - `vCenter` added only through the shared platform-connections workspace - one saved-connection contract for create, update, masked-secret preservation, test, health, and contribution summary - one backend contract for VMware session ownership, provider ownership, dual API-family access, and stable failure classification under that same saved connection model - explicit disabled/default behavior, reconnect semantics, and credential ownership on the shared platform-connections path Required proof: - real `vCenter` connection succeeds through the governed setup path - auth, TLS, endpoint, and permission failures classify cleanly - minimum privilege bundle is written down from live validation, not inferred - supported version floor is written down from live validation, not inferred - a real `vCenter` capability is recorded in `LOCAL_CAPABILITIES.md` so the support-floor proof path is explicit and reusable ### 2. Canonical Projection Floor Owners: - `monitoring` - `unified-resources` Slice contract: - `docs/release-control/v6/internal/VMWARE_VCENTER_PHASE1_RESOURCE_PROJECTION_SPEC.md` Deliver: - API-backed ingest from the official vCenter Automation API plus the Virtual Infrastructure JSON API - one canonical VMware source classification and `platformType: vmware-vsphere` on shared resources instead of provider-local source forks - stable identity and dedupe for ESXi hosts, VMs, and datastores - shared-resource projection with no provider-local `esxi-host`, `vsphere-vm`, or `vsphere-datastore` top-level types - relationship metadata for cluster, folder, placement, and datastore attachment without promoting those objects to new top-level Pulse types Required proof: - one real `vCenter` produces canonical `agent`, `vm`, and `storage` resources end to end as defined in the projection spec - topology, identity, and counts stay coherent across infrastructure and workload surfaces - no phase-1 path depends on a unified agent being installed on ESXi or guests ### 3. Alerts, History, And Assistant Read Owners: - `alerts` - `monitoring` - `ai-runtime` Slice contract: - `docs/release-control/v6/internal/VMWARE_VCENTER_PHASE1_ALERTS_AND_ASSISTANT_SPEC.md` Deliver: - vSphere alarm and health signals routed through shared alert/incident paths - event/task/performance context available where the shared monitoring and history model expects it - assistant read on canonical VMware-backed resources through shared tools and read-state views - no VMware-specific control verbs, remediation tools, or admin-plane promises Required proof: - shared alerts can drill into VMware-backed incidents without a provider-local shell - assistant can inspect canonical VMware-backed resources without special-case VMware tools or VMware-specific capability exposure - assistant control remains read-only in both product wording and runtime capability exposure Automated proof already landed for part of this slice: - `tests/integration/tests/38-vmware-ai-chat-mentions.spec.ts` - `tests/integration/tests/42-vmware-ai-chat-read-recovery.spec.ts` - `internal/ai/chat/context_prefetch_additional_test.go` - `internal/ai/chat/service_tooling_test.go` - `internal/ai/tools/control_resource_test.go` ### 4. Support Claim Ratchet Owners: - release-control governance - owning subsystem contracts above Companion proof matrix: - `docs/release-control/v6/internal/VMWARE_VCENTER_PHASE1_PROOF_MATRIX.md` - `docs/release-control/v6/internal/VMWARE_VCENTER_PHASE1_PROOF_RECORD_TEMPLATE.md` - `docs/release-control/v6/internal/VMWARE_VCENTER_PHASE1_RESOURCE_PROJECTION_SPEC.md` - `docs/release-control/v6/internal/records/vmware-vcenter-phase1-proof-blocked-2026-03-30.md` Deliver: - version floor documented - minimum privilege bundle documented - explicit phase-1 exclusions documented in support language - support matrix changed only after live proof exists - successful proof record written from the shared VMware proof template - blocked proof state replaced by a dated successful proof record only after the first real `vCenter` pass Required proof: - onboarding, inventory, storage, alerts, metrics/history, and assistant read all hold on a real `vCenter` - support wording matches the narrow floor exactly - the implementation can fail closed without silently inheriting direct-ESXi or recovery support claims Automated exclusion proof already landed for the shipped floor: - `internal/api/route_inventory_test.go` - `tests/integration/tests/41-vmware-phase1-exclusion-integrity.spec.ts` ## What Must Be True Before Pulse Can Say VMware Is Supported Pulse should not call VMware supported until all of these are true: 1. `vCenter` onboarding works through the shared platform-connections path 2. the minimum required privilege bundle is validated on a real environment 3. the supported `vCenter` version floor is validated on a real environment 4. ESXi hosts, VMs, and datastores project cleanly into canonical `agent`, `vm`, and `storage` 5. alarm, health, and metrics/history signals appear on the shared alert and monitoring surfaces 6. assistant read works on those canonical resources without VMware-specific tools 7. product wording keeps direct `ESXi`, recovery, and broad control out of the support claim ## Known Gaps Requiring Live Validation These are not reasons to block the planning decision, but they are reasons to block a support claim until proven: 1. exact minimum privilege bundle for a production-grade read-first floor 2. exact supported `vCenter` version floor 3. signal quality and consistency of alarms, events, and history across that version floor 4. whether guest-identity and snapshot-detail fidelity is sufficient in mixed VMware Tools coverage environments ## Primary Source Basis The architecture lock and this execution plan are grounded in the official VMware/Broadcom APIs: 1. vCenter and inventory/control surface: [vCenter VM APIs](https://developer.broadcom.com/xapis/vsphere-automation-api/latest/vcenter/) 2. detail and topology surface: [Virtual Infrastructure JSON API](https://developer.broadcom.com/xapis/virtual-infrastructure-json-api/latest/) 3. alarms: [AlarmManager GetAlarm](https://developer.broadcom.com/xapis/virtual-infrastructure-json-api/latest/sdk/vim25/release/AlarmManager/moId/GetAlarm/post/) 4. snapshots: [VirtualMachine snapshot API](https://developer.broadcom.com/xapis/virtual-infrastructure-json-api/latest/sdk/vim25/release/VirtualMachine/moId/snapshot/get/) 5. performance/history: [PerformanceManager QueryPerfComposite](https://developer.broadcom.com/xapis/virtual-infrastructure-json-api/latest/sdk/vim25/release/PerformanceManager/moId/QueryPerfComposite/post/) ## Next Decision The next proper move is the first real `vCenter` proof run. Additional non-live VMware work is still valid only when it: 1. closes a newly found shared-contract or shared-runtime gap 2. materially reduces first-lab risk 3. strengthens the same governed phase-1 floor instead of adding synthetic VMware-local polish Do not keep extending VMware through repetitive non-live polish once this plan is already `first-lab-ready`.