design-proposal: toggle_vga_video_device.md

We want to allow cluster administrators and VM owners to toggle the
video device type, between VGA (for compatibility with older VMs) and
virtio (that will be used by default).

Signed-off-by: Daniel Sionov <[email protected]>

design-proposals/toggle_vga_video_device.md

@@ -0,0 +1,130 @@
+# Overview
+We want to allow cluster administrators and VM owners to toggle the video device type.
+between VGA (for compatibility with older VMs) and virtio (that will be used by default).
+
+## Motivation
+Currently, the default video device type for AMD64 in KubeVirt is VGA.
+Which limits the functionality available to virtual machines.
+For example, VGA restricts display resolution settings for Windows VMs and may not support modern workloads effectively.
+However, it is necessary to maintain compatibility for older virtual machines that depend on VGA (e.g., RHEL 5/6).
+To address this, we propose making virtio the default video device type for AMD64 systems while providing a mechanism to toggle VGA for older VMs.
+
+## Goals
+the kubevirt resource should have the ability to toggle the default video device between vga and virtio
+
+## Non Goals
+(limitations to the scope of the design)
+
+## Definition of Users
+Cluster admins managing KubeVirt deployments who need to standardize the default video device type across their cluster.
+vm-owners who require specific default configurations for VMIs in their environments.
+
+## User Stories
+- As a cluster administrator, I want to ensure my old VMs continue using VGA as the default video device type
+while transitioning new workloads to use virtio by default.
+
+- As a VM owner, I want to ensure compatibility with older VMs that require VGA by marking the kv resource accordingly before upgrading.
+
+## Repos
+- [KubeVirt](https://github.com/kubevirt/kubevirt)
+
+# Design
+
+### Option 1: Kubevirt resource Annotation-Based Toggle
+**Description:** Introduce an annotation on the KubeVirt CR to specify the default video device type. The annotation kubevirt.io/default-video-device: vga can be used to default all VMs to VGA unless overridden in individual VMIs.
+
+**Pros:**
+
+- Minimal changes to the API schema.
+- Easy to implement and maintain.
+
+**Cons:**
+
+- Less visible to users compared to a dedicated configuration field.
+
+### Option 2: Kubevirt resource Configuration Field
+
+**Description:** Add a dedicated field vgaVideoDevice under spec.configuration in the KubeVirt CR to toggle the default video device type.
+
+**Pros:**
+- Clear and explicit configuration.
+- Easily visible and intuitive for users.
+
+**Cons:**
+- Requires changes to the API schema.
+- Slightly more complex to implement and maintain.
+
+### Option 3: VM-Level Configuration Field
+
+**Description:** Introduce a dedicated field defaultVideoDevice under spec.template.spec.domain.devices in the VM template schema.
+This field allows VM-specific control of the default video device type.
+By default, the VM mutator will populate this field based on architecture.
+Users can explicitly override this default to maintain VGA for older workloads.
+
+**Pros:**
+- Granular Control: Enables precise configuration for each VM, avoiding cluster-wide changes that could affect unrelated workloads.
+- Default Logic: Ensures reasonable defaults based on architecture while allowing user overrides for legacy compatibility.
+- Scalability: Provides flexibility for administrators and VM owners in mixed environments with diverse requirements.
+
+**Cons:**
+- API Complexity: Requires schema changes to the VM template API, introducing additional fields that need maintenance and testing.
+- Implementation Overhead: Increases complexity for the mutator logic to handle defaults and explicit configurations seamlessly.
+- Administrative Effort: Per-VM configuration may lead to higher administrative overhead if many VMs require toggling.
+
+## API Examples
+
+**option 1: kubevirt resource dedicated annotation.**
+```yaml
+apiVersion: kubevirt.io/v1
+kind: KubeVirt
+metadata:
+  name: kubevirt
+  annotations:
+    kubevirt.io/default-_vga_video-device: "true"
+spec:
+```
+
+**option 2: kubevirt resource dedicated configuration field.**
+```yaml
+apiVersion: kubevirt.io/v1
+kind: KubeVirt
+metadata:
+  name: kubevirt
+spec:
+  configuration:
+    vgaVideoDevice: true
+```
+
+**option 3: vm-level configuration.**
+```yaml
+apiVersion: kubevirt.io/v1
+kind: VirtualMachine
+metadata:
+  name: vm
+spec:
+  template:
+    spec:
+      domain:
+        devices:
+           defaultVideoDevice: vga
+```
+
+## Scalability
+The proposed changes have no anticipated impact on scalability capabilities of the KubeVirt framework
+
+## Update/Rollback Compatibility
+cluster admins and vm-owners that have old vms that supports only vga video device.
+will have to use the annotation or the field to mark they want to keep the vga video device as the default,
+before they upgrade the virt operator
+
+## Functional Testing Approach
+* Validate that the default video device type is virtio when no annotation is set.
+* Validate that the default video device type switches to VGA when the annotation/field is set in the KubeVirt CR.
+
+# Implementation Phases
+1. **Phase 1 Annotation/Field Toggle Support**
+    - Add logic in the virt launcher to verify the annotation/field configuration before setting the relevant video device.
+    - Write unit and functional tests for the new behavior.
+
+2. **Phase 2 Documentation**
+    - Update KubeVirt documentation to include examples of configuring the default video device type.