Skip to content

Configure Tenant Layer 2 Networks#

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#

Action Location Purpose
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:

  1. NIC Interface on the Tenant Node - A new virtual NIC is added to the tenant node, connected to the specified VLAN
  2. 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 -"
  3. 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#

Feature Tenant Layer 2 Networks 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.

  1. From the top menu, navigate to Tenants > List
  2. Locate your target tenant in the tenant list
  3. Click on the tenant name to open the tenant dashboard
  4. 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.

  1. Click New in the left sidebar
  2. 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.

  1. 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
  1. 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
  1. 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.

  1. Wait 10-15 seconds for the configuration to propagate
  2. Log into the tenant UI using tenant admin credentials
  3. From the tenant's Main Dashboard, navigate to Networks → List
  4. 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:

  1. Within the tenant UI, navigate to the VM you want to connect
  2. Access the VM's NICs section

  3. When creating or editing a NIC, select the External network for the passed-through VLAN

  4. Save the NIC configuration

  5. 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:

  1. Navigate to Tenants → [Tenant Name] → Networks
  2. Verify the Layer 2 network appears in the list
  3. Confirm Enabled toggle is ON (blue)
  4. Check that no error messages appear in the log

Tenant-Level Verification#

Within the tenant environment, perform these checks:

  1. 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)
  1. VM NIC Configuration:
  • Open a test VM's configuration
  • Navigate to NICs
  • Verify the External network appears as a selectable option
  1. 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:

  1. 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)

  2. 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#

  1. From the top menu, navigate to Tenants > List
  2. Double-click the tenant name to open the tenant dashboard
  3. In the left navigation menu, expand Network and click Layer2 Networks
  4. Select the checkbox next to the Layer 2 network you want to remove
  5. Click Disable in the left sidebar
  6. Confirm the disable action when prompted

Step 2: Delete the Layer 2 Network#

  1. With the Layer 2 network still selected, click Delete in the left sidebar
  2. 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.

  1. Log into the tenant UI using tenant admin credentials
  2. Navigate to Networks → List
  3. Delete the External network first (named to match the root-side network)
  4. 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