From 1efb9c0cf6e2fe42840ec6e61c497fbfbf2059a5 Mon Sep 17 00:00:00 2001
From: Shikha Jhala <sjhala@sjhala-thinkpadp1gen4i.rht.csb>
Date: Thu, 27 Mar 2025 11:05:36 -0400
Subject: [PATCH] CNV-52859: Configuring VM interface link state

---
 _topic_maps/_topic_map.yml                    |  2 +
 ...virt-configuring-interface-link-state.adoc | 87 +++++++++++++++++++
 .../virt-setting-interface-link-state.adoc    | 22 +++++
 3 files changed, 111 insertions(+)
 create mode 100644 modules/virt-configuring-interface-link-state.adoc
 create mode 100644 virt/vm_networking/virt-setting-interface-link-state.adoc

diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
index f6f849d91d..a0dcdb2b4c 100644
--- a/_topic_maps/_topic_map.yml
+++ b/_topic_maps/_topic_map.yml
@@ -4771,6 +4771,8 @@ Topics:
     File: virt-connecting-vm-to-ovn-secondary-network
   - Name: Hot plugging secondary network interfaces
     File: virt-hot-plugging-network-interfaces
+  - Name: Setting VM interface link state
+    File: virt-setting-interface-link-state
   - Name: Connecting a VM to a service mesh
     File: virt-connecting-vm-to-service-mesh
   - Name: Configuring a dedicated network for live migration
diff --git a/modules/virt-configuring-interface-link-state.adoc b/modules/virt-configuring-interface-link-state.adoc
new file mode 100644
index 0000000000..33079c8993
--- /dev/null
+++ b/modules/virt-configuring-interface-link-state.adoc
@@ -0,0 +1,87 @@
+// Module included in the following assemblies:
+//
+// * virt/vm_networking/virt-setting-interface-link-state.adoc
+
+:_mod-docs-content-type: PROCEDURE                                  
+[id="virt-configuring-interface-link-state_{context}"]
+= Setting the VM interface link state by using the CLI
+
+You can set the link state of a primary or secondary virtual machine (VM) network interface by using the CLI.
+
+.Prerequisites
+* You have installed the OpenShift CLI (`oc`).
+
+
+.Procedure
+. Edit the VM configuration to set the interface link state, as in the following example:
++
+[source,yaml]
+----
+apiVersion: kubevirt.io/v1
+kind: VirtualMachine
+metadata:
+  name: my-vm
+spec:
+  template:
+    spec:
+      domain:
+        devices:
+          interfaces:
+            - name: default # <1>
+              state: down # <2>
+              masquerade: { }
+      networks:
+        - name: default
+          pod: { }
+# ...
+----
+<1> The name of the interface.
+<2> The state of the interface. The possible values are:
++
+* `up`: Represents an active network connection. This is the default if no value is specified.
+* `down`: Represents a network interface link that is switched off.
+* `absent`: Represents a network interface that is hot unplugged.
++
+[IMPORTANT]
+====
+If you have defined readiness or liveness probes to run VM health checks, setting the primary interface's link state to `down` causes the probes to fail. If a liveness probe fails, the VM is deleted and a new VM is created to restore responsiveness.
+====
+
+. Apply the `VirtualMachine` manifest:
++
+[source,terminal]
+----
+$ oc apply -f <filename>.yaml
+----
+
+.Verification
+* Verify that the desired link state is set by checking the `status.interfaces.linkState` field of the `VirtualMachineInstance` manifest.
++
+[source,terminal]
+----
+$ oc get vmi <vmi-name>
+----
++
+.Example output
+[source,yaml]
+----
+apiVersion: kubevirt.io/v1
+kind: VirtualMachineInstance
+metadata:
+  name: my-vm
+spec:
+  domain:
+    devices:
+      interfaces:
+      - name: default
+        state: down
+        masquerade: { }
+  networks:
+  - name: default
+    pod: { }
+status:
+  interfaces:
+    - name: default
+      linkState: down
+# ...
+----
diff --git a/virt/vm_networking/virt-setting-interface-link-state.adoc b/virt/vm_networking/virt-setting-interface-link-state.adoc
new file mode 100644
index 0000000000..fcf964912a
--- /dev/null
+++ b/virt/vm_networking/virt-setting-interface-link-state.adoc
@@ -0,0 +1,22 @@
+:_mod-docs-content-type: ASSEMBLY                              
+[id="virt-setting-interface-link-state"]                                    
+= Managing the link state of a virtual machine interface                                               
+include::_attributes/common-attributes.adoc[]                  
+:context: virt-setting-interface-link-state                                   
+                                                               
+toc::[]                                                         
+
+You can manage the link state of a primary or secondary virtual machine (VM) interface by using the CLI. By specifying the link state, you can logically connect or disconnect the virtual network interface controller (vNIC) from a network.
+
+[NOTE]
+====
+{VirtProductName} does not support link state management for Single Root I/O Virtualization (SR-IOV) secondary network interfaces and their link states are not reported.
+====
+
+You can specify the desired link state when you first create a VM, by editing the configuration of an existing VM that is stopped or running, or when you hot plug a new network interface to a running VM. If you edit a running VM, you do not need to restart or migrate the VM for the changes to be applied. The current link state of a VM interface is reported in the `status.interfaces.linkState` field of the `VirtualMachineInstance` manifest.
+
+:FeatureName: Setting the VM interface link state
+include::snippets/technology-preview.adoc[]
+
+include::modules/virt-configuring-interface-link-state.adoc[leveloffset=+1]
+