> For the complete documentation index, see [llms.txt](https://docs.vergeos-demo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vergeos-demo.com/run-the-platform/tenants/layer-2-networks.md).

# 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](/knowledge-base/networking/routing-l2-networks.md)
* 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

{% hint style="info" %}
**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](#removing-a-tenant-layer-2-network) for details.
{% endhint %}

{% hint style="warning" %}
**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.
{% endhint %}

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.

{% hint style="info" %}
**Prerequisite**

You must have a Layer 2 External network already created in the root system before proceeding. See [Creating a Layer 2 External Network](/knowledge-base/networking/routing-l2-networks.md) for instructions.
{% endhint %}

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

{% hint style="warning" %}
**Reserved VLANs**

VLANs 1, 100, 101, and 102 cannot be used for Tenant Layer 2 Networks. These VLANs are reserved for internal traffic.
{% endhint %}

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

{% hint style="success" %}
**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.
{% endhint %}

## 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](/run-the-platform/networking/internal-networks.md) 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**)
2. **VM NIC Configuration:**
   * Open a test VM's configuration
   * Navigate to **NICs**
   * Verify the External network appears as a selectable option
3. **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.

{% hint style="warning" %}
**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.
{% endhint %}

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

{% hint style="info" %}
**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.
{% endhint %}

### 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 -")

{% hint style="warning" %}
**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.
{% endhint %}

{% hint style="success" %}
**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.
{% endhint %}

## 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)](/knowledge-base/tenants/provide-layer2-to-tenant.md) - Alternative method for multi-VLAN scenarios
* [Configuring VLANs](/run-the-platform/networking/create-vlan.md) - Creating VLAN networks at the host level
* [Network Concepts](/run-the-platform/networking/network-concepts.md) - Understanding VergeOS networking fundamentals
* [Tenant Overview](/run-the-platform/tenants/overview.md) - Comprehensive tenant networking guide
* [Network Troubleshooting](/run-the-platform/networking/net-troubleshooting.md) - Advanced network diagnostic procedures


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.vergeos-demo.com/run-the-platform/tenants/layer-2-networks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.