Architecture

End-to-end provisioning flow, network topology, and component responsibilities.

Provisioning Flow

The golden path follows a linear pipeline from developer self-service to a running VM on the cluster. Every step is automated; no manual cluster operations are required after the initial platform setup.

 ┌──────────────────┐
 │  Red Hat          │
 │  Developer Hub    │   1. Developer fills wizard
 │  (Backstage)      │   2. Template generates manifests
 └────────┬─────────┘
          │
          │  publish:gitea
          ▼
 ┌──────────────────┐
 │  Gitea            │   3. New repo created with
 │  (Git Server)     │      manifests/ directory
 └────────┬─────────┘
          │
          │  webhook / poll
          ▼
 ┌──────────────────┐
 │  ArgoCD           │   4. Application created
 │  (OpenShift       │      auto-sync + self-heal
 │   GitOps)         │
 └────────┬─────────┘
          │
          │  kubectl apply (SSA)
          ▼
 ┌──────────────────────────────────────────────┐
 │  OpenShift Cluster                            │
 │                                               │
 │  ┌─────────────┐  ┌────────────────────────┐ │
 │  │ Namespace    │  │ VirtualMachine         │ │
 │  │ (user-vms)  │  │  ├─ DataVolume (disk)  │ │
 │  │             │  │  ├─ cloud-init Secret   │ │
 │  │             │  │  └─ SSH Secret          │ │
 │  │             │  └────────────────────────┘ │
 │  │             │                              │
 │  │             │  ┌────────────────────────┐ │
 │  │             │  │ Service (ClusterIP)    │ │
 │  │             │  │  port 22 (SSH)         │ │
 │  │             │  │  port 8080 (HTTP)      │ │
 │  │             │  └────────────────────────┘ │
 │  └─────────────┘                              │
 │                                               │
 │  ┌─ Optional: Connectivity Link ────────────┐│
 │  │  Gateway (Istio)                         ││
 │  │  HTTPRoute ──► Service ──► VM:8080       ││
 │  │  AuthPolicy (OIDC / API Key)             ││
 │  │  RateLimitPolicy                         ││
 │  │  Route (OpenShift, TLS edge)             ││
 │  └──────────────────────────────────────────┘│
 └──────────────────────────────────────────────┘

Network Data Flow

When Connectivity Link is enabled, external traffic traverses several layers before reaching the VM guest OS.

  Internet / Client
        │
        ▼
  ┌─────────────────┐
  │ OpenShift Route  │  TLS termination (edge)
  │ (*.apps.domain)  │
  └────────┬────────┘
           │  port 8080
           ▼
  ┌─────────────────┐
  │ Istio Gateway    │  GatewayClass: istio
  │ (envoy proxy)    │  Listener: HTTP/8080
  └────────┬────────┘
           │
           ▼
  ┌─────────────────┐
  │ HTTPRoute        │  Path prefix matching
  │                  │  Backend: Service:8080
  └────────┬────────┘
           │
     ┌─────┴─────┐
     ▼           ▼
┌─────────┐ ┌──────────┐
│AuthPolicy│ │RateLimit │  Kuadrant policy enforcement
│(Authorino)│ │Policy    │  (runs as Envoy ext-auth
└─────────┘ │(Limitador)│   and rate-limit filters)
            └──────────┘
           │
           ▼
  ┌─────────────────┐
  │ Kubernetes       │  ClusterIP
  │ Service          │  port 8080 ──► targetPort 8080
  └────────┬────────┘
           │
           ▼
  ┌─────────────────┐
  │ VirtualMachine   │  RHEL guest OS
  │ (KubeVirt VMI)   │  httpd listening on :8080
  └─────────────────┘

Component Responsibilities

Component	Responsibility	Kubernetes Resources
Red Hat Developer Hub	Self-service UI (wizard), manifest generation from templates, Gitea repo creation, ArgoCD app creation, catalog registration, email notification.	None (runs as a Backstage instance)
Gitea	Hosts the Git repository containing VM manifests. Single source of truth for the desired state.	None (external Git server)
ArgoCD	Watches the Git repo, applies manifests to the cluster, detects drift, self-heals, prunes deleted resources.	`Application` in `openshift-gitops`
OpenShift Virtualization	Runs the VM using KubeVirt. Manages VM lifecycle (start, stop, migrate), provisions storage via CDI DataVolumes.	`VirtualMachine`, `DataVolume`, `VirtualMachineInstance`
cloud-init	Guest-side initialization: sets hostname, creates users, installs packages, configures SSH keys, enables services.	`Secret` (cloudInitNoCloud userdata)
Istio / Service Mesh	Provides the `istio` GatewayClass and spawns envoy proxy pods for Gateway resources.	`Gateway` (creates istio ingress pods)
Kuadrant	Policy engine for authentication (Authorino) and rate limiting (Limitador). Enforces AuthPolicy and RateLimitPolicy on HTTPRoutes.	`AuthPolicy`, `RateLimitPolicy`, `PlanPolicy`, `APIProduct`

GitOps Reconciliation Loop

After initial provisioning, the system enters a continuous reconciliation loop. Any change to the Git repository triggers an automatic sync:

  ┌────────────────────────────────────────────────┐
  │                                                │
  │   Developer pushes YAML change to Gitea        │
  │              │                                 │
  │              ▼                                 │
  │   ArgoCD detects diff (poll / webhook)         │
  │              │                                 │
  │              ▼                                 │
  │   ArgoCD applies changes (Server-Side Apply)   │
  │              │                                 │
  │              ▼                                 │
  │   OpenShift reconciles resources               │
  │   (VM restarted if spec changed,               │
  │    policies updated in-place)                  │
  │              │                                 │
  │              ▼                                 │
  │   ArgoCD marks app as "Synced + Healthy"       │
  │              │                                 │
  │              └──────────── loop ───────────────┘
  │
  │   If manual cluster change detected:
  │   ArgoCD self-heals (reverts to Git state)
  └────────────────────────────────────────────────┘