Direct Routed networks: IPv4 is optional, enabling IPv6-only networks

Nothing on an L3 network depends on IPv4: there is no DHCP, no password
or metadata service, ConfigDrive carries whatever families exist, the
IPv6 address derives from the subnet and NIC MAC with EUI-64, and the
allocation chain was already family-conditional. Make that a supported
configuration: at network creation each address family is optional, a
given family must be complete - IPv4 is gateway, netmask and startip
(v4 addresses are drawn from a pool), IPv6 is ip6gateway and ip6cidr
alone (no range needed) - and at least one family must be present.
Enforced by NetworkServiceImpl.validateL3AddressFamilies(), which also
replaces the Shared-network start/end-IP check for L3, since an L3
network defined by ip6cidr alone is valid. The create form validates
the same groups client-side.

Sweep the paths that quietly assumed an IPv4 address exists:
- security_group.py: add_to_ipset() skips empty and '0' placeholder
  addresses, and vm_ip is normalised to '' - an IPv6-only Instance's
  default rules now program cleanly (its v4 ipset stays empty, the v6
  ipset is populated as before). The classic golden test stays
  byte-identical.
- LibvirtComputingResource.addNetworkRules() only passes --vmip when
  there is one, as the other call sites already did.

UI, Instances overview: the address column now shows the active
families - IPv4 as before, IPv6 compressed and, when long, elided in
the middle with the last four characters always visible; hovering shows
the full address and clicking copies it to the clipboard.

Tests: unit tests for the family validation, golden-harness tests for
the IPv6-only rule programming, and three integration tests in
test_l3_networks.py (IPv6-only create, IPv6-only deploy asserting a
/128 with fe80::1 and no IPv4, and rejection of incomplete families).

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

Author: wido

docs/design/direct-routed-networks.md

@@ -268,6 +268,14 @@ This is the mechanism Shared networks already use: `DirectNetworkGuru.allocateDi
 `IpAddressManagerImpl.allocateDirectIp()`
 (`server/src/main/java/com/cloud/network/IpAddressManagerImpl.java:2434`).
 
+**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.
+
 Consequences, all good:
 
 * No new tables, no new allocation logic, no new capacity accounting.

plugins/hypervisors/kvm/src/main/java/com/cloud/hypervisor/kvm/resource/LibvirtComputingResource.java

@@ -5868,7 +5868,9 @@ public boolean addNetworkRules(final String vmName, final String vmId, final Str
         cmd.add("add_network_rules");
         cmd.add("--vmname", vmName);
         cmd.add("--vmid", vmId);
-        cmd.add("--vmip", guestIP);
+        if (StringUtils.isNotBlank(guestIP)) {
+            cmd.add("--vmip", guestIP);
+        }
         if (StringUtils.isNotBlank(guestIP6)) {
             cmd.add("--vmip6", guestIP6);
         }

scripts/vm/network/security_group.py

@@ -481,7 +481,9 @@ def create_ipset_forvm(ipsetname, type='iphash', family='inet'):
 
 
 def add_to_ipset(ipsetname, ips, action):
-    for ip in ips:
+    # An address slot can be empty (an IPv6-only NIC has no IPv4 address) or the
+    # '0' placeholder used for absent secondary IPs; neither belongs in an ipset
+    for ip in [_f for _f in ips if _f and str(_f) != '0']:
         logging.debug("vm ip " + str(ip))
         execute("ipset -! " + action + " " + ipsetname + " " + str(ip))
 
@@ -620,7 +622,10 @@ def add_l3_fw_framework(brname):
 def default_network_rules(vm_name, vm_id, vm_ip, vm_ip6, vm_mac, vif, brname, sec_ips, is_first_nic=False, direct_routed=False):
     """ direct_routed marks an Instance on a Direct Routed (L3) network, whose traffic the host
     routes rather than bridges. The Agent decides this - it is the only component that knows the
-    network type - and passes --directrouted; the script never infers it. """
+    network type - and passes --directrouted; the script never infers it.
+
+    vm_ip may be empty: an Instance on an IPv6-only network has no IPv4 address. """
+    vm_ip = vm_ip or ''
     l3 = direct_routed
 
     if l3:
@@ -1221,6 +1226,7 @@ def parse_network_rules(rules):
 
 
 def add_network_rules(vm_name, vm_id, vm_ip, vm_ip6, signature, seqno, vmMac, rules, vif, brname, sec_ips, direct_routed=False):
+    vm_ip = vm_ip or ''
     try:
         vmName = vm_name
         domId = get_vm_id(vmName)

scripts/vm/network/tests/test_security_group.py

@@ -76,7 +76,7 @@ def fake_execute(cmd):
     return captured
 
 
-def capture_default_network_rules(sg, brname, direct_routed):
+def capture_default_network_rules(sg, brname, direct_routed, vm_ip=VM_ARGS['vm_ip']):
     """ Run default_network_rules with all side effects stubbed, returning the commands the
     script would have executed. """
     captured = []
@@ -94,7 +94,7 @@ def fake_execute(cmd):
     sg.delete_rules_for_vm_in_bridge_firewall_chain = lambda name: None
     sg.destroy_ebtables_rules = lambda name, vif: None
 
-    ok = sg.default_network_rules(VM_ARGS['vm_name'], VM_ARGS['vm_id'], VM_ARGS['vm_ip'], VM_ARGS['vm_ip6'],
+    ok = sg.default_network_rules(VM_ARGS['vm_name'], VM_ARGS['vm_id'], vm_ip, VM_ARGS['vm_ip6'],
                                   VM_ARGS['vm_mac'], VM_ARGS['vif'], brname, VM_ARGS['sec_ips'],
                                   is_first_nic=True, direct_routed=direct_routed)
     return ok, captured
@@ -238,6 +238,28 @@ def regenerate_golden():
     print("wrote %d commands to %s" % (len(captured), GOLDEN))
 
 
+class TestIpv6OnlyDirectRouted(unittest.TestCase):
+    """ An Instance on an IPv6-only Direct Routed network has no IPv4 address at all; the
+    default rules must program cleanly without one. """
+
+    def setUp(self):
+        self.sg = load_script()
+        ok, self.captured = capture_default_network_rules(self.sg, "brdr-42", direct_routed=True, vm_ip=None)
+        self.assertTrue(ok, "default rules must succeed for an IPv6-only Instance")
+
+    def test_no_command_carries_a_none_address(self):
+        offenders = [c for c in self.captured if 'None' in c]
+        self.assertEqual([], offenders)
+
+    def test_ipv4_ipset_stays_empty(self):
+        adds = [c for c in self.captured if c.startswith('ipset -! -A ') and not c.split()[3].endswith('-6')]
+        self.assertEqual([], adds)
+
+    def test_ipv6_ipset_still_populated(self):
+        adds = [c for c in self.captured if c.startswith('ipset -! -A ') and c.split()[3].endswith('-6')]
+        self.assertTrue(any(VM_ARGS['vm_ip6'] in c for c in adds), "the IPv6 address must still reach its ipset")
+
+
 if __name__ == '__main__':
     if '--regenerate' in sys.argv:
         regenerate_golden()

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

@@ -872,6 +872,34 @@ protected NetworkServiceImpl() {
      * True when the NIC belongs to a Direct Routed (L3) network, where secondary IPs need a host
      * route and neighbour entry on the hypervisor whether or not security groups are in use.
      */
+    /**
+     * 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
+     * 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);
+        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));
+        }
+        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));
+        }
+        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));
+        }
+    }
+
     /**
      * Whether the NIC sits on a Direct Routed (L3) network. Such a NIC needs the agent told about
      * secondary IPs regardless of the zone's security group setting: the host route and neighbour
@@ -1630,14 +1658,17 @@ public Network createGuestNetwork(CreateNetworkCmd cmd) throws InsufficientCapac
             }
         }
 
-        // Start and end IP address are mandatory for shared and L3 (Direct Routed) networks.
-        if ((ntwkOff.getGuestType() == GuestType.Shared || ntwkOff.getGuestType() == GuestType.L3) && vpcId == null) {
+        // Start and end IP address are mandatory for shared networks.
+        if (ntwkOff.getGuestType() == GuestType.Shared && vpcId == null) {
             if (!AllowEmptyStartEndIpAddress.valueIn(owner.getAccountId()) &&
                 (startIP == null && endIP == null) &&
                 (startIPv6 == null && endIPv6 == null)) {
                 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) {

server/src/test/java/com/cloud/network/NetworkServiceImplTest.java

@@ -1378,4 +1378,44 @@ public void getAndValidateSupportForKeepMacAddressOnPublicNicParameterTestReturn
 
         Assert.assertFalse(service.getAndValidateSupportForKeepMacAddressOnPublicNicParameter(false, networkOfferingVO));
     }
+
+    @Test
+    public void validateL3AddressFamiliesAcceptsDualStack() {
+        service.validateL3AddressFamilies("10.1.1.1", "255.255.255.0", "10.1.1.10", "10.1.1.20", "fd00::1", "fd00::/64", null, null);
+    }
+
+    @Test
+    public void validateL3AddressFamiliesAcceptsIpv4Only() {
+        service.validateL3AddressFamilies("10.1.1.1", "255.255.255.0", "10.1.1.10", null, null, null, null, null);
+    }
+
+    @Test
+    public void validateL3AddressFamiliesAcceptsIpv6Only() {
+        service.validateL3AddressFamilies(null, null, null, null, "fd00::1", "fd00::/64", null, null);
+    }
+
+    @Test(expected = InvalidParameterValueException.class)
+    public void validateL3AddressFamiliesRejectsIncompleteIpv4() {
+        service.validateL3AddressFamilies("10.1.1.1", "255.255.255.0", null, null, "fd00::1", "fd00::/64", null, null);
+    }
+
+    @Test(expected = InvalidParameterValueException.class)
+    public void validateL3AddressFamiliesRejectsNetmaskAlone() {
+        service.validateL3AddressFamilies(null, "255.255.255.0", null, null, "fd00::1", "fd00::/64", null, null);
+    }
+
+    @Test(expected = InvalidParameterValueException.class)
+    public void validateL3AddressFamiliesRejectsIncompleteIpv6() {
+        service.validateL3AddressFamilies(null, null, null, null, "fd00::1", null, null, null);
+    }
+
+    @Test(expected = InvalidParameterValueException.class)
+    public void validateL3AddressFamiliesRejectsIpv6RangeWithoutCidr() {
+        service.validateL3AddressFamilies(null, null, null, null, null, null, "fd00::100", "fd00::200");
+    }
+
+    @Test(expected = InvalidParameterValueException.class)
+    public void validateL3AddressFamiliesRejectsNoFamilyAtAll() {
+        service.validateL3AddressFamilies(null, null, null, null, null, null, null, null);
+    }
 }

test/integration/smoke/test_l3_networks.py

@@ -235,3 +235,81 @@ def test_05_l3_subnets_may_not_overlap_zone_wide(self):
             self.fail("creating an L3 network overlapping another must fail")
         except (CloudstackAPIException, Exception):
             pass
+
+    def create_ipv6_only_l3_network(self, ip6gateway="2001:db8:113::1", ip6cidr="2001:db8:113::/64"):
+        services = {
+            "name": "Test IPv6-only L3 Network",
+            "displaytext": "Test IPv6-only L3 Network",
+            "ip6gateway": ip6gateway,
+            "ip6cidr": ip6cidr
+        }
+        return Network.create(
+            self.apiclient,
+            services,
+            zoneid=self.zone.id,
+            networkofferingid=self.network_offering.id,
+            accountid=self.account.name,
+            domainid=self.account.domainid
+        )
+
+    @attr(tags=["advanced", "smoke"], required_hardware="false")
+    def test_06_create_ipv6_only_l3_network(self):
+        """ Nothing on an L3 network depends on IPv4 - no DHCP, no password or metadata
+            service - so IPv4 is optional and an IPv6-only network is valid. Addresses
+            derive from the subnet and the NIC MAC (EUI-64), so no IPv6 range is needed
+            either: ip6gateway and ip6cidr alone define the network. """
+        network = self.create_ipv6_only_l3_network()
+        self.cleanup.append(network)
+
+        self.assertEqual(network.type, "L3", "network type should be L3")
+        self.assertEqual(network.ip6cidr, "2001:db8:113::/64", "the network must carry its IPv6 CIDR")
+        self.assertFalse(getattr(network, "cidr", None), "an IPv6-only network must carry no IPv4 CIDR")
+
+    @attr(tags=["advanced", "smoke"], required_hardware="false")
+    def test_07_deploy_vm_in_ipv6_only_l3_network(self):
+        """ An Instance in an IPv6-only L3 network gets a /128 with the shared link-local
+            gateway and no IPv4 address at all. """
+        network = self.create_ipv6_only_l3_network()
+        self.cleanup.append(network)
+
+        virtual_machine = VirtualMachine.create(
+            self.apiclient,
+            self.services["virtual_machine"],
+            accountid=self.account.name,
+            domainid=self.account.domainid,
+            serviceofferingid=self.service_offering.id,
+            networkids=[network.id]
+        )
+        self.cleanup.append(virtual_machine)
+
+        self.assertEqual(virtual_machine.state, "Running")
+        nic = virtual_machine.nic[0]
+        self.assertTrue(getattr(nic, "ip6address", None), "the NIC must carry an IPv6 address")
+        self.assertEqual(nic.ip6gateway, "fe80::1", "an L3 NIC uses the shared link-local IPv6 gateway")
+        self.assertFalse(getattr(nic, "ipaddress", None), "the NIC of an IPv6-only network must carry no IPv4 address")
+
+    @attr(tags=["advanced", "smoke"], required_hardware="false")
+    def test_08_l3_network_rejects_incomplete_address_family(self):
+        """ Each address family is optional, but a given family must be complete, and at
+            least one family must be present. """
+        incomplete_ipv4 = {
+            "name": "Test L3 incomplete IPv4 - must fail",
+            "displaytext": "Test L3 incomplete IPv4 - must fail",
+            "gateway": "203.0.113.1",
+            "netmask": "255.255.255.0"
+        }
+        no_family = {
+            "name": "Test L3 without addresses - must fail",
+            "displaytext": "Test L3 without addresses - must fail"
+        }
+        for services in [incomplete_ipv4, no_family]:
+            with self.assertRaises(Exception):
+                network = Network.create(
+                    self.apiclient,
+                    services,
+                    zoneid=self.zone.id,
+                    networkofferingid=self.network_offering.id,
+                    accountid=self.account.name,
+                    domainid=self.account.domainid
+                )
+                self.cleanup.append(network)

ui/public/locales/en.json

@@ -3692,6 +3692,9 @@
 "message.error.required.input": "Please enter input",
 "message.error.reset.config": "Unable to reset config to default value",
 "message.error.retrieve.kubeconfig": "Unable to retrieve Kubernetes Cluster config",
+"message.error.l3.ipv4.incomplete": "IPv4 is optional for L3 networks, but when any IPv4 detail is given, the IPv4 gateway, netmask and start IP are all required",
+"message.error.l3.ipv6.incomplete": "IPv6 is optional for L3 networks, but when any IPv6 detail is given, the IPv6 gateway and IPv6 CIDR are both required",
+"message.error.l3.no.address.family": "Provide at least one address family: IPv4 (gateway, netmask, start IP) or IPv6 (IPv6 gateway, IPv6 CIDR)",
 "message.error.routedid": "Please enter the Routed ID for this network; the selected network offering requires the operator to choose it",
 "message.error.routing.policy.term": "Community need to have the following format number:number",
 "message.error.s3nfs.path": "Please enter S3 NFS Path",
@@ -3913,7 +3916,7 @@
 "message.note.about.keypair.permissions.title": "Note about API key pair rule permissions",
 "message.note.about.keypair.permissions.body": "During the creation of API key pairs, it is possible to define a corresponding set of rule permissions. If a rule set is defined, the API key pair will only have access to APIs for which access has been explicitly granted (i.e., APIs whose corresponding rules are marked as allowed). On the other hand, if no rule set is specified, the API key pair permissions will follow and adapt to the permission set of the user's account role.",
 "message.offering.internet.protocol.warning": "WARNING: IPv6 supported Networks use static routing and will require upstream routes to be configured manually.",
-"message.create.l3.network": "The hypervisor routes a public IPv4/IPv6 address directly to each Instance on this network: no Virtual Router, no NAT and no DHCP. The subnet is an allocation pool routed to the hypervisors; its gateway is required but never used, since Instances always use the shared link-local gateway. Instances receive their configuration via ConfigDrive.",
+"message.create.l3.network": "The hypervisor routes a public IPv4/IPv6 address directly to each Instance on this network: no Virtual Router, no NAT and no DHCP. IPv4 and IPv6 are each optional - provide at least one family; IPv6-only networks are supported. The subnet is an allocation pool routed to the hypervisors; its gateway is required but never used, since Instances always use the shared link-local gateway. Instances receive their configuration via ConfigDrive.",
 "message.success.create.l3.network": "Successfully created L3 (Direct Routed) network",
 "message.offering.l3": "The hypervisor routes a public IPv4/IPv6 address directly to each Instance: no Virtual Router, no NAT and no DHCP. UserData via ConfigDrive is always enabled, since it is the only channel that carries the Instance's network configuration. DNS is strongly recommended; Security Groups are optional.",
 "message.offering.ipv6.warning": "Please refer documentation for creating IPv6 enabled Network/VPC offering <a href='http://docs.cloudstack.apache.org/en/latest/plugins/ipv6.html#isolated-network-and-vpc-tier'>IPv6 support in CloudStack - Isolated Networks and VPC Network Tiers</a>",

ui/src/components/view/ListView.vue

@@ -344,7 +344,13 @@
           :to="{ path: $route.path + '/' + record.id }"
         >{{ text }}</router-link>
         <span v-else>
-          <copy-label :label="text" />
+          <copy-label v-if="text" :label="text" />
+          <br v-if="text && ipV6Address(null, record)"/>
+          <copy-label
+            v-if="ipV6Address(null, record)"
+            :label="shortenIpV6(ipV6Address(null, record))"
+            :copyValue="ipV6Address(null, record)"
+            :tooltip="ipV6Address(null, record)" />
         </span>
         <span v-if="record.issourcenat">
           &nbsp;
@@ -1402,6 +1408,12 @@ export default {
 
       return record.nic.filter(e => { return e.ip6address }).map(e => { return e.ip6address }).join(', ') || text
     },
+    shortenIpV6 (address) {
+      if (!address || address.length <= 16) {
+        return address
+      }
+      return address.substring(0, 11) + '…' + address.substring(address.length - 4)
+    },
     generateCommentsPath (record) {
       if (this.entityTypeToPath(record.entitytype) === 'ssh') {
         return '/' + this.entityTypeToPath(record.entitytype) + '/' + record.entityname