Cleanup of NSX segment post cutover activity
search cancel

Cleanup of NSX segment post cutover activity

book

Article ID: 444429

calendar_today

Updated On:

Products

VMware NSX

Issue/Introduction

 

  • Cleanup activity following a network cutover fails due to stale port interfaces connected to an NSX segment.

  • The segment remains in an admin down state with multiple attached logical ports.

  • This document outlines the best practices and detailed, step-by-step procedures to perform a cleanup activity for stale port interfaces connected to an NSX segment which is administratively down.

Environment

VMware NSX 

Cause

The stale logical ports are left behind, when the detach operation occurred, due to the port delete not being successful and no retry mechanism being present.

Resolution

Prerequisites

  • Ensure a recent backup of the NSX environment is available before proceeding.
  • Verify that no Virtual Machines (VMs) are actively connected to the port group associated with the target segment.

Phase 1: Verification in vSphere Client

Before initiating any deletion, confirm that the segment is completely unused on the compute side.

  1. Log in to the vSphere Client.
  2. Navigate to the Networking inventory view.
  3. Expand the datacenter and folder structure to locate the target distributed port group/segment.
  4. Select the port group.
  5. Click on the VMs tab in the central pane.
  6. Verify that the list is empty (it should state "No items found"). This confirms no VMs are attached.

Phase 2: Identify the Logical Switch UUID in NSX Manager

  1. Log in to the NSX Manager UI.
  2. Ensure you are operating in Manager Mode (toggle located at the top right of the UI).
  3. Navigate to Inventory > Switches > Logical Switches.
  4. Locate the target logical switch in the list. Note that its Admin Status should indicate "Down".
  5. Click on the logical switch name to view its detailed properties.
  6. In the Summary tab, locate the ID field.
  7. Copy the ID

Phase 3: Force Delete via NSX API

Since the segment has stale interfaces, standard UI deletion might fail. A force delete via API is required.

Option A: Using an API Client (e.g., Postman/SoapUI)

  1. Open your API client and configure the authentication (Basic Auth using NSX admin credentials).
  2. Set the HTTP Method to DELETE.
  3. Construct the Endpoint URL: https://[NSX-Manager-IP]/api/v1/logical-switches/[Logical-Switch-UUID]?detach=true&cascade=true
  4. Navigate to the Headers section of your request.
  5. Add a new custom HTTP Header: Key: X-Allow-Overwrite, Value: true

    Name

    Description

    		TypeNotes
    cascadeDelete a Logical Switch and all the logical ports in it, if none of the logical ports have any attachment.booleanDefault: "False"
    detachForce delete a logical switch

    If this is set to true, then logical switch is deleted
    regardless of whether or not it is added to NSGroup.
    If cascade is set to true in the meantime, then logical
    switch and all logical ports are deleted regardless of
    whether any logical port in this switch has attachments.    		booleanDefault: "False"

Option B: Using cURL Command

Alternatively, execute the following command from a terminal with network access to the NSX Manager:

curl -k -u 'admin' -H "Content-Type: application/json" -H "X-Allow-Overwrite: true" -X DELETE "https://[NSX-Manager-IP]/api/v1/logical-switches/[Logical-Switch-UUID]?detach=true&cascade=true"

 

Phase 4: Verify Deletion via API and Manager UI

  1. In your API client, change the HTTP Method to GET.
  2. Request the standard logical switch endpoint: GET https://[NSX-Manager-IP]/api/v1/logical-switches/[Logical-Switch-UUID]
  3. Verify that the response returns a 404 Not Found status with an error message stating "The requested object could not be found."
  4. Return to the NSX Manager UI (Manager Mode).
  5. Refresh the Inventory > Switches > Logical Switches page. The switch should no longer be present in the list.

Phase 5: Cleanup Segment in Policy Mode

  1. In the NSX UI, toggle the view from Manager Mode back to Policy Mode.
  2. Navigate to Networking > Connectivity > Segments.
  3. Expand the segment list and locate the target segment that was just force-deleted on the backend.
  4. Click the three vertical dots (Actions menu) next to the segment name.
  5. Select Delete from the dropdown menu.
  6. A warning prompt will appear stating: "Are you sure you want to delete [Segment-Name]? This action is permanent and cannot be recovered."
  7. Click the DELETE button to confirm and remove the stale policy object.

Additional Information

KBs to refer :
The issue and workaround are documented in KB 319115 available at

 

 

Powered by Wolken Software