deliver multi-VLAN trunk nics via libvirt vlan XML and bridge fallback

Pearl1594 · Sep 14, 2026 · Sep 14, 2026 · Sep 14, 2026 · Sep 16, 2026 · Sep 28, 2026
commit eb97acf2fbd775f5d4269220ff4710d8a06c0be5
diff --git a/api/src/main/java/com/cloud/agent/api/to/NicTO.java b/api/src/main/java/com/cloud/agent/api/to/NicTO.java
@@ -37,6 +37,9 @@ public class NicTO extends NetworkTO {
 
     String networkSegmentName;
 
+    boolean trunkVlan;
+    List<NetworkTO> associatedNetworks;
+
     public NicTO() {
         super();
     }
@@ -163,4 +166,21 @@ public boolean isEnabled() {
     public void setEnabled(boolean enabled) {
         this.enabled = enabled;
     }
+
+    // trunkVlan/associatedNetworks carry the additional networks for a multi-VLAN trunk nic; unset for ordinary nics
+    public boolean isTrunkVlan() {
+        return trunkVlan;
+    }
+
+    public void setTrunkVlan(boolean trunkVlan) {
+        this.trunkVlan = trunkVlan;
+    }
+
+    public List<NetworkTO> getAssociatedNetworks() {
+        return associatedNetworks;
+    }
+
+    public void setAssociatedNetworks(List<NetworkTO> associatedNetworks) {
+        this.associatedNetworks = associatedNetworks;
+    }
 }
diff --git a/plugins/hypervisors/kvm/src/main/java/com/cloud/hypervisor/kvm/resource/BridgeVifDriver.java b/plugins/hypervisors/kvm/src/main/java/com/cloud/hypervisor/kvm/resource/BridgeVifDriver.java
@@ -20,9 +20,13 @@
 package com.cloud.hypervisor.kvm.resource;
 
 import java.io.File;
+import java.net.URI;
 import java.util.ArrayList;
+import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
@@ -33,6 +37,7 @@
 import org.apache.commons.lang3.StringUtils;
 import org.libvirt.LibvirtException;
 
+import com.cloud.agent.api.to.NetworkTO;
 import com.cloud.agent.api.to.NicTO;
 import com.cloud.agent.properties.AgentProperties;
 import com.cloud.agent.properties.AgentPropertiesFileHandler;
@@ -43,6 +48,8 @@
 
 public class BridgeVifDriver extends VifDriverBase {
 
+    private static final String GUEST_UPLINK_TRUNK_VLAN_RANGE = "2-4094";
+
     private int _timeout;
 
     private final Object _vnetBridgeMonitor = new Object();
@@ -51,6 +58,7 @@
     private String _macIpScriptPath;
     private String _controlCidr = NetUtils.getLinkLocalCIDR();
     private Long libvirtVersion;
+    private final Set<String> uplinkVlanTrunkEnsuredBridges = ConcurrentHashMap.newKeySet();
 
     private static boolean isVxlanOrNetris(String protocol) {
         return protocol.equals(Networks.BroadcastDomainType.Vxlan.scheme()) || protocol.equals(Networks.BroadcastDomainType.Netris.scheme());
@@ -199,6 +207,102 @@
         return vNetId != null && protocol != null && !vNetId.equalsIgnoreCase("untagged");
     }
 
+    protected void plugTrunkVlanNic(LibvirtVMDef.InterfaceDef intf, NicTO nic, String trafficLabel, String guestOsType, String nicAdapter,
+            Integer networkRateKBps) throws InternalErrorException {
+        if (nic.getBroadcastType() != Networks.BroadcastDomainType.Vlan) {
+            throw new InternalErrorException("Multi-VLAN trunk nics are only supported on VLAN-isolated guest networks");
+        }
+        if (!_libvirtComputingResource.hostSupportsVlanFiltering()) {
+            throw new InternalErrorException("vlan_filtering is not enabled on this host's guest bridge; "
+                    + "this host cannot accept a multi-VLAN trunk nic");
+        }
+
+        String brName = trafficLabel != null && !trafficLabel.isEmpty() ? trafficLabel : _bridges.get("guest");
+
+        ensureUplinkAllowsAllVlans(brName);
+
+        List<Integer> vlanTags = collectTrunkVlanTags(nic);
+
+        logger.debug("plugging trunk nic " + nic.getMac() + " onto guest bridge " + brName + " with vlan tags " + vlanTags);
+        intf.defBridgeNet(brName, null, nic.getMac(), getGuestNicModel(guestOsType, nicAdapter), networkRateKBps);
+
+        if (_libvirtComputingResource.hostSupportsVlanTrunkXml()) {
+            intf.setTrunkVlanTags(vlanTags);
+        }
+        // else: older libvirt can't express trunk membership; ensureVlanTrunkMembership() applies it manually once the tap exists
+    }
+
+    private List<Integer> collectTrunkVlanTags(NicTO nic) throws InternalErrorException {
+        Set<Integer> vlanTags = new LinkedHashSet<>();
+        vlanTags.add(parseVlanTag(nic.getBroadcastUri(), "primary network of nic " + nic.getMac()));
+        if (nic.getAssociatedNetworks() != null) {
+            for (NetworkTO associatedNetwork : nic.getAssociatedNetworks()) {
+                if (associatedNetwork.getBroadcastType() != Networks.BroadcastDomainType.Vlan) {
+                    throw new InternalErrorException("Multi-VLAN trunk nics only support VLAN-isolated associated networks");
+                }
+                vlanTags.add(parseVlanTag(associatedNetwork.getBroadcastUri(), "associated network " + associatedNetwork.getUuid()));
+            }
+        }
+        return new ArrayList<>(vlanTags);
+    }
+
+    private Integer parseVlanTag(URI broadcastUri, String description) throws InternalErrorException {
+        String vlanValue = broadcastUri == null ? null : Networks.BroadcastDomainType.getValue(broadcastUri);
+        if (StringUtils.isBlank(vlanValue)) {
+            throw new InternalErrorException("Cannot determine VLAN for " + description
+                    + ": no VLAN has been assigned yet (is the network implemented?). Refusing to plug this multi-VLAN trunk nic.");
+        }
+        try {
+            return Integer.valueOf(vlanValue);
+        } catch (NumberFormatException e) {
+            throw new InternalErrorException("Invalid VLAN value '" + vlanValue + "' for " + description);
+        }
+    }
+
+    private void ensureUplinkAllowsAllVlans(String brName) throws InternalErrorException {
+        if (uplinkVlanTrunkEnsuredBridges.contains(brName)) {
+            return;
+        }
+        synchronized (_vnetBridgeMonitor) {
+            if (uplinkVlanTrunkEnsuredBridges.contains(brName)) {
+                return;
+            }
+            String uplinkPif = _pifs.get(brName);
+            if (StringUtils.isBlank(uplinkPif)) {
+                throw new InternalErrorException("Cannot determine the uplink interface for guest bridge " + brName
+                        + "; refusing to plug a multi-VLAN trunk nic");
+            }
+            runBridgeVlanCommand("add", uplinkPif, GUEST_UPLINK_TRUNK_VLAN_RANGE);
+            uplinkVlanTrunkEnsuredBridges.add(brName);
+        }
+    }
+
+    @Override
+    public void ensureVlanTrunkMembership(LibvirtVMDef.InterfaceDef iface, NicTO nic) throws InternalErrorException {
+        if (!nic.isTrunkVlan() || _libvirtComputingResource.hostSupportsVlanTrunkXml()) {
+            return;
+        }
+        String tapName = iface.getDevName();
+        if (StringUtils.isBlank(tapName)) {
+            throw new InternalErrorException("Cannot apply manual VLAN trunk membership: tap device name unknown for nic " + nic.getMac());
+        }
+        for (Integer vlanTag : collectTrunkVlanTags(nic)) {
+            runBridgeVlanCommand("add", tapName, String.valueOf(vlanTag));
+        }
+    }
+
+    protected void runBridgeVlanCommand(String operation, String dev, String vid) throws InternalErrorException {
+        final Script command = new Script("bridge", _timeout, logger);
+        command.add("vlan");
+        command.add(operation);
+        command.add("dev", dev);
+        command.add("vid", vid);
+        final String result = command.execute();
+        if (result != null) {
+            throw new InternalErrorException("Failed to " + operation + " VLAN " + vid + " membership on " + dev + ": " + result);
+        }
+    }
+
     protected String createStorageVnetBridgeIfNeeded(NicTO nic, String trafficLabel,
                  String storageBrName) throws InternalErrorException {
         if (nic.getBroadcastUri() == null) {
@@ -248,7 +352,9 @@
         }
 
         if (nic.getType() == Networks.TrafficType.Guest) {
-            if (isBroadcastTypeVlanOrVxlan(nic) && isValidProtocolAndVnetId(vNetId, protocol)) {
+            if (nic.isTrunkVlan()) {
+                plugTrunkVlanNic(intf, nic, trafficLabel, guestOsType, nicAdapter, networkRateKBps);
+            } else if (isBroadcastTypeVlanOrVxlan(nic) && isValidProtocolAndVnetId(vNetId, protocol)) {
                     if (trafficLabel != null && !trafficLabel.isEmpty()) {
                         logger.debug("creating a vNet dev and bridge for guest traffic per traffic label " + trafficLabel);
                         String brName = createVnetBr(vNetId, trafficLabel, protocol);

diff --git a/plugins/hypervisors/kvm/src/main/java/com/cloud/hypervisor/kvm/resource/LibvirtVMDef.java b/plugins/hypervisors/kvm/src/main/java/com/cloud/hypervisor/kvm/resource/LibvirtVMDef.java
@@ -30,6 +30,7 @@
 import com.cloud.cpu.CPU;
 import org.apache.cloudstack.api.ApiConstants.IoDriverPolicy;
 import org.apache.cloudstack.utils.qemu.QemuObject;
+import org.apache.commons.collections.CollectionUtils;
 import org.apache.commons.lang.StringEscapeUtils;
 import org.apache.commons.lang3.StringUtils;
 import org.apache.logging.log4j.Logger;
@@ -1602,6 +1603,8 @@
         private String _virtualPortType;
         private String _virtualPortInterfaceId;
         private int _vlanTag = -1;
+        private boolean _vlanTrunk = false;
+        private List<Integer> _vlanTrunkTags;
         private boolean _pxeDisable = false;
         private boolean _linkStateUp = true;
         private Integer _slot;
@@ -1611,8 +1614,8 @@
        private String _interfaceMode;
        private String _userIp4Network;
        private Integer _userIp4Prefix;
        private Integer _multiQueueNumber;
        private Boolean _packedVirtQueues;

        public void defBridgeNet(String brName, String targetBrName, String macAddr, NicModel model) {
            defBridgeNet(brName, targetBrName, macAddr, model, 0);
@@ -1762,6 +1765,19 @@
             return _vlanTag;
         }
 
+        public void setTrunkVlanTags(List<Integer> vlanTags) {
+            _vlanTrunk = true;
+            _vlanTrunkTags = vlanTags;
+        }
+
+        public List<Integer> getTrunkVlanTags() {
+            return _vlanTrunkTags;
+        }
+
+        public boolean isVlanTrunk() {
+            return _vlanTrunk;
+        }
+
         public void setSlot(Integer slot) {
             _slot = slot;
         }
@@ -1865,7 +1881,13 @@
                 }
                 netBuilder.append("</virtualport>\n");
             }
-            if (_vlanTag > 0 && _vlanTag < 4095) {
+            if (_vlanTrunk && CollectionUtils.isNotEmpty(_vlanTrunkTags)) {
+                netBuilder.append("<vlan trunk='yes'>\n");
+                for (Integer tag : _vlanTrunkTags) {
+                    netBuilder.append("<tag id='" + tag + "'/>\n");
+                }
+                netBuilder.append("</vlan>");
+            } else if (_vlanTag > 0 && _vlanTag < 4095) {
                 netBuilder.append("<vlan trunk='no'>\n<tag id='" + _vlanTag + "'/>\n</vlan>");
             }
 
@@ -1873,7 +1895,7 @@
                netBuilder.append(_dpdkExtraLines);
            }

            if (_netType != GuestNetType.VHOSTUSER && _netType != GuestNetType.USER) {
                netBuilder.append("<link state='" + (_linkStateUp ? "up" : "down") +"'/>\n");
            }


diff --git a/plugins/hypervisors/kvm/src/main/java/com/cloud/hypervisor/kvm/resource/VifDriver.java b/plugins/hypervisors/kvm/src/main/java/com/cloud/hypervisor/kvm/resource/VifDriver.java
@@ -46,4 +46,8 @@ public interface VifDriver {
 
     void deleteBr(NicTO nic);
 
+    // applies manual VLAN trunk membership to a trunk nic's live tap on hosts whose libvirt can't do it via <vlan> XML; no-op otherwise
+    default void ensureVlanTrunkMembership(LibvirtVMDef.InterfaceDef iface, NicTO nic) throws InternalErrorException {
+    }
+
 }
diff --git a/...src/main/java/com/cloud/hypervisor/kvm/resource/wrapper/LibvirtPlugNicCommandWrapper.java b/...src/main/java/com/cloud/hypervisor/kvm/resource/wrapper/LibvirtPlugNicCommandWrapper.java
@@ -29,6 +29,7 @@
 import com.cloud.hypervisor.kvm.resource.VifDriver;
 import com.cloud.resource.CommandWrapper;
 import com.cloud.resource.ResourceWrapper;
+import com.cloud.utils.exception.CloudRuntimeException;
 import com.cloud.vm.VirtualMachine;
 import org.libvirt.Connect;
 import org.libvirt.Domain;
@@ -67,6 +68,15 @@
             }
             vm.attachDevice(interfaceDef.toString());
 
+            if (nic.isTrunkVlan()) {
+                try {
+                    final InterfaceDef liveInterfaceDef = libvirtComputingResource.getInterface(conn, vmName, nic.getMac());
+                    vifDriver.ensureVlanTrunkMembership(liveInterfaceDef, nic);
+                } catch (CloudRuntimeException e) {
+                    throw new InternalErrorException("Failed to locate live tap for trunk nic " + nic.getMac() + ": " + e.getMessage());
+                }
+            }
+
             // apply default network rules on new nic
             if (vmType == VirtualMachine.Type.User && nic.isSecurityGroupEnabled()) {
                 final Long vmId = Long.valueOf(vmName.split("-")[2]);

diff --git a/...m/src/main/java/com/cloud/hypervisor/kvm/resource/wrapper/LibvirtStartCommandWrapper.java b/...m/src/main/java/com/cloud/hypervisor/kvm/resource/wrapper/LibvirtStartCommandWrapper.java
@@ -49,6 +49,7 @@
 import com.cloud.network.Networks.TrafficType;
 import com.cloud.resource.CommandWrapper;
 import com.cloud.resource.ResourceWrapper;
+import com.cloud.utils.exception.CloudRuntimeException;
 import com.cloud.vm.UserVmManager;
 import com.cloud.vm.VirtualMachine;
 
@@ -96,6 +97,7 @@ public Answer execute(final StartCommand command, final LibvirtComputingResource
             String vmFinalSpecification = performXmlTransformHook(vmInitialSpecification, libvirtComputingResource);
             libvirtComputingResource.startVM(conn, vmName, vmFinalSpecification);
             performAgentStartHook(vmName, libvirtComputingResource);
+            applyManualVlanTrunkMembership(conn, vmName, nics, libvirtComputingResource);
 
             libvirtComputingResource.applyDefaultNetworkRules(conn, vmSpec, false);
 
@@ -179,6 +181,21 @@ public Answer execute(final StartCommand command, final LibvirtComputingResource
         }
     }
 
+    private void applyManualVlanTrunkMembership(Connect conn, String vmName, NicTO[] nics, LibvirtComputingResource libvirtComputingResource)
+            throws InternalErrorException {
+        for (NicTO nic : nics) {
+            if (!nic.isTrunkVlan()) {
+                continue;
+            }
+            try {
+                LibvirtVMDef.InterfaceDef liveInterface = libvirtComputingResource.getInterface(conn, vmName, nic.getMac());
+                libvirtComputingResource.getVifDriver(nic.getType(), nic.getName()).ensureVlanTrunkMembership(liveInterface, nic);
+            } catch (CloudRuntimeException e) {
+                throw new InternalErrorException("Failed to locate live tap for trunk nic " + nic.getMac() + ": " + e.getMessage());
+            }
+        }
+    }
+
     private void mountSecondaryStoragesIfNeeded(StartCommand command, LibvirtComputingResource libvirtComputingResource, List<KVMStoragePool> secondaryStorages) {
         if (CollectionUtils.isNotEmpty(command.getSecondaryStorages())) {
             for (String secondaryStorageUrl : command.getSecondaryStorages()) {