When attempting to deploy an NSX Edge Cluster using the SDDC Manager API, Fails due to uplink name conflict, and correct names fail REST Validation
search cancel

When attempting to deploy an NSX Edge Cluster using the SDDC Manager API, Fails due to uplink name conflict, and correct names fail REST Validation

book

Article ID: 448200

calendar_today

Updated On:

Products

VMware SDDC Manager / VCF Installer VMware NSX

Issue/Introduction

When attempting to deploy an NSX Edge Cluster using the SDDC Manager API (e.g., POST /v1/edge-clusters), the task fails during the validation phase or at the vCenter task "Add Distributed Port Group."

Error Messages Observed:

  • SDDC Manager UI/API: ECM_ERROR_DURING_PERFORMING_VALIDATION: Cannot determine default NSX enabled VDS uplinks.
  • vCenter Task Failure: Some Edge nodes in the specification do not have NSX enabled VDS uplinks specified. Either omit or specify NSX enabled VDS uplink names for all new Edge nodes.
  • Validation Logic: A specified parameter was not correct: spec.uplinkTeamingPolicy.uplinkPortOrder.activeUplinkPort. The activeUplinkPortName value: [Value] is not valid...

Environment

SDDC Manager 9.0 

NSX Manager 9.0

Cause

This issue occurs due to a mismatch between the literal vSphere Distributed Switch (VDS) uplink names and the internal enum values required by the SDDC Manager API.

  1. API Enum Requirement: The SDDC Manager API for EdgeClusterCreationSpec requires specific internal enum values: uplink1, uplink2, ..., up to uplink8.
  2. Literal Name Mismatch: Users often mistakenly provide the literal name seen in the vCenter UI (e.g., Uplink 1 or Uplink 2). SDDC Manager cannot resolve these literal strings against its internal per-cluster mapping.
  3. Brownfield/OOB Conflicts: In Brownfield environments or environments where the VDS was modified out-of-band, the internal is_used_by_nsxt flag or the Transport Node Profile (TNP) mapping may be inconsistent, preventing the resolution of the standard uplink1 mapping.
  4. Stale Artifacts: Stale Edge uplink profiles from previous failed attempts may carry old uplink references, causing validation conflicts during retries.

Resolution

To resolve this issue, align the API payload with SDDC Manager's expected internal naming and ensure the underlying infrastructure mapping is consistent.

1. Correct the API Payload

Review the JSON body used for the Edge Cluster deployment. Ensure that the firstNsxVdsUplink and secondNsxVdsUplink parameters use lowercase, non-spaced enum values.

  • Correct: "firstNsxVdsUplink": "uplink1"
  • Incorrect: "firstNsxVdsUplink": "Uplink 1" or "uplink-1"

2. Verify Transport Node Profile (TNP)

Ensure the TNP in NSX-T Manager is configured to use the correct uplink naming convention:

  • Navigate to System > Fabric > Profiles > Transport Node Profiles.
  • Edit the profile and verify that the Uplink Mapping matches the enum format (uplink1, uplink2) expected by SDDC Manager.

3. Infrastructure Homogeneity

Verify that the target cluster's vmnic-to-uplink associations are complete and homogeneous across all hosts in the cluster. SDDC Manager relies on this translation layer to map uplink1 to a physical NIC.

4. Cleanup Stale Artifacts

Before retrying the deployment:

  • Remove any stale or orphaned Edge uplink profiles in NSX-T Manager.
  • If multiple failures have occurred, consider using the VCF NSX-T Edge Cluster Deployment Removal Tool to ensure a clean state.

Additional Information

SDDC Manager API Reference: EdgeClusterCreationSpec}

Powered by Wolken Software