Skip to main content
Version: 3.10.x

Find and Resolve Duplicate Routes

Check for duplicate routes before synchronizing configuration or upgrading a control plane. Two indistinguishable routes make traffic ownership ambiguous, and an existing duplicate can prevent later Service updates.

The write-time checks described here were introduced in API7 Enterprise 3.10.7. They apply to route creation and updates, Service updates, and OpenAPI imports through the control plane, including changes made by ADC and API clients.

Prerequisites​

  • Access to the target gateway group's Services and Routes, including configuration managed by other teams.
  • A backup or export of the current configuration and the proposed configuration in version control.
  • A test environment for verifying routing changes before production synchronization.

Identify Exact Duplicates​

Compare routes within the same gateway group. Expand each Service's hosts and path_prefix with each Route's paths to obtain the effective URLs. Normalize each HTTP method list as a set: ordering does not distinguish routes, and an omitted or empty list means all methods. Compare the Route priorities as well.

For the same gateway group and effective URL:

Route ARoute BWrite-time result
GET, priority 0GET, priority 0Exact duplicate; rejected with 400.
GET, POST, priority 0POST, GET, priority 0Exact duplicate; method order makes no difference.
All methods, priority 0All methods, priority 0Exact duplicate.
GET, priority 0GET, priority 10Accepted; the higher-priority matching route takes precedence.
GET, priority 0GET, POST, priority 0Accepted by this guard; the method sets overlap but are not equal.
GET, priority 0POST, priority 0Accepted; the method sets are disjoint.

Overlapping paths, such as /orders/* and /orders/1, are also different from identical URLs. Routes with vars are excluded from this URL-based guard, and inactive Services are excluded until activation. Review these cases separately; acceptance does not prove that traffic reaches the route you intended.

Check Configuration before Synchronization​

Make the following checks part of the deployment pipeline:

  1. Export the target gateway group's configuration and combine it with the proposed changes. Include resources outside the subset managed by the current deployment.
  2. Compare effective URLs, method sets, and priorities using the rules above. Report both Service and Route identifiers for each exact duplicate, and block the deployment until its owner resolves it.
  3. Report partial method overlaps, wildcard paths, and conditional routes separately for review. If your organization rejects overlaps, document that as a stricter policy than the control plane's exact-duplicate check.
  4. Serialize deployments to the same gateway group, apply the approved changes, and export the resulting configuration again. The write-time check is best effort under concurrent changes; it does not replace a final audit.

The Dashboard's conflict check is advisory and can report overlaps that the write path allows. A clean client-side lint result is also insufficient if another deployment changes the target group before synchronization.

Resolve Existing Duplicates and Blocked Service Updates​

An upgrade does not remove existing duplicates. Editing a duplicate Route can return 400, and any update to its Service can be blocked, including a description or label change. Service updates recheck all their routes because changes to hosts, path prefixes, or activation can change traffic matching.

Use the conflict error's Service ID, Route ID, URL, methods, and priority to locate both resources. Decide which route should own the traffic. Remove an obsolete route, change its matching conditions, or assign different priorities when precedence is intentional. Do not change priorities merely to silence an error without testing the resulting traffic selection.

Correct the Route that causes the conflict first, then retry the Service update. Keep the declarative source and live configuration consistent so the next synchronization does not recreate the duplicate.

Recover from a Partially Completed Synchronization​

A synchronization can successfully write some resources before another write fails. Do not infer a complete rollback from a failed command.

  1. Stop further deployment attempts and retain the failed command's output, resource identifiers, and control plane error.
  2. Read back the target group's Services and Routes. Compare them with both the pre-deployment export and the desired configuration to identify which changes succeeded.
  3. Correct the conflict in the desired configuration, review the remaining changes, and synchronize again. If reverting, review the reverse changes against the current state before applying the backup.
  4. Confirm data plane configuration synchronization and test each affected host, path, and HTTP method. Check the selected Route in request logs, including cases with overlapping methods or different priorities.

Next Steps​