# Pulse v6 Platform Support Model Last updated: 2026-03-31 Status: ACTIVE This file is the canonical governed model for platform support in Pulse v6. It exists so new platforms are admitted against one shared contract instead of through platform-by-platform improvisation. ## Canonical Rules 1. A first-class platform is a governed Pulse platform id with one declared primary ingestion mode, one owned onboarding path, explicit canonical resource projections, and one declared support matrix across the product surfaces below. 2. Platform families are grouping aids, not the support unit. `Proxmox` is a family; `proxmox-pve`, `proxmox-pbs`, and `proxmox-pmg` are separate first-class platforms because they onboard differently, project different canonical resources, and carry different support floors. 3. Runtime variants are not top-level platforms. `podman` is a runtime variant inside the first-class `docker` platform. `qemu`, `lxc`, OCI guest/runtime details, and TrueNAS app-runtime internals are workload technologies inside an owning platform, not new platforms. 4. Transport-specific implementations are not platforms. API clients, JSON-RPC sessions, pollers, agent heartbeat schemas, install flags, CRUD routes, and saved-connection tests are implementation details. 5. Optional augmentation paths are not platforms. A unified agent installed on an API-backed host may enrich or enable control for that platform, but it does not replace the platform's primary support contract. 6. `hybrid` is an ingestion mode, not a platform category. Use `hybrid` only when one first-class platform or resource contract intentionally merges API-backed and agent-backed truth. 7. Platform work must project into canonical shared resources first. Do not add provider-local top-level resource types by default. ## Platform Categories ### First-Class Platform A first-class platform must define: 1. canonical platform id 2. platform family, if any 3. primary ingestion mode: `api-backed`, `agent-backed`, or `hybrid` 4. owned onboarding path 5. canonical unified-resource projections 6. support-floor row across the product surfaces below 7. assistant read classification and assistant control classification 8. optional augmentation rules, if a secondary path is allowed ### Runtime Variant A runtime variant changes how a platform runs but does not change the owning platform id, onboarding path, or top-level support contract. Examples: 1. `podman` inside `docker` 2. `qemu` versus `lxc` inside `proxmox-pve` 3. container-runtime details inside TrueNAS-managed `app-container` resources ### Transport-Specific Implementation A transport-specific implementation is the concrete mechanism used to ingest, test, or execute a platform path. Examples: 1. `pkg/pbs`, `pkg/pmg`, and TrueNAS JSON-RPC clients 2. Docker and Kubernetes agent report schemas 3. `--enable-docker`, `--enable-kubernetes`, and `--proxmox-type pve|pbs` 4. platform-connections CRUD and saved-connection test routes ### Optional Augmentation Path An optional augmentation path is a secondary governed path that enriches an existing first-class platform without replacing its primary ingestion mode. Examples: 1. a unified agent on a Proxmox node enabling hybrid host telemetry or guest control for `proxmox-pve` 2. a unified agent on a TrueNAS appliance enriching a `truenas` system that is already supported through the API-backed poller ## Canonical Ingestion Modes ### API-backed Pulse polls or queries the platform API directly. Optional agent data may augment the platform later, but API truth defines the support floor. Current API-backed primary platforms: 1. `proxmox-pve` 2. `proxmox-pbs` 3. `proxmox-pmg` 4. `truenas` ### Agent-backed Pulse relies on a Pulse-managed agent as the primary source of truth. Specialized runtime modules may ride on the same host install, but the agent path defines the support floor. Current agent-backed primary platforms: 1. `agent` for unified-agent hosts 2. `docker` 3. `kubernetes` ### Hybrid Hybrid means one admitted platform deliberately merges API-backed and agent-backed truth into one canonical resource contract. Hybrid is valid only when the primary owner and the augmentation rule are both explicit. Current governed hybrid-capable platforms: 1. `proxmox-pve` 2. `proxmox-pbs` 3. `truenas` `docker` and `kubernetes` do not become hybrid platforms merely because they run on a machine that also reports as `agent`; those are parallel first-class platforms sharing one physical host. ## Canonical Resource Projection Rules 1. Host-like systems should project as canonical `agent` resources plus `platformType`, not as provider-local host types. 2. Current top-level exceptions are `pbs` and `pmg`, which remain dedicated canonical resource types because their product semantics are not reducible to a generic host row. 3. Proxmox guest workloads project as `vm` and `system-container`. 4. OCI and application workloads project as `app-container`, including TrueNAS-managed apps. 5. Docker Swarm service topology projects as `docker-service`. 6. Kubernetes projects as `k8s-cluster`, `k8s-node`, `pod`, and `k8s-deployment`. 7. Storage projects through shared `storage`, `ceph`, and `physical-disk` resources instead of provider-local storage types. 8. Recovery artifacts stay in `internal/recovery` and reference canonical platform ids plus canonical resource ids. Recovery provider strings are forward-compatible vocabulary, not support declarations by themselves. ## Support Floor Every first-class platform must declare one matrix row covering these product surfaces: 1. onboarding/setup 2. infrastructure visibility 3. workloads, if the platform projects workload resources 4. storage, if the platform projects storage or disk resources 5. recovery, if the platform emits protected-item or recovery-artifact truth 6. alerts, if the platform contributes operator-significant health state 7. assistant read 8. assistant control A platform counts as supported only when every applicable surface above is either `supported` or explicitly `n/a`. Blank, implied, or hand-wavy coverage is not acceptable. `assistant control` must be classified explicitly as one of: 1. `supported` 2. `augmentation-only` 3. `read-only` 4. `n/a` ## Pre-Support Readiness Stages An admitted first-class platform may be real engineering work long before it is honest to call it supported. Pulse therefore uses one governed pre-support checkpoint so delivery progress is visible without inflating the support claim. 1. `architecture-locked` The admission model is resolved and implementation may start, but the platform is still only a planned or admitted direction. 2. `first-lab-ready` The architecture is locked, the bounded shared phase floor is implemented, automated non-live proof covers that floor well enough to catch regression, and the next highest-value step is a real lab or customer environment run. `first-lab-ready` is an implementation checkpoint, not a support claim. 3. `supported` Live proof validates the declared floor and the platform is admitted into the current support matrix. Rules: 1. Only `supported` changes the current support matrix. 2. `first-lab-ready` may be used in execution plans, proof matrices, blocked-proof records, and progress reporting for admitted platforms. 3. `first-lab-ready` must not leak into product wording, settings wording, or Assistant behavior as if support already exists. ## Current Classification ### First-class platforms 1. `agent` for unified-agent hosts 2. `docker` 3. `kubernetes` 4. `proxmox-pve` 5. `proxmox-pbs` 6. `proxmox-pmg` 7. `truenas` ### Admitted platforms (not yet supported) 1. `vmware-vsphere` ### Presentation-only platform vocabulary 1. `unraid` 2. `synology-dsm` 3. `microsoft-hyperv` 4. `aws` 5. `azure` 6. `gcp` ### Machine-readable projection `PLATFORM_SUPPORT_MANIFEST.json` is the machine-readable projection of the supported, admitted, and presentation-only platform vocabulary declared here, plus the canonical onboarding-path classification for supported and admitted platforms. Tests and shared frontend vocabulary may consume that manifest, and the tracked frontend projection in `frontend-modern/src/utils/platformSupportManifest.generated.ts` must be generated from it, but neither projection may introduce platform ids or governance states or onboarding paths that are not declared in this document. ### Runtime variants 1. `podman` is a runtime variant inside `docker`, surfaced through runtime metadata such as `containerRuntime`, not as a top-level platform. 2. `qemu`, `lxc`, and OCI guest/runtime details are workload technologies inside `proxmox-pve`, not first-class platforms. 3. TrueNAS app runtime internals are implementation details of `truenas`-owned `app-container` resources, not `docker` adoption. ### Transport-specific implementations 1. Proxmox, PBS, PMG, and TrueNAS connection CRUD and test routes 2. PBS/PMG API clients and the TrueNAS JSON-RPC poller stack 3. Docker and Kubernetes agent report contracts 4. install-command helpers and setup-script flags 5. platform badge and filter helpers ### Optional augmentation paths 1. unified agent on a Proxmox node 2. unified agent on a TrueNAS appliance 3. host-level agent support that enables shell or guest control for an already admitted API-backed platform ## Current Support Matrix | Platform | Family | Primary mode | Optional augmentation | Canonical projections | | ------------- | ------------------ | ------------ | ---------------------------------- | --------------------------------------------------------------------- | | `agent` | Pulse-managed host | agent-backed | none | `agent`, `storage`, `physical-disk` | | `docker` | container runtime | agent-backed | none | `agent`, `app-container`, `docker-service` | | `kubernetes` | cluster runtime | agent-backed | none | `k8s-cluster`, `k8s-node`, `pod`, `k8s-deployment` | | `proxmox-pve` | Proxmox | api-backed | host agent may augment into hybrid | `agent`, `vm`, `system-container`, `storage`, `ceph`, `physical-disk` | | `proxmox-pbs` | Proxmox | api-backed | host agent may augment into hybrid | `pbs`, `storage` | | `proxmox-pmg` | Proxmox | api-backed | none today | `pmg` | | `truenas` | TrueNAS | api-backed | host agent may augment into hybrid | `agent`, `app-container`, `storage`, `physical-disk` | | Platform | Setup | Visibility | Workloads | Storage | Recovery | Alerts | Assistant read | Assistant control | | ------------- | -------------------------------------- | ---------- | --------- | --------- | --------- | --------- | -------------- | ----------------- | | `agent` | install workspace | supported | `n/a` | supported | `n/a` | supported | supported | supported | | `docker` | install workspace / runtime enablement | supported | supported | `n/a` | `n/a` | supported | supported | supported | | `kubernetes` | install workspace / runtime enablement | supported | supported | `n/a` | supported | supported | supported | supported | | `proxmox-pve` | platform connections | supported | supported | supported | supported | supported | supported | augmentation-only | | `proxmox-pbs` | platform connections | supported | `n/a` | supported | supported | supported | supported | read-only | | `proxmox-pmg` | platform connections | supported | `n/a` | `n/a` | `n/a` | supported | supported | read-only | | `truenas` | platform connections | supported | supported | supported | supported | supported | supported | supported | ## Current Inconsistencies To Treat Explicitly 1. `PLATFORM_SUPPORT_MANIFEST.json` intentionally carries admitted and presentation-only ids such as `vmware-vsphere`, `microsoft-hyperv`, `aws`, `azure`, `gcp`, `unraid`, and `synology-dsm` so shared tests and frontend vocabulary can normalize them consistently. Those ids must not be interpreted as current support unless the classifications above say so. 2. Recovery provider strings are intentionally forward-compatible and already include values such as `docker`, `agent`, and `proxmox-pmg`. Those strings do not mean recovery support exists until the platform matrix above marks recovery as supported. 3. Frontend compatibility types still expose some legacy or presentation-local resource aliases. The canonical backend truth remains the shared unified-resource model plus this platform matrix. ## Future Platform Admission A new platform may be admitted as first-class only after governance answers all of these questions before implementation starts: 1. What is the canonical platform id, and what platform family does it belong to, if any? 2. Is the primary ingestion mode `api-backed`, `agent-backed`, or `hybrid`? If hybrid, what is primary and what is only augmentation? 3. What is the canonical onboarding path: platform connections, install workspace, or both? 4. What existing canonical resource types does it project into? New resource types require explicit justification; provider-local host types are forbidden by default. 5. Which support-floor surfaces are `supported`, `augmentation-only`, `read-only`, or `n/a`? 6. What stable identities drive dedupe, monitored-system counting, and cross-source merge with `agent`, `docker`, `kubernetes`, or other existing platforms? 7. What transport/security boundary owns credentials, polling cadence, reconnect semantics, and disabled/default behavior? 8. What proof demonstrates the declared floor is real in onboarding, visibility, applicable domain surfaces, alerts, and assistant behavior? 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. ## VMware vSphere Admission Model 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 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 | Platform | Family | Entry point | Primary mode | Optional augmentation | Canonical projections | Admission state | Readiness stage | | ---------------- | ------ | ------------------------- | ------------ | -------------------------------------- | ------------------------ | ---------------------------------------------- | ----------------- | | `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 in support matrix | `first-lab-ready` | ## 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. The concrete first-implementation slice order and stop/go checks live in `docs/release-control/v6/internal/VMWARE_VSPHERE_PHASE1_EXECUTION_PLAN.md`. As of 2026-03-31, VMware has reached the governed `first-lab-ready` checkpoint: the non-live phase-1 floor is implemented and regression-proofed well enough that the next proper step is a real `vCenter` proof run rather than more architecture work.