Direct Routed networks: drop the gateways entirely

The gateways on an L3 network were pure ballast: the Instance's gateway
is always the shared link-local address (169.254.0.1 / fe80::1), the
design doc already recorded the stored values as never used, and for
IPv6 the declared gateway burnt an address in the subnet the operator
then had to keep free. Stop requiring them: gateway and ip6gateway are
accepted for API compatibility but ignored and stored as NULL. A
complete IPv4 family is now netmask + startip (endip defaults to
startip, the subnet derives from startip + netmask), a complete IPv6
family is ip6cidr alone; start/end IPs are validated against the subnet
itself.

The gateways were load-bearing in the plumbing though, in four places
this rewires:
- The orchestrator only copied cidr/ip6cidr onto the network when the
  matching gateway was present; L3 keeps its cidrs without one.
- The two allocation gates keyed on gateway presence -
  IpAddressManagerImpl.allocateDirectIp() for IPv4 and
  Ipv6AddressManagerImpl.setNicIp6Address() for IPv6 - gate on the L3
  network's cidr instead.
- createVlanAndPublicIpRange() derived the range's subnet from the
  gateway and validated it; a gateway-less L3 range derives it from the
  start IP, and checkPublicIpRangeErrors()/checkZoneVlanIpOverlap()
  are null-gateway tolerant (the latter also stops keying its IPv6
  overlap loop on ip6_gateway, using ip6_cidr - which is what it
  actually compares).
- DirectRoutedNetworkGuru.design() no longer demands cidr and gateway
  as a pair.

The UI form loses both gateway fields. Existing L3 networks with stored
gateways keep working: every changed gate checks the gateway first.

Tests: validator and checkL3Ip6Parameters unit tests reworked for the
new groups, integration tests create gateway-less networks and assert
given gateways are ignored, and the l3_network test data drops its
gateway.

Claude-Session: https://claude.ai/code/session_01LkswKyuC2a58YCHFTEPnay

Author: wido

docs/design/direct-routed-networks.md

@@ -271,10 +271,17 @@ This is the mechanism Shared networks already use: `DirectNetworkGuru.allocateDi
 **Each family is optional (added 2026-09-09): IPv6-only networks are supported.** Nothing on an
 L3 network depends on IPv4 — no DHCP, no password or metadata service, and ConfigDrive carries
 whatever families exist — so network creation requires only that at least one family is given and
-that a given family is complete: IPv4 is gateway + netmask + startip (a pool is mandatory, since
-v4 addresses are drawn from one), IPv6 is ip6gateway + ip6cidr alone (no range — §6.3.4).
-Enforced by `NetworkServiceImpl.validateL3AddressFamilies()`; the allocation chain was already
-family-conditional and needed no change. IPv4-only networks work symmetrically.
+that a given family is complete: IPv4 is netmask + startip (a pool is mandatory, since v4
+addresses are drawn from one; the subnet derives from startip + netmask), IPv6 is ip6cidr alone
+(no range — §6.3.4). Enforced by `NetworkServiceImpl.validateL3AddressFamilies()`; the allocation
+chain gates on the cidrs. IPv4-only networks work symmetrically.
+
+**Gateways play no part at all (revised 2026-09-09).** The Instance's gateway is always the
+shared link-local address (§6.2), so declaring a subnet gateway only burnt an address the
+operator then had to keep free. `gateway` and `ip6gateway` are accepted for API compatibility
+but ignored and stored as NULL; start/end IPs are validated against the subnet itself. The two
+allocation gates that historically keyed on the gateway (`allocateDirectIp()` for IPv4,
+`setNicIp6Address()` for IPv6) gate on the L3 network's cidr instead.
 
 Consequences, all good:
 

engine/orchestration/src/main/java/org/apache/cloudstack/engine/orchestration/NetworkOrchestrator.java

@@ -3119,12 +3119,14 @@ public Network doInTransaction(final TransactionStatus status) {
                 final NetworkVO userNetwork = new NetworkVO();
                 userNetwork.setNetworkDomain(networkDomainFinal);
 
-                    if (cidr != null && gateway != null) {
+                    // An L3 (Direct Routed) network carries no gateways at all: instances always
+                    // use the shared link-local gateway, so the subnets stand on their own
+                    if (cidr != null && (gateway != null || ntwkOff.getGuestType() == GuestType.L3)) {
                         userNetwork.setCidr(cidr);
                         userNetwork.setGateway(gateway);
                     }
 
-                    if (StringUtils.isNoneBlank(ip6Gateway, ip6Cidr)) {
+                    if (StringUtils.isNotBlank(ip6Cidr) && (StringUtils.isNotBlank(ip6Gateway) || ntwkOff.getGuestType() == GuestType.L3)) {
                         userNetwork.setIp6Cidr(ip6Cidr);
                         userNetwork.setIp6Gateway(ip6Gateway);
                     }

server/src/main/java/com/cloud/configuration/ConfigurationManagerImpl.java

@@ -5841,9 +5841,12 @@ public Vlan createVlanAndPublicIpRange(final long zoneId, final long networkId,
             throw new InvalidParameterValueException("Vlan owner can be defined only in the zone of type " + NetworkType.Advanced);
         }
 
+        // An L3 (Direct Routed) range carries no gateways at all: the Instance's gateway is
+        // always the shared link-local address, and the IPv4 subnet stands on netmask + start IP
+        final boolean gatewaylessL3 = network.getGuestType() == GuestType.L3;
         if (ipv4) {
             // Make sure the gateway is valid
-            if (!NetUtils.isValidIp4(vlanGateway)) {
+            if (!(gatewaylessL3 && vlanGateway == null) && !NetUtils.isValidIp4(vlanGateway)) {
                 throw new InvalidParameterValueException("Please specify a valid gateway");
             }
 
@@ -5854,7 +5857,7 @@ public Vlan createVlanAndPublicIpRange(final long zoneId, final long networkId,
         }
 
         if (ipv6) {
-            if (!NetUtils.isValidIp6(vlanIp6Gateway)) {
+            if (!(gatewaylessL3 && vlanIp6Gateway == null) && !NetUtils.isValidIp6(vlanIp6Gateway)) {
                 throw new InvalidParameterValueException("Please specify a valid IPv6 gateway");
             }
             if (!NetUtils.isValidIp6Cidr(vlanIp6Cidr)) {
@@ -5866,10 +5869,10 @@ public Vlan createVlanAndPublicIpRange(final long zoneId, final long networkId,
         boolean isSharedNetworkWithoutSpecifyVlan = _networkMgr.isSharedNetworkWithoutSpecifyVlan(networkOffering);
         boolean isL3NetworkWithoutSpecifyVlan = _networkMgr.isL3NetworkWithoutSpecifyVlan(networkOffering);
         if (ipv4) {
-            final String newCidr = NetUtils.getCidrFromGatewayAndNetmask(vlanGateway, vlanNetmask);
+            final String newCidr = NetUtils.getCidrFromGatewayAndNetmask(vlanGateway != null ? vlanGateway : startIP, vlanNetmask);
 
             //Make sure start and end ips are with in the range of cidr calculated for this gateway and netmask {
-            if (!NetUtils.isIpWithInCidrRange(vlanGateway, newCidr) || !NetUtils.isIpWithInCidrRange(startIP, newCidr) || !NetUtils.isIpWithInCidrRange(endIP, newCidr)) {
+            if ((vlanGateway != null && !NetUtils.isIpWithInCidrRange(vlanGateway, newCidr)) || !NetUtils.isIpWithInCidrRange(startIP, newCidr) || !NetUtils.isIpWithInCidrRange(endIP, newCidr)) {
                 throw new InvalidParameterValueException("Please specify a valid IP range or valid netmask or valid gateway");
             }
 
@@ -5903,7 +5906,7 @@ public Vlan createVlanAndPublicIpRange(final long zoneId, final long networkId,
 
             final List<VlanVO> vlans = _vlanDao.listByZone(zone.getId());
             for (final VlanVO vlan : vlans) {
-                if (vlan.getIp6Gateway() == null) {
+                if (vlan.getIp6Cidr() == null) {
                     continue;
                 }
                 if ((StringUtils.isAllEmpty(ipv6Range, vlan.getIp6Range())) &&
@@ -6049,7 +6052,7 @@ private void checkZoneVlanIpOverlap(DataCenterVO zone, Network network, String n
                 }
 
                 // extend IP range
-                if (!vlanGateway.equals(otherVlanGateway) || !vlanNetmask.equals(vlan.getVlanNetmask())) {
+                if (!Objects.equals(vlanGateway, otherVlanGateway) || !Objects.equals(vlanNetmask, vlan.getVlanNetmask())) {
                     throw new InvalidParameterValueException("The IP range has already been added with gateway "
                             + otherVlanGateway + " ,and netmask " + otherVlanNetmask
                             + ", Please specify the gateway/netmask if you want to extend ip range" );
@@ -6853,24 +6856,30 @@ private void checkPublicIpRangeErrors(final long zoneId, final String vlanId, fi
             throw new InvalidParameterValueException("Please ensure that your start IP and end IP are in the same subnet, as per the IP range's netmask.");
         }
 
-        if (!NetUtils.sameSubnet(startIP, vlanGateway, vlanNetmask)) {
-            throw new InvalidParameterValueException("Please ensure that your start IP is in the same subnet as your IP range's gateway, as per the IP range's netmask.");
-        }
+        // A gateway-less range (L3 networks) skips the gateway checks: the subnet is defined by
+        // netmask + start IP alone
+        if (vlanGateway != null) {
+            if (!NetUtils.sameSubnet(startIP, vlanGateway, vlanNetmask)) {
+                throw new InvalidParameterValueException("Please ensure that your start IP is in the same subnet as your IP range's gateway, as per the IP range's netmask.");
+            }
 
-        if (endIP != null && !NetUtils.sameSubnet(endIP, vlanGateway, vlanNetmask)) {
-            throw new InvalidParameterValueException("Please ensure that your end IP is in the same subnet as your IP range's gateway, as per the IP range's netmask.");
+            if (endIP != null && !NetUtils.sameSubnet(endIP, vlanGateway, vlanNetmask)) {
+                throw new InvalidParameterValueException("Please ensure that your end IP is in the same subnet as your IP range's gateway, as per the IP range's netmask.");
+            }
         }
         // check if the gatewayip is the part of the ip range being added.
         // RFC 3021 - 31-Bit Prefixes on IPv4 Point-to-Point Links
         //     GW              Netmask         Stat IP        End IP
         // 192.168.24.0 - 255.255.255.254 - 192.168.24.0 - 192.168.24.1
         // https://tools.ietf.org/html/rfc3021
         // Added by Wilder Rodrigues
-        final String newCidr = NetUtils.getCidrFromGatewayAndNetmask(vlanGateway, vlanNetmask);
-        if (!NetUtils.is31PrefixCidr(newCidr)) {
-            if (NetUtils.ipRangesOverlap(startIP, endIP, vlanGateway, vlanGateway)) {
-                throw new InvalidParameterValueException(
-                        "The gateway ip should not be the part of the ip range being added.");
+        if (vlanGateway != null) {
+            final String newCidr = NetUtils.getCidrFromGatewayAndNetmask(vlanGateway, vlanNetmask);
+            if (!NetUtils.is31PrefixCidr(newCidr)) {
+                if (NetUtils.ipRangesOverlap(startIP, endIP, vlanGateway, vlanGateway)) {
+                    throw new InvalidParameterValueException(
+                            "The gateway ip should not be the part of the ip range being added.");
+                }
             }
         }
     }

server/src/main/java/com/cloud/network/IpAddressManagerImpl.java

@@ -2436,9 +2436,9 @@ public void allocateDirectIp(final NicProfile nic, final DataCenter dc, final Vi
         Transaction.execute(new TransactionCallbackWithExceptionNoReturn<InsufficientAddressCapacityException>() {
             @Override
             public void doInTransactionWithoutResult(TransactionStatus status) throws InsufficientAddressCapacityException {
-                //This method allocates direct ip for the Shared network in Advance zones
-                boolean ipv4 = false;
-                if (network.getGateway() != null) {
+                //This method allocates direct ip for the Shared network in Advance zones.
+                //An L3 (Direct Routed) network carries no gateway, so its IPv4 presence is the cidr
+                if (network.getGateway() != null || (GuestType.L3 == network.getGuestType() && network.getCidr() != null)) {
                     if (nic.getIPv4Address() == null) {
                         PublicIp ip = null;
 

server/src/main/java/com/cloud/network/Ipv6AddressManagerImpl.java

@@ -204,7 +204,8 @@ protected boolean isIp6Taken(Network network, String requestedIpv6) {
      */
     @Override
     public void setNicIp6Address(final NicProfile nic, final DataCenter dc, final Network network) throws InsufficientAddressCapacityException {
-        if (network.getIp6Gateway() != null) {
+        // An L3 (Direct Routed) network carries no gateway, so its IPv6 presence is the cidr
+        if (network.getIp6Gateway() != null || (Network.GuestType.L3 == network.getGuestType() && network.getIp6Cidr() != null)) {
             if (nic.getIPv6Address() == null) {
                 logger.debug("Found IPv6 CIDR " + network.getIp6Cidr() + " for Network " + network);
                 nic.setIPv6Cidr(network.getIp6Cidr());

server/src/main/java/com/cloud/network/NetworkServiceImpl.java

@@ -875,28 +875,51 @@ protected NetworkServiceImpl() {
     /**
      * An L3 (Direct Routed) network has no DHCP and no password/metadata service, so nothing in
      * it depends on IPv4: each address family is optional, making IPv6-only networks possible.
-     * What remains mandatory is that a given family is complete — IPv4 is gateway, netmask and
-     * startip (endip defaults to startip), IPv6 is ip6gateway and ip6cidr (no range: addresses
+     * Gateways play no part at all — the Instance's gateway is always the shared link-local
+     * address, so none needs to be declared (or burnt in the subnet). What remains mandatory is
+     * that a given family is complete — IPv4 is netmask and startip (endip defaults to startip,
+     * the subnet derives from startip and netmask), IPv6 is ip6cidr alone (no range: addresses
      * derive from the subnet and the NIC MAC with EUI-64) — and that at least one family is
      * present at all.
      */
-    protected void validateL3AddressFamilies(String gateway, String netmask, String startIP, String endIP,
-            String ip6Gateway, String ip6Cidr, String startIPv6, String endIPv6) {
-        boolean anyIpv4 = !StringUtils.isAllBlank(gateway, netmask, startIP, endIP);
-        boolean completeIpv4 = StringUtils.isNoneBlank(gateway, netmask, startIP);
-        boolean anyIpv6 = !StringUtils.isAllBlank(ip6Gateway, ip6Cidr, startIPv6, endIPv6);
-        boolean completeIpv6 = StringUtils.isNoneBlank(ip6Gateway, ip6Cidr);
+    protected void validateL3AddressFamilies(String netmask, String startIP, String endIP,
+            String ip6Cidr, String startIPv6, String endIPv6) {
+        boolean anyIpv4 = !StringUtils.isAllBlank(netmask, startIP, endIP);
+        boolean completeIpv4 = StringUtils.isNoneBlank(netmask, startIP);
+        boolean anyIpv6 = !StringUtils.isAllBlank(ip6Cidr, startIPv6, endIPv6);
+        boolean completeIpv6 = StringUtils.isNotBlank(ip6Cidr);
         if (anyIpv4 && !completeIpv4) {
             throw new InvalidParameterValueException(String.format(
-                    "IPv4 is optional for %s networks, but when any IPv4 detail is given, gateway, netmask and startip are all required", GuestType.L3));
+                    "IPv4 is optional for %s networks, but when any IPv4 detail is given, netmask and startip are both required", GuestType.L3));
         }
         if (anyIpv6 && !completeIpv6) {
             throw new InvalidParameterValueException(String.format(
-                    "IPv6 is optional for %s networks, but when any IPv6 detail is given, ip6gateway and ip6cidr are both required", GuestType.L3));
+                    "IPv6 is optional for %s networks, but when any IPv6 detail is given, ip6cidr is required", GuestType.L3));
         }
         if (!anyIpv4 && !anyIpv6) {
             throw new InvalidParameterValueException(String.format(
-                    "A %s network needs at least one address family: IPv4 (gateway, netmask, startip) or IPv6 (ip6gateway, ip6cidr)", GuestType.L3));
+                    "A %s network needs at least one address family: IPv4 (netmask, startip) or IPv6 (ip6cidr)", GuestType.L3));
+        }
+    }
+
+    /**
+     * The L3 counterpart of {@code NetworkModel.checkIp6Parameters()}: no gateway is involved,
+     * and the range is optional — when given it must lie inside the subnet.
+     */
+    protected void checkL3Ip6Parameters(String startIPv6, String endIPv6, String ip6Cidr) {
+        if (!NetUtils.isValidIp6Cidr(ip6Cidr)) {
+            throw new InvalidParameterValueException("Invalid ip6cidr");
+        }
+        for (String ip : new String[] {startIPv6, endIPv6}) {
+            if (StringUtils.isBlank(ip)) {
+                continue;
+            }
+            if (!NetUtils.isValidIp6(ip)) {
+                throw new InvalidParameterValueException(String.format("Invalid IPv6 address %s", ip));
+            }
+            if (!NetUtils.isIp6InNetwork(ip, ip6Cidr)) {
+                throw new InvalidParameterValueException(String.format("IPv6 address %s is not within the subnet %s", ip, ip6Cidr));
+            }
         }
     }
 
@@ -1634,12 +1657,29 @@ public Network createGuestNetwork(CreateNetworkCmd cmd) throws InsufficientCapac
             }
         }
 
-        boolean ipv4 = false, ipv6 = false;
-        if (org.apache.commons.lang3.StringUtils.isNoneBlank(gateway, netmask)) {
-            ipv4 = true;
+        final boolean isL3 = ntwkOff.getGuestType() == GuestType.L3;
+        if (isL3) {
+            validateL3AddressFamilies(netmask, startIP, endIP, ip6Cidr, startIPv6, endIPv6);
+            // Gateways are ignored on L3 networks: the Instance's gateway is always the shared
+            // link-local address, so requiring one would only burn an address in the subnet
+            if (!StringUtils.isAllBlank(gateway, ip6Gateway)) {
+                logger.debug("Ignoring the gateway(s) given for {} network {}: instances always use the shared link-local gateway", GuestType.L3, name);
+                gateway = null;
+                ip6Gateway = null;
+            }
         }
-        if (StringUtils.isNoneBlank(ip6Cidr, ip6Gateway)) {
-            ipv6 = true;
+
+        boolean ipv4 = false, ipv6 = false;
+        if (isL3) {
+            ipv4 = StringUtils.isNoneBlank(netmask, startIP);
+            ipv6 = StringUtils.isNotBlank(ip6Cidr);
+        } else {
+            if (org.apache.commons.lang3.StringUtils.isNoneBlank(gateway, netmask)) {
+                ipv4 = true;
+            }
+            if (StringUtils.isNoneBlank(ip6Cidr, ip6Gateway)) {
+                ipv6 = true;
+            }
         }
 
         if (gateway != null) {
@@ -1666,9 +1706,6 @@ public Network createGuestNetwork(CreateNetworkCmd cmd) throws InsufficientCapac
                 throw new InvalidParameterValueException("Either IPv4 or IPv6 start and end address are mandatory");
             }
         }
-        if (ntwkOff.getGuestType() == GuestType.L3) {
-            validateL3AddressFamilies(gateway, netmask, startIP, endIP, ip6Gateway, ip6Cidr, startIPv6, endIPv6);
-        }
 
         String cidr = null;
         if (ipv4) {
@@ -1682,11 +1719,17 @@ public Network createGuestNetwork(CreateNetworkCmd cmd) throws InsufficientCapac
                 } else if (!NetUtils.isValidIp4(endIP)) {
                     throw new InvalidParameterValueException("Invalid format for the endIp parameter");
                 }
-                if (!(gateway != null && netmask != null)) {
+                if (!(netmask != null && (gateway != null || isL3))) {
                     throw new InvalidParameterValueException("gateway and netmask should be defined when startIP/endIP are passed in");
                 }
             }
-            if (gateway != null && netmask != null) {
+            if (isL3 && netmask != null && startIP != null) {
+                if (!NetUtils.isValidIp4Netmask(netmask)) {
+                    throw new InvalidParameterValueException("Invalid netmask");
+                }
+                // No gateway on an L3 network: the subnet derives from the start IP instead
+                cidr = NetUtils.getCidrFromGatewayAndNetmask(startIP, netmask);
+            } else if (gateway != null && netmask != null) {
                 if (NetUtils.isNetworkorBroadcastIP(gateway, netmask)) {
                     if (logger.isDebugEnabled()) {
                         logger.debug("The gateway IP provided is " + gateway + " and netmask is " + netmask + ". The IP is either broadcast or network IP.");
@@ -1710,7 +1753,11 @@ public Network createGuestNetwork(CreateNetworkCmd cmd) throws InsufficientCapac
             if (endIPv6 == null) {
                 endIPv6 = startIPv6;
             }
-            _networkModel.checkIp6Parameters(startIPv6, endIPv6, ip6Gateway, ip6Cidr);
+            if (isL3) {
+                checkL3Ip6Parameters(startIPv6, endIPv6, ip6Cidr);
+            } else {
+                _networkModel.checkIp6Parameters(startIPv6, endIPv6, ip6Gateway, ip6Cidr);
+            }
             if (!GuestType.Shared.equals(ntwkOff.getGuestType()) && !GuestType.L3.equals(ntwkOff.getGuestType())) {
                 _networkModel.checkIp6CidrSizeEqualTo64(ip6Cidr);
             }