Add L2 tenant network creation details and removal process

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,16 +132,19 @@ 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.
 
 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