Hyper-V class and relationship model

The object model must represent operational ownership without making transient placement part of an object's identity. A VM can move between cluster nodes; its SCOM identity must survive that move. A host adapter cannot move between computers; its identity can be hosted by the host. This distinction drives class keys, hosting, relationship discovery, workflow placement, and upgrade safety.

The final class IDs and base classes remain gated by topology research and ADR 0028. The names on this page are working design identifiers in the HybridSolutionsCloud.HyperV namespace.

Conceptual object model

Rendering diagram…

This is a service model, not a promise to discover every possible child by default. High-cardinality classes such as virtual disks and VM network adapters require an explicit catalog and scale decision.

Class categories

Category	Candidate classes	Identity and placement rule
Service boundary	Deployment, Cluster, Standalone Host Boundary	Stable cluster identity or host principal name; never a display name alone
Compute	Hyper-V Host Role, Cluster Node, VM	Host follows Windows computer; VM uses Hyper-V VM GUID and is contained by the stable boundary
Cluster	Cluster, Quorum, Clustered Role, Cluster Resource, Cluster Network	Prefer stable cluster identifiers and approved Microsoft cluster base types where supportable
Storage	CSV, volume, virtual disk, VHD/VHDX, storage path, Replica relationship	Keys use provider IDs or canonical paths with documented normalization
Network	Physical adapter, switch, port, VM adapter, Network ATC intent, SDN authority	Host-local components are hosted by host; authority objects are scoped to the boundary
Management	SCVMM management relationship, Network Controller dependency	Reference relationships only when the topology selects that authority
Monitoring	Boundary monitoring pipeline and discovery freshness	One platform-owned instance per DA boundary

Identity decision tree

Rendering diagram…

VM mobility contract

Rendering diagram…

The VM is not hosted by a cluster node. Hosting it by a node would change its SCOM identity when it moves and could orphan health history, alerts, relationships, and overrides.

Relationship semantics

Rendering diagram…

Relationship	Use	Do not use for
Hosting	A child truly exists on one parent and workflows must execute there	Mobile VMs, cross-node cluster objects, or presentation-only grouping
Containment	A boundary or component group owns members for service modeling	Inferring where a workflow can execute
Reference	Current placement, Replica pairing, external authority, or another non-lifecycle dependency	Deleting a child when a source disappears

Candidate keys

Entity	Preferred key	Fallback requiring proof	Never use alone
Failover cluster	Stable cluster/provider ID	Canonical cluster fully qualified domain name	Friendly display name
Standalone boundary	Windows computer principal name plus role identity	Machine GUID with rename migration plan	NetBIOS name only
VM	Hyper-V VM GUID	None unless Microsoft changes the provider contract	VM name or current host
CSV	Cluster-scoped volume unique ID	Normalized CSV path plus cluster key	Owner node or drive label
Virtual switch	Host key plus switch GUID	Host key plus invariant provider name	Display name without host
Physical adapter	Host key plus interface GUID	Host key plus permanent hardware identifier	Interface index alone
Replica	Source VM ID plus target relationship/provider ID	Normalized endpoint tuple	Friendly replication name

Class modeling rules

• Model only entities that need independent health, targeting, properties, relationships, views, overrides, or lifecycle. A property bag is preferable when a first-class object adds no value.
• Target workflows at the narrowest stable class that owns the signal.
• Keep class properties small, stable, operationally meaningful, and safe to store. Do not store rapidly changing measurements as properties.
• Every discovered class has a deterministic display name and every public property has a localized display string.
• Never use a mutable friendly name as the sole key.
• Avoid deep hosting chains; each level increases identity, discovery, and workflow complexity.
• Separate current placement from identity for every mobile or failover-capable object.
• Explicitly document whether disappearance means deletion, stale topology, monitoring failure, or temporary unavailability.

Boundary variants

Rendering diagram…

Research gates

Before ADR 0028 is accepted, topology and lab research must prove:

1. the stable key for every supported entity;
2. the appropriate Microsoft base class and library dependency;
3. workflow execution location for hosted, unhosted, and cluster-owned objects;
4. deletion and rediscovery behavior during rename, live migration, failover, drain, and role removal;
5. scale/cardinality for optional child classes; and
6. whether SCVMM/SDN objects are modeled directly or represented as external dependencies.