When and How to Use Shared Networks in CloudStack

CloudStack Shared Networks serve as a foundational networking model designed for high-density multi-tenant environments where resource efficiency and simplified routing are prioritized over complete administrative isolation. In the context of large-scale cloud infrastructure; the deployment of individual isolated guest networks for every account can lead to control plane exhaustion and increased latency due to the proliferation of Virtual Routers. Shared Networks mitigate this by allowing multiple accounts to share a single L2 broadcast domain and a common IP gateway. This architectural choice is particularly prevalent in Public Cloud and Enterprise Private Cloud scenarios where the underlying physical network infrastructure; such as high-capacity L3 switches and specialized border routers; handles the primary routing and security logic. By reducing the encapsulation overhead associated with technologies like VXLAN or GRE; Shared Networks facilitate higher throughput and lower packet-loss ratios. This implementation is critical when integrating with existing physical assets where VLAN tags are already defined at the core switch level. The professional application of this network type ensures an idempotent state for VM connectivity across expansive zones; providing a stable platform for high-performance computing and massive concurrency of network traffic.

Technical Specifications

The Configuration Protocol

Environment Prerequisites:

Successful implementation of CloudStack Shared Networks requires a pre-configured Physical Network within the CloudStack Zone. The environment must be running CloudStack version 4.15 or higher to ensure compatibility with modern SDN controllers. Hypervisors; specifically KVM or XCP-ng; must have the bridge-utils package installed and the physical interfaces bonded for redundancy to prevent signal-attenuation at the hardware layer. Users must possess Root Admin privileges; as Shared Networks are global or domain-specific resources and cannot be created by standard end-users. Firewall rules on the upstream physical router must permit traffic for the intended IP ranges to avoid immediate connectivity failure upon VM instantiation.

Section A: Implementation Logic:

The engineering design of Shared Networks focuses on minimizing the path between the Virtual Machine and the physical gateway. Unlike Isolated Networks that utilize a Source NAT on a Virtual Router; Shared Networks bridge the VM’s virtual interface (vif) directly to a tagged VLAN interface on the physical host. When a VM sends a payload; the frame is tagged by the hypervisor and passed onto the physical switch. This bypasses the need for complex internal routing within the cloud’s overlay; thereby reducing the CPU overhead on the management nodes. This “Direct-Access” logic is essential for services requiring low-latency communication or those that must remain visible to external monitoring sensors and logic-controllers within an industrial or enterprise network.

Step-By-Step Execution

Step 1: Initialize the API Selection

Access the CloudStack Management Console or use the cmk (CloudStack Monkey) CLI tool. Navigate to the Infrastructure section and select the Zone where the network will reside.
System Note: This action queries the infrastructure table in the cloud MySQL database to verify the availability of the physical network provider. The management server validates that the physical network is in the “Enabled” state via the listPhysicalNetworks API call.

Step 2: Define the Network Scope and VLAN ID

Select “Add Guest Network” and choose the “Shared” offering. Input the VLAN ID that corresponds to the tagged traffic on your physical switch fabric.
System Note: The cloudstack-management service registers the VLAN ID. When a VM is later deployed; the cloudstack-agent on the hypervisor will use ip link add link eth0 name eth0.100 type vlan id 100 (assuming VLAN 100) to create the sub-interface required for the bridge.

Step 3: Configure the IP Subnet and Gateway

Enter the Gateway; Netmask; and the Start/End IP range. Ensure this range does not overlap with existing static assignments in your data center to prevent IP conflicts.
System Note: These variables are pushed to the dnsmasq.conf file if using the CloudStack Virtual Router for services. If using an external DHCP provider; ensure the “DHCP Provider” field is set to the appropriate external string to prevent the system from attempting to spawn an internal DHCP listener.

Step 4: Map Network to Domain or Project

Specify the “Scope” of the network. A “Global” scope allows any account in the zone to attach VMs; while “Domain” limits usage to a specific organizational unit.
System Note: This step updates the network_domain settings in the database. When the cloudstack-agent starts a VM; it checks these permissions through the isAccountAllowedToAccessNetwork logic before plumbing the virtual interface.

Step 5: Verify Bridge Connectivity on Hypervisor

Log into a KVM host and execute the brctl show command to ensure the new VLAN bridge has been instantiated and the physical interface is properly attached.
System Note: The command brctl addbr brvlan-100 is executed by the agent to create the bridge. Ensure the state is “UP” using the ip link set dev brvlan-100 up command. Failure to see the bridge indicates a communication failure between the management server and the host agent.

Section B: Dependency Fault-Lines:

The primary failure point in CloudStack Shared Networks is “VLAN Leaking” or mismatch between the CloudStack configuration and the physical switchport trunking. If the switchport is not configured as a “trunk” or “tagged” port for the specific VLAN ID assigned in Step 2; the VM will reach a “PROVISIONING” state but fail to acquire an IP via DHCP. Another critical bottleneck is the exhaustion of the IP pool; which occurs when the “Start IP” and “End IP” range is too small for the concurrency of the environment. Ensure that no other manual devices are connected to the same VLAN without being registered in the CloudStack “Reserved IP” list; as this will lead to duplicate IP assignments and immediate packet-loss.

THE TROUBLESHOOTING MATRIX

Section C: Logs & Debugging:

When a Shared Network fails to deploy or VMs cannot communicate; the first point of audit is the Management Server log located at /var/log/cloudstack/management/management-server.log. Search for the string “NetworkDesignError” or “VlanIdNotAvailable”.

On the Hypervisor side; examine /var/log/cloudstack/agent/agent.log to verify if the vif was successfully created. Use the following diagnostic path:
1. Run bridge link show to see if the vnet interfaces are mapped to the correct bridge.
2. Execute tcpdump -i any vlan 100 (replace 100 with your VLAN ID) to observe if DHCP Discover packets are leaving the host.
3. Check iptables -L -v -n and ebtables -L to ensure that automated security groups are not dropping traffic. Specifically look for rules in the FORWARD chain that might be blocking the payload based on MAC-address filtering.

Physical fault codes on switches; such as “STP-BLOCKING”; can also indicate that the hypervisor’s bridge is causing a loop. Ensure Spanning Tree Protocol (STP) is configured as “admin-edge” or “portfast” on the switch side to prevent ports from being disabled during the bridge initialization process.

OPTIMIZATION & HARDENING

– Performance Tuning: To maximize throughput; enable “Virtio-Net” for the VM network interfaces. On the host level; increase the net.core.netdev_max_backlog kernel parameter to 5000 via sysctl to handle bursts of high-volume traffic. This reduces the thermal-inertia of the processing unit by offloading some interrupt handling to multiple cores.
– Security Hardening: Implement strict “Network ACLs” even in a Shared Network. Since multiple tenants share the L2 domain; use ebtables to prevent ARP spoofing and IP hijacking. CloudStack’s “Security Groups” should be enabled to enforce L3/L4 isolation even when L2 isolation is absent. Ensure that the cloudstack-agent is running with the minimum necessary sudo permissions for bridge management.
– Scaling Logic: As the number of VMs grows; the DHCP server (if using the Virtual Router) can become a bottleneck. Transition to an external; highly-available DHCP cluster (such as ISC Kea) to handle high-frequency IP requests. Use multiple Physical Networks in CloudStack to distribute the load across different physical NICs; effectively increasing the total available bandwidth and reducing the impact of a single link failure.

THE ADMIN DESK

1. What happens if I change the VLAN ID after VMs are deployed?
Changing the VLAN ID in a Shared Network is a disruptive action. Existing VMs will keep their old vif configuration until they are stopped and started. You must manually update the hypervisor bridges or use an automated script.

2. Can I use Shared Networks with VXLAN?
Yes; CloudStack supports Shared Networks over VXLAN. In this scenario; the “VLAN ID” field serves as the VNI (Virtual Network Identifier). This allows L2 extension across L3 boundaries while maintaining the Shared Network functional logic.

3. Why is my VM not getting an IP on a Shared Network?
This is usually a trunking issue on the physical switch. Verify that the physical port is in “trunk” mode and allows the VLAN ID. Also; check the dnsmasq logs on the Virtual Router if services are enabled.

4. Is there a limit to the number of IPs in a Shared Network?
The limit is defined by the CIDR mask. For a /24; 254 IPs are available. For massive scale; use a /20 or larger CIDR. CloudStack handles the database indexing efficiently; but physical L2 limits often cap at 4,000 devices.

5. How do I prevent one account from seeing another account’s traffic?
Enable “Security Groups” during the Shared Network creation. This applies iptables and ebtables rules at the hypervisor level to isolate traffic between different accounts; even though they reside on the same broadcast domain.