#Creating Virtual Machines

Create a virtual machine (a VirtualMachine resource) using an image, and schedule it to physical nodes with KubeVirt components installed and virtualization enabled. A VirtualMachine is the desired-state object (analogous to a Deployment); when it is started, KubeVirt produces a running VirtualMachineInstance (analogous to a Pod). For the terms used on this page, see Concepts and Glossary.

You can create a virtual machine through Create Virtual Machine using a form, and you may also switch to YAML format for the operation.

#Prerequisites

• Before creating a virtual machine using an image, please confirm the following with the platform administrator:

  • The target cluster is a self-built cluster, and the Kubevirt components have been deployed.

  • The target node must be a physical node with virtualization enabled.

  • A virtual machine image has been added to the platform.

• If you need to use the physical GPU passthrough feature of the virtual machine, please contact the platform administrator for the following configuration:

  1. Obtain GPU passthrough environment preparation plan and prepare the necessary environment.

  2. Prepare the required physical GPU and enable the related features for physical GPU passthrough for the virtual machine.

#Notes

When using Windows virtual machines, only logins via the username/password set in the virtual machine image are supported. Please contact the platform administrator to obtain this information in advance.

#Create Virtual Machine

#Procedure

Note: The following content presents an example of creating a virtual machine using a form, and you may also switch to YAML format for the operation.

1. Enter Container Platform.

2. In the left navigation bar, click Virtualization > Virtual Machines.

3. Click Create Virtual Machine.

4. In the Basic Information area, fill in the name and display name of the virtual machine and set tags or annotations.

   Parameter	Description
   Tags	Used to select objects and find collections of objects that meet certain criteria. Must be a key-value pair, for example: app.kubernetes.io/name: hello-app.
   Annotations	Used to provide any information to development and operations teams. Must be a key-value pair, for example: cpaas.io/maintainer: kim.

5. Set the machine type and choose a virtual machine image.

   Parameter	Description
   Specifications	You can select recommended usage scenarios or custom resource limits based on your needs.
   Physical GPU (Alpha)	Select the model of the physical GPU; only one physical GPU can be allocated to each virtual machine. Note: Physical GPU passthrough for the virtual machine refers to the direct allocation of the actual Graphics Processing Unit (GPU) to the virtual machine in a virtualization environment, enabling it to directly access and utilize the physical GPU to achieve graphical performance equivalent to running directly on a physical machine, avoiding performance bottlenecks caused by virtual graphics adapters and enhancing overall performance.
   Image	Choose a public image that has been assigned to the platform project by the platform administrator. Note: Only supports selecting images with the same CPU architecture as the cluster architecture.

6. In the Storage area, refer to the following instructions to configure the relevant information.

   Parameter	Description
   Disk Name	The name of the storage disk; the system disk name cannot be modified.
   Type	Root Disk: The system automatically creates a VirtIO type rootfs system disk to store the operating system and data. Data Disk: Click to add multiple data disks for persistent data storage. Defaults to VirtIO device. Note: Data disk names must not duplicate existing disk names.
   Volume Mode	File System: Mount the disk as a mounted file directory. Block Device: Mount the disk as a block device.
   Storage Class	The platform maintains virtual machine disks by creating and managing persistent volume claims. You need to specify a storage class required for dynamically creating persistent volume claims. Different storage classes support different volume modes; if there is no available storage class for the selected volume mode, please contact an administrator for addition.
   Capacity	The capacity required for the virtual machine storage; the minimum for the system disk is 20 G.
   Delete with VM	Defaults to enabled, cannot be modified, indicating that the disk data will also be deleted when the virtual machine is deleted.

7. In the Network area, refer to the following instructions to configure the relevant information.

   Parameter	Description
   IP Address	Defaults to Dynamic (DHCP); an IP is dynamically assigned when the virtual machine starts, and the IP is released when the virtual machine stops. If binding a Static IP, the virtual machine will always use this IP address even after a restart. If there are no available IPs in the current project, please release an IP appropriately first.
   Network Mode	Bridged: The virtual machine shares the same IP address as the container group and communicates externally through this IP address. NAT: The virtual machine will be assigned an internal IP address but will translate to the container group IP address for external communication. Open ports indicate the exposed ports of the virtual machine, such as the SSH service port 22; not filling in Open Ports indicates that all ports are open.
   Auxiliary Network Card	Add auxiliary network cards as needed. Note: If auxiliary network card features are required or there are no available types of auxiliary network card networks, please contact the platform administrator for configuration. SR-IOV types only support Linux operating systems on x86_64 architecture. Defaults to obtaining IP addresses via DHCP. After multiple reboots, SR-IOV virtual machines may exhibit two different VFs but with the same MAC address.

8. In the Initialization Settings area, refer to the following instructions to configure the relevant information.

   Parameter	Description
   Keys	Always use SSH keys for remote login verification. This method does not require password validation; it is recommended to log in to the virtual machine using keys. You can use the keys already available in the platform or create new keys immediately; all relevant keys can be viewed on the Virtualization > Key Pairs page. Only individuals with the private key can access the virtual machine via SSH. If multiple people are to maintain the virtual machine together, multiple keys can be associated, and private keys can be assigned to different users. If key leakage occurs, the associated key can be promptly revoked to reduce damage. The public key of the SSH key is stored in the platform in a confidential form; the platform does not store your private key, so please keep it safe by yourself. Please consult the relevant operating system documentation for the root user password.
   Password	Use the operating system user and password for login verification, which can still be updated to the key method later. The user is only an initial account; after the virtual machine is successfully created, you can also create other operating system users in the virtual machine for login. The platform encrypts and stores your root user password, and you will not see its plaintext password again, so please keep it safe by yourself.
   Start Immediately	Defaults to enabled. Enabling this option will start the virtual machine immediately after creation, otherwise only the virtual machine will be created.

9. (Optional) In the Advanced Configuration area, refer to the following instructions to configure the relevant information.

   Parameter	Description
   Health Check	Liveness Check: Checks if the virtual machine is in a healthy state; if the detection result is abnormal, it will determine whether to restart the instance based on the health check configuration. Availability Check: Checks if the virtual machine has completed startup and is in a normal service state; if the health status of the virtual machine instance is detected as abnormal, the state of the virtual machine will be updated. For related parameter descriptions.
   Node Affinity	Preferred: The virtual machine will be scheduled to nodes that meet affinity requirements whenever possible. The system will determine nodes capable of running the virtual machine by combining affinity weights and other scheduling requirements (e.g., compute resource requirements). Required: The virtual machine will only be scheduled to nodes that fully meet affinity requirements.

10. After confirming that the information is correct, click Create.

    Wait for the virtual machine to change from Creating to Running status.

#Related Operations

You can click the ⋮ icon on the right side of the list page or the Actions in the upper right corner of the details page to update or delete the virtual machine as needed. For other related operations like resetting passwords or updating keys, please refer to Manage Virtual Machines.

Note:

• Updates can only be performed when the virtual machine is in Abnormal, Unknown, or Stopped status.

• Updates do not support displaying disks that were separately attached or created after the virtual machine was created.

• By default, Start Immediately is disabled during updates; you can enable it as needed.

#Using the API

A virtual machine is a VirtualMachine (kubevirt.io/v1). The example below boots from a bootable volume (a DataSource), attaches a pod network, and injects an SSH key through cloud-init:

apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: web-01
  namespace: demo
spec:
  running: false           # set true to start on creation
  dataVolumeTemplates:
    - metadata:
        name: web-01-rootfs
      spec:
        sourceRef:          # clone an existing bootable volume (DataSource)
          kind: DataSource
          name: centos-stream9
          namespace: kube-public
        storage:
          resources:
            requests:
              storage: 20Gi
          storageClassName: rbd-1
          volumeMode: Block
          accessModes:
            - ReadWriteMany
  template:
    metadata:
      labels:
        kubevirt.io/vm: web-01
    spec:
      domain:
        cpu:
          cores: 1
        resources:          # ACP resource-limit model: requests == limits
          requests:
            memory: 2Gi
          limits:
            memory: 2Gi
        devices:
          disks:
            - name: rootfs
              disk: { bus: virtio }
            - name: cloudinit
              disk: { bus: virtio }
          interfaces:
            - name: default
              masquerade: {}
      networks:
        - name: default
          pod: {}
      volumes:
        - name: rootfs
          dataVolume:
            name: web-01-rootfs
        - name: cloudinit
          cloudInitNoCloud:
            userData: |
              #cloud-config
              ssh_authorized_keys:
                - ssh-ed25519 AAAAC3...example user@host

kubectl apply -f vm.yaml
# Start it (ACP virtual machines use the spec.running field):
kubectl patch vm web-01 -n demo --type merge -p '{"spec":{"running":true}}'

The boot disk is provisioned by the dataVolumeTemplates entry, which clones the referenced bootable volume. A virtual machine imported with a spec.instancetype reference (instead of inline resources) is also supported and is converted to an inline spec when you edit it — see Managing Virtual Machines.