Pearl1594 · Sep 14, 2026 · Sep 14, 2026 · Sep 14, 2026 · Sep 16, 2026 · Sep 28, 2026
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/api/src/main/java/com/cloud/event/EventTypes.java b/api/src/main/java/com/cloud/event/EventTypes.java
@@ -233,6 +233,11 @@ public class EventTypes {
     public static final String EVENT_NIC_DETAIL_ADD = "NIC.DETAIL.ADD";
     public static final String EVENT_NIC_DETAIL_UPDATE = "NIC.DETAIL.UPDATE";
     public static final String EVENT_NIC_DETAIL_REMOVE = "NIC.DETAIL.REMOVE";
+    public static final String EVENT_NIC_NETWORK_ASSOCIATE = "NIC.NETWORK.ASSOCIATE";
+    public static final String EVENT_NIC_NETWORK_DISASSOCIATE = "NIC.NETWORK.DISASSOCIATE";
+    public static final String EVENT_NIC_PRIMARY_NETWORK_CHANGE = "NIC.PRIMARY.NETWORK.CHANGE";
+    // internal-only signal consumed by the usage job - never user-facing, not an audit event
+    public static final String EVENT_NIC_NETWORK_ID_BACKFILL = "NIC.NETWORK.ID.BACKFILL";
 
     // Load Balancers
     public static final String EVENT_ASSIGN_TO_LOAD_BALANCER_RULE = "LB.ASSIGN.TO.RULE";
@@ -1000,6 +1005,9 @@ public class EventTypes {
 
         // Nic Events
         entityEventDetails.put(EVENT_NIC_CREATE, Nic.class);
+        entityEventDetails.put(EVENT_NIC_NETWORK_ASSOCIATE, Nic.class);
+        entityEventDetails.put(EVENT_NIC_NETWORK_DISASSOCIATE, Nic.class);
+        entityEventDetails.put(EVENT_NIC_PRIMARY_NETWORK_CHANGE, Nic.class);
 
         // Load Balancers
         entityEventDetails.put(EVENT_ASSIGN_TO_LOAD_BALANCER_RULE, FirewallRule.class);

diff --git a/api/src/main/java/com/cloud/host/Host.java b/api/src/main/java/com/cloud/host/Host.java
@@ -76,6 +76,9 @@ public static String[] toStrings(Host.Type... types) {
     String HOST_QEMU_RBD_SUPPORT = "host.qemu.rbd.support";
     String HOST_SSH_PORT = "host.ssh.port";
     String HOST_CDROM_MAX_COUNT = "host.cdrom.max.count";
+    String HOST_VLAN_FILTERING_ENABLED = "vlan.filtering.enabled";
+    String HOST_VLAN_TRUNK_XML_SUPPORTED = "vlan.trunk.xml.supported";
+    String HOST_GUEST_BRIDGE_STP_ENABLED = "guest.bridge.stp.enabled";
     String GUEST_OS_CATEGORY_ID = "guest.os.category.id";
     String GUEST_OS_RULE = "guest.os.rule";
 

diff --git a/api/src/main/java/com/cloud/network/NetworkModel.java b/api/src/main/java/com/cloud/network/NetworkModel.java
@@ -74,6 +74,7 @@ public interface NetworkModel {
     String CLOUD_DOMAIN_FILE = "cloud-domain";
     String CLOUD_DOMAIN_ID_FILE = "cloud-domain-id";
     String CLOUD_NAME_FILE = "cloud-name";
+    String NIC_VLAN_MAPPING_FILE = "nic-vlan-mapping";
     int CONFIGDATA_DIR = 0;
     int CONFIGDATA_FILE = 1;
     int CONFIGDATA_CONTENT = 2;
@@ -137,6 +138,13 @@ public interface NetworkModel {
 
     Nic getNicInNetwork(long vmId, long networkId);
 
+    /**
+     * Resolves the nic and guest ip(s) a VM answers on for a given network - the nic's own primary network match
+     * when one exists, or a trunk nic's association (from nic_network_map) otherwise. Returns null if the VM has
+     * neither a primary nor an associated nic in that network.
+     */
+    Pair<Nic, Network.IpAddresses> getNicAndIpInNetwork(long vmId, long networkId);
+
     List<? extends Nic> getNicsForTraffic(long vmId, TrafficType type);
 
     Network getDefaultNetworkForVm(long vmId);

diff --git a/api/src/main/java/com/cloud/network/NetworkService.java b/api/src/main/java/com/cloud/network/NetworkService.java
@@ -35,6 +35,9 @@
 import org.apache.cloudstack.api.command.user.network.ResetNetworkPermissionsCmd;
 import org.apache.cloudstack.api.command.user.network.RestartNetworkCmd;
 import org.apache.cloudstack.api.command.user.network.UpdateNetworkCmd;
+import org.apache.cloudstack.api.command.admin.network.AssociateNetworkToNicCmd;
+import org.apache.cloudstack.api.command.admin.network.ChangeNicPrimaryNetworkCmd;
+import org.apache.cloudstack.api.command.admin.network.DisassociateNetworkFromNicCmd;
 import org.apache.cloudstack.api.command.user.vm.ListNicsCmd;
 import org.apache.cloudstack.api.response.AcquirePodIpCmdResponse;
 import org.apache.cloudstack.framework.config.ConfigKey;
@@ -59,6 +62,7 @@
 import com.cloud.utils.exception.CloudRuntimeException;
 import com.cloud.vm.Nic;
 import com.cloud.vm.NicSecondaryIp;
+import com.cloud.vm.VirtualMachine;
 
 /**
  * The NetworkService interface is the "public" api to entities that make requests to the orchestration engine
@@ -249,6 +253,32 @@ Network createPrivateNetwork(String networkName, String displayText, long physic
 
     List<? extends NicSecondaryIp> listVmNicSecondaryIps(ListNicsCmd listNicsCmd);
 
+    /**
+     * Associates one or more additional networks with an existing nic, delivering them as a multi-VLAN trunk
+     */
+    Nic associateNetworkToNic(AssociateNetworkToNicCmd cmd)
+        throws ConcurrentOperationException, ResourceUnavailableException, InsufficientCapacityException, InsufficientAddressCapacityException;
+
+    /**
+     * Disassociates a network from an existing nic, shrinking its multi-VLAN trunk. The primary network cannot be disassociated.
+     */
+    Nic disassociateNetworkFromNic(DisassociateNetworkFromNicCmd cmd) throws ResourceUnavailableException;
+
+    /**
+     * Changes a multi-VLAN trunk nic's primary network to one of its already-associated networks. Only allowed while
+     * the owning Instance is stopped, since the nic is rebuilt fresh on its next start.
+     */
+    Nic changeNicPrimaryNetwork(ChangeNicPrimaryNetworkCmd cmd);
+
+    /**
+     * Associates additional networks with a nic that was just created (e.g. during VM deploy), before the owning
+     * Instance has ever started. No live agent update is issued - the nic's first plug already reads these
+     * associations fresh. requestedIps (nullable) optionally requests a specific ip4/ip6 address per associated
+     * network id - a network with no entry (or a null map) auto-allocates, same as today.
+     */
+    void associateNetworksToNic(Nic nic, List<Long> networkIds, Map<Long, IpAddresses> requestedIps)
+        throws ConcurrentOperationException, ResourceUnavailableException, InsufficientCapacityException, InsufficientAddressCapacityException;
+
     AcquirePodIpCmdResponse allocatePodIp(Account account, String zoneId, String podId) throws ResourceAllocationException, ConcurrentOperationException;
 
     boolean releasePodIp(ReleasePodIpCmdByAdmin ip) throws CloudRuntimeException;
@@ -281,4 +311,10 @@ Network createPrivateNetwork(String networkName, String displayText, long physic
     String getNicVlanValueForExternalVm(NicTO nic);
 
     Long getPreferredNetworkIdForPublicIpRuleAssignment(IpAddress ip, Long networkId);
+
+    // Re-applies each nic's VLAN membership on the host of a Running Instance, e.g. after a memory revert recreates its taps.
+    void reapplyLiveVlanMembership(VirtualMachine vm) throws ResourceUnavailableException;
+
+    // Pushes a migrated network's new VLAN and DHCP entries to the Running Instances that carry it as a trunk nic association.
+    void refreshTrunkNicsAssociatedToNetwork(Network network);
 }
diff --git a/api/src/main/java/com/cloud/server/ManagementService.java b/api/src/main/java/com/cloud/server/ManagementService.java
@@ -472,6 +472,20 @@ public interface ManagementService {
 
     Ternary<Pair<List<? extends Host>, Integer>, List<? extends Host>, Map<Host, Boolean>> listHostsForMigrationOfVM(VirtualMachine vm, Long startIndex, Long pageSize, String keyword, List<VirtualMachine> vmList);
 
+    /**
+     * If vm has a multi-VLAN trunk NIC and host is not ready for it (VLAN filtering not enabled), returns a
+     * human-readable reason; null otherwise (including when vm has no such NIC, in which case host readiness
+     * for this concern is irrelevant).
+     */
+    String getMultiNetworkNicUnsuitableReason(VirtualMachine vm, Host host);
+
+    /**
+     * If host's guest bridge has STP enabled, returns a human-readable caution about the forward-delay outage
+     * every new port on it incurs (migration, nic plug, vm start); null otherwise. Applies to every VM, not
+     * just ones with a multi-VLAN trunk NIC - unlike getMultiNetworkNicUnsuitableReason, never excludes the host.
+     */
+    String getGuestBridgeStpMigrationCaution(Host host);
+
     /**
      * Apply affinity group constraints and other exclusion rules for VM migration.
      * This is a helper method that can be used independently for per-iteration affinity checks in DRS.

diff --git a/api/src/main/java/com/cloud/vm/Nic.java b/api/src/main/java/com/cloud/vm/Nic.java
@@ -146,6 +146,8 @@ public enum ReservationStrategy {
 
     boolean getSecondaryIp();
 
+    boolean getMultiNetwork();
+
     //
     // IPv4
     //

diff --git a/api/src/main/java/org/apache/cloudstack/api/ApiConstants.java b/api/src/main/java/org/apache/cloudstack/api/ApiConstants.java
@@ -335,6 +335,8 @@ public class ApiConstants {
     public static final String MOVE_ACL_CONSISTENCY_HASH = "aclconsistencyhash";
     public static final String IMAGE_PATH = "imagepath";
     public static final String INSTANCE_CONVERSION_SUPPORTED = "instanceconversionsupported";
+    public static final String VLAN_FILTERING_ENABLED = "vlanfilteringenabled";
+    public static final String VLAN_TRUNK_XML_SUPPORTED = "vlantrunkxmlsupported";
     public static final String INTERNAL_DNS1 = "internaldns1";
     public static final String INTERNAL_DNS2 = "internaldns2";
     public static final String INTERNET_PROTOCOL = "internetprotocol";
@@ -438,6 +440,7 @@ public class ApiConstants {
     public static final String NIC = "nic";
     public static final String NICS = "nics";
     public static final String NIC_NETWORK_LIST = "nicnetworklist";
+    public static final String NIC_NETWORKS_LIST = "nicnetworkslist";
     public static final String NIC_IP_ADDRESS_LIST = "nicipaddresslist";
     public static final String NIC_MULTIQUEUE_NUMBER = "nicmultiqueuenumber";
     public static final String NIC_PACKED_VIRTQUEUES_ENABLED = "nicpackedvirtqueuesenabled";
@@ -906,6 +909,8 @@ public class ApiConstants {
     public static final String ASSOCIATED_NETWORK = "associatednetwork";
     public static final String ASSOCIATED_NETWORK_ID = "associatednetworkid";
     public static final String ASSOCIATED_NETWORK_NAME = "associatednetworkname";
+    public static final String ASSOCIATED_NETWORKS = "associatednetworks";
+    public static final String TRUNKED = "trunked";
     public static final String ASSOCIATED_VPC_ID = "associatedvpcid";
     public static final String ASSOCIATED_VPC_NAME = "associatedvpcname";
     public static final String SOURCE_NAT_SUPPORTED = "sourcenatsupported";

diff --git a/api/src/main/java/org/apache/cloudstack/api/ResponseGenerator.java b/api/src/main/java/org/apache/cloudstack/api/ResponseGenerator.java
@@ -529,6 +529,8 @@ UsageRecordResponse createUsageResponse(Usage usageRecord,
 
     public NicResponse createNicResponse(Nic result);
 
+    public NicResponse createNicResponse(Nic result, Long networkId);
+
     ApplicationLoadBalancerResponse createLoadBalancerContainerReponse(ApplicationLoadBalancerRule lb,
             Map<Ip, UserVm> lbInstances);
 

diff --git a/api/src/main/java/org/apache/cloudstack/api/command/admin/host/FindHostsForMigrationCmd.java b/api/src/main/java/org/apache/cloudstack/api/command/admin/host/FindHostsForMigrationCmd.java
@@ -32,6 +32,7 @@
 import com.cloud.host.Host;
 import com.cloud.utils.Pair;
 import com.cloud.utils.Ternary;
+import com.cloud.vm.VirtualMachine;
 
 @APICommand(name = "findHostsForMigration", description = "Find hosts suitable for migrating an Instance.", responseObject = HostForMigrationResponse.class,
         requestHasSensitiveInfo = false, responseHasSensitiveInfo = false)
@@ -73,6 +74,8 @@ public void execute() {
         List<? extends Host> hostsWithCapacity = hostsForMigration.second();
         hostsRequiringStorageMotion = hostsForMigration.third();
 
+        VirtualMachine vm = _entityMgr.findById(VirtualMachine.class, getVirtualMachineId());
+
         response = new ListResponse<HostForMigrationResponse>();
         List<HostForMigrationResponse> hostResponses = new ArrayList<HostForMigrationResponse>();
         for (Host host : result.first()) {
@@ -90,6 +93,11 @@ public void execute() {
                 hostResponse.setRequiresStorageMotion(false);
             }
 
+            if (!suitableForMigration && vm != null) {
+                hostResponse.setUnsuitableReason(_mgr.getMultiNetworkNicUnsuitableReason(vm, host));
+            }
+            hostResponse.setMigrationCaution(_mgr.getGuestBridgeStpMigrationCaution(host));
+
             hostResponse.setObjectName("host");
             hostResponses.add(hostResponse);
         }
-Original file line number
+Diff line change
@@ Expand Up / @@ -146,6 +146,8 @@ public enum ReservationStrategy { @@
         boolean getSecondaryIp();
+        boolean getMultiNetwork();
         //
         // IPv4
         //
@@ Expand Down @@