diff --git a/docs/product-guide/tenants/layer-2-networks.md b/docs/product-guide/tenants/layer-2-networks.md index 98ff27e7..6673f27f 100644 --- a/docs/product-guide/tenants/layer-2-networks.md +++ b/docs/product-guide/tenants/layer-2-networks.md @@ -43,6 +43,7 @@ In this guide, you'll learn how to: - 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:** @@ -52,6 +53,7 @@ In this guide, you'll learn how to: - 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? @@ -62,6 +64,7 @@ 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/routing-l2-networks/) - Physical switch ports configured with appropriate VLAN access - Understanding of the VLAN IDs that need to be passed to the tenant @@ -80,7 +83,7 @@ This includes creating the Tenant Layer 2 Network, verification within the tenan | 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 or Physical network | Connect workload to VLAN | +| Attach VM | Tenant VM → `NICs` → Select External network | Connect workload to VLAN | ## Understanding Tenant Layer 2 Networks @@ -92,10 +95,17 @@ Tenant Layer 2 Networks provide direct VLAN connectivity from the host infrastru ### Automatic Network Creation -When you create a Tenant Layer 2 Network, VergeOS automatically provisions two networks within the tenant: +When you create a Tenant Layer 2 Network, VergeOS automatically provisions the following components within the tenant: -1. **External Network** - Appears in the tenant's network list with the name of the network you're passing through -2. **Physical Network** - Backend network infrastructure. Appears in the tenant's network list with the name of the network you're passing through, prepended by "**Physical -**" +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 + +!!! 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. + +!!! 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. Tenant virtual machines can attach NICs to these networks to gain direct access to the passed-through VLAN. @@ -122,6 +132,9 @@ Tenant Layer 2 Networks are ideal for scenarios requiring: 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. +!!! note "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/routing-l2-networks/) 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. @@ -129,9 +142,9 @@ First, access the tenant's network configuration area where you'll create the La 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, click **Networks** +4. In the left navigation menu, expand **Network** and click **Layer2 Networks** -You should now see the Tenant Networks view, which displays any existing Layer 2 networks configured for this tenant. +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 @@ -144,18 +157,17 @@ Next, initiate the creation of a new Layer 2 network pass-through for your tenan Now configure which network (VLAN) you want to pass through to the tenant and enable the connection. -!!! warning - VLANs 1, 100, 101, and 102 cannot be used in a Virtual Switch Port capacity. These VLANs are reserved for internal traffic. +!!! warning "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 VLAN you want to pass through to the tenant +1. In the **Network** dropdown field, select the external Layer 2 network tied to the VLAN you want to pass through to the tenant - - Available options include External networks and VLANs configured on your host - - The dropdown displays all Layer 2 networks available for pass-through + - 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, the configuration remains but the VLAN is not accessible to the tenant + - When disabled after creation, the configuration remains but the VLAN is not accessible to the tenant 3. Click **Submit** to save the configuration @@ -167,15 +179,15 @@ After submitting the configuration, VergeOS automatically creates the required n 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** +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 VLAN (e.g., "External") - - **Physical Network** - Backend infrastructure network (typically named "Physical") + - **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 should show **Status: Running** and appear in the tenant's network dashboard. +Both networks will show **Status: Stopped**. You can start the External network if you need to pass that traffic to a sub-tenant. !!! success "Verification Checkpoint" - At this point, you should see both the External and Physical networks running in the tenant's network dashboard. These networks represent the Layer 2 connectivity to the host VLAN. + 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 @@ -187,19 +199,15 @@ Tenant administrators attach VMs to the passed-through VLAN by selecting the app 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 either: - - **External Network** - For direct VLAN attachment - - **Physical Network** - For backend connectivity +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 -When designing tenant network architecture with Layer 2 Networks: +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](/product-guide/networks/internal-networks/) for more information. -- **VM Networks:** Place tenant-managed internal VM networks in the **External** network -- **Direct Workloads:** Attach VMs requiring direct VLAN access to the **External** or **Physical** network - **Isolation:** Consider which VMs truly need Layer 2 access vs. those that can use internal tenant networks ### Tenant Management Considerations @@ -208,7 +216,6 @@ 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) -- Firewall rules governing traffic on these networks - Internal routing between Layer 2 networks and other tenant networks ## Verification and Testing @@ -231,16 +238,15 @@ Within the tenant environment, perform these checks: 1. **Network Presence:** - Log into tenant UI - - Navigate to **Networks** + - Navigate to **Networks** → **List** - Verify External and Physical networks exist - - Confirm both show **Status: Running** + - 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 or Physical network appears as a selectable option - - Confirm VMs attached to these networks can power on successfully + - Verify the External network appears as a selectable option 3. **Connectivity Testing:** @@ -275,23 +281,61 @@ Follow these recommendations for optimal Tenant Layer 2 Network implementation a - **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 -- **Firewall Rules:** Consider whether tenant-managed firewall rules are appropriate for your security model - **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. + +!!! 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. + +### 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 + +!!! 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. + +### 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 -") + +!!! 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. + +!!! tip "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 -- **Tenant Network Rules:** Understand how to configure firewall rules within tenant environments - **Network Monitoring:** Set up monitoring and alerting for tenant network health ### Related Documentation