On this page
Summary
This draft defines the target architecture for the candidate OpenShift Virtualization SBB. It gives the implementation context for the Virtual Machines as a Service (VMaaS) and Worker Virtualization ABBs and makes WP-13 testable. It complements, rather than selects or approves, the candidate SBB.
The target scope is a general-purpose virtualization service on the OpenShift production platform. The architecture inherits the platform direction in openshift-concept-overview, external RHCS/Ceph supplied through ODF external mode, Git/ACM/Argo governance, and the target OADP/Cohesity protection direction. Those inherited directions still require their respective release, integration, and acceptance evidence; this note does not claim they are deployed or support-approved.
The product baseline is publicly released OpenShift Virtualization 4.22. Each deployment must pass an exact 4.22.z compatibility gate covering OpenShift, the OpenShift Virtualization operator, supported storage/network integrations, and planned management tooling before promotion.
Applicable Principles
- Automation First - VM definitions, templates, policies, operator configuration, and promotion evidence are Git-reviewed and reconciled rather than manually changed.
- Security by Design - authorization, tenant boundaries, image provenance, and privileged device access are explicit and least-privilege.
- Reliability and Resilience - eligibility, maintenance behavior, recovery, and failure handling are tested before a workload receives an availability commitment.
- Observability by Default - platform and workload health is observable, with alerting and evidence captured for acceptance.
- Data Protection - protection selection and restore evidence are mandatory before production onboarding.
Architecture
Scope and building-block bridge
| Building block or delivery item | Architecture role | Boundary in this draft |
|---|---|---|
| OpenShift Virtualization SBB | Candidate product realization using KubeVirt. | Candidate until ownership, support model, and acceptance criteria are confirmed. |
| VMaaS ABB | Tenant-facing lifecycle service for eligible VMs. | Standardized templates, quota/RBAC, networks, storage, and documented lifecycle workflows. |
| Worker Virtualization ABB | Virtual-machine capability used where a platform worker role is appropriate. | Subject to separate sizing, node-role, lifecycle, and supportability review; it is not an automatic use of VMaaS. |
| WP-13 | Delivery and acceptance work package. | Establishes the profiles, migration guidance, protection, and evidence needed to onboard workloads. |
Platform boundary
- Proposed target: a dedicated x86 worker-pool proposal in the OpenShift production environment hosts virtualization workloads. Pool topology, capacity, taints, labels, and failure-domain design require validation before selection.
- Inherited: cluster lifecycle and add-on governance use Git as the approval boundary, ACM policy/fleet governance, and Argo CD reconciliation as described in openshift-concept-overview and intent-to-runtime-automation-flow.
- Open: the final cluster placement and whether worker virtualization is co-located with, or separated from, tenant VMaaS capacity remain subject to sizing and lifecycle evidence.
Runtime, storage, and network model
OpenShift Virtualization 4.22 is installed through OLM and configured by the HyperConverged v1beta1 custom resource. KubeVirt supplies the VM runtime: a VirtualMachine expresses desired state and a VirtualMachineInstance represents a running instance. CDI provides image import and clone workflows through DataVolume resources and StorageProfile defaults. Curated VM templates and instance types provide the permitted sizing and operating-system patterns.
| Concern | Target direction | Guardrail |
|---|---|---|
| Compute | Dedicated x86 worker-pool proposal for virtualization. | Confirm node compatibility, capacity, maintenance behavior, and exact-version support before use. |
| Storage | External RHCS/Ceph via ODF external mode and CSI. | Prefer qualified RBD raw-block profiles for VM disks; validate the selected StorageClass, access mode, snapshot, clone, and migration behavior per 4.22.z. |
| Primary networking | OVN masquerade is the general default for VM connectivity. | It does not replace the approved service/exposure and tenant-network contracts. |
| Additional networking | Governed UDN or additional-network profiles are available only for approved workload needs. | Do not claim broad CUDN-for-VM support; each profile requires release-pinned supportability and EVPN evidence. |
| Images and provisioning | CDI DataVolume import/clone workflows, curated images, templates, and instance types. | Sources must be approved, scanned where the platform standard requires it, versioned, and traceable to a provenance record. |
| Migration | Live migration is conditional, not a universal service property. | It requires compatible compute, network, storage, eviction, and workload settings; prove it with the chosen profile. |
Authorization and lifecycle boundaries
Platform operators control cluster-scoped operator configuration, node-pool placement, StorageClasses, approved network profiles, policy, and backup integration. Tenant or service teams receive only namespace-scoped rights needed to create and operate approved VirtualMachine, DataVolume, template/instance-type, and service resources. They do not receive cluster administration, arbitrary node placement, unrestricted privileged-device access, or authority to create unapproved external network attachments.
Git review is the production change boundary. ACM policies and Argo CD reconcile approved configuration; Kubernetes RBAC enforces runtime access. A self-service interface, if introduced, must call the same GitOps/API contract and must not bypass admission, provenance, quota, or approval controls.
Workload eligibility matrix
| Workload class | Initial baseline | Required evidence before onboarding | Explicit boundary |
|---|---|---|---|
| Standard x86 business VM using curated image, qualified RBD raw-block storage, and OVN masquerade | Proposed eligible | Template/image provenance, storage and network profile validation, backup/restore selection, monitoring, and lifecycle test. | Subject to namespace RBAC, quota, and service onboarding. |
| VM requiring a governed additional network or UDN | Conditional | Release-pinned compatibility, tenant/isolation design, EVPN route and failover evidence, and security review. | Not enabled by default; no broad CUDN-for-VM claim. |
| VM requiring live migration | Conditional | Successful planned migration and maintenance/eviction test on its exact storage/network/compute profile. | No migration commitment until evidence is accepted. |
| Worker virtualization | Conditional | Worker role design, cluster lifecycle compatibility, availability behavior, and supportability evidence. | Not automatically offered as tenant VMaaS. |
| GPU/vGPU, SR-IOV, PCI passthrough, or other hardware passthrough | Excluded from initial baseline | Separate architecture and vendor support assessment. | No implied device entitlement or availability behavior. |
| Confidential VMs and Technology Preview features | Excluded | Separate approved scope after product maturity and support review. | Not part of the 4.22 baseline. |
Availability, maintenance, and remediation contract
The initial availability contract is profile-based and evidence-gated. It does not assign an SLO, SLA, RPO, RTO, support response time, or approved production support commitment. A workload is eligible for a stated availability tier only after its VM profile documents the selected storage/network path, recovery approach, maintenance treatment, health monitoring, and successful acceptance tests.
KubeVirt health, VM/VMI state, node readiness, storage health, and network signals feed platform observability. Platform operations must validate planned maintenance behavior, including migration where eligible, controlled stop/start where it is not, and recovery after node failure. Automated remediation, fencing, and failover behavior must be enabled only where their exact integration and consequences have been validated; they are not presumed by installing the operator.
Control and data flows
- Control flow: approved Git changes are reconciled through ACM policy and Argo CD. OLM installs the operator; the
HyperConvergedresource establishes the virtualization control plane. Kubernetes API, RBAC, admission, templates, instance types, and quotas govern VM intent. - Image flow: an approved source is imported or cloned through CDI into a
DataVolume; a curated template/instance type references that controlled image path. Provenance and vulnerability/approval evidence are retained with the release process. - Data flow: the VMI consumes CSI-provisioned persistent storage from external RHCS/Ceph through ODF external mode. VM network traffic uses the approved OVN masquerade or explicitly governed additional-network profile; exposure follows the platform service and ingress/load-balancer rules.
- Protection and recovery flow: Git-managed OADP configuration and Cohesity integration are the target direction. OADP/Velero protection, CSI snapshot capability, Cohesity policy, and any guest-level agent use must be selected per VM profile and proven by restore drills. See topic-openshift-backup-and-restore.
- Onboarding flow: migration from legacy virtualization is assessed and executed through WP-13. Migration Toolkit for Virtualization (MTV) is a candidate onboarding mechanism, not an assumed migration outcome; source compatibility, cutover, rollback, and validation remain workload-specific.
Visual architecture views
The following views describe the candidate target architecture. Each rendered SVG is embedded for reading, with its editable .drawio source linked directly below the view heading.
Solution context
OpenShift Virtualization solution context source
Runtime, network, and storage
OpenShift Virtualization runtime, network, and storage source
Governance and protection
OpenShift Virtualization governance and protection source
Acceptance evidence
Before a profile is promoted beyond draft, capture evidence for the exact 4.22.z combination: operator and HyperConverged health; x86 worker-pool scheduling and node lifecycle; VM/VMI lifecycle; CDI import or clone from an approved image; template and instance-type enforcement; qualified CSI RBD raw-block provisioning; approved network reachability and isolation; observability alerts/checkups; controlled maintenance and, where claimed, live migration; backup and restore; and a GitOps/API audit trail. MTV-based onboarding additionally requires source assessment, migration rehearsal, cutover/rollback evidence, and workload acceptance.
Technical documentation and references
- OpenShift Virtualization 4.22 release notes
- Installing OpenShift Virtualization 4.22
- OpenShift Virtualization 4.22 networking
- OpenShift Virtualization 4.22 storage
- OpenShift Virtualization 4.22 live migration
- OpenShift Virtualization 4.22 nodes
- OpenShift Virtualization 4.22 backup and restore
- OpenShift Virtualization 4.22 monitoring
Decisions
- Inherited: OpenShift lifecycle governance is Git/ACM/Argo based; the platform uses external RHCS/Ceph through ODF external mode; and the target protection direction is OADP/Cohesity. These are inherited architecture directions, not evidence that every integration is complete.
- Proposed: general-purpose virtualization uses a dedicated x86 worker-pool proposal and an exact
4.22.zcompatibility gate. - Proposed: OLM plus
HyperConvergedv1beta1, KubeVirt VM/VMI, CDI/DataVolumes/StorageProfiles, curated images, templates, and instance types form the initial declarative service surface. - Proposed: qualified CSI RBD raw-block storage is preferred for VM disks; OVN masquerade is the general default; additional networks/UDN are governed exception profiles.
- Open: definitive platform/service ownership, support model, availability tiers, commercial commitments, final worker-pool topology, networking profiles, and remediation/fencing design remain required before the SBB can move beyond candidate.
- Excluded: Technology Preview features, confidential VMs, broad CUDN-for-VM claims, and unqualified GPU/vGPU/SR-IOV/passthrough are outside the initial baseline.
Open Questions
- Which exact OpenShift Virtualization
4.22.zrelease and component combinations are qualified for ODF external mode, the selected RHCS version, OVN/UDN profiles, OADP, Cohesity, ACM, Argo CD, and MTV? - Which VM classes require live migration, and which must use a tested stop/start maintenance and recovery procedure instead?
- Which availability, recovery, and protection tiers will be offered after owner, support, and restore-test evidence are agreed?
- What are the approved image sources, signing/scanning controls, retention model, and template release process for each supported operating system?
- Which additional-network and EVPN profiles are supportable for VM workloads, and what route, isolation, MTU, and failover evidence is mandatory?
- What migration waves are eligible for MTV, and what source compatibility, cutover, rollback, and application acceptance criteria apply?