GitHub

How to Use

Step-by-step guide to provisioning a RHEL virtual machine through the Developer Hub wizard and managing it with GitOps.

Prerequisites

Provisioning a VM

  1. Open Developer Hub
    Navigate to your Developer Hub instance and click Create in the left sidebar. Find the template titled "RHEL Virtual Machine (bootc / OpenShift Virtualization)" and click Choose.
  2. Page 1: VM Identity
    Enter a DNS-compatible VM Name (e.g., my-webserver). Set your Owner username. Optionally override the Target Namespace (defaults to <owner>-vms).
  3. Page 2: Compute Resources
    Select CPU Cores (1-16), Sockets (1-2), Threads (1-2), and Memory (2-32 GiB). Choose a Run Strategy:
    • Always — auto-start and restart on failure
    • RerunOnFailure — restart only on crash
    • Manual — start/stop manually via virtctl
    • Halted — create the VM but do not start it
  4. Page 3: Storage & Boot Source
    Set the Root Disk Size (20-200 GiB) and optionally a Storage Class. Choose the Boot Source:
    • Container Registry — uses a RHEL guest image (default: registry.redhat.io/rhel9/rhel-guest-image:latest)
    • bootc Image — uses an image-mode RHEL OCI image (default: quay.io/centos-bootc/centos-bootc:stream9)
  5. Page 4: Network & Access
    Set a VM Password for console access. Paste your SSH Public Key. Optionally enable Apache HTTP Server installation and specify Extra Packages. Toggle Expose via Connectivity Link if you want external Gateway API routing.
  6. Page 5: Connectivity Link Configuration
    (Only applies when Connectivity Link is enabled)
    Set the Route Path Prefix, choose an Authentication Model (None / OIDC / API Key), and configure the Rate Limit (requests per minute). For OIDC, provide the Keycloak Realm and Client ID.

What Happens After Submit

When you click Create, the template executes these steps automatically:

Step Action Result
1 Resolve Cluster Domain Reads workshop-config ConfigMap to get the cluster domain
2 Generate VM Manifests Renders the skeleton templates with your parameter values
3 Push to Gitea Creates a new public repo ws-<owner>/<vmName>-vm
4 Register in Catalog Imports catalog-info.yaml into Backstage catalog
5 Create ArgoCD Application Posts an Application CR to the openshift-gitops namespace
6 Send Notification Sends an HTML email via Mailpit with VM details

Accessing Your VM

SSH via virtctl

virtctl ssh cloud-user@my-webserver -n user1-vms

SSH via port-forward

oc port-forward svc/my-webserver 2222:22 -n user1-vms
ssh -p 2222 cloud-user@localhost

VNC Console

virtctl console my-webserver -n user1-vms

HTTP Access (Connectivity Link)

If Connectivity Link was enabled, access the VM service via its OpenShift Route:

curl https://my-webserver-route-user1-vms.apps.cluster.example.com/

Day-2 Operations

Modifying VM Configuration

Since the VM is managed via GitOps, all changes go through Git:

  1. Clone the Gitea repo: git clone https://gitea-gitea.apps.cluster.example.com/ws-user1/my-webserver-vm
  2. Edit the desired manifest under manifests/
  3. Commit and push to the main branch
  4. ArgoCD detects the change and syncs automatically

Scaling Resources

Edit manifests/virtualmachine.yaml to change CPU cores, memory, or disk size. The VM may need to be restarted for changes to take effect: 

virtctl restart my-webserver -n user1-vms

Updating the Boot Image

For bootc VMs, update the bootcImageUrl in manifests/virtualmachine.yaml to point to a new image tag. See the bootc deep dive for details on building custom images.

Stopping / Starting

# Stop
virtctl stop my-webserver -n user1-vms

# Start
virtctl start my-webserver -n user1-vms

# Restart
virtctl restart my-webserver -n user1-vms

Deleting a VM

To decommission a VM, delete the ArgoCD Application. ArgoCD will clean up all resources in the namespace thanks to the resources-finalizer.argocd.argoproj.io finalizer: 

oc delete application user1-my-webserver-vm -n openshift-gitops