Virtual Machines

This chapter describes how UCloud/IM for Kubernetes uses KubeVirt to run full virtual machines. VM support is enabled in the Kubernetes configuration and is further controlled per machine group through allowVirtualMachines.

Overview

Each VM job is tracked as a normal UCloud job, but the integration module creates and manages a VirtualMachine in Kubernetes instead of a container-based workload. The VM is named vm-<job-id>-0 and is currently limited to rank 0.

The integration module also creates the supporting Kubernetes resources needed for the job, including:

  • a VirtualMachine
  • a persistent disk for the VM image
  • a network policy for the VM traffic
  • services for SSH, public IPs, or internal job access when requested

Storage

VM disks are prepared from the application image, converted to a raw disk image, and resized to the requested disk size. The disk backend is controlled by the Kubernetes VM storage configuration:

  • HostPath stores the disk on a local host path prefix
  • CsiStaticPv creates a static PV/PVC pair through the configured CSI driver

User files are mounted into the VM through virtiofs. The integration module stores the VM-specific configuration under Jobs/VirtualMachines/<job-id> inside the provider file system.

Guest setup

KubeVirt VMs boot with cloud-init configuration generated by the integration module. This sets up:

  • a ucloud user with sudo access
  • the VM agent service
  • the metrics service
  • network configuration suitable for DHCP inside the guest

The VM agent is what allows the provider to manage shell access, VNC sessions, SSH key updates, and job state reporting.

Access

Interactive access is available through the same job/session mechanisms as the rest of UCloud/IM:

  • shell sessions first try the VM agent and fall back to the serial console if needed
  • VNC sessions are proxied through KubeVirt’s VNC stream
  • web sessions use the normal ingress-based flow when the job exposes web services

VM Agent

Each VM runs a small agent service that connects back to the integration module using a job-specific token. After the agent authenticates, the provider returns a second token used for server-to-agent communication.

The agent is responsible for:

  • keeping the VM session alive with heartbeat messages
  • receiving updated SSH keys for the job owner
  • accepting TTY requests for interactive shell sessions
  • helping the provider route shell traffic to the right VM session

This is the path used by the normal shell experience. If the agent is unavailable, the integration module can fall back to the KubeVirt serial console.

Metrics Service

The VM also runs a metrics service alongside the agent. It writes VM statistics into the job’s logs directory, where the integration module can read them back and forward them to the normal job-follow stream.

The service exists to provide runtime telemetry from inside the guest, including utilization data that is emitted while the VM is running. These metrics are stored under the job’s logs folder together with the other VM log output.

Lifecycle

When a VM job is started, the integration module creates or updates the KubeVirt resources to match the job configuration. Suspending a job stops the VM, and terminating a job deletes the VM and cleans up the disk data.

VMs are not available for sensitive projects, and jobs with more than one rank are rejected.

Configuration

See the Kubernetes configuration reference for the full VM-related configuration, including storage settings and machine-group permissions.