Configure Tenant Layer 2 Networks
How to configure Tenant Layer 2 Networks in VergeOS to pass VLANs directly to tenant environments, including creation, verification, VM attachment, and removal procedures.
Overview
Tenant Layer 2 Networks provide a streamlined method for passing VLANs directly to tenant environments in VergeOS. This feature creates direct Layer 2 connectivity between the host network infrastructure and tenant workloads, enabling tenants to access specific VLANs without complex Virtual Switch Port configurations.
When you configure a Tenant Layer 2 Network, VergeOS automatically creates corresponding External and Physical networks within the tenant environment, providing transparent VLAN access to tenant virtual machines.
Target Audience: System administrators and network engineers managing multi-tenant VergeOS environments who need to provide isolated Layer 2 network access to tenants.
What You'll Learn
In this guide, you'll learn how to:
Navigate to Tenant Layer 2 Networks configuration
Create Layer 2 network pass-through for tenants
Verify automatic network creation within tenants
Attach tenant VMs to passed-through VLANs
Properly remove a Tenant Layer 2 Network and clean up tenant-side components
Troubleshoot common Layer 2 connectivity issues
Common Questions This Guide Answers:
How do I pass a VLAN directly to a tenant in VergeOS?
What's the difference between Tenant Layer 2 Networks and Virtual Switch Ports?
How do I give tenant VMs direct access to physical network VLANs?
What networks are automatically created when I configure a Tenant Layer 2 Network?
How can I verify that my tenant has Layer 2 network access?
How do I properly remove a Tenant Layer 2 Network without errors?
Why would I use Tenant Layer 2 Networks instead of routed tenant connectivity?
Can tenant administrators manage the passed-through VLANs themselves?
Requirements
Before configuring Tenant Layer 2 Networks, ensure you have:
VergeOS cluster running version 26.0 or later
Cluster Admin access level
An existing tenant environment
A Layer 2 External network in the root system. For details on how to create a Layer 2 External network, see Creating a Layer 2 External Network
Physical switch ports configured with appropriate VLAN access
Understanding of the VLAN IDs that need to be passed to the tenant
Time Estimate
Estimated completion time: 10-15 minutes per VLAN configuration
This includes creating the Tenant Layer 2 Network, verification within the tenant, and basic connectivity testing.
Quick Reference
Navigate to Tenant Layer 2 Networks
Tenants → [Tenant Name] → Networks (left nav) → Layer2 Networks
Access tenant network configuration
Create new Layer 2 network
Click New
Initiate VLAN pass-through
Select network
Network dropdown
Choose which VLAN to pass through
Enable network
Toggle Enabled
Activate Layer 2 pass-through
Verify in tenant
Tenant UI → Networks
Confirm automatic network creation
Attach VM
Tenant VM → NICs → Select External network
Connect workload to VLAN
Understanding Tenant Layer 2 Networks
Before diving into configuration, it's essential to understand what Tenant Layer 2 Networks are and how they differ from other tenant networking approaches in VergeOS.
What Are Tenant Layer 2 Networks?
Tenant Layer 2 Networks provide direct VLAN connectivity from the host infrastructure to tenant environments. When configured, each physical tenant node receives a virtual NIC connected to the specified VLAN, enabling transparent Layer 2 access for tenant workloads.
Automatic Network Creation
When you create a Tenant Layer 2 Network, VergeOS automatically provisions the following components within the tenant:
NIC Interface on the Tenant Node - A new virtual NIC is added to the tenant node, connected to the specified VLAN
Physical Network - Backend network infrastructure that the NIC plugs into. Appears in the tenant's network list with the name of the network you're passing through, prepended by "Physical -"
External Network - Plugs into the Physical network above. Appears in the tenant's network list with the name of the network you're passing through
Understanding These Components
All three components are created automatically and work together to provide Layer 2 connectivity. If you later remove the Tenant Layer 2 Network from the host side, the NIC is automatically removed, but the Physical and External networks inside the tenant must be cleaned up manually. See Removing a Tenant Layer 2 Network for details.
Do Not Tag the External Network
The External Network created inside the tenant will not have a VLAN tag on it. The interface is already tagged for this VLAN. Leave this network untagged. Adding a VLAN tag to the tenant-side External Network is a common misconfiguration that will break connectivity.
Tenant virtual machines can attach NICs to these networks to gain direct access to the passed-through VLAN.
Use Cases
Tenant Layer 2 Networks are ideal for scenarios requiring:
Direct VLAN Access: Tenants need unfiltered access to specific VLANs
Tenant-Managed Networking: Tenant administrators want full control over their network configuration
Legacy Application Support: Applications requiring Layer 2 adjacency to physical infrastructure
Simplified Network Architecture: Avoiding complex routing and firewall configurations for certain workloads
Comparison with Virtual Switch Ports
Configuration Complexity
Simple - single UI action
More complex - multiple steps
Supported VergeOS Version
26.0 or later
All versions
Automatic Network Creation
Yes
No - manual configuration required
VLAN Trunking Support
Single VLAN per configuration
Can trunk multiple VLANs
Typical Use Case
Single VLAN pass-through
Complex multi-VLAN scenarios
Configuration Steps
This section walks you through creating a Tenant Layer 2 Network to pass a VLAN to a tenant environment. The process involves selecting the tenant, choosing the network, and enabling the pass-through.
Prerequisite
You must have a Layer 2 External network already created in the root system before proceeding. See Creating a Layer 2 External Network for instructions.
Step 1: Navigate to Tenant Networks
First, access the tenant's network configuration area where you'll create the Layer 2 network pass-through.
From the top menu, navigate to Tenants > List
Locate your target tenant in the tenant list
Click on the tenant name to open the tenant dashboard
In the left navigation menu, expand Network and click Layer2 Networks
You should now see the Tenant Layer2 Networks view, which displays any existing Layer 2 networks configured for this tenant.
Step 2: Create New Tenant Layer 2 Network
Next, initiate the creation of a new Layer 2 network pass-through for your tenant.
Click New in the left sidebar
The Tenant Layer2 Network configuration form appears
Step 3: Configure Network Settings
Now configure which network (VLAN) you want to pass through to the tenant and enable the connection.
Reserved VLANs
VLANs 1, 100, 101, and 102 cannot be used for Tenant Layer 2 Networks. These VLANs are reserved for internal traffic.
In the Network dropdown field, select the external Layer 2 network tied to the VLAN you want to pass through to the tenant
The dropdown includes all internal and external networks on the host; only select an external Layer 2 network tied to the VLAN you are passing
Toggle the Enabled switch to the ON position (blue)
This activates the Layer 2 pass-through
When disabled after creation, the configuration remains but the VLAN is not accessible to the tenant
Click Submit to save the configuration
The system will process the request and create the necessary network infrastructure within the tenant.
Step 4: Verify Automatic Network Creation
After submitting the configuration, VergeOS automatically creates the required networks within the tenant environment. Let's verify these were created successfully.
Wait 10-15 seconds for the configuration to propagate
Log into the tenant UI using tenant admin credentials
From the tenant's Main Dashboard, navigate to Networks → List
Verify the following networks appear in the tenant's network list:
External Network - Named after the selected network (e.g., "External VLAN 400")
Physical Network - Backend infrastructure network (typically named "Physical - [Network Name]", e.g., "Physical - External VLAN 400")
Both networks will show Status: Stopped. You can start the External network if you need to pass that traffic to a sub-tenant.
Verification Checkpoint
At this point, you should see both the External and Physical networks in the tenant's network list. These networks represent the Layer 2 connectivity to the host VLAN.
Using Tenant Layer 2 Networks
With the Tenant Layer 2 Network configured and verified, tenant administrators can now attach virtual machine workloads to the passed-through VLAN. This section explains how tenants use these networks.
Attaching VMs to Layer 2 Networks
Tenant administrators attach VMs to the passed-through VLAN by selecting the appropriate network during NIC configuration:
Within the tenant UI, navigate to the VM you want to connect
Access the VM's NICs section
When creating or editing a NIC, select the External network for the passed-through VLAN
Save the NIC configuration
Power on or restart the VM for changes to take effect
Network Placement Best Practices
Set the gateway of internal VM networks to the External network. For a new VM Network, the Gateway field is in the wizard. For existing networks, the gateway is a default gateway under the rules section. See Internal Networks for more information.
Isolation: Consider which VMs truly need Layer 2 access vs. those that can use internal tenant networks
Tenant Management Considerations
Once configured, tenant administrators have full control over:
Which VMs connect to the Layer 2 networks
Network addressing and DHCP configuration (if IP management is required)
Internal routing between Layer 2 networks and other tenant networks
Verification and Testing
After configuring Tenant Layer 2 Networks, verify connectivity and proper operation with these systematic checks. These tests confirm that Layer 2 pass-through is functioning correctly and that tenant workloads can communicate as expected.
Host-Level Verification
From the host perspective, confirm the Tenant Layer 2 Network configuration:
Navigate to Tenants → [Tenant Name] → Networks
Verify the Layer 2 network appears in the list
Confirm Enabled toggle is ON (blue)
Check that no error messages appear in the log
Tenant-Level Verification
Within the tenant environment, perform these checks:
Network Presence:
Log into tenant UI
Navigate to Networks → List
Verify External and Physical networks exist
Confirm both networks are present (they will show Status: Stopped)
VM NIC Configuration:
Open a test VM's configuration
Navigate to NICs
Verify the External network appears as a selectable option
Connectivity Testing:
Deploy a test VM connected to the Layer 2 network
Assign appropriate IP addressing for the VLAN
Test connectivity to other devices on the same VLAN
Verify expected network behavior (DHCP, routing, etc.)
Physical Infrastructure Verification
Confirm the underlying physical network configuration:
Verify physical switch ports are configured correctly:
Ports connected to tenant nodes have VLAN access
VLAN tagging matches VergeOS configuration
Switch port mode is appropriate (access or trunk)
Test connectivity from physical devices on the same VLAN to tenant VMs
Best Practices
Follow these recommendations for optimal Tenant Layer 2 Network implementation and management:
Planning and Design
Document VLAN Assignments: Maintain clear documentation of which VLANs are passed to which tenants
VLAN Reservation: Reserve VLANs 1 and 100-102 for VergeOS internal use (these cannot be used for pass-through)
Security Segmentation: Only pass necessary VLANs to tenants based on least-privilege principles
Naming Conventions: Use descriptive names for Layer 2 networks that indicate purpose and VLAN ID
Implementation
Test Before Production: Create test VMs in tenant to verify connectivity before migrating production workloads
Staged Rollout: Configure Layer 2 networks for one tenant at a time, verifying each before proceeding
External VLAN Network in Root: Add all Layer 2 External Networks in the Root system and test connectivity there first
Physical Infrastructure First: Ensure physical switch configuration is complete before creating Tenant Layer 2 Networks
Tenant Communication: Inform tenant administrators before configuring Layer 2 pass-through
Security Considerations
VLAN Isolation: Ensure physical switch properly isolates tenant VLANs
Access Control: Limit which administrators can create and modify Tenant Layer 2 Networks
Audit Trail: Regularly review logs for any unauthorized network configuration changes
Removing a Tenant Layer 2 Network
When a Tenant Layer 2 Network is no longer needed, follow this process carefully. Attempting to delete the network while it is still enabled or while the tenant is running will result in errors.
Follow This Order
You must disable the Layer 2 network before deleting it. Skipping the disable step or leaving tenant-side components behind will cause errors on deletion or prevent successful recreation.
Step 1: Disable the Layer 2 Network
From the top menu, navigate to Tenants > List
Double-click the tenant name to open the tenant dashboard
In the left navigation menu, expand Network and click Layer2 Networks
Select the checkbox next to the Layer 2 network you want to remove
Click Disable in the left sidebar
Confirm the disable action when prompted
Step 2: Delete the Layer 2 Network
With the Layer 2 network still selected, click Delete in the left sidebar
Confirm the deletion when prompted
NIC Removal
The NIC interface that was added to the tenant node is automatically removed when the Layer 2 network is disabled and deleted from the host side.
Step 3: Clean Up Tenant-Side Networks
The auto-created networks inside the tenant are not automatically removed when you delete the Layer 2 network from the host side. You must manually remove them from within the tenant.
Log into the tenant UI using tenant admin credentials
Navigate to Networks → List
Delete the External network first (named to match the root-side network)
Then delete the Physical network (prefixed with "Physical -")
Deletion Order Matters
You must delete the External network before the Physical network. The External network references the Physical network as its interface network, so attempting to delete the Physical network first will result in an error.
Verify Cleanup
After removing all components, confirm that no orphaned networks remain. Leftover networks can cause errors if you attempt to recreate the Layer 2 network later.
Next Steps
After successfully configuring Tenant Layer 2 Networks, consider these related topics:
Advanced Tenant Networking: Explore routing between tenant Layer 2 and internal networks
Virtual Switch Ports: Learn when to use Virtual Switch Ports for more complex multi-VLAN scenarios
Network Monitoring: Set up monitoring and alerting for tenant network health
Related Documentation
Provide Layer 2 Access to a Tenant (Virtual Switch Ports) - Alternative method for multi-VLAN scenarios
Configuring VLANs - Creating VLAN networks at the host level
Network Concepts - Understanding VergeOS networking fundamentals
Tenant Overview - Comprehensive tenant networking guide
Network Troubleshooting - Advanced network diagnostic procedures
Last updated
Was this helpful?