VmApplication API schema reference

Use the following reference to compose valid VmApplication specifications for deploying VM applications through the Red Hat Edge Manager API, CLI, or web console.

VmApplication fields
Copy link

The VmApplication schema extends ApplicationProviderBase with VM-specific fields.

Table 1. VmApplication specification fields
Field Type Required Description

name

String

Yes

The application name. Must be 1-253 lowercase characters, consisting of lowercase letters (a-z), digits (0-9), and hyphens (-). Must start and end with a lowercase letter or digit. Must match the metadata.name in vm.yaml.

appType

String

Yes

Must be vm.

inline

List

Yes

Must contain exactly one file entry with path: vm.yaml. The content field contains the KubeVirt VirtualMachine YAML.

publishPorts

List of Strings

No

Host-to-guest port mappings in hostPort:guestPort or hostPort:guestPort/protocol format, where protocol is tcp, udp, or sctp. For example, "2222:22" for SSH forwarding.

desiredState

String

Read-only

The target power state of the application. Values: running (default), stopped. This field is read-only and cannot be set through flightctl apply. Use flightctl app start or flightctl app stop (or the equivalent UI actions) to change the application power state. The field appears on the rendered specification that the agent reconciles.

restartGeneration

Integer

Read-only

Restart counter managed by the control plane. This field is read-only and cannot be set through flightctl apply. Use flightctl app restart (or the equivalent UI action) to restart an application. The control plane increments this value when a restart is requested. Default: 0.

annotations

Map

Read-only

Internal key-value pairs used by the control plane during render. This field is read-only and is not intended for user-supplied metadata.

Validation rules
Copy link

The Red Hat Edge Manager API validates VmApplication specifications against the following rules. Violations return HTTP 422.

  1. The inline set must contain exactly one file named vm.yaml.
  2. The vm.yaml content must include kind: VirtualMachine.
  3. The vm.yaml content must include apiVersion: kubevirt.io/v1.
  4. The metadata.name in vm.yaml must match the name of the VmApplication.
  5. Each publishPorts entry must follow the hostPort:guestPort or hostPort:guestPort/protocol format, where protocol is tcp, udp, or sctp.
  6. Only the inline provider is supported. The image provider is accepted by the schema but returns "not yet supported" at render time. The gitRef provider is not valid for VM applications.

Examples
Copy link

Minimal VM application 

spec:
  applications:
  - name: fedora-vm
    appType: vm
    inline:
    - path: vm.yaml
      content: |
        apiVersion: kubevirt.io/v1
        kind: VirtualMachine
        metadata:
          name: fedora-vm
        spec:
          running: true
          template:
            spec:
              domain:
                devices:
                  disks:
                  - name: rootdisk
                    disk:
                      bus: virtio
                resources:
                  requests:
                    memory: 2048Mi
              volumes:
              - name: rootdisk
                containerDisk:
                  image: quay.io/containerdisks/fedora:40

VM application with SSH port publishing 

spec:
  applications:
  - name: fedora-vm
    appType: vm
    publishPorts:
    - "2222:22"
    inline:
    - path: vm.yaml
      content: |
        apiVersion: kubevirt.io/v1
        kind: VirtualMachine
        metadata:
          name: fedora-vm
        spec:
          running: true
          template:
            spec:
              domain:
                devices:
                  disks:
                  - name: rootdisk
                    disk:
                      bus: virtio
                resources:
                  requests:
                    memory: 2048Mi
              volumes:
              - name: rootdisk
                containerDisk:
                  image: quay.io/containerdisks/fedora:40

VM application with cloud-init credentials 

spec:
  applications:
  - name: fedora-vm
    appType: vm
    publishPorts:
    - "2222:22"
    inline:
    - path: vm.yaml
      content: |
        apiVersion: kubevirt.io/v1
        kind: VirtualMachine
        metadata:
          name: fedora-vm
        spec:
          running: true
          template:
            spec:
              domain:
                devices:
                  disks:
                  - name: rootdisk
                    disk:
                      bus: virtio
                  - name: cloudinitdisk
                    disk:
                      bus: virtio
                resources:
                  requests:
                    memory: 2048Mi
              volumes:
              - name: rootdisk
                containerDisk:
                  image: quay.io/containerdisks/fedora:40
              - name: cloudinitdisk
                cloudInitNoCloud:
                  userData: |
                    #cloud-config
                    user: fedora
                    ssh_pwauth: true
                    chpasswd:
                      expire: false
                      users:
                      - name: fedora
                        password: <password>
                        type: text
                    ssh_authorized_keys:
                    - <ssh_public_key>

Application type lifecycle support
Copy link

The desiredState and restartGeneration fields are available for all application types through the ApplicationProviderBase schema. These fields are read-only and appear on the rendered application specification that the agent reconciles. They are driven by the flightctl app start, flightctl app stop, and flightctl app restart APIs (or the equivalent UI actions), not by editing and applying the device specification.

Table 2. Lifecycle field support by application type
Application type desiredState restartGeneration

vm

Supported

Supported

quadlet

Supported

Supported

container

Supported

Supported

compose

Supported

Supported

helm

Supported

Supported