NE: add network.allocate.extension.ip to control if allocate a placeholder NIC

Author: weizhouapache

api/src/main/java/org/apache/cloudstack/extension/ExtensionHelper.java

@@ -26,6 +26,7 @@
 public interface ExtensionHelper {
     Long getExtensionIdForCluster(long clusterId);
     Extension getExtension(long id);
+    Extension getExtensionByNameAndType(String name, Extension.Type type);
     Extension getExtensionForCluster(long clusterId);
     List<String> getExtensionReservedResourceDetails(long extensionId);
 

framework/extensions/src/main/java/org/apache/cloudstack/framework/extensions/manager/ExtensionsManagerImpl.java

@@ -2222,6 +2222,11 @@ public Extension getExtension(long id) {
         return extensionDao.findById(id);
     }
 
+    @Override
+    public Extension getExtensionByNameAndType(String name, Extension.Type type) {
+        return extensionDao.findByNameAndType(name, type);
+    }
+
     @Override
     public Extension getExtensionForCluster(long clusterId) {
         Long extensionId = getExtensionIdForCluster(clusterId);

framework/extensions/src/main/java/org/apache/cloudstack/framework/extensions/network/NetworkExtensionElement.java

@@ -122,6 +122,7 @@
 import org.apache.cloudstack.extension.ExtensionHelper;
 import org.apache.cloudstack.extension.NetworkCustomActionProvider;
 import org.apache.cloudstack.framework.extensions.dao.ExtensionDetailsDao;
+import org.apache.cloudstack.framework.extensions.vo.ExtensionDetailsVO;
 import org.apache.cloudstack.resourcedetail.dao.VpcDetailsDao;
 import org.apache.commons.collections.CollectionUtils;
 import org.apache.commons.collections.MapUtils;
@@ -256,6 +257,21 @@ public class NetworkExtensionElement extends AdapterBase implements
      */
     public static final String NETWORK_DETAIL_EXTENSION_DETAILS = "extension.details";
 
+    /**
+     * Extension detail key that controls whether {@link #ensureExtensionIp} allocates
+     * a placeholder NIC/IP.
+     *
+     * <p>Applies to any network whose DHCP/DNS/UserData service is provided by this
+     * extension <em>without</em> SourceNat or Gateway — i.e. shared networks and
+     * isolated networks that omit SourceNat.  Set the value to {@code "false"} on the
+     * Extension object (via {@code createExtension} or {@code updateExtension}) when
+     * the extension handles its own data-plane addressing and does not need CloudStack
+     * to reserve a real IP from the subnet pool (e.g. OVN, which programs port
+     * bindings in-fabric).  Omitting the detail or setting any value other than
+     * {@code "false"} preserves the original behaviour (placeholder IP is allocated).</p>
+     */
+    public static final String NETWORK_ALLOCATE_EXTENSION_IP = "network.allocate.extension.ip";
+
     public String getProviderName() {
         return providerName;
     }
@@ -677,6 +693,17 @@ protected String ensureExtensionIp(Network network) {
 
         if (networkModel.isAnyServiceSupportedInNetwork(network.getId(), this.getProvider(),
                 Service.Dhcp, Service.Dns, Service.UserData)) {
+                // Some extensions (e.g. OVN) handle shared-network addressing in the
+                // data plane and do not need a CloudStack-allocated placeholder IP.
+            Extension ext = extensionHelper.getExtensionByNameAndType(providerName, Extension.Type.NetworkOrchestrator);
+            if (ext != null) {
+                ExtensionDetailsVO allocateDetail =
+                        extensionDetailsDao.findDetail(ext.getId(), NETWORK_ALLOCATE_EXTENSION_IP);
+                if (allocateDetail != null && "false".equalsIgnoreCase(allocateDetail.getValue())) {
+                    logger.debug("Skipping placeholder IP for network {} — {} detail is false",
+                            network.getId(), NETWORK_ALLOCATE_EXTENSION_IP);
+                    return null;
+                }
                 try {
                     // An extra IP will be allocated and configured on the external network
                     Nic placeholderNic = networkModel.getPlaceholderNicForRouter(network, null);
@@ -685,7 +712,7 @@ protected String ensureExtensionIp(Network network) {
                         String routerIp = routerIpDetail != null ? routerIpDetail.getValue() : null;
                         Account account = accountService.getAccount(network.getAccountId());
                         String extensionIp = Network.GuestType.Shared.equals(network.getGuestType()) ?
-                                ipAddressManager.assignPublicIpAddress(network.getDataCenterId(), null, account, Vlan.VlanType.DirectAttached, network.getId(), routerIp, false, false).getAddress().toString():
+                                ipAddressManager.assignPublicIpAddress(network.getDataCenterId(), null, account, Vlan.VlanType.DirectAttached, network.getId(), routerIp, false, false).getAddress().toString() :
                                 ipAddressManager.acquireGuestIpAddress(network, routerIp);
                         logger.debug("Saving placeholder nic with ip4 address {} for the network", extensionIp, network);
                         networkManager.savePlaceholderNic(network, extensionIp, null, VirtualMachine.Type.DomainRouter);
@@ -695,6 +722,7 @@ protected String ensureExtensionIp(Network network) {
                 } catch (Exception e) {
                     logger.warn("Failed to acquire extension IP for network {}: {}", network, e.getMessage());
                 }
+            }
         }
         return null;
     }

framework/extensions/src/main/java/org/apache/cloudstack/framework/extensions/network/README.md

@@ -188,11 +188,10 @@ registration as extension metadata. The `custom-action` path embeds them
 directly into the payload file under `physical-network-extension-details`.
 The schema is entirely yours — CloudStack treats it as opaque.
 
-> **`isolation_method=NetworkExtension`** tells CloudStack to select
-> `NetworkExtensionGuestNetworkGuru` when designing guest networks backed by
-> this extension.  This is required whenever your `implement-network` handler
-> outputs JSON that updates the network's broadcast domain type (e.g.
-> `"network.broadcast_domain_type": "Lswitch"` for OVN-backed extensions).
+> **`network.isolation.method=NetworkExtension`** must be set as an Extension
+> detail (via `createExtension` or `updateExtension`).
+> This is required whenever your `implement-network` handler outputs JSON that
+> updates the network's broadcast domain type.
 > Without it the script output is accepted but silently ignored — the network
 > record in the CloudStack database is not updated.
 
@@ -391,14 +390,14 @@ configure the gateway.
 > CloudStack now also includes `network_ip6_gateway` and `network_ip6_cidr`
 > when the guest network has IPv6 configured.
 
-**Stdout (required when `isolation_method=NetworkExtension`):**
+**Stdout (required when `network.isolation.method=NetworkExtension`):**
 
-When the physical-network registration detail `isolation_method=NetworkExtension`
-is set, CloudStack selects `NetworkExtensionGuestNetworkGuru` and applies the
-JSON object printed to stdout back to the network record.  The following two
-fields **must** be present in the output so that CloudStack stores the correct
-broadcast type and URI — without them the KVM agent (`OvsVifDriver`) will not
-set `external_ids:iface-id` on the OVS tap port and OVN port-binding will fail:
+When the Extension detail `network.isolation.method=NetworkExtension` is set,
+CloudStack selects `NetworkExtensionGuestNetworkGuru` and applies the JSON object
+printed to stdout back to the network record.  The following two fields **must**
+be present in the output so that CloudStack stores the correct broadcast type and
+URI — without them the KVM agent (`OvsVifDriver`) will not set
+`external_ids:iface-id` on the OVS tap port and OVN port-binding will fail:
 
 | Output key | Required value | Description |
 |---|---|---|
@@ -411,8 +410,8 @@ Example stdout:
 {"network.broadcast_domain_type": "Lswitch", "network.broadcast_uri": "ovn://cs-net-42"}
 ```
 
-> **Note:** These fields are only consumed when `isolation_method=NetworkExtension`
-> is set on the physical-network registration.  Without that detail, the script
+> **Note:** These fields are only consumed when the Extension detail
+> `network.isolation.method=NetworkExtension` is set.  Without it, the script
 > output is accepted but the network record is **not** updated (the update is
 > silently skipped).
 
@@ -1260,6 +1259,31 @@ To use this extension as a VPC provider:
   it.  The device must listen on this IP for DHCP, DNS, and metadata (port 80)
   requests.
 
+### Opting out of the placeholder IP
+
+Some extensions (e.g. OVN) manage their own data-plane addressing and do not
+need CloudStack to reserve a real IP for networks that provide DHCP/DNS/UserData
+without SourceNat or Gateway.  This covers **both** shared networks and isolated
+networks that omit SourceNat.  Set the Extension detail
+**`network.allocate.extension.ip=false`** when creating or updating the Extension
+to suppress the allocation:
+
+```bash
+cmk createExtension \
+    name=my-sdn \
+    ... \
+    "details[N].key=network.allocate.extension.ip" "details[N].value=false"
+```
+
+When this detail is `false`, `ensureExtensionIp` returns `null` for any network
+backed by this extension that reaches the placeholder-IP branch — i.e. networks
+with DHCP/DNS/UserData but without SourceNat/Gateway.  `extension_ip` will not
+be set in command payloads, and no IP is consumed from the subnet pool.
+
+Omitting the detail (or setting any value other than `false`) preserves the
+original behaviour — a placeholder NIC is allocated and `extension_ip` is
+included in every command payload.
+
 ---
 
 ## Exit Codes