Deploy a VM application by using the guided form

You can deploy a VM application on an edge device by using the guided form in the Red Hat Edge Manager web console. The guided form constructs a KubeVirt VirtualMachine YAML specification from the values you enter and submits it as a VmApplication in the device specification.

Before you begin

  • A container disk image is pushed to an OCI-compatible registry accessible from the edge device.
  • The target edge device meets the KVM readiness requirements.
  • Pull credentials for registry.redhat.io are configured on the device at /root/.config/containers/auth.json. See Configure pull credentials on an edge device for VM applications.
  • You have the Admin or Operator role in Red Hat Edge Manager. Viewer-role users cannot create or edit VM applications.

Procedure

  1. In the Red Hat Edge Manager web console, navigate to the device details page or fleet template where you want to add the VM application.
  2. In the Applications section, click Add application.
  3. Select VM as the application type.
  4. Complete the guided form fields:
    Name
    Enter a name for the VM application. The name must be 1-253 lowercase characters, consisting of lowercase letters (a-z), digits (0-9), and hyphens (-). The name must start and end with a lowercase letter or digit.
    Disk image
    Enter the OCI reference to the container disk image, such as quay.io/containerdisks/fedora:40. This field is required.
    CPU cores
    Enter the number of virtual CPU cores to allocate to the VM. Allocate at least 1 CPU core. For general-purpose Linux guests, 2 or more cores are recommended.
    Memory
    Enter the amount of memory to allocate as any valid Kubernetes resource quantity, such as 2048Mi, 4Gi, 2048M, or 4G. You can also specify raw bytes without a unit. Allocate at least 512Mi for minimal Linux guests, or 2048Mi or more for general-purpose workloads. The guided form generates a KubeVirt resources.requests.memory field, which accepts any valid Kubernetes resource quantity.
    SSH key
    Optionally, enter a public SSH key to inject into the VM guest through cloud-init. The guided form does not set a user: directive. The key is added to the default user account defined by the guest image’s cloud-init configuration. For Red Hat Enterprise Linux cloud images, the default user is typically cloud-user. Other guest images use their own default user; for example, community Fedora container disk images use fedora. To connect through SSH, you must also configure a publishPorts entry that maps a host port to the VM SSH port, for example 2222:22. For a Red Hat Enterprise Linux guest with port 2222 published to SSH, connect with ssh -p 2222 cloud-user@<device_host>.
    Password

    Optionally, set a password for the default user account defined by the guest image. The guided form does not set a user: directive. Use the same default username as for SSH key authentication. For Red Hat Enterprise Linux cloud images, the default user is typically cloud-user. Other guest images use their own default user; for example, community Fedora container disk images use fedora. You can use this password to log in through the serial console or SSH when password authentication is enabled.

    Warning

    Credentials are stored as plain text in the device specification. Use SSH key authentication instead of passwords when possible.
    Cloud-init user-data
    Optionally, enter cloud-config YAML for additional guest first-boot configuration such as package installation, custom scripts, or a custom user account. To create your own user instead of using the image default, configure the users directive here or in raw YAML. For examples, see Configure cloud-init for a VM application in the Additional resources section.
    Port publishing
    Optionally, add port mappings in <host_port>:<vm_port> or <host_port>:<vm_port>/<protocol> format, such as 2222:22 for SSH forwarding. The optional protocol suffix can be tcp, udp, or sctp.
  5. Click Save to submit the VM application.
    Important

    Changing any field in the VM application specification after initial deployment causes the VM to reboot. Plan configuration changes accordingly to minimize disruption to running workloads.

Results

  1. Navigate to the device details page and locate the VM application in the Applications section. The VM application appears in this section after the device has updated to the new spec. For VMs that require downloading large images, this might take a while. Review the device update status for troubleshooting if needed.
  2. Monitor the application status transitions:
    • Preparing: The agent is pre-fetching the container disk image.
    • Starting: The Podman pod and QEMU process are initializing.
    • Running: The VM guest is booted and operational.

    If the status shows Error, verify that the device meets the KVM prerequisites and that the container disk image is accessible from the device.

    Note

    On its first boot, a Windows VM guest might start without network connectivity. To recover, restart the VM application by using lifecycle control: click Restart on the device details page, or stop and then start the application.