diff --git a/docs/release-control/v6/internal/PLATFORM_SUPPORT_MODEL.md b/docs/release-control/v6/internal/PLATFORM_SUPPORT_MODEL.md index 6eaa7e8a3..2e003c817 100644 --- a/docs/release-control/v6/internal/PLATFORM_SUPPORT_MODEL.md +++ b/docs/release-control/v6/internal/PLATFORM_SUPPORT_MODEL.md @@ -269,22 +269,78 @@ all of these questions before implementation starts: If those answers are not yet stable, the work must stop at a governed open-decision or resolved-decision update instead of starting runtime code. -## Likely vSphere Path +## VMware vSphere Admission Model -If VMware vSphere is added in v6 or later, the default evaluation path is: +Pulse now has a resolved architecture recommendation for any future VMware +vSphere work. This does not admit `vmware-vsphere` into the current support +matrix yet. It defines the only acceptable phase-1 model if implementation +starts. -1. treat it as a separate first-class platform id such as `vmware-vsphere`, - not as another Proxmox subtype and not as a generic future-label shortcut -2. assume API-backed primary ingestion unless governance explicitly chooses an - agent-first or hybrid contract -3. reuse canonical `agent` for host-like top-level systems when that model is - appropriate, `vm` for guests, and `storage` for datastores; do not invent - `esxi-host` or `vsphere-vm` types by default -4. require explicit answers for host-versus-cluster top-level identity, - vCenter-versus-direct-ESXi support, storage/datastore scope, recovery - truth, alerts floor, assistant read, assistant control, and any agent - augmentation rule before implementation starts +1. treat VMware as one separate first-class platform id, + `vmware-vsphere`, not as another Proxmox subtype and not as a generic + future-label shortcut +2. use `vCenter` as the only supported phase-1 entry point +3. treat direct `ESXi` onboarding as deferred work, not as an implied part of + the vCenter claim +4. keep the primary ingestion mode `api-backed` +5. use official VMware APIs first: vCenter Automation API for modern inventory + and VM control surfaces, plus the Virtual Infrastructure JSON API for + alarm, event, snapshot, and performance/detail paths +6. treat a Pulse-managed agent only as future augmentation for deeper host or + guest behavior, not as a bootstrap requirement or primary support contract +7. project ESXi hosts as canonical `agent`, guest workloads as canonical `vm`, + and datastores as canonical `storage` +8. keep vCenter, datacenter, cluster, folder, and resource-pool objects as + topology or relationship metadata under those shared resources rather than + inventing top-level `esxi-host`, `vsphere-cluster`, or `vsphere-vm` types +9. keep `physical-disk`, `system-container`, `app-container`, and recovery + artifacts out of the phase-1 projection contract unless a later governed + slice proves they belong on the shared path -Adding `vmware-vsphere` to a label helper, filter list, or presentation badge -does not admit the platform. Admission happens only when this model, the -owning contracts, and the required proof surfaces are updated together. +| Platform | Family | Entry point | Primary mode | Optional augmentation | Canonical projections | Admission state | +| --- | --- | --- | --- | --- | --- | --- | +| `vmware-vsphere` | VMware | `vCenter` only in phase 1 | `api-backed` | host or guest agent later, not phase 1 | `agent`, `vm`, `storage` | architecture locked, not yet admitted | + +## VMware vSphere Proposed Phase-1 Floor + +This is the proposed phase-1 support floor once implementation and proof land. +It is not a claim that VMware is currently supported in Pulse. + +| Platform | Setup | Visibility | Workloads | Storage | Recovery | Alerts | Assistant read | Assistant control | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| `vmware-vsphere` | platform connections to `vCenter` only | supported | supported | supported | `n/a` | supported | supported | read-only | + +Phase-1 floor details: + +1. visibility means inventory and topology read across vCenter-backed ESXi + hosts, VM placement, and datastore relationships +2. workloads means VM inventory, power/runtime state, guest identity when the + API exposes it, snapshot-tree visibility, and metrics/alarm context +3. storage means datastore inventory, capacity/free-space/accessibility, host + attachments, and VM-to-datastore usage +4. recovery stays `n/a` in the platform matrix because vSphere snapshots and + changed-disk APIs are recovery-adjacent read signals, not a governed Pulse + recovery-artifact or restore surface by themselves +5. alerts means vSphere alarm state, overall health state, and related + event/task history projected through shared alert and incident paths +6. assistant control stays read-only even though VMware exposes real control + APIs, because Pulse has not yet expanded the governed action surface into a + general VMware admin plane + +Phase-1 exclusions: + +1. direct `ESXi` onboarding +2. `physical-disk` projection, including vSAN-only physical disk health APIs +3. `system-container` or `app-container` projections +4. treating vSphere snapshots as shared Pulse recovery support +5. assistant or operator control claims for VM power, snapshot lifecycle, or + guest operations +6. any provider-local resource type, page shell, or AI tool family + +Support gate: + +Pulse should not call VMware supported until a real vCenter proves the declared +floor end to end: connection onboarding, minimum privilege bundle, supported +version floor, canonical `agent`/`vm`/`storage` projections, alert and metrics +history truth, and assistant read behavior. If that proof does not hold, +implementation must stop at governance rather than widening the support claim. diff --git a/docs/release-control/v6/internal/SOURCE_OF_TRUTH.md b/docs/release-control/v6/internal/SOURCE_OF_TRUTH.md index 5d0be4ae0..19d3a76f3 100644 --- a/docs/release-control/v6/internal/SOURCE_OF_TRUTH.md +++ b/docs/release-control/v6/internal/SOURCE_OF_TRUTH.md @@ -469,6 +469,57 @@ owning subsystem contracts; user-facing claims must not exceed this floor. tools, host command execution without the unified agent, or broader action promises ahead of the existing action-governance coverage gap. +## VMware vSphere Admission Model + +Pulse v6 now has one locked architecture recommendation for any future VMware +vSphere work. This is not a current support claim. It defines the only +acceptable phase-1 model if implementation starts. + +1. Architecture boundary: + VMware vSphere should enter Pulse only as the first-class + `vmware-vsphere` platform. Phase 1 is `vCenter` only; direct `ESXi` is + deferred work and must not inherit support by implication. +2. Ingestion model: + VMware should be API-first. The baseline path is the official vCenter + Automation API plus the Virtual Infrastructure JSON API. A Pulse-managed + agent may augment a VMware environment later, but it is not part of the + bootstrap or baseline support contract. +3. Canonical resource projections: + ESXi hosts must project as canonical `agent`, guest workloads as canonical + `vm`, and datastores as canonical `storage`. vCenter, datacenter, cluster, + folder, and resource-pool objects remain topology or relationship metadata, + not top-level Pulse resource types. Out of scope for phase 1: provider-local + `esxi-host` or `vsphere-vm` types plus `physical-disk`, `system-container`, + or `app-container` projections. +4. Visibility, workloads, and storage: + The phase-1 floor is read-first infrastructure support through shared Pulse + surfaces: host inventory, VM inventory/runtime/guest identity when the API + exposes it, snapshot-tree visibility, datastore capacity/accessibility, and + metrics/alarm context routed onto the shared resource model. +5. Recovery: + vSphere snapshots and changed-disk visibility are useful read-side signals, + but they do not make VMware a recovery-supported platform in Pulse by + themselves. Until shared recovery artifacts and restore flows exist on the + governed path, VMware recovery stays out of the support claim. +6. Alerts: + The phase-1 floor may include vSphere alarm state, overall health state, + and related event/task history when those signals are projected through the + shared alerts, incidents, and resource-timeline contracts instead of a + provider-local incident surface. +7. Assistant read/control: + Assistant read may be supported on those canonical resources once the + shared read paths land. Assistant control stays read-only in phase 1 even + though VMware exposes power, snapshot, and guest-operation APIs, because + Pulse is not yet claiming a broad VMware action plane ahead of the existing + action-governance coverage gap. +8. Support gate: + Do not call VMware supported until a real vCenter proves connection + onboarding, the minimum privilege bundle, the supported version floor, + canonical `agent`/`vm`/`storage` projection, alert and metrics-history + truth, and assistant read behavior. If those proofs do not hold, + implementation should stop at governance rather than shipping an inflated + support claim. + ## Cross-Repo Contracts These contracts must not drift: diff --git a/docs/release-control/v6/internal/status.json b/docs/release-control/v6/internal/status.json index 364824a53..b2d86b73f 100644 --- a/docs/release-control/v6/internal/status.json +++ b/docs/release-control/v6/internal/status.json @@ -3915,6 +3915,24 @@ "L15", "L16" ] + }, + { + "id": "vmware-vsphere-vcenter-first-admission-model", + "summary": "VMware vSphere is architecture-locked as a vCenter-first, API-first platform candidate: phase 1 projects ESXi hosts as `agent`, VMs as `vm`, datastores as `storage`, keeps direct ESXi out of scope, treats snapshots as read-side workload context rather than recovery support, and leaves assistant control read-only until the governed action model expands.", + "kind": "architecture", + "decided_at": "2026-03-30", + "subsystem_ids": [ + "ai-runtime", + "api-contracts", + "monitoring", + "storage-recovery", + "unified-resources" + ], + "lane_ids": [ + "L6", + "L13", + "L15" + ] } ] } diff --git a/docs/release-control/v6/internal/subsystems/monitoring.md b/docs/release-control/v6/internal/subsystems/monitoring.md index 65d0a0a4b..2c772da92 100644 --- a/docs/release-control/v6/internal/subsystems/monitoring.md +++ b/docs/release-control/v6/internal/subsystems/monitoring.md @@ -71,6 +71,15 @@ This subsystem now sits under the dedicated core monitoring runtime lane so discovery, metrics-history correctness, and platform-specific runtime coverage can be governed as first-class product work instead of staying diluted inside architecture coherence. +VMware vSphere now also has a locked phase-1 ingestion boundary under this +lane. If `vmware-vsphere` implementation starts, monitoring must treat vCenter +as the only supported phase-1 entry point and must stay API-first through the +official vCenter Automation API plus the Virtual Infrastructure JSON API. +Direct ESXi remains out of phase 1 because the standalone host-agent hierarchy +is materially narrower than the vCenter inventory and the declared support +floor depends on vCenter-backed topology, shared datastore scope, alarm state, +and historical performance access. Any later direct-ESXi work must be admitted +explicitly instead of inheriting vCenter support by implication. The monitor adapter now also acts as the canonical bridge from live registry rebuilds and supplemental ingest into the unified-resource timeline. That means diff --git a/docs/release-control/v6/internal/subsystems/unified-resources.md b/docs/release-control/v6/internal/subsystems/unified-resources.md index 132482a12..7c3066163 100644 --- a/docs/release-control/v6/internal/subsystems/unified-resources.md +++ b/docs/release-control/v6/internal/subsystems/unified-resources.md @@ -170,6 +170,16 @@ assembly branch. This subsystem now sits under the dedicated core monitoring runtime lane so canonical resource identity, discovery normalization, and platform-runtime coverage stay governed as a first-class Pulse product surface. +VMware vSphere now follows the same admission rule. If `vmware-vsphere` +implementation starts, vCenter is the phase-1 connection authority but not a +top-level unified resource: ESXi hosts must project as canonical `agent` +resources, virtual machines as canonical `vm`, and datastores as canonical +`storage`. Datacenters, clusters, folders, and resource pools stay topology or +relationship metadata under those shared resources rather than becoming new +top-level types. Phase-1 vSphere work must not invent `esxi-host`, +`vsphere-vm`, `vsphere-cluster`, `system-container`, `app-container`, or +`physical-disk` projections just because the upstream APIs expose additional +object classes. TrueNAS disk telemetry now follows the same rule. API-backed TrueNAS disks must populate canonical `physicalDisk.temperature` and reuse the shared physical-disk risk semantics, so infrastructure, storage, charts, and AI read diff --git a/scripts/release_control/subsystem_lookup_test.py b/scripts/release_control/subsystem_lookup_test.py index b91826046..bd96beb5d 100644 --- a/scripts/release_control/subsystem_lookup_test.py +++ b/scripts/release_control/subsystem_lookup_test.py @@ -4381,6 +4381,7 @@ class SubsystemLookupTest(unittest.TestCase): "canonical-timeline-source-precedence", "host-type-migration-boundary-audit", "platform-support-model-v1", + "vmware-vsphere-vcenter-first-admission-model", }, )