feat(network): apply richer IPAM at network creation time

Extends `container network create` and the `container-network-vmnet`
plugin to honor six compose-spec / Docker-style network creation
options that were previously silently dropped: `--gateway`,
`--ip-range`, `--aux-address`, `--driver-opt`, `--ipv6`, and
`--attachable`. The vmnet plugin now actually wires the user's
gateway override and IPv4 sub-range constraints through to the
runtime; aux-address reservations are pre-allocated in the per-network
attachment allocator so the dynamic pool never hands them out.

Motivation
----------

Container-Compose (and other compose-spec orchestrators) decode these
fields from `docker-compose.yml` but cannot apply them today because
`container network create` only accepts `--label`, `--internal`,
`--subnet`, `--subnet-v6`, `--plugin`, and `--plugin-variant`. The
gap was tracked downstream in CHAOS-1334 and surfaced as warn-and-skip
behaviour in container-compose's `setupNetwork` path. With this PR
the runtime accepts the full IPAM surface and the plugin honours each
field at network start.

What this PR changes
--------------------

- Sources/ContainerResource/Network/NetworkConfiguration.swift: six
  new optional fields on the persisted `NetworkConfiguration`
  (`ipv4Gateway`, `ipv4Range`, `auxAddresses`, `driverOpts`,
  `attachable`, `enableIPv6`). All decoded with `decodeIfPresent`,
  encoded with `encodeIfPresent`, and validated end-to-end (gateway,
  range, and aux-addresses must lie inside `ipv4Subnet` when both are
  configured).
- Sources/ContainerCommands/Network/NetworkCreate.swift: matching CLI
  flags (`--gateway`, `--ip-range`, `--aux-address HOSTNAME=IP`
  repeatable, `--driver-opt KEY=VALUE` repeatable, `--ipv6`, and
  `--attachable`). The CLI emits an explicit advisory on stderr when
  `--attachable` is requested because apple/container has no swarm
  attachment concept.
- Sources/Services/ContainerAPIService/Server/Networks/NetworksService.swift:
  `registerService` now serializes the new configuration fields into
  argv passed to the plugin's `start` subcommand. `auxAddresses` is
  encoded as a single JSON argv value to keep the wire shape simple
  and trivially extensible; `driverOpts` is forwarded as repeated
  `--driver-opt KEY=VALUE` entries.
- Sources/Plugins/NetworkVmnet/NetworkVmnetHelper+Start.swift: parses
  the new argv (`--gateway`, `--ip-range`, `--aux-addresses`,
  `--driver-opt`, `--ipv6`) and reconstructs a richer
  `NetworkConfiguration` for the vmnet variants.
- Sources/Services/ContainerNetworkService/Server/ReservedVmnetNetwork.swift
  and AllocationOnlyVmnetNetwork.swift: the IPv4 gateway is no longer
  hard-coded to `subnet.lower + 1`. When the configuration carries an
  explicit `ipv4Gateway`, that address is passed directly to
  `vmnet_network_configuration_set_ipv4_subnet` and validated as
  in-subnet. The allocation-only variant explicitly rejects the IPv6
  request paths with an actionable error pointing users at the
  `reserved` variant on macOS 26+.
- Sources/Services/ContainerNetworkService/Server/NetworkService.swift:
  the per-network attachment allocator now accepts an `ipv4Range`
  override (so the dynamic pool spans the user-supplied sub-CIDR
  rather than the full subnet) and pre-reserves both a custom gateway
  and any in-range `auxAddresses` through `RotatingAddressAllocator`'s
  existing `reserve(_:)` API. Out-of-range aux entries are recorded
  for reference but require no allocator state because they are
  already outside the dynamic pool.
- Sources/Services/ContainerNetworkService/Server/AttachmentAllocator.swift:
  small `reserveHostname(hostname:address:)` helper that wraps the
  underlying allocator's `reserve(_:)` with the actor's
  hostname-to-index dictionary, so reserved entries round-trip
  through `lookup` / `deallocate`.

Wire compatibility
------------------

All new `NetworkConfiguration` fields are optional and decoded with
`decodeIfPresent`; configurations persisted by older daemons decode
cleanly with `nil` defaults (covered by the
`testLegacyConfigurationDecodesWithoutNewFields` regression test).
Plugin argv is purely additive: a newer `NetworksService` against an
older plugin will pass argv that the plugin ignores; an older
`NetworksService` against a newer plugin simply omits the new flags
and the plugin behaves as before.

Known limitations (intentional, follow-up work)
-----------------------------------------------

- `--attachable` is accepted at the CLI for compose-spec parity but
  is not threaded into the plugin and produces no behavioural change
  on apple/container, which has no swarm-mode attachment concept. The
  CLI surfaces this explicitly on stderr.
- `--driver-opt KEY=VALUE` is parsed, persisted on the configuration,
  and forwarded through to the plugin process, but the vmnet plugin
  does not currently interpret any specific keys. Keeping the surface
  on day one means future plugin enhancements can interpret options
  (e.g. DHCP toggles) without another wire-format break.
- Bare `--ipv6` (no `--subnet-v6`) takes effect on the `reserved`
  variant only; the `allocation-only` variant does not yet support
  IPv6 and now emits an actionable error pointing at the `reserved`
  variant on macOS 26+.
- The IPv4 gateway override only takes effect when an explicit
  `--subnet` is also supplied; without a subnet, vmnet is the source
  of truth for both subnet and gateway.

Verification
------------

- `swift build -c release` clean on macOS 26 / Apple silicon.
- `swift test --filter ContainerResourceTests.NetworkConfigurationTest`
  passes 11 tests (3 pre-existing + 8 new), covering: gateway/range/
  aux-address validation (positive and negative), full-shape Codable
  round-trip, and decoding a legacy (pre-PR) JSON configuration with
  none of the new fields populated.

Author: chrisgeo

Sources/ContainerCommands/Network/NetworkCreate.swift

@@ -54,6 +54,42 @@ extension Application {
         @Option(name: .long, help: "Set the variant of the network plugin to use.")
         var pluginVariant: String?
 
+        @Option(
+            name: .customLong("gateway"),
+            help: "Set the IPv4 gateway address for the network. Defaults to the first usable host address in --subnet.",
+            transform: {
+                try IPv4Address($0)
+            })
+        var ipv4Gateway: IPv4Address? = nil
+
+        @Option(
+            name: .customLong("ip-range"),
+            help: "Restrict dynamic IPv4 allocation to a sub-range of --subnet, expressed as CIDR.",
+            transform: {
+                try CIDRv4($0)
+            })
+        var ipv4Range: CIDRv4? = nil
+
+        @Option(
+            name: .customLong("aux-address"),
+            help: "Reserve a static hostname-to-IPv4 mapping (HOSTNAME=IPV4). Repeatable.")
+        var auxAddresses: [String] = []
+
+        @Option(
+            name: .customLong("driver-opt"),
+            help: "Set a free-form network driver option (KEY=VALUE). Repeatable. Currently informational; the vmnet plugin does not interpret any keys.")
+        var driverOpts: [String] = []
+
+        @Flag(
+            name: .customLong("attachable"),
+            help: "Accepted for compose-spec parity. Currently a no-op on apple/container, which has no swarm concept.")
+        var attachable: Bool = false
+
+        @Flag(
+            name: .customLong("ipv6"),
+            help: "Enable IPv6 even when no --subnet-v6 is supplied. The runtime asks vmnet to auto-allocate an IPv6 prefix.")
+        var enableIPv6: Bool = false
+
         @OptionGroup
         public var logOptions: Flags.Logging
 
@@ -65,11 +101,44 @@ extension Application {
         public func run() async throws {
             let parsedLabels = try ResourceLabels(Utility.parseKeyValuePairs(labels))
             let mode: NetworkMode = hostOnly ? .hostOnly : .nat
+
+            let parsedAuxAddresses: [String: IPv4Address]?
+            if auxAddresses.isEmpty {
+                parsedAuxAddresses = nil
+            } else {
+                let raw = Utility.parseKeyValuePairs(auxAddresses)
+                var mapped: [String: IPv4Address] = [:]
+                mapped.reserveCapacity(raw.count)
+                for (hostname, addressText) in raw {
+                    mapped[hostname] = try IPv4Address(addressText)
+                }
+                parsedAuxAddresses = mapped
+            }
+
+            let parsedDriverOpts: [String: String]? = driverOpts.isEmpty ? nil : Utility.parseKeyValuePairs(driverOpts)
+
+            // Compose-spec parity: report acceptance of attachable but make it explicit
+            // that apple/container has no swarm-style attachment concept.
+            if attachable {
+                FileHandle.standardError.write(
+                    Data("Note: --attachable is accepted for compose-spec parity but has no behavioral effect on apple/container.\n".utf8)
+                )
+            }
+
+            // Either an explicit --subnet-v6 or an explicit --ipv6 enables IPv6 on the network.
+            let resolvedEnableIPv6: Bool? = (enableIPv6 || ipv6Subnet != nil) ? true : nil
+
             let config = try NetworkConfiguration(
                 id: self.name,
                 mode: mode,
                 ipv4Subnet: ipv4Subnet,
                 ipv6Subnet: ipv6Subnet,
+                ipv4Gateway: ipv4Gateway,
+                ipv4Range: ipv4Range,
+                auxAddresses: parsedAuxAddresses,
+                driverOpts: parsedDriverOpts,
+                attachable: attachable ? true : nil,
+                enableIPv6: resolvedEnableIPv6,
                 labels: parsedLabels,
                 pluginInfo: NetworkPluginInfo(plugin: self.plugin, variant: self.pluginVariant)
             )

Sources/ContainerResource/Network/NetworkConfiguration.swift

@@ -54,12 +54,52 @@ public struct NetworkConfiguration: Codable, Sendable, Identifiable {
     /// to be proliferated to most users when they update container.
     public let pluginInfo: NetworkPluginInfo?
 
+    /// The IPv4 gateway address for the network, if explicitly specified.
+    /// When `nil`, the runtime derives the gateway from `ipv4Subnet` (typically
+    /// the first usable host address). When set, the value must lie within
+    /// `ipv4Subnet`.
+    public let ipv4Gateway: IPv4Address?
+
+    /// A sub-CIDR of `ipv4Subnet` from which the runtime should allocate
+    /// dynamic IPv4 addresses. When `nil`, the entire usable subnet is
+    /// available. When set, must be contained within `ipv4Subnet`.
+    public let ipv4Range: CIDRv4?
+
+    /// Static hostname-to-IPv4 reservations that must not be handed out by the
+    /// dynamic allocator. Each address must lie within `ipv4Subnet`. Entries
+    /// outside `ipv4Range` (when specified) are recorded but have no allocator
+    /// effect because they are already outside the dynamic pool.
+    public let auxAddresses: [String: IPv4Address]?
+
+    /// Free-form network driver options. Persisted on the configuration and
+    /// forwarded to the network plugin via repeated `--driver-opt KEY=VALUE`
+    /// arguments. The vmnet plugin accepts no options today; future driver
+    /// enhancements may interpret known keys without changing the wire format.
+    public let driverOpts: [String: String]?
+
+    /// Whether to allow ad-hoc container attachments to the network. Accepted
+    /// for compose-spec parity but currently a no-op on apple/container,
+    /// which does not have a multi-host swarm concept.
+    public let attachable: Bool?
+
+    /// Request IPv6 connectivity even when no explicit `ipv6Subnet` is
+    /// configured. When `true` and `ipv6Subnet` is `nil`, the runtime asks
+    /// vmnet to auto-allocate an IPv6 prefix at network start. The flag is
+    /// implicitly `true` whenever `ipv6Subnet` is set.
+    public let enableIPv6: Bool?
+
     /// Creates a network configuration
     public init(
         id: String,
         mode: NetworkMode,
         ipv4Subnet: CIDRv4? = nil,
         ipv6Subnet: CIDRv6? = nil,
+        ipv4Gateway: IPv4Address? = nil,
+        ipv4Range: CIDRv4? = nil,
+        auxAddresses: [String: IPv4Address]? = nil,
+        driverOpts: [String: String]? = nil,
+        attachable: Bool? = nil,
+        enableIPv6: Bool? = nil,
         labels: ResourceLabels = .init(),
         pluginInfo: NetworkPluginInfo?
     ) throws {
@@ -68,6 +108,12 @@ public struct NetworkConfiguration: Codable, Sendable, Identifiable {
         self.mode = mode
         self.ipv4Subnet = ipv4Subnet
         self.ipv6Subnet = ipv6Subnet
+        self.ipv4Gateway = ipv4Gateway
+        self.ipv4Range = ipv4Range
+        self.auxAddresses = auxAddresses
+        self.driverOpts = driverOpts
+        self.attachable = attachable
+        self.enableIPv6 = enableIPv6
         self.labels = labels
         self.pluginInfo = pluginInfo
         try validate()
@@ -79,6 +125,12 @@ public struct NetworkConfiguration: Codable, Sendable, Identifiable {
         case mode
         case ipv4Subnet
         case ipv6Subnet
+        case ipv4Gateway
+        case ipv4Range
+        case auxAddresses
+        case driverOpts
+        case attachable
+        case enableIPv6
         case labels
         case pluginInfo
         // TODO: retain for deserialization compatibility for now, remove later
@@ -99,6 +151,23 @@ public struct NetworkConfiguration: Codable, Sendable, Identifiable {
         ipv4Subnet = try subnetText.map { try CIDRv4($0) }
         ipv6Subnet = try container.decodeIfPresent(String.self, forKey: .ipv6Subnet)
             .map { try CIDRv6($0) }
+        ipv4Gateway = try container.decodeIfPresent(String.self, forKey: .ipv4Gateway)
+            .map { try IPv4Address($0) }
+        ipv4Range = try container.decodeIfPresent(String.self, forKey: .ipv4Range)
+            .map { try CIDRv4($0) }
+        if let rawAux = try container.decodeIfPresent([String: String].self, forKey: .auxAddresses) {
+            var decoded: [String: IPv4Address] = [:]
+            decoded.reserveCapacity(rawAux.count)
+            for (hostname, addressText) in rawAux {
+                decoded[hostname] = try IPv4Address(addressText)
+            }
+            auxAddresses = decoded
+        } else {
+            auxAddresses = nil
+        }
+        driverOpts = try container.decodeIfPresent([String: String].self, forKey: .driverOpts)
+        attachable = try container.decodeIfPresent(Bool.self, forKey: .attachable)
+        enableIPv6 = try container.decodeIfPresent(Bool.self, forKey: .enableIPv6)
         let decodedLabels = try container.decodeIfPresent([String: String].self, forKey: .labels) ?? [:]
         labels = try .init(decodedLabels)
         pluginInfo = try container.decodeIfPresent(NetworkPluginInfo.self, forKey: .pluginInfo)
@@ -114,6 +183,15 @@ public struct NetworkConfiguration: Codable, Sendable, Identifiable {
         try container.encode(mode, forKey: .mode)
         try container.encodeIfPresent(ipv4Subnet, forKey: .ipv4Subnet)
         try container.encodeIfPresent(ipv6Subnet, forKey: .ipv6Subnet)
+        try container.encodeIfPresent(ipv4Gateway?.description, forKey: .ipv4Gateway)
+        try container.encodeIfPresent(ipv4Range, forKey: .ipv4Range)
+        if let auxAddresses {
+            let encodable = auxAddresses.mapValues { $0.description }
+            try container.encode(encodable, forKey: .auxAddresses)
+        }
+        try container.encodeIfPresent(driverOpts, forKey: .driverOpts)
+        try container.encodeIfPresent(attachable, forKey: .attachable)
+        try container.encodeIfPresent(enableIPv6, forKey: .enableIPv6)
         try container.encode(labels, forKey: .labels)
         try container.encodeIfPresent(pluginInfo, forKey: .pluginInfo)
     }
@@ -122,5 +200,31 @@ public struct NetworkConfiguration: Codable, Sendable, Identifiable {
         guard NetworkResource.nameValid(id) else {
             throw ContainerizationError(.invalidArgument, message: "invalid network ID: \(id)")
         }
+        if let ipv4Gateway, let ipv4Subnet {
+            guard ipv4Subnet.contains(ipv4Gateway) else {
+                throw ContainerizationError(
+                    .invalidArgument,
+                    message: "gateway \(ipv4Gateway) is not within IPv4 subnet \(ipv4Subnet)"
+                )
+            }
+        }
+        if let ipv4Range, let ipv4Subnet {
+            guard ipv4Subnet.contains(ipv4Range.lower) && ipv4Subnet.contains(ipv4Range.upper) else {
+                throw ContainerizationError(
+                    .invalidArgument,
+                    message: "ip-range \(ipv4Range) is not contained within IPv4 subnet \(ipv4Subnet)"
+                )
+            }
+        }
+        if let auxAddresses, let ipv4Subnet {
+            for (hostname, address) in auxAddresses {
+                guard ipv4Subnet.contains(address) else {
+                    throw ContainerizationError(
+                        .invalidArgument,
+                        message: "aux-address \(hostname)=\(address) is not within IPv4 subnet \(ipv4Subnet)"
+                    )
+                }
+            }
+        }
     }
 }

Sources/Plugins/NetworkVmnet/NetworkVmnetHelper+Start.swift

@@ -66,6 +66,21 @@ extension NetworkVmnetHelper {
             return .reserved
         }()
 
+        @Option(name: .customLong("gateway"), help: "Explicit IPv4 gateway address (optional; default derived from subnet)")
+        var ipv4Gateway: String?
+
+        @Option(name: .customLong("ip-range"), help: "Sub-CIDR of subnet from which dynamic IPv4 addresses are allocated")
+        var ipv4Range: String?
+
+        @Option(name: .customLong("aux-addresses"), help: "JSON-encoded hostname-to-IPv4 reservations")
+        var auxAddressesJSON: String?
+
+        @Option(name: .customLong("driver-opt"), help: "Free-form driver option (KEY=VALUE), repeatable")
+        var driverOpts: [String] = []
+
+        @Flag(name: .customLong("ipv6"), help: "Enable IPv6 even when no IPv6 subnet is supplied")
+        var enableIPv6 = false
+
         var logRoot = LogRoot.path
 
         func run() async throws {
@@ -81,6 +96,25 @@ extension NetworkVmnetHelper {
                 log.info("configuring XPC server")
                 let ipv4Subnet = try self.ipv4Subnet.map { try CIDRv4($0) }
                 let ipv6Subnet = try self.ipv6Subnet.map { try CIDRv6($0) }
+                let ipv4Gateway = try self.ipv4Gateway.map { try IPv4Address($0) }
+                let ipv4Range = try self.ipv4Range.map { try CIDRv4($0) }
+                let auxAddresses = try Self.decodeAuxAddresses(self.auxAddressesJSON)
+                let parsedDriverOpts: [String: String]?
+                if driverOpts.isEmpty {
+                    parsedDriverOpts = nil
+                } else {
+                    var collected: [String: String] = [:]
+                    collected.reserveCapacity(driverOpts.count)
+                    for entry in driverOpts {
+                        guard let separatorIndex = entry.firstIndex(of: "=") else {
+                            throw ContainerizationError(.invalidArgument, message: "driver option '\(entry)' is missing '='")
+                        }
+                        let key = String(entry[..<separatorIndex])
+                        let value = String(entry[entry.index(after: separatorIndex)...])
+                        collected[key] = value
+                    }
+                    parsedDriverOpts = collected
+                }
                 let pluginInfo = NetworkPluginInfo(
                     plugin: NetworkVmnetHelper._commandName,
                     variant: self.variant.rawValue
@@ -91,6 +125,12 @@ extension NetworkVmnetHelper {
                     mode: mode,
                     ipv4Subnet: ipv4Subnet,
                     ipv6Subnet: ipv6Subnet,
+                    ipv4Gateway: ipv4Gateway,
+                    ipv4Range: ipv4Range,
+                    auxAddresses: auxAddresses,
+                    driverOpts: parsedDriverOpts,
+                    attachable: nil,
+                    enableIPv6: (self.enableIPv6 || ipv6Subnet != nil) ? true : nil,
                     pluginInfo: pluginInfo
                 )
                 let network = try Self.createNetwork(
@@ -139,5 +179,19 @@ extension NetworkVmnetHelper {
                 return try ReservedVmnetNetwork(configuration: configuration, log: log)
             }
         }
+
+        private static func decodeAuxAddresses(_ jsonText: String?) throws -> [String: IPv4Address]? {
+            guard let jsonText, !jsonText.isEmpty else { return nil }
+            guard let data = jsonText.data(using: .utf8) else {
+                throw ContainerizationError(.invalidArgument, message: "aux-addresses payload is not valid UTF-8")
+            }
+            let raw = try JSONDecoder().decode([String: String].self, from: data)
+            var decoded: [String: IPv4Address] = [:]
+            decoded.reserveCapacity(raw.count)
+            for (hostname, addressText) in raw {
+                decoded[hostname] = try IPv4Address(addressText)
+            }
+            return decoded
+        }
     }
 }

Sources/Services/ContainerAPIService/Server/Networks/NetworksService.swift

@@ -485,6 +485,34 @@ public actor NetworksService {
             args += ["--variant", variant]
         }
 
+        if let ipv4Gateway = configuration.ipv4Gateway {
+            args += ["--gateway", ipv4Gateway.description]
+        }
+
+        if let ipv4Range = configuration.ipv4Range {
+            args += ["--ip-range", ipv4Range.description]
+        }
+
+        if let auxAddresses = configuration.auxAddresses, !auxAddresses.isEmpty {
+            // Encode as JSON so a single argv value can carry the full hostname-to-IP mapping.
+            let serializable = auxAddresses.mapValues { $0.description }
+            let payload = try JSONEncoder().encode(serializable)
+            guard let payloadString = String(data: payload, encoding: .utf8) else {
+                throw ContainerizationError(.internalError, message: "failed to encode aux-addresses for plugin")
+            }
+            args += ["--aux-addresses", payloadString]
+        }
+
+        if let driverOpts = configuration.driverOpts {
+            for (key, value) in driverOpts {
+                args += ["--driver-opt", "\(key)=\(value)"]
+            }
+        }
+
+        if configuration.enableIPv6 == true {
+            args.append("--ipv6")
+        }
+
         let entityPath = try store.entityPath(configuration.id)
         try pluginLoader.registerWithLaunchd(
             plugin: networkPlugin,

Sources/Services/ContainerNetworkService/Server/AllocationOnlyVmnetNetwork.swift

@@ -69,7 +69,13 @@ public actor AllocationOnlyVmnetNetwork: Network {
 
         let ipv4Subnet = configuration.ipv4Subnet ?? Self.defaultIPv4Subnet
 
-        let gateway = IPv4Address(ipv4Subnet.lower.value + 1)
+        let gateway = configuration.ipv4Gateway ?? IPv4Address(ipv4Subnet.lower.value + 1)
+        guard ipv4Subnet.contains(gateway) else {
+            throw ContainerizationError(
+                .invalidArgument,
+                message: "gateway \(gateway) is not within IPv4 subnet \(ipv4Subnet)"
+            )
+        }
         let status = NetworkPluginStatus(
             ipv4Subnet: ipv4Subnet,
             ipv4Gateway: gateway,

Sources/Services/ContainerNetworkService/Server/AttachmentAllocator.swift

@@ -61,4 +61,12 @@ actor AttachmentAllocator {
     func lookup(hostname: String) async throws -> UInt32? {
         hostnames[hostname]
     }
+
+    /// Pre-reserve a hostname-to-address mapping in the allocator's pool.
+    /// The address must be within the allocator's range; out-of-range or
+    /// already-allocated addresses cause the underlying allocator to throw.
+    func reserveHostname(hostname: String, address: UInt32) async throws {
+        try allocator.reserve(address)
+        hostnames[hostname] = address
+    }
 }